---
estimated_steps: 54
estimated_files: 6
skills_used: []
---

# T03: Build frontend search flow: landing page, search results, and technique page

## Description

Build the primary user flow: landing page with search bar → search results page → technique page detail. This is the R005/R006/R015 critical path. Includes the new typed API client for public endpoints, App.tsx routing with both admin and public routes, and 3 new page components with CSS.

The frontend uses React 18 + Vite + TypeScript with strict mode (`noUnusedLocals`, `noUnusedParameters`, `noUncheckedIndexedAccess`). Existing pattern: plain CSS in `App.css`, typed `fetch()` API client, React Router v6.

## Steps

1. Create `frontend/src/api/public-client.ts` — typed API client for public endpoints:
   - Types: `SearchResultItem`, `SearchResponse`, `TechniquePageDetail`, `KeyMomentSummary`, `CreatorInfo`, `RelatedLink`, `TopicCategory`, `TopicSubTopic`, `CreatorBrowseItem`
   - Functions: `searchApi(q, scope?, limit?)`, `fetchTechnique(slug)`, `fetchTechniques(params?)`, `fetchTopics()`, `fetchCreators(params?)`, `fetchCreator(slug)`
   - Reuse the `request<T>` helper pattern from existing `client.ts` (or extract shared helper)

2. Create `frontend/src/pages/Home.tsx` — landing page:
   - Prominent search bar (auto-focus on mount) with debounce (300ms)
   - Live typeahead: after 2+ chars, show top 5 results in dropdown below search bar
   - On Enter or "See all results" link, navigate to `/search?q=...`
   - Two navigation cards: "Topics" (links to `/topics`) and "Creators" (links to `/creators`)
   - "Recently Added" section showing last 5 technique pages (fetch from `/api/v1/techniques?limit=5`)

3. Create `frontend/src/pages/SearchResults.tsx` — full search results page:
   - Read `q` from URL search params
   - Display results grouped by type (technique_pages first, then key_moments)
   - Each result: title (linked to technique page), summary snippet, creator name, category/tags
   - Show "No results found" for empty results, "Showing keyword results" when fallback_used=true
   - Search bar at top for refining query

4. Create `frontend/src/pages/TechniquePage.tsx` — technique page display (R006):
   - Fetch technique by slug from URL params via `fetchTechnique(slug)`
   - Header: title, topic_category badge, topic_tags pills, creator name (linked to `/creators/{slug}`), source_quality indicator
   - Amber banner if source_quality === 'unstructured' (livestream-sourced)
   - Study guide prose: render `body_sections` JSONB — iterate Object.entries, render each section as `<h2>` + paragraph. Handle both string and object values gracefully.
   - Key moments index: ordered list with title, start_time→end_time, content_type badge, summary
   - Signal chains section (if present): render each chain as name + ordered steps
   - Plugins referenced (if present): pill list
   - Related techniques (if present): linked list
   - Loading state and 404 error state

5. Update `frontend/src/App.tsx` routing:
   - Import new pages
   - Add public routes: `/` → Home, `/search` → SearchResults, `/techniques/:slug` → TechniquePage
   - Keep admin routes at `/admin/*`
   - Update header: "Chrysopedia" title (not "Chrysopedia Admin"), nav links to Home, Topics, Creators, and Admin

6. Add CSS to `frontend/src/App.css` for new pages:
   - Search bar styles (large, centered on home, inline on results page)
   - Typeahead dropdown styles
   - Navigation cards (grid layout)
   - Technique page layout (readable prose width, section spacing)
   - Search result items (hover state, meta info)
   - Tag/badge pill styles
   - Loading and error states

## Must-Haves

- [ ] Typed public API client with all endpoint functions
- [ ] Landing page with search bar, typeahead, navigation cards, recently added
- [ ] Search results page with grouped results
- [ ] Technique page with all sections (header, prose, key moments, related links)
- [ ] App.tsx routes both public and admin paths
- [ ] `cd frontend && npx tsc -b` passes with zero errors

## Verification

- `cd frontend && npx tsc -b` — zero TypeScript errors
- `cd frontend && npm run build` — clean production build
- Verify files exist: `test -f frontend/src/api/public-client.ts && test -f frontend/src/pages/Home.tsx && test -f frontend/src/pages/SearchResults.tsx && test -f frontend/src/pages/TechniquePage.tsx`

## Inputs

- ``frontend/src/api/client.ts` — existing API client pattern (request helper, typed functions)`
- ``frontend/src/App.tsx` — existing routing structure to extend`
- ``frontend/src/App.css` — existing styles to extend (620 lines)`
- ``frontend/src/main.tsx` — entry point (BrowserRouter already configured)`
- ``frontend/tsconfig.app.json` — strict TS config (noUnusedLocals, noUnusedParameters, noUncheckedIndexedAccess)`
- ``frontend/package.json` — dependencies (react 18, react-router-dom 6, vite 6)`
- ``backend/schemas.py` — response schemas defining API contract shapes (SearchResponse, TechniquePageDetail, etc.)`

## Expected Output

- ``frontend/src/api/public-client.ts` — typed API client for search, techniques, topics, creators endpoints`
- ``frontend/src/pages/Home.tsx` — landing page with search bar, typeahead, nav cards, recently added`
- ``frontend/src/pages/SearchResults.tsx` — search results page with grouped results`
- ``frontend/src/pages/TechniquePage.tsx` — full technique page display with all sections`
- ``frontend/src/App.tsx` — updated with public + admin routes and navigation`
- ``frontend/src/App.css` — extended with styles for all new components`

## Verification

cd frontend && npx tsc -b && npm run build && echo 'Frontend build OK'
