docs(05-01): complete image display fix and hero area plan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-15 17:12:54 +01:00
parent 3243be433f
commit 036d8ac183
3 changed files with 120 additions and 23 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -13,10 +13,10 @@ Requirements for v1.1 Fixes & Polish. Each maps to roadmap phases.

 ### Images

- [ ] **IMG-01**: User can see uploaded images displayed on item detail views
+- [x] **IMG-01**: User can see uploaded images displayed on item detail views
 - [ ] **IMG-02**: User can see item images on gear collection cards
- [ ] **IMG-03**: User sees image preview area at top of item form with placeholder icon when no image is set
- [ ] **IMG-04**: User can upload an image by clicking the placeholder area
+- [x] **IMG-03**: User sees image preview area at top of item form with placeholder icon when no image is set
+- [x] **IMG-04**: User can upload an image by clicking the placeholder area

 ### Planning

@@ -75,10 +75,10 @@ Which phases cover which requirements. Updated during roadmap creation.
 | Requirement | Phase | Status |
 |-------------|-------|--------|
 | DB-01 | Phase 4 | Complete |
-| IMG-01 | Phase 5 | Pending |
+| IMG-01 | Phase 5 | Complete |
 | IMG-02 | Phase 5 | Pending |
-| IMG-03 | Phase 5 | Pending |
-| IMG-04 | Phase 5 | Pending |
+| IMG-03 | Phase 5 | Complete |
+| IMG-04 | Phase 5 | Complete |
 | PLAN-01 | Phase 4 | Complete |
 | PLAN-02 | Phase 4 | Complete |
 | CAT-01 | Phase 6 | Pending |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -2,16 +2,16 @@
 gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Fixes & Polish
-status: completed
-stopped_at: Phase 5 context gathered
-last_updated: "2026-03-15T16:02:32.448Z"
-last_activity: 2026-03-15 -- Completed 04-02 planning tab frontend overhaul
+status: executing
+stopped_at: Completed 05-01-PLAN.md
+last_updated: "2026-03-15T16:12:40.684Z"
+last_activity: 2026-03-15 -- Completed 05-01 image display fix and hero area
 progress:
  total_phases: 3
  completed_phases: 1
-  total_plans: 2
-  completed_plans: 2
-  percent: 100
+  total_plans: 4
+  completed_plans: 3
+  percent: 75
 ---

 # Project State
@@ -21,16 +21,16 @@ progress:
 See: .planning/PROJECT.md (updated 2026-03-15)

 **Core value:** Make it effortless to manage gear and plan new purchases -- see how a potential buy affects your total setup weight and cost before committing.
-**Current focus:** Phase 4 - Database & Planning Fixes
+**Current focus:** Phase 5 - Image Handling

 ## Current Position

-Phase: 4 of 6 (Database & Planning Fixes)
-Plan: 2 of 2 in current phase (COMPLETE)
-Status: Phase Complete
-Last activity: 2026-03-15 -- Completed 04-02 planning tab frontend overhaul
+Phase: 5 of 6 (Image Handling)
+Plan: 1 of 2 in current phase (plan 1 complete)
+Status: In Progress
+Last activity: 2026-03-15 -- Completed 05-01 image display fix and hero area

-Progress: [██████████] 100% (v1.1 phases)
+Progress: [████████░░] 75% (v1.1 phases)

 ## Accumulated Context

@@ -42,6 +42,8 @@ Progress: [██████████] 100% (v1.1 phases)
 - [Phase 04]: Modal dialog for thread creation instead of inline form -- cleaner UX, supports category selection
 - [Phase 04]: Educational empty state with numbered workflow steps -- helps new users understand planning flow
 - [Phase 04]: Pill tab segment control for Active/Resolved -- replaces checkbox, more intuitive
+- [Phase 05]: Image bug root cause: Zod schemas missing imageFilename -- validator silently stripped it from payloads
+- [Phase 05]: Inline SVGs instead of lucide-react -- only 3 icons needed, avoids dependency

 ### Pending Todos

@@ -50,11 +52,11 @@ None.
 ### Blockers/Concerns

 - `threads` table missing from database (schema exists, never pushed) -- Phase 4
- Images upload but don't display in UI -- Phase 5
+- ~~Images upload but don't display in UI -- Phase 5~~ FIXED in 05-01
 - Category emoji system being replaced with Lucide icons -- Phase 6

 ## Session Continuity

-Last session: 2026-03-15T16:02:32.447Z
-Stopped at: Phase 5 context gathered
-Resume file: .planning/phases/05-image-handling/05-CONTEXT.md
+Last session: 2026-03-15T16:12:39.861Z
+Stopped at: Completed 05-01-PLAN.md
+Resume file: None
--- a/.planning/phases/05-image-handling/05-01-SUMMARY.md
+++ b/.planning/phases/05-image-handling/05-01-SUMMARY.md
@@ -0,0 +1,95 @@
+---
+phase: 05-image-handling
+plan: 01
+subsystem: ui
+tags: [image-upload, hero-area, zod, tailwind, forms]
+
+# Dependency graph
+requires:
+  - phase: none
+    provides: existing ImageUpload, ItemForm, CandidateForm components
+provides:
+  - Working image persistence (Zod schema fix)
+  - Hero image preview area component
+  - Redesigned form layout with image-first UX
+affects: [06-category-icons]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [hero-image-area, inline-svg-icons]
+
+key-files:
+  created: []
+  modified:
+    - src/shared/schemas.ts
+    - src/client/components/ImageUpload.tsx
+    - src/client/components/ItemForm.tsx
+    - src/client/components/CandidateForm.tsx
+
+key-decisions:
+  - "Used inline SVGs instead of adding lucide-react dependency -- keeps bundle lean for 3 icons"
+  - "Root cause of image bug: Zod schemas missing imageFilename field, validator silently stripped it"
+
+patterns-established:
+  - "Hero image area: full-width 4:3 aspect ratio clickable area with placeholder/preview states"
+
+requirements-completed: [IMG-01, IMG-03, IMG-04]
+
+# Metrics
+duration: 3min
+completed: 2026-03-15
+---
+
+# Phase 5 Plan 1: Image Display Fix & Hero Area Summary
+
+**Fixed image persistence bug (Zod schema missing imageFilename) and redesigned ImageUpload as 4:3 hero area at top of item/candidate forms**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-03-15T16:08:51Z
+- **Completed:** 2026-03-15T16:11:27Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+- Identified and fixed root cause of image display bug: imageFilename was missing from Zod validation schemas, causing @hono/zod-validator to silently strip it from payloads
+- Redesigned ImageUpload into a full-width 4:3 hero image area with placeholder, preview, upload spinner, and remove states
+- Moved ImageUpload to first element in both ItemForm and CandidateForm, removing redundant labels
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Fix image display bug and investigate root cause** - `8c0529c` (fix)
+2. **Task 2: Redesign ImageUpload as hero area and move to top of forms** - `3243be4` (feat)
+
+## Files Created/Modified
+- `src/shared/schemas.ts` - Added imageFilename to createItemSchema and createCandidateSchema
+- `src/client/components/ImageUpload.tsx` - Redesigned as 4:3 hero area with placeholder/preview/spinner states
+- `src/client/components/ItemForm.tsx` - Moved ImageUpload to top, removed label wrapper
+- `src/client/components/CandidateForm.tsx` - Moved ImageUpload to top, removed label wrapper
+
+## Decisions Made
+- Used inline SVGs instead of adding lucide-react dependency -- only 3 icons needed, avoids bundle bloat
+- Root cause identified as Zod schema issue, not static file serving or Vite proxy (both were working correctly)
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Image display and upload flow fully functional
+- Hero area component ready for any future image-related enhancements in plan 05-02
+- Forms have clean image-first layout
+
+---
+*Phase: 05-image-handling*
+*Completed: 2026-03-15*