docs(phase-20): complete phase execution

.planning/STATE.md

@@ -4,13 +4,13 @@ milestone: v1.3
 milestone_name: Research & Decision Tools
 status: planning
 stopped_at: Completed 20-02-PLAN.md
-last_updated: "2026-04-06T06:12:00.000Z"
+last_updated: "2026-04-06T06:17:39.050Z"
 last_activity: 2026-04-06
 progress:
-  total_phases: 13
-  completed_phases: 11
-  total_plans: 33
-  completed_plans: 33
+  total_phases: 14
+  completed_phases: 13
+  total_plans: 38
+  completed_plans: 36
   percent: 0
 ---
 
@@ -25,10 +25,10 @@ See: .planning/PROJECT.md (updated 2026-04-03)
 
 ## Current Position
 
-Phase: 18 of 18 (PostgreSQL Migration)
+Phase: 20 of 18 (PostgreSQL Migration)
 Plan: Not started
 Status: Ready to plan
-Last activity: 2026-04-05
+Last activity: 2026-04-06
 
 Progress: [----------] 0% (v2.0 milestone)
 

.planning/phases/20-fab-full-screen-catalog-search/20-VERIFICATION.md

@@ -0,0 +1,231 @@
+---
+phase: 20-fab-full-screen-catalog-search
+verified: 2026-04-06T06:30:00Z
+status: human_needed
+score: 14/14 automated must-haves verified
+re_verification: false
+human_verification:
+  - test: "FAB visible on all authenticated pages, hidden on login/public routes"
+    expected: "Gray circle FAB (bottom-right) appears on /collection, /threads, /setups, /dashboard, /settings, /global-items; hidden on /login and /users/* routes"
+    why_human: "Route-based visibility requires a running browser session to confirm"
+  - test: "FAB mini menu opens with animation"
+    expected: "Tapping FAB shows backdrop + staggered spring-animated menu items: 'Add to Collection' and 'Start New Thread'; 'New Setup' also appears on /setups"
+    why_human: "Framer Motion animation quality and spring behavior requires visual confirmation"
+  - test: "Full-screen catalog search overlay opens from both actions"
+    expected: "Tapping 'Add to Collection' shows overlay with 'Adding to Collection' header; 'Start New Thread' shows 'Starting a Thread' header"
+    why_human: "UIStore mode wiring and overlay header text require a live interaction check"
+  - test: "Search input debounce and tag chip filtering work correctly"
+    expected: "Results appear ~300ms after typing stops; clicking a tag chip toggles it blue and filters results (AND logic across multiple tags)"
+    why_human: "Debounce timing and live filtering behavior require interactive verification"
+  - test: "Result cards display correct data fields"
+    expected: "Each card shows brand (uppercase), model (semibold), weight badge (blue), price badge (green), category badge (gray), and Add button"
+    why_human: "Card layout and badge rendering require visual inspection"
+  - test: "Loading skeleton and empty state render correctly"
+    expected: "6 pulsing skeleton cards visible during load; 'No items found matching your search' message when results are empty"
+    why_human: "UI states require live interaction to trigger"
+  - test: "Back arrow closes overlay; FAB not visible while overlay is open"
+    expected: "Tapping back arrow closes overlay; FAB button does not peek through the overlay"
+    why_human: "Overlay/FAB interaction requires browser testing"
+  - test: "Mobile viewport: single column cards, horizontal scrollable tag chips"
+    expected: "On narrow viewport (<640px), result grid shows 1 column; tag chips are horizontally scrollable without wrapping"
+    why_human: "Responsive layout requires viewport resize testing"
+---
+
+# Phase 20: FAB Full-Screen Catalog Search — Verification Report
+
+**Phase Goal:** Users discover and add gear through a catalog-first search experience with tag filtering
+**Verified:** 2026-04-06T06:30:00Z
+**Status:** human_needed
+**Re-verification:** No — initial verification
+
+---
+
+## Goal Achievement
+
+### Observable Truths (Plan 01)
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | GET /api/tags returns all tags from the database | VERIFIED | `tag.service.ts` selects `{id, name}` from `tags` table ordered alphabetically; route registered at `/api/tags`; 4 tests pass |
+| 2 | GET /api/global-items endpoint is reachable (route registered) | VERIFIED | `app.route("/api/global-items", globalItemRoutes)` at index.ts:120; auth skip at lines 103-105 |
+| 3 | UIStore exposes fabMenu and catalogSearch state slices | VERIFIED | `uiStore.ts` lines 60-69 (interface) and 135-149 (implementation); all 6 fields + 4 actions present |
+| 4 | useGlobalItems hook supports optional tags parameter | VERIFIED | `useGlobalItems(query?, tags?)` at `useGlobalItems.ts:26`; `URLSearchParams` builds tag query string; query key includes tags |
+| 5 | useTags hook fetches and caches tag data | VERIFIED | `useTags.ts` exports `useTags()` with queryKey `["tags"]`, staleTime `5 * 60 * 1000` |
+
+### Observable Truths (Plan 02)
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 6 | FAB is visible on all authenticated pages | HUMAN NEEDED | `__root.tsx:164`: `showFab = isAuthenticated && !isPublicRoute` — logic correct, visual confirmation needed |
+| 7 | FAB is NOT visible on login page or public profile/setup pages | HUMAN NEEDED | `isPublicRoute` checks `/users/` and `/login` at `__root.tsx:159-160` — logic correct, visual confirmation needed |
+| 8 | Tapping FAB opens mini menu with 'Add to Collection' and 'Start New Thread' | HUMAN NEEDED | `FabMenu.tsx:27-38` builds `menuItems` array with both options; `AnimatePresence` at line 76 — needs live interaction |
+| 9 | On setups page, FAB menu also shows 'New Setup' option | HUMAN NEEDED | `FabMenu.tsx:40-49` conditional `isSetupsPage` push of New Setup item — needs live browser confirmation |
+| 10 | Tapping 'Add to Collection' opens catalog overlay in 'collection' mode | HUMAN NEEDED | `FabMenu.tsx:32`: `openCatalogSearch("collection")`; `CatalogSearchOverlay.tsx:66-69` shows mode-specific text — needs interaction |
+| 11 | Tapping 'Start New Thread' opens catalog overlay in 'thread' mode | HUMAN NEEDED | `FabMenu.tsx:36`: `openCatalogSearch("thread")`; same overlay — needs interaction |
+| 12 | Catalog search overlay has search input with debounce, tag chips, result cards | HUMAN NEEDED | `CatalogSearchOverlay.tsx:26-31` (debounce); lines 109-129 (tag chips); lines 136-199 (result cards) — needs visual check |
+| 13 | Tag chips toggle on/off and filter search results via AND logic | HUMAN NEEDED | `toggleTag()` at lines 54-59; `selectedTags` passed to `useGlobalItems` — AND logic in service confirmed; visual interaction needed |
+| 14 | Result cards show brand, model, weight, price, category, and Add button (stub) | HUMAN NEEDED | `CatalogSearchOverlay.tsx:168-199` renders all fields with correct badge colors — needs visual confirmation |
+
+**Automated Score:** 5/5 Plan 01 truths verified. Plan 02 truths verified at code level; all require human visual confirmation.
+
+---
+
+## Required Artifacts
+
+### Plan 01 Artifacts
+
+| Artifact | Expected | Lines | Status | Details |
+|----------|----------|-------|--------|---------|
+| `src/server/services/tag.service.ts` | getAllTags function | 12 | VERIFIED | Exports `getAllTags`; real DB query via Drizzle |
+| `src/server/routes/tags.ts` | GET /api/tags endpoint | 14 | VERIFIED | Exports `tagRoutes`; calls `getAllTags(db)`; returns `c.json(allTags)` |
+| `src/client/stores/uiStore.ts` | FAB menu + catalog search state | 151 | VERIFIED | Contains `fabMenuOpen`, `catalogSearchOpen`, `catalogSearchMode`, all 4 actions |
+| `src/client/hooks/useTags.ts` | Tag fetching hook | 15 | VERIFIED | Exports `useTags` and `Tag` interface; `staleTime: 5 * 60 * 1000` |
+| `src/client/hooks/useGlobalItems.ts` | Updated hook with tag support | 77 | VERIFIED | `tags?: string[]` parameter; `URLSearchParams` query building |
+
+### Plan 02 Artifacts
+
+| Artifact | Expected | Lines | Status | Details |
+|----------|----------|-------|--------|---------|
+| `src/client/components/FabMenu.tsx` | FAB with mini menu (min 60 lines) | 115 | VERIFIED | Imports `AnimatePresence`; uses `useUIStore`; renders both menu items + conditional New Setup |
+| `src/client/components/CatalogSearchOverlay.tsx` | Full-screen catalog search (min 100 lines) | 262 | VERIFIED | Imports `useTags`, `useGlobalItems`; contains debounce, tag chips, skeleton, empty state |
+
+---
+
+## Key Link Verification
+
+### Plan 01 Key Links
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `tags.ts` | `tag.service.ts` | `getAllTags` import | WIRED | `import { getAllTags }` at `routes/tags.ts:2`; called at line 10 |
+| `index.ts` | `routes/tags.ts` | `app.route` registration | WIRED | `app.route("/api/tags", tagRoutes)` at `index.ts:121` |
+| `index.ts` | `routes/global-items.ts` | `app.route` registration | WIRED | `app.route("/api/global-items", globalItemRoutes)` at `index.ts:120` |
+
+### Plan 02 Key Links
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `FabMenu.tsx` | `uiStore.ts` | `useUIStore` | WIRED | Imports and uses `fabMenuOpen`, `openFabMenu`, `closeFabMenu`, `openCatalogSearch`, `catalogSearchOpen` |
+| `CatalogSearchOverlay.tsx` | `useGlobalItems.ts` | `useGlobalItems(query, tags)` | WIRED | `useGlobalItems(debouncedQuery || undefined, selectedTags.length > 0 ? selectedTags : undefined)` at line 20 |
+| `CatalogSearchOverlay.tsx` | `useTags.ts` | `useTags()` | WIRED | `const { data: tags } = useTags()` at line 19 |
+| `__root.tsx` | `FabMenu.tsx` | `FabMenu` component render | WIRED | Imports `FabMenu` at line 16; renders `{showFab && <FabMenu isSetupsPage={isSetupsPage} />}` at line 252 |
+| `__root.tsx` | `CatalogSearchOverlay.tsx` | `CatalogSearchOverlay` component render | WIRED | Imports at line 13; renders `<CatalogSearchOverlay />` at line 255 |
+
+---
+
+## Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+|----------|--------------|--------|-------------------|--------|
+| `CatalogSearchOverlay.tsx` | `items` (from `useGlobalItems`) | `global-item.service.ts:searchGlobalItems` | Yes — Drizzle query against `globalItems` table with ILIKE text search and tag subquery AND logic | FLOWING |
+| `CatalogSearchOverlay.tsx` | `tags` (from `useTags`) | `tag.service.ts:getAllTags` | Yes — Drizzle `select({id, name}).from(tags).orderBy(asc(tags.name))` | FLOWING |
+
+---
+
+## Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| `getAllTags` is a callable function | `node -e "require('./src/server/services/tag.service.ts').getAllTags"` | `function` | PASS |
+| Tag service tests: returns empty array + populated array | `bun test tests/services/tag.service.test.ts tests/routes/tags.test.ts` | 4 pass, 0 fail | PASS |
+| Route registrations present | `grep "app.route.*tags\|app.route.*global-items" src/server/index.ts` | Lines 120-121 found | PASS |
+| Old single-action FAB removed from root | `grep "title=\"Add new item\"" src/client/routes/__root.tsx` | No matches | PASS |
+| Phase 20 files have zero lint errors | `bun run lint` filtered to phase files | No matches in phase files | PASS |
+
+*Note: `bun run lint` reports 16 errors globally — all in pre-existing files unrelated to Phase 20 (CandidateCard.tsx, ImageUpload.tsx, ItemCard.tsx, various services/tests). Phase 20 files are lint-clean.*
+
+---
+
+## Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|------------|-------------|--------|----------|
+| CATFLOW-01 | 20-01, 20-02 | FAB shows mini menu globally, plus "New Setup" on setups page | SATISFIED | `FabMenu.tsx` renders menu with both global actions; `isSetupsPage` prop gates "New Setup" item; `__root.tsx` passes `isSetupsPage` and gates FAB on `isAuthenticated && !isPublicRoute` |
+| CATFLOW-02 | 20-01, 20-02 | Full-screen catalog search with tag chip filtering | SATISFIED | `CatalogSearchOverlay.tsx` (262 lines) implements debounced search, tag chip AND-filtering, responsive result grid; data flows through `useGlobalItems` to real DB query |
+
+No orphaned requirements — REQUIREMENTS.md maps exactly CATFLOW-01 and CATFLOW-02 to Phase 20, matching both plan frontmatter declarations.
+
+---
+
+## Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| `CatalogSearchOverlay.tsx` | 62-64 | `handleAddStub()` — empty function, Add button does nothing | INFO | Intentional stub per plan spec; Phase 21 wires add-to-collection and add-to-thread flows |
+| `FabMenu.tsx` | 44-47 | `onClick` for "New Setup" only calls `closeFabMenu()` — no navigation | INFO | Intentional stub per plan spec; Phase 21 or existing setup creation flow wires this |
+
+Both stubs are **plan-sanctioned** (explicitly documented in `20-02-SUMMARY.md` Known Stubs table). Neither prevents the Phase 20 goal — catalog discovery and tag filtering work; only the action-completion flows are deferred.
+
+---
+
+## Human Verification Required
+
+### 1. FAB Visibility Across Routes
+
+**Test:** Log in, navigate to `/collection`, `/threads`, `/setups`, `/dashboard`, `/settings`, `/global-items` one by one.
+**Expected:** Gray circle FAB appears at bottom-right on every page. Navigate to `/login` — FAB must not be visible.
+**Why human:** Route-based conditional rendering requires a live session.
+
+### 2. FAB Mini Menu Animation
+
+**Test:** Click the FAB button from any authenticated page.
+**Expected:** Backdrop fades in, "Add to Collection" and "Start New Thread" items spring-animate upward with stagger. "+" icon rotates to "x". Clicking backdrop closes menu.
+**Why human:** Framer Motion spring animation quality cannot be verified from static code.
+
+### 3. "New Setup" on Setups Page
+
+**Test:** Navigate to `/setups`, click FAB.
+**Expected:** Mini menu shows three items: "Add to Collection", "Start New Thread", and "New Setup" at bottom.
+**Why human:** `isSetupsPage` computed via `matchRoute` requires live router context.
+
+### 4. Catalog Search Overlay — Open / Mode Text
+
+**Test:** From collection page, click FAB → "Add to Collection". From threads page, click FAB → "Start New Thread".
+**Expected:** Full-screen white overlay slides up. Header shows "Adding to Collection" for first action, "Starting a Thread" for second. Search input is auto-focused.
+**Why human:** UIStore mode passing and header text require interactive verification.
+
+### 5. Tag Chip Filtering
+
+**Test:** Open catalog search, type a query, then click one or more tag chips.
+**Expected:** Active chips turn blue (`bg-blue-100 text-blue-700`). Results update to only show items matching ALL selected tags (AND logic). Clicking again deactivates chip and broadens results.
+**Why human:** Live filter behavior and tag chip toggle state require interaction.
+
+### 6. Loading Skeleton and Empty State
+
+**Test:** Open catalog search and type immediately; also try a query that returns no results.
+**Expected:** 6 pulsing gray skeleton cards visible during load. Empty state shows "No items found matching your search" with a gear SVG icon.
+**Why human:** Race condition with debounce makes skeletons hard to catch; empty state requires a specific query.
+
+### 7. Back Arrow Closes Overlay
+
+**Test:** Open catalog search overlay, click the back arrow (top-left).
+**Expected:** Overlay slides down/fades. FAB reappears. Body scroll is restored (page scrollable again).
+**Why human:** Overlay exit animation and scroll-lock restoration require live interaction.
+
+### 8. Mobile Responsive Layout
+
+**Test:** Open catalog search in browser devtools at 375px width.
+**Expected:** Result grid shows 1 column. Tag chips are horizontally scrollable without line-wrapping.
+**Why human:** Responsive CSS requires viewport resize testing.
+
+---
+
+## Gaps Summary
+
+No automated gaps found. All code-level must-haves are fully implemented, wired, and data-flowing:
+
+- Tags API: real DB query, route registered, auth-skipped for GET, 4 tests green.
+- UIStore: all 6 state fields and 4 actions present and wired to components.
+- Hooks: `useTags` and `useGlobalItems` (with tag support) fully implemented and consumed.
+- `FabMenu.tsx`: 115 lines, framer-motion animated, all menu items correct, wired to UIStore.
+- `CatalogSearchOverlay.tsx`: 262 lines, debounced search, tag chip AND-filtering, skeleton, empty state, wired to both hooks.
+- `__root.tsx`: old single-action FAB replaced, FabMenu and CatalogSearchOverlay both imported and rendered with correct conditional logic.
+
+Phase 20's two stubs (`handleAddStub` and "New Setup" onClick) are plan-sanctioned deferrals to Phase 21. They are informational only and do not block the Phase 20 goal.
+
+**Pending:** 8 items require human visual/interactive verification before the phase can be fully closed.
+
+---
+
+_Verified: 2026-04-06T06:30:00Z_
+_Verifier: Claude (gsd-verifier)_