diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index 4d760e00..0155af24 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -364,7 +364,7 @@ Plans: - Replace current quickstart template selection Plans: -- [ ] 25-01: Template types, TemplateCard component, TemplateExplorerView grid layout +- [x] 25-01: Template types, TemplateCard component, TemplateExplorerView grid layout - [ ] 25-02: Sidebar filters (search, category, tags), WelcomeModal integration #### Phase 26: Template Preview Rendering @@ -455,7 +455,7 @@ Phases execute in numeric order: 1 → 2 → ... → 24 → 25 → 26 → 27 → | 22. Generate Node Dynamic Input Tests | v1.2 | 1/1 | Complete | 2026-01-13 | | 23. Model Browser Improvements | v1.2 | 1/1 | Complete | 2026-01-13 | | 24. Improved Cost Summary | v1.2 | 1/3 | In progress | - | -| 25. Template Explorer UI | v1.3 | 0/2 | Not started | - | +| 25. Template Explorer UI | v1.3 | 1/2 | In progress | - | | 26. Template Preview Rendering | v1.3 | 0/? | Not started | - | | 27. Node Defaults Infrastructure | v1.3 | 0/? | Not started | - | | 28. Node Defaults UI | v1.3 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 00000000..d0941f15 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,155 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-01-09) + +**Core value:** Provider infrastructure that dynamically discovers models from external APIs, enabling users to access hundreds of image/video generation models without hardcoding schemas. +**Current focus:** Testing and modularization (v1.2) + +## Current Position + +Phase: 25 of 29 (Template Explorer UI) +Plan: 1 of 2 in current phase +Status: In progress +Last activity: 2026-01-16 - Completed 25-01-PLAN.md + +Progress: █████████░ 90% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 26 +- Average duration: 7 min +- Total execution time: 3.1 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| 1. Provider Infrastructure | 2/2 | 14 min | 7 min | +| 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 | 2/2 | 5 min | 2.5 min | +| 6. Video & Polish | 4/4 | 43 min | 14.3 min | +| 7. Video Connections | 1/1 | 4 min | 4 min | +| 8. Error Display | 1/1 | 14 min | 14 min | +| 9. Video History | 1/1 | 12 min | 12 min | +| 10. Node Autosizing | 1/1 | 2 min | 2 min | +| 11. UI Polish | 1/1 | 8 min | 8 min | +| 12. Model Improvements | 1/1 | - | - | +| 13. Fix Duplicate Generations | 1/1 | 1 min | 1 min | +| 14. Fix Drag-Connect Bugs | 1/1 | 7 min | 7 min | +| 15. Test Infrastructure | 1/1 | 3 min | 3 min | +| 16. Store Modularization | 1/1 | 22 min | 22 min | +| 19. Type Refactoring | 2/2 | 16 min | 8 min | +| 22. Generate Node Dynamic Input Tests | 1/1 | 20 min | 20 min | +| 23. Model Browser Improvements | 1/1 | 5 min | 5 min | +| 20. Integration Tests | 2/2 | 11 min | 5.5 min | +| 24. Improved Cost Summary | 1/3 | 2 min | 2 min | +| 25. Template Explorer UI | 1/2 | 8 min | 8 min | + +**Recent Trend:** +- Last 5 plans: 2 min, 5 min, 9 min, 2 min, 8 min +- Trend: UI component phases take moderate time + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- Gemini always enabled via env var (GEMINI_API_KEY), Replicate/fal.ai optional +- API keys stored in localStorage under node-banana-provider-settings key +- Local state in modal to avoid saving on every keystroke +- Provider config pattern: {id, name, enabled, apiKey, apiKeyEnvVar?} +- Provider registry uses self-registration pattern via registerProvider() +- Gemini remains special-cased in /api/generate for now, not yet migrated +- Capability inference from model name/description keywords +- fal.ai API key optional (works without but rate limited) +- fal.ai auth header: "Key {apiKey}" format (not Bearer) +- fal.ai category maps directly to ModelCapability (no inference) +- 1-hour cache TTL for model lists (extended from 10 min) +- Unified API at /api/models with header-based auth +- Provider dropdown shows Gemini always, others only if API key configured +- Aspect ratio/resolution controls shown only for Gemini provider +- Backward compatibility via aliases: NanoBananaNode, saveNanoBananaDefaults +- Server-side provider execution in API route (not client-side) +- Header-based API key passing: X-Replicate-API-Key, X-Fal-API-Key +- fal.ai sync API (fal.run) instead of queue-based async +- Dual migration approach: loadWorkflow migrates + UI effect for runtime +- fal.ai icon always visible in action bar (works without key but rate limited) +- Replicate icon only visible when API key is configured +- 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) +- Gemini excluded from video node (doesn't support video generation) +- Large videos (>20MB) return URL instead of base64 to avoid memory issues +- Fetch schema from provider API at model selection time with 10-min cache +- Filter internal params, prioritize user-relevant ones (seed, steps, guidance) +- Collapsible parameters section to keep node UI compact +- Node autosizing constraints: 200-500px width, 200-600px height, ~100px chrome +- Provider badges prepend node title (left side) with w-4 h-4 icons +- Node titles show only model name (no "Generate Image/Video" prefix) +- BaseNode supports titlePrefix prop for icon prepending +- Header aligned for saved/unsaved states with same icon layout +- isImageInput() uses word-boundary checks (not substring) to avoid matching num_images +- Workflow execution gets fresh node data from store (not stale captured array) +- regenerateNode includes parameters in request body +- MD5 content hashing for generation deduplication (fast, collision resistance not critical) +- Hash prefix in filename for O(1) duplicate lookup +- Normalized handle IDs (image, text, image-0) for connection stability across model changes +- Handle-to-schema mapping built at execution time from inputSchema +- Placeholder handles (dimmed 30%) for input types not used by model, preserving connections +- ReactFlowProvider wrapper for component tests using @xyflow/react hooks +- Zustand store mocking with vi.mock pattern returning mocked functions +- Vitest jsdom environment for React component tests +- Store utilities extracted to src/store/utils/ with re-exports for backward compatibility +- Consolidated defaultNodeDimensions (was duplicated in addNode and createGroup) +- localStorage mocking pattern for testing utility modules +- Type domain files live in src/types/*.ts with re-exports from index.ts +- BaseNodeData in annotation.ts to avoid circular imports (nodes.ts imports annotation.ts) +- 7 type domain files: annotation, nodes, providers, models, workflow, api, quickstart +- index.ts is pure re-export hub with no type definitions +- Max 8 recent models stored in localStorage, 4 displayed in UI +- Gemini models hardcoded in /api/models (not fetched from external API) +- Green color theme for Gemini provider (bg-green-500/20 text-green-300) +- Cost dialog: two-section layout (Known Costs vs Pricing Unavailable) grouping by provider +- fal.ai pricing via API, Replicate excluded from cost tracking (no API available) +- Incurred cost only tracks providers with known pricing (Gemini, fal.ai) +- Template category colors: blue=product, purple=style, green=composition, amber=community +- Template grid layout: 2 cols mobile, 3 cols lg+ +- Template node count calculated at runtime from workflow.nodes.length + +### Deferred Issues + +- UAT-001: Resolved - Provider icons now use real Replicate/fal.ai logos +- ISS-001: Resolved - Generate nodes now adapt to model requirements via dynamic parameters + +### Blockers/Concerns + +- Pre-existing lint configuration issue (ESLint not configured). Not blocking development. + +### Roadmap Evolution + +- v1.0 Multi-Provider Support shipped: 6 phases (Phase 1-6), 15 plans +- Milestone v1.1 Improvements created: 6 phases (Phase 7-12), improvements and polish +- Phase 13 added: Fix duplicate generations (hashing failure investigation) +- Phase 14 added: Fix drag-connect node creation bugs (consolidated from two phases) +- Milestone v1.2 Improvements created: 6 phases (Phase 15-20), testing and modularization +- Phase 21 added: Fix Gemini Pro image input handling and image deduplication issues +- Phase 22 added: Generate node dynamic input validation and API call tests +- Phase 23 added: Model browser improvements (recently used, icon dropdown, Gemini models in list) +- Phase 24 added: Improved cost summary (fal.ai pricing API, video node tracking, multi-provider support) +- Milestone v1.3 Improvements created: 5 phases (Phase 25-29), template explorer, node defaults, canvas performance + +## Session Continuity + +Last session: 2026-01-16 +Stopped at: Completed 25-01-PLAN.md (template explorer UI components) +Resume file: None +Next action: Execute 25-02-PLAN.md (sidebar filters and WelcomeModal integration) diff --git a/.planning/phases/25-template-explorer-ui/25-01-SUMMARY.md b/.planning/phases/25-template-explorer-ui/25-01-SUMMARY.md new file mode 100644 index 00000000..c86a9e25 --- /dev/null +++ b/.planning/phases/25-template-explorer-ui/25-01-SUMMARY.md @@ -0,0 +1,119 @@ +--- +phase: 25-template-explorer-ui +plan: 01 +subsystem: ui +tags: [templates, quickstart, react, tailwind] + +# Dependency graph +requires: + - phase: 24-improved-cost-summary + provides: Cost tracking infrastructure +provides: + - TemplateMetadata interface for template categorization + - TemplateCard component for card-based template display + - TemplateExplorerView component with grid layout +affects: [template-preview, welcome-modal] + +# Tech tracking +tech-stack: + added: [] + patterns: + - Card-based template layout with metadata badges + - Category color coding for visual differentiation + +key-files: + created: + - src/components/quickstart/TemplateCard.tsx + - src/components/quickstart/TemplateExplorerView.tsx + modified: + - src/types/quickstart.ts + - src/lib/quickstart/templates.ts + +key-decisions: + - "Category color scheme: blue=product, purple=style, green=composition, amber=community" + - "Grid layout 2 cols on mobile, 3 cols on larger screens" + - "Node count calculated from workflow.nodes.length at runtime" + +patterns-established: + - "TemplateMetadata pattern for template categorization" + - "Card component with category badges and tag pills" + +issues-created: [] + +# Metrics +duration: 8min +completed: 2026-01-16 +--- + +# Phase 25 Plan 01: Template Explorer UI Components Summary + +**Template card and grid layout components with category/tag metadata for scalable template browsing** + +## Performance + +- **Duration:** 8 min +- **Started:** 2026-01-16T18:30:00Z +- **Completed:** 2026-01-16T18:38:00Z +- **Tasks:** 3 +- **Files modified:** 4 + +## Accomplishments + +- Extended template types with TemplateMetadata interface (nodeCount, category, tags) +- Created TemplateCard component with card layout, metadata badges, and tag pills +- Created TemplateExplorerView with responsive grid layout for preset and community templates + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Extend template types with rich metadata** - `94e1716` (feat) +2. **Task 2: Create TemplateCard component** - `2b96054` (feat) +3. **Task 3: Create TemplateExplorerView with grid layout** - `09457d5` (feat) + +**Note:** Also fixed pre-existing blocking issue from Phase 24-01 - `18c3bf2` (fix: costCalculator type migration) + +## Files Created/Modified + +- `src/types/quickstart.ts` - Added TemplateCategory type and TemplateMetadata interface +- `src/lib/quickstart/templates.ts` - Added category/tags to PresetTemplate, getTemplateMetadata() +- `src/components/quickstart/TemplateCard.tsx` - New card component with metadata display +- `src/components/quickstart/TemplateExplorerView.tsx` - New grid layout with template fetching + +## Decisions Made + +- Category color scheme: blue for product, purple for style, green for composition, amber for community +- Grid layout: 2 columns on mobile, 3 columns on lg+ screens +- Node count calculated dynamically from workflow.nodes.length +- Tags limited to 4 displayed per card for visual consistency + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] Fixed costCalculator multi-provider type migration** +- **Found during:** Build verification +- **Issue:** Phase 24-01 incomplete - calculatePredictedCost returned old format, PredictedCostResult expected CostBreakdownItem[] +- **Fix:** Updated calculatePredictedCost to produce CostBreakdownItem format with provider, modelId, modelName fields +- **Files modified:** src/utils/costCalculator.ts +- **Verification:** npm run build passes +- **Committed in:** 18c3bf2 + +--- + +**Total deviations:** 1 auto-fixed (blocking issue from prior phase), 0 deferred +**Impact on plan:** Fix was necessary to unblock build. No scope creep. + +## Issues Encountered + +None - plan executed smoothly after blocking issue resolved. + +## Next Phase Readiness + +- Template card and grid layout components ready +- Ready for Plan 02 to add sidebar filters (search, category, tags) and WelcomeModal integration +- TemplateExplorerView can replace QuickstartTemplatesView once integrated + +--- +*Phase: 25-template-explorer-ui* +*Completed: 2026-01-16*