docs(05-01): complete image serving endpoint plan

Tasks completed: 3/3
- In-memory image store with explicit cleanup
- Image serving API endpoint
- uploadImageForUrl utility

SUMMARY: .planning/phases/05-image-url-server/05-01-SUMMARY.md

.planning/ROADMAP.md

@@ -73,7 +73,7 @@ Plans:
 **Plans**: TBD
 
 Plans:
-- [ ] 05-01: Image serving endpoint and URL generation
+- [x] 05-01: Image serving endpoint and URL generation
 - [ ] 05-02: Integration with generate node for URL-based providers
 
 ### Phase 6: Video & Polish
@@ -100,5 +100,5 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6
 | 2. Model Discovery | 3/3 | Complete | 2026-01-09 |
 | 3. Generate Node Refactor | 3/3 | Complete | 2026-01-09 |
 | 4. Model Search Dialog | 2/2 | Complete | 2026-01-09 |
-| 5. Image URL Server | 0/2 | Not started | - |
+| 5. Image URL Server | 1/2 | In progress | - |
 | 6. Video & Polish | 0/4 | Not started | - |

.planning/STATE.md

@@ -9,19 +9,19 @@ See: .planning/PROJECT.md (updated 2026-01-09)
 
 ## Current Position
 
-Phase: 4 of 6 (Model Search Dialog) - COMPLETE
+Phase: 5 of 6 (Image URL Server)
-Plan: 2 of 2 in current phase
+Plan: 1 of 2 in current phase
-Status: Phase complete
+Status: In progress
-Last activity: 2026-01-09 - Completed 04-02-PLAN.md (Model search dialog)
+Last activity: 2026-01-09 - Completed 05-01-PLAN.md (Image serving endpoint)
 
-Progress: [=================================================================] 67% (10/15 plans)
+Progress: [=====================================================================] 73% (11/15 plans)
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 10
+- Total plans completed: 11
-- Average duration: 5.6 min
+- Average duration: 5.4 min
-- Total execution time: 0.93 hours
+- Total execution time: 0.98 hours
 
 **By Phase:**
 
@@ -31,10 +31,11 @@ Progress: [=================================================================] 67
 | 2. Model Discovery | 3/3 | 14 min | 4.7 min |
 | 3. Generate Node Refactor | 3/3 | 13 min | 4.3 min |
 | 4. Model Search Dialog | 2/2 | 17 min | 8.5 min |
+| 5. Image URL Server | 1/2 | 3 min | 3 min |
 
 **Recent Trend:**
-- Last 5 plans: 5 min, 3 min, 2 min, 15 min
+- Last 5 plans: 3 min, 2 min, 15 min, 3 min
-- Trend: stable (04-02 included UAT refinements)
+- Trend: fast (05-01 was infrastructure only)
 
 ## Accumulated Context
 
@@ -67,6 +68,8 @@ Recent decisions affecting current work:
 - Client-side search filtering for Replicate (their search API unreliable)
 - Show all capability badges to differentiate similar models
 - Extract variant suffix from fal.ai model IDs for display name
+- No TTL for image store - explicit cleanup pattern (callers delete after use)
+- 256KB threshold for shouldUseImageUrl (Replicate recommendation)
 
 ### Deferred Issues
 
@@ -79,6 +82,6 @@ Recent decisions affecting current work:
 ## Session Continuity
 
 Last session: 2026-01-09
-Stopped at: Completed Phase 4 (Model Search Dialog)
+Stopped at: Completed 05-01-PLAN.md (Image serving endpoint)
 Resume file: None
-Next action: Plan Phase 5 (Image URL Server)
+Next action: Execute 05-02-PLAN.md (Integration with generate node)

.planning/phases/05-image-url-server/05-01-SUMMARY.md

@@ -0,0 +1,117 @@
+---
+phase: 05-image-url-server
+plan: 01
+subsystem: api
+tags: [next.js, api-routes, image-serving, in-memory-cache]
+
+# Dependency graph
+requires:
+  - phase: 03-02
+    provides: Server-side provider execution pattern
+  - phase: 02-03
+    provides: TTL-based caching pattern (adapted to no-TTL for explicit cleanup)
+provides:
+  - In-memory image store with explicit cleanup
+  - Image serving API endpoint (/api/images/[id])
+  - uploadImageForUrl utility returning URL + ID for cleanup
+  - shouldUseImageUrl threshold detection (256KB)
+affects: [05-02, generate-node, provider-execution]
+
+# Tech tracking
+tech-stack:
+  added: [crypto.randomUUID]
+  patterns: [explicit-cleanup-vs-ttl, request-scoped-resources]
+
+key-files:
+  created:
+    - src/lib/images/store.ts
+    - src/lib/images/index.ts
+    - src/app/api/images/[id]/route.ts
+  modified: []
+
+key-decisions:
+  - "No TTL for image store - callers responsible for cleanup after provider fetches"
+  - "Return both URL and ID from uploadImageForUrl to enable cleanup"
+  - "256KB threshold matches Replicate recommendation for URL vs base64"
+
+patterns-established:
+  - "Explicit cleanup pattern: store returns ID, caller deletes after use"
+
+issues-created: []
+
+# Metrics
+duration: 3min
+completed: 2026-01-09
+---
+
+# Phase 5 Plan 01: Image Serving Endpoint Summary
+
+**In-memory image store with explicit cleanup, serving endpoint at /api/images/[id], and uploadImageForUrl utility returning URL+ID**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-01-09T09:41:34Z
+- **Completed:** 2026-01-09T09:44:59Z
+- **Tasks:** 3
+- **Files modified:** 3
+
+## Accomplishments
+
+- In-memory Map-based image store with storeImage/getImage/deleteImage/deleteImages
+- API endpoint serving stored images with correct Content-Type and Cache-Control: no-store
+- uploadImageForUrl utility returning { url, id } for cleanup after use
+- shouldUseImageUrl threshold check for 256KB (Replicate's recommendation)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create in-memory image store** - `5cbff58` (feat)
+2. **Task 2: Create image serving API endpoint** - `9e85f0b` (feat)
+3. **Task 3: Create uploadImageForUrl utility** - `49ad058` (feat)
+
+**Plan metadata:** `5ebea8d` (docs: complete plan)
+
+## Files Created/Modified
+
+- `src/lib/images/store.ts` - Map-based store with storeImage, getImage, deleteImage, deleteImages
+- `src/app/api/images/[id]/route.ts` - GET endpoint serving stored images with proper headers
+- `src/lib/images/index.ts` - uploadImageForUrl and shouldUseImageUrl utilities, re-exports store
+
+## Decisions Made
+
+- No TTL for image store - using explicit cleanup pattern instead (callers delete after provider fetches)
+- Return both URL and ID from uploadImageForUrl to enable cleanup
+- 256KB threshold for shouldUseImageUrl matches Replicate's documented recommendation
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Buffer to Uint8Array conversion in API route**
+- **Found during:** Task 2 (API endpoint implementation)
+- **Issue:** NextResponse doesn't directly accept Buffer, needed Uint8Array
+- **Fix:** Convert Buffer to Uint8Array in response
+- **Files modified:** src/app/api/images/[id]/route.ts
+- **Verification:** Build succeeds, TypeScript compiles
+- **Committed in:** 9e85f0b (Task 2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (blocking), 0 deferred
+**Impact on plan:** Minor implementation detail, no scope change
+
+## Issues Encountered
+
+None
+
+## Next Phase Readiness
+
+- Image serving infrastructure complete and ready for integration
+- Next plan (05-02) will integrate with generate node for URL-based providers
+- No blockers
+
+---
+*Phase: 05-image-url-server*
+*Completed: 2026-01-09*