# S03 Research: Homepage Cards & Creator Metric Polish

## Summary

Straightforward UI polish slice with two changes:
1. **Homepage technique cards**: Add sub-topic tag pills and key moment count to the "Recently Added" cards on `Home.tsx`
2. **Creator detail page**: Replace the meaningless "0 views" stat with technique count grouped by topic category

## Recommendation

Light frontend work + one small backend addition. No new libraries, no architectural changes, no risky integration.

## Implementation Landscape

### Change 1: Homepage cards — sub-topic tags + key moment count

**Frontend** (`frontend/src/pages/Home.tsx`, lines ~166-185):
- `recent-card` already renders `topic_category` badge and `summary`
- `TechniqueListItem` type already has `topic_tags: string[] | null` — it's just not rendered in the card
- **Missing**: `key_moment_count` is not in `TechniqueListItem` or `TechniquePageRead` schema

**Backend** (`backend/schemas.py`, `backend/routers/techniques.py`):
- `TechniquePageRead` (line 132) needs a new `key_moment_count: int = 0` field
- `list_techniques` endpoint (line 33) currently does `selectinload(TechniquePage.creator)` — needs to also count key moments
- Two approaches for count:
  - **Subquery** (preferred): `select(func.count()).where(KeyMoment.technique_page_id == TechniquePage.id).correlate(TechniquePage).scalar_subquery()` — same pattern already used in `creators.py` for `technique_count_sq`
  - **selectinload + len**: Loads all key moments just to count them — wasteful
- The subquery approach matches the existing codebase pattern in `routers/creators.py` lines 42-47

**Frontend type** (`frontend/src/api/public-client.ts`):
- Add `key_moment_count: number` to `TechniqueListItem` interface (line ~87)

**CSS** (`frontend/src/App.css`):
- `recent-card__meta` (line 1100) already uses flex + gap + wrap — tag pills will flow naturally
- Existing `.pill` class can be reused for sub-topic tags
- Key moment count needs a small inline element — pattern: `<span className="recent-card__moments">3 moments</span>`

### Change 2: Creator detail — technique count by topic instead of "0 views"

**Frontend** (`frontend/src/pages/CreatorDetail.tsx`, lines ~90-96):
- Currently shows: `{creator.view_count.toLocaleString()} views`
- The `techniques` array is already fetched (line 39: `fetchTechniques({ creator_slug: slug, limit: 100 })`)
- Each `TechniqueListItem` has `topic_category` — group with a simple reduce to get `{category: count}` map
- Replace the views span with pills like `"Mixing: 4 · Synthesis: 2 · Sound Design: 1"` or similar compact display

**Backend**: No backend change needed — all data already present in the frontend.

**CSS**: Minimal — the existing `.creator-detail__stats` (line 1830) styles work. May need small additions for the category breakdown display.

### Files to modify

| File | Change |
|------|--------|
| `backend/schemas.py` | Add `key_moment_count: int = 0` to `TechniquePageRead` |
| `backend/routers/techniques.py` | Add key_moment count subquery to `list_techniques`, populate field in loop |
| `frontend/src/api/public-client.ts` | Add `key_moment_count: number` to `TechniqueListItem` |
| `frontend/src/pages/Home.tsx` | Render `topic_tags` pills and `key_moment_count` in recent cards |
| `frontend/src/pages/CreatorDetail.tsx` | Replace `view_count` display with topic-category breakdown derived from `techniques` array |
| `frontend/src/App.css` | Small additions for key moment count display and any creator topic breakdown styling |

### Natural task seams

1. **Backend: Add key_moment_count to technique list endpoint** — schema change + subquery + verify via curl. Independent, unblocks T2.
2. **Frontend: Homepage card enhancements** — render topic_tags + key_moment_count in Home.tsx recent cards + CSS. Depends on T1.
3. **Frontend: Creator detail metric polish** — replace views with topic breakdown in CreatorDetail.tsx + CSS. Independent of T1/T2.

T1 and T3 can run in parallel. T2 depends on T1.

### Verification approach

- `cd backend && python -c "from schemas import TechniquePageRead; print(TechniquePageRead.model_fields.keys())"` — confirm field exists
- `curl http://ub01:8096/api/v1/techniques?limit=3 | python -m json.tool` — confirm `key_moment_count` appears in response
- `cd frontend && npx tsc --noEmit` — zero TypeScript errors
- `cd frontend && npm run build` — production build succeeds
- Visual: homepage cards show tag pills and "N moments" text
- Visual: creator detail page shows topic breakdown instead of "0 views"

### Constraints / edge cases

- Some techniques may have 0 key moments — display should handle gracefully (omit or show "0 moments")
- Some techniques may have null `topic_tags` — already handled by the card pattern on CreatorDetail.tsx (conditional render)
- The `techniques` fetch on CreatorDetail uses `limit: 100` — sufficient for current data but won't scale to creators with 100+ techniques. Noted but not in scope.
