docs(05): capture phase context

.planning/phases/05-image-handling/05-CONTEXT.md

@@ -0,0 +1,100 @@
+# Phase 5: Image Handling - Context
+
+**Gathered:** 2026-03-15
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Fix image display throughout the app (images upload but don't render), redesign the upload UX with a hero image preview area and placeholder icons, and add image display to gear cards, candidate cards, and setup item lists. No new image features (galleries, editing, tagging) — those would be separate phases.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Image preview area (item form)
+- Move image from bottom of form to a full-width hero area at the top
+- 4:3 landscape aspect ratio (matches ItemCard's existing aspect-[4/3])
+- When no image: light gray background with centered Lucide icon (ImagePlus or Camera) and "Click to add photo" text below
+- When image exists: full-width image with object-cover, small circular X button in top-right to remove
+- Clicking the image opens file picker to replace (same behavior as clicking placeholder)
+
+### Card placeholders
+- All cards (items and candidates) show the 4:3 image area always — consistent card heights in grid
+- When no image: light gray (gray-50/gray-100) background with the item's category icon centered
+- Category icons are currently emoji — use whatever is current (Phase 6 will migrate to Lucide)
+- Candidate cards get the same placeholder treatment as item cards
+
+### Upload interaction
+- Click only — no drag-and-drop (keeps it simple for side panel form)
+- Spinner overlay centered on hero area while uploading
+- No client-side image processing (no crop, no resize) — CSS object-cover handles display
+- CandidateForm gets the same hero area redesign as ItemForm
+
+### Image in detail/setup views
+- Clicking uploaded image in form opens file picker to replace (no lightbox/zoom)
+- Setup item lists show small square thumbnails (~40px) with rounded corners next to item name
+- Setup thumbnails show category icon placeholder when item has no image
+
+### Image display bug fix
+- Investigate and fix root cause of images uploading but not rendering (likely path/proxy issue)
+- This is prerequisite work — fix before redesigning the UX
+
+### Claude's Discretion
+- Exact placeholder icon choice (ImagePlus vs Camera vs similar)
+- Spinner animation style
+- Exact gray shade for placeholder backgrounds
+- Transition/animation on image load
+- Error state design for failed uploads
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `ImageUpload` component (`src/client/components/ImageUpload.tsx`): Existing upload logic with file validation, apiUpload call, preview, and remove button — needs restructuring into hero area pattern
+- `ItemCard` (`src/client/components/ItemCard.tsx`): Already renders imageFilename with `aspect-[4/3]` but skips image area when null — needs placeholder addition
+- `CandidateCard` / `CandidateForm`: Candidate equivalents that need same treatment
+- `apiUpload` helper in `lib/api.ts`: Upload function already works
+
+### Established Patterns
+- Images stored as UUID filenames in `./uploads/` directory
+- Server serves `/uploads/*` via `hono/bun` serveStatic
+- Vite dev proxy forwards `/uploads` to `http://localhost:3000`
+- Image upload API at `POST /api/images` returns `{ filename }` (201 status)
+- `imageFilename` field on items and candidates — string or null
+- 5MB max, JPG/PNG/WebP accepted
+
+### Integration Points
+- `src/client/components/ItemForm.tsx`: Move ImageUpload from bottom to top, redesign as hero area
+- `src/client/components/CandidateForm.tsx`: Same hero area redesign
+- `src/client/components/ItemCard.tsx`: Add placeholder when imageFilename is null
+- `src/client/components/CandidateCard.tsx`: Add placeholder when imageFilename is null
+- `src/client/routes/setups/$setupId.tsx`: Add small thumbnails to setup item list
+- Server static file serving: Verify `/uploads/*` path works in both dev and production
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- Hero area should feel like a product photo section — clean, prominent, image-first
+- Placeholder with category icon adds visual meaning even before images are uploaded
+- Consistent 4:3 aspect ratio across hero area and cards keeps everything aligned
+- Setup thumbnails should be compact (40px square) — don't dominate the list layout
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 05-image-handling*
+*Context gathered: 2026-03-15*