version: "1.0.0" name: add-frontend-feature description: Scaffold a frontend feature in PictoPy — Redux slice, API wrapper, hook, component, and test. Use when adding UI, a new screen, or frontend state. argument-hint: [feature-name]

Add a frontend feature

A feature spans state, data access, and presentation. Build it in that order — bottom up — so each layer is testable before the next depends on it.

$1 is the feature name in camelCase (videos, faceClusters, memories).

Read agent-kit/references/frontend-feature-walkthrough.md for the video feature traced from slice to component.

1. Types — src/types/

Define the shape the backend actually returns. Check the FastAPI response model in backend/app/routes/<resource>.py rather than guessing — the two must agree, and the backend is the source of truth.

2. API layer — two files, both required

1. src/api/apiEndpoints.ts — add a <feature>Endpoints object. Parameterised URLs are

functions that encodeURIComponent their arguments.

1. src/api/api-functions/<feature>.ts — a typed wrapper per endpoint, using the shared

apiClient from ../axiosConfig, returning Promise<APIResponse>.

Components never call axios directly. If you find yourself importing axios into a component, the wrapper is missing.

3. State — src/features/

Template: agent-kit/templates/slice.ts.md.

• <feature>Slice.ts — Redux Toolkit createSlice.
• <feature>Selectors.ts — derived data lives here, not in components.
• <feature>Thunks.ts — only if the feature needs async orchestration beyond a hook.

Keep reducers total: validate indices and ranges inside the reducer, not at the call site. setCurrentViewIndex in src/features/videoSlice.ts is the reference.

Register the reducer in the store (src/store/).

4. Hook — src/hooks/use<Feature>.ts

Bridges the API layer and the store, and is where components get their data. Existing hooks use React Query alongside Redux — follow whichever the neighbouring feature uses rather than introducing a third pattern.

5. Component — src/components/<Area>/

• src/components/ui/ is generated by shadcn. Do not hand-edit it.
• Tailwind v4 with prettier-plugin-tailwindcss. Never hand-order class names.
• Import through @/, which resolves to frontend/src.
• No `TODO` or `FIXME` comments. ESLint treats them as errors and CI fails.

6. Tests — __tests__/ beside the code

Template: agent-kit/templates/component.test.tsx.md.

Jest + React Testing Library. Test through rendered output, not implementation details. Cover the loading state, the populated state, and the empty state — empty states are where this codebase has had regressions.

7. Verify

cd frontend && npm run lint:check && npm run format:check && npm test

If format:check fails, run npm run format:fix rather than editing by hand.

Checklist

• [ ] Types in src/types/, matching the backend response model
• [ ] <feature>Endpoints in src/api/apiEndpoints.ts
• [ ] Wrappers in src/api/api-functions/<feature>.ts using apiClient
• [ ] <feature>Slice.ts and <feature>Selectors.ts, reducer registered in the store
• [ ] use<Feature>.ts hook
• [ ] Component under src/components/<Area>/, no hand-ordered Tailwind classes
• [ ] Tests covering loading, populated, and empty
• [ ] No TODO or FIXME anywhere in the diff
• [ ] lint:check, format:check, and npm test all pass