Browse Source
Phase 25: Template Explorer UI - 2 plans created - 5 total tasks defined - Ready for execution Plan 01: Template types, TemplateCard, grid layout (3 tasks) Plan 02: Sidebar filters, WelcomeModal integration (2 tasks + checkpoint) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>handoff-20260429-1057
shrimbly
6 months ago
3 changed files with 767 additions and 0 deletions
@ -0,0 +1,462 @@ |
|||||
|
# Roadmap: Node Banana Multi-Provider Support |
||||
|
|
||||
|
## Overview |
||||
|
|
||||
|
Transform Node Banana from a Gemini-only image generator into a multi-provider platform supporting Replicate and fal.ai. The journey builds provider infrastructure first, then adds dynamic model discovery, refactors the generate node for flexibility, creates a searchable model browser, adds local image serving for URL-based providers, and finishes with video support and polish. |
||||
|
|
||||
|
## Domain Expertise |
||||
|
|
||||
|
None |
||||
|
|
||||
|
## Milestones |
||||
|
|
||||
|
- ✅ **v1.0 Multi-Provider Support** - Phases 1-6 (shipped 2026-01-11) |
||||
|
- ✅ **v1.1 Improvements** - Phases 7-14 (shipped 2026-01-12) |
||||
|
- 🚧 **v1.2 Improvements** - Phases 15-24 (in progress) |
||||
|
- 📋 **v1.3 Improvements** - Phases 25-29 (planned) |
||||
|
|
||||
|
## Phases |
||||
|
|
||||
|
**Phase Numbering:** |
||||
|
- Integer phases (1, 2, 3): Planned milestone work |
||||
|
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) |
||||
|
|
||||
|
<details> |
||||
|
<summary>✅ v1.0 Multi-Provider Support (Phases 1-6) - SHIPPED 2026-01-11</summary> |
||||
|
|
||||
|
### Phase 1: Provider Infrastructure |
||||
|
**Goal**: Users can configure Replicate and fal.ai API keys in settings, with keys securely stored |
||||
|
**Depends on**: Nothing (first phase) |
||||
|
**Research**: Unlikely (internal UI patterns, Zustand state management) |
||||
|
**Plans**: 2 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 01-01: Provider settings UI in ProjectSetupModal |
||||
|
- [x] 01-02: Provider abstraction layer and types |
||||
|
|
||||
|
### Phase 2: Model Discovery |
||||
|
**Goal**: App can fetch and cache available models from enabled providers at runtime |
||||
|
**Depends on**: Phase 1 |
||||
|
**Research**: Likely (external APIs) |
||||
|
**Research topics**: Replicate model listing API endpoints, fal.ai model discovery endpoints, response schemas and pagination |
||||
|
**Plans**: 3 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 02-01: Replicate model fetching API route |
||||
|
- [x] 02-02: fal.ai model fetching API route |
||||
|
- [x] 02-03: Model caching and unified model interface |
||||
|
|
||||
|
### Phase 3: Generate Node Refactor |
||||
|
**Goal**: NanoBanana node becomes GenerateImage node supporting any provider's image models |
||||
|
**Depends on**: Phase 2 |
||||
|
**Research**: Unlikely (internal refactoring using existing patterns) |
||||
|
**Design decision**: Separate nodes for image vs video generation (GenerateVideo added in Phase 6) |
||||
|
**Plans**: 3 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 03-01: Rename NanoBanana to GenerateImage, add model selector (image models only) |
||||
|
- [x] 03-02: Provider-specific execution in generate API route |
||||
|
- [x] 03-03: Backward compatibility for existing workflows |
||||
|
|
||||
|
### Phase 4: Model Search Dialog |
||||
|
**Goal**: Users can browse models via floating action bar icons and searchable dialog |
||||
|
**Depends on**: Phase 3 |
||||
|
**Research**: Unlikely (internal UI using React patterns) |
||||
|
**Plans**: 2 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 04-01: Floating action bar with provider icons |
||||
|
- [x] 04-02: Model search dialog with filtering and selection |
||||
|
|
||||
|
### Phase 5: Image URL Server |
||||
|
**Goal**: Local API endpoint serves workflow images as URLs for providers requiring URL inputs |
||||
|
**Depends on**: Phase 3 |
||||
|
**Research**: Unlikely (Next.js API routes, existing patterns) |
||||
|
**Plans**: 2 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 05-01: Image serving endpoint and URL generation |
||||
|
- [x] 05-02: Integration with generate node for URL-based providers |
||||
|
|
||||
|
### Phase 6: Video & Polish |
||||
|
**Goal**: GenerateVideo node for video generation, video playback, custom parameters, edge cases |
||||
|
**Depends on**: Phase 5 |
||||
|
**Research**: Likely (video handling) |
||||
|
**Research topics**: HTML5 video element for base64/blob URLs, provider response formats for video content |
||||
|
**Design decision**: GenerateVideo as separate node type (not combined with GenerateImage) |
||||
|
**Plans**: 4 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 06-01: GenerateVideo node with video-capable model selector |
||||
|
- [x] 06-02: Video playback in output node |
||||
|
- [x] 06-03: Custom model parameters from provider schemas |
||||
|
- [x] 06-04: Edge case handling and final polish |
||||
|
|
||||
|
</details> |
||||
|
|
||||
|
<details> |
||||
|
<summary>✅ v1.1 Improvements (Phases 7-14) - SHIPPED 2026-01-12</summary> |
||||
|
|
||||
|
**Milestone Goal:** Fix connection issues, improve error visibility, add video history, auto-size nodes, and polish UI |
||||
|
|
||||
|
#### Phase 7: Video Connections ✅ |
||||
|
|
||||
|
**Goal**: Fix video handle connections to only allow valid targets (generateVideo, output) |
||||
|
**Depends on**: Phase 6 |
||||
|
**Research**: Unlikely (internal connection validation patterns) |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 07-01: Add video handle type and connection validation |
||||
|
|
||||
|
#### Phase 8: Error Display ✅ |
||||
|
|
||||
|
**Goal**: Better error visibility with overlay display, not hidden by previous output |
||||
|
**Depends on**: Phase 7 |
||||
|
**Research**: Unlikely (internal UI patterns) |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 08-01: Error notifications with persistent toast and node overlays |
||||
|
|
||||
|
#### Phase 9: Video History ✅ |
||||
|
|
||||
|
**Goal**: Add history carousel for generated videos matching image history pattern |
||||
|
**Depends on**: Phase 8 |
||||
|
**Research**: Unlikely (existing image history pattern) |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 09-01: Video history types, store support, load API, and carousel UI |
||||
|
|
||||
|
#### Phase 10: Node Autosizing ✅ |
||||
|
|
||||
|
**Goal**: Auto-size nodes to output dimensions and aspect ratio |
||||
|
**Depends on**: Phase 9 |
||||
|
**Research**: Unlikely (React Flow node sizing) |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 10-01: Node dimension utility and auto-resize on output |
||||
|
|
||||
|
#### Phase 11: UI Polish ✅ |
||||
|
|
||||
|
**Goal**: Flora UI alignment, header UI improvements, project settings, provider logos on nodes |
||||
|
**Depends on**: Phase 10 |
||||
|
**Research**: Unlikely (internal UI work) |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 11-01: Provider badges on nodes and header UI streamlining |
||||
|
|
||||
|
#### Phase 12: Model Improvements ✅ |
||||
|
|
||||
|
**Goal**: Verify Replicate image models work, extend model cache TTL |
||||
|
**Depends on**: Phase 11 |
||||
|
**Research**: Likely (Replicate API behavior verification) |
||||
|
**Research topics**: Replicate image model endpoints, cache invalidation strategies |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 12-01: Extended cache TTL, fixed isImageInput, fixed stale node data in execution |
||||
|
|
||||
|
#### Phase 13: Fix Duplicate Generations ✅ |
||||
|
|
||||
|
**Goal**: Fix image deduplication - generations folder has duplicate images due to hashing failure |
||||
|
**Depends on**: Phase 12 |
||||
|
**Research**: Likely (investigate current hashing implementation) |
||||
|
**Research topics**: Current save-generation hashing logic, why duplicates are being created |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 13-01: Add MD5 content hashing and deduplication to save-generation API |
||||
|
|
||||
|
#### Phase 14: Fix Drag-Connect Node Creation Bugs ✅ |
||||
|
|
||||
|
**Goal**: Fix bugs with nodes created via drag-connect: (1) connection vanishes after selecting model from browser, (2) defaults to Gemini with missing model selector in header |
||||
|
**Depends on**: Phase 13 |
||||
|
**Research**: Unlikely (React Flow connection state, node creation flow) |
||||
|
**Research topics**: Connection state during node creation, model selection callbacks, createDefaultNodeData initialization |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 14-01: Normalize dynamic handle IDs and fix connection persistence |
||||
|
|
||||
|
</details> |
||||
|
|
||||
|
### 🚧 v1.2 Improvements (In Progress) |
||||
|
|
||||
|
**Milestone Goal:** Add automated testing across the application, modularize large monolithic files for better maintainability, and improve cost tracking for multi-provider support |
||||
|
|
||||
|
#### Phase 15: Test Infrastructure |
||||
|
|
||||
|
**Goal**: Set up testing framework with Vitest and React Testing Library for Next.js 16 |
||||
|
**Depends on**: Phase 14 |
||||
|
**Research**: Likely (Vitest + Next.js 16 App Router setup) |
||||
|
**Research topics**: Vitest configuration for Next.js 16, React Testing Library setup, test file organization |
||||
|
**Plans**: TBD |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 15-01: React Testing Library setup and configuration |
||||
|
|
||||
|
#### Phase 16: Store Modularization ✅ |
||||
|
|
||||
|
**Goal**: Break up workflowStore.ts into focused modules (execution, nodes, edges, persistence) |
||||
|
**Depends on**: Phase 15 |
||||
|
**Research**: Unlikely (internal Zustand patterns) |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 16-01: Extract localStorage helpers and node defaults to utility modules |
||||
|
|
||||
|
#### Phase 17: Component Tests |
||||
|
|
||||
|
**Goal**: Add tests for all 34 React components covering nodes, toolbars, modals, and edges |
||||
|
**Depends on**: Phase 16 |
||||
|
**Research**: Unlikely (established React Testing Library patterns) |
||||
|
**Plans**: 11 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 17-01: Core Nodes (BaseNode, PromptNode, ImageInputNode) |
||||
|
- [x] 17-02: Display Nodes (OutputNode, SplitGridNode, GroupNode) |
||||
|
- [x] 17-03: Generate Nodes (GenerateImageNode, GenerateVideoNode) |
||||
|
- [x] 17-04: Processing Nodes (LLMGenerateNode, AnnotationNode) |
||||
|
- [x] 17-05: Toolbars (Header, FloatingActionBar, MultiSelectToolbar) |
||||
|
- [x] 17-06: Canvas & Edges (WorkflowCanvas, EditableEdge, ReferenceEdge, EdgeToolbar) |
||||
|
- [x] 17-07: Menus & Notifications (ConnectionDropMenu, Toast, CostIndicator) |
||||
|
- [x] 17-08: Core Modals (ModelSearchDialog, ProjectSetupModal, CostDialog) |
||||
|
- [x] 17-09: Editor Modals (PromptEditorModal, SplitGridSettingsModal, AnnotationModal) |
||||
|
- [x] 17-10: Quickstart (WelcomeModal, QuickstartInitialView, QuickstartTemplatesView, PromptWorkflowView, QuickstartBackButton) |
||||
|
- [x] 17-11: Utilities (GlobalImageHistory, GroupsOverlay, ModelParameters) |
||||
|
|
||||
|
#### Phase 18: API Route Tests |
||||
|
|
||||
|
**Goal**: Add tests for generate, llm, models, and workflow API routes |
||||
|
**Depends on**: Phase 17 |
||||
|
**Research**: Unlikely (Next.js API route testing patterns) |
||||
|
**Plans**: 5 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 18-01: File I/O routes (workflow, save-generation) |
||||
|
- [x] 18-02: LLM route (Google, OpenAI providers) |
||||
|
- [x] 18-03: Generate route (Gemini provider) |
||||
|
- [x] 18-04: Generate route (Replicate, fal.ai providers) |
||||
|
- [x] 18-05: Models route (caching, aggregation) |
||||
|
|
||||
|
#### Phase 19: Type Refactoring |
||||
|
|
||||
|
**Goal**: Split types/index.ts into domain-specific type files (nodes, providers, workflow) |
||||
|
**Depends on**: Phase 18 |
||||
|
**Research**: Unlikely (internal refactoring) |
||||
|
**Plans**: 2 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 19-01: Extract node and annotation types |
||||
|
- [x] 19-02: Extract provider, workflow, API, and model types |
||||
|
|
||||
|
#### Phase 20: Integration Tests |
||||
|
|
||||
|
**Goal**: End-to-end workflow execution tests covering node connections and data flow |
||||
|
**Depends on**: Phase 19 |
||||
|
**Research**: Unlikely (internal testing patterns) |
||||
|
**Plans**: 2 plans |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 20-01: Store integration tests (getConnectedInputs, validateWorkflow, topological sort) |
||||
|
- [x] 20-02: Workflow execution tests (data flow, error handling, connection validation) |
||||
|
|
||||
|
#### Phase 21: Fix Image Input & Deduplication Issues |
||||
|
|
||||
|
**Goal**: Fix Gemini nano-banana-pro model ignoring image inputs and resolve duplicate image saving across input/generated images |
||||
|
**Depends on**: Phase 20 |
||||
|
**Research**: Likely (Gemini API image input handling, current hashing implementation) |
||||
|
**Research topics**: Gemini 3 Pro image generation API requirements, why image inputs are ignored, current save logic for inputs vs generations |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
**Issues:** |
||||
|
1. ~~nano-banana-pro model generates without considering image inputs~~ - RESOLVED (no longer an issue) |
||||
|
2. Input and generated images have duplicate files despite different hashes - need consistent hashing approach matching video saving |
||||
|
3. Generated images should be prepended with prompt details like generated videos |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 21-01: Unify MD5 hashing for image deduplication |
||||
|
|
||||
|
#### Phase 22: Generate Node Dynamic Input Tests |
||||
|
|
||||
|
**Goal**: Test that generate nodes properly validate and render dynamic inputs from provider schemas, and that all inputs/parameters are correctly included in API calls |
||||
|
**Depends on**: Phase 21 |
||||
|
**Research**: Unlikely (existing test patterns from Phase 17) |
||||
|
**Plans**: 1 plan |
||||
|
|
||||
|
**Test coverage:** |
||||
|
1. Dynamic inputs from provider schemas render correctly as parameters and input handles on node creation |
||||
|
2. Validation of dynamic inputs (required fields, type checking, constraints) |
||||
|
3. Standard inputs (image, text) validate properly |
||||
|
4. On submission, all parameters and inputs are included in API call payload correctly (covered by Phase 18) |
||||
|
5. Coverage across all providers (Gemini, Replicate, fal.ai) |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 22-01: ModelParameters tests, GenerateImageNode/GenerateVideoNode dynamic handle tests |
||||
|
|
||||
|
#### Phase 23: Model Browser Improvements |
||||
|
|
||||
|
**Goal**: Improve model browser UX with recently used models section, icon-based provider dropdown with Gemini, and include Gemini models in browse list |
||||
|
**Depends on**: Phase 22 |
||||
|
**Research**: Unlikely (existing UI patterns) |
||||
|
**Plans**: TBD |
||||
|
|
||||
|
**Features:** |
||||
|
1. Recently used models section at top of browse dialog showing last 4 models used |
||||
|
2. Provider dropdown uses icons instead of text, add Gemini to the provider list |
||||
|
3. Include Gemini models (nano-banana, nano-banana-pro) in the browsable model list alongside Replicate/fal.ai models |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 23-01: Recently used models, icon-based provider filter, Gemini models in browse |
||||
|
|
||||
|
#### Phase 24: Improved Cost Summary |
||||
|
|
||||
|
**Goal**: Expand cost tracking to include fal.ai models (via their pricing API), video generation nodes, and graceful handling for Replicate (no pricing API available) |
||||
|
**Depends on**: Phase 23 |
||||
|
**Research**: Complete (see research notes below) |
||||
|
**Plans**: 3 plans |
||||
|
|
||||
|
**Research Notes:** |
||||
|
- fal.ai has a pricing API: `GET /v1/models/pricing?endpoint_id=model1,model2` returns `{ prices: [{ endpoint_id, unit_price, unit, currency }] }` |
||||
|
- Replicate does NOT expose pricing via API (open GitHub issue, unresolved). Prediction response has `metrics.predict_time` but no hardware/cost info. |
||||
|
- `ProviderModel` type already has `pricing?: { type, amount, currency }` field at `src/lib/providers/types.ts:69-74` |
||||
|
|
||||
|
**UX Decision: Provider-Grouped with Uncertainty Section** |
||||
|
- Two sections: "Known Costs" (Gemini + fal.ai) and "Pricing Unavailable" (Replicate) |
||||
|
- Known costs show total at section header, breakdown by provider with icons |
||||
|
- fal.ai items show billing unit from API (e.g., "per image", "per 5s video") |
||||
|
- Replicate section includes help text: "Pricing varies by hardware and runtime. Check replicate.com" |
||||
|
- Incurred cost only tracks Gemini & fal.ai (Replicate excluded with note) |
||||
|
- Empty provider sections hidden |
||||
|
|
||||
|
**Features:** |
||||
|
1. Fetch fal.ai model pricing via their pricing API and populate `ProviderModel.pricing` |
||||
|
2. Track generateVideo nodes in cost predictions (currently ignored) |
||||
|
3. For Replicate models: display "pricing unavailable" gracefully in dedicated section |
||||
|
4. Update CostDialog with two-section layout: Known Costs (Gemini, fal.ai) and Pricing Unavailable (Replicate) |
||||
|
5. Show billing units for fal.ai models (per image, per second of video, etc.) |
||||
|
6. Incurred cost excludes Replicate with explanatory note |
||||
|
|
||||
|
Plans: |
||||
|
- [x] 24-01: fal.ai pricing API integration and ProviderModel.pricing population |
||||
|
- [ ] 24-02: Expand costCalculator to handle video nodes and external providers |
||||
|
- [ ] 24-03: Update CostDialog UI for multi-provider breakdown |
||||
|
|
||||
|
### 📋 v1.3 Improvements (Planned) |
||||
|
|
||||
|
**Milestone Goal:** Add rich template exploration with search/filters, node default preferences in settings, and canvas performance optimizations |
||||
|
|
||||
|
#### Phase 25: Template Explorer UI |
||||
|
|
||||
|
**Goal**: Full template exploration interface with cards layout, left-hand filter/search panel, supporting many templates |
||||
|
**Depends on**: Phase 24 |
||||
|
**Research**: Unlikely (internal UI patterns) |
||||
|
**Plans**: 2 plans |
||||
|
|
||||
|
**Features:** |
||||
|
- Cards layout for template browsing (scalable for many templates) |
||||
|
- Left-hand panel with search and category filters |
||||
|
- Template metadata display (name, description, node count, etc.) |
||||
|
- Replace current quickstart template selection |
||||
|
|
||||
|
Plans: |
||||
|
- [ ] 25-01: Template types, TemplateCard component, TemplateExplorerView grid layout |
||||
|
- [ ] 25-02: Sidebar filters (search, category, tags), WelcomeModal integration |
||||
|
|
||||
|
#### Phase 26: Template Preview Rendering |
||||
|
|
||||
|
**Goal**: Visual preview of workflow templates showing node layout and connections before loading |
||||
|
**Depends on**: Phase 25 |
||||
|
**Research**: Unlikely (React Flow rendering, existing patterns) |
||||
|
**Plans**: TBD |
||||
|
|
||||
|
**Features:** |
||||
|
- Miniature workflow visualization in preview panel |
||||
|
- Show nodes, connections, and overall structure |
||||
|
- Non-interactive preview (view only) |
||||
|
|
||||
|
Plans: |
||||
|
- [ ] 26-01: TBD (run /gsd:plan-phase 26 to break down) |
||||
|
|
||||
|
#### Phase 27: Node Defaults Infrastructure |
||||
|
|
||||
|
**Goal**: Store default model and settings preferences per node type in localStorage |
||||
|
**Depends on**: Phase 26 |
||||
|
**Research**: Unlikely (localStorage, existing patterns) |
||||
|
**Plans**: TBD |
||||
|
|
||||
|
**Features:** |
||||
|
- Schema for node type defaults (model, parameters, settings) |
||||
|
- Apply defaults when creating nodes via keyboard shortcuts (Shift+G, etc.) |
||||
|
- Per-provider model defaults (e.g., default fal.ai model for GenerateImage) |
||||
|
|
||||
|
Plans: |
||||
|
- [ ] 27-01: TBD (run /gsd:plan-phase 27 to break down) |
||||
|
|
||||
|
#### Phase 28: Node Defaults UI |
||||
|
|
||||
|
**Goal**: Settings panel for configuring default node preferences per node type |
||||
|
**Depends on**: Phase 27 |
||||
|
**Research**: Unlikely (internal UI patterns) |
||||
|
**Plans**: TBD |
||||
|
|
||||
|
**Features:** |
||||
|
- Section in settings for node defaults |
||||
|
- Select default model per node type (GenerateImage, GenerateVideo, LLM) |
||||
|
- Configure default parameters (e.g., seedream 4.5 with specific settings) |
||||
|
- Clear/reset to system defaults |
||||
|
|
||||
|
Plans: |
||||
|
- [ ] 28-01: TBD (run /gsd:plan-phase 28 to break down) |
||||
|
|
||||
|
#### Phase 29: Canvas Performance |
||||
|
|
||||
|
**Goal**: Optimize canvas rendering for large workflows using virtualization and memoization |
||||
|
**Depends on**: Phase 28 |
||||
|
**Research**: Likely (React Flow virtualization, performance optimization) |
||||
|
**Research topics**: React Flow performance best practices, node virtualization, selective rendering |
||||
|
**Plans**: TBD |
||||
|
|
||||
|
Plans: |
||||
|
- [ ] 29-01: TBD (run /gsd:plan-phase 29 to break down) |
||||
|
|
||||
|
## Progress |
||||
|
|
||||
|
**Execution Order:** |
||||
|
Phases execute in numeric order: 1 → 2 → ... → 24 → 25 → 26 → 27 → 28 → 29 |
||||
|
|
||||
|
| Phase | Milestone | Plans Complete | Status | Completed | |
||||
|
|-------|-----------|----------------|--------|-----------| |
||||
|
| 1. Provider Infrastructure | v1.0 | 2/2 | Complete | 2026-01-09 | |
||||
|
| 2. Model Discovery | v1.0 | 3/3 | Complete | 2026-01-09 | |
||||
|
| 3. Generate Node Refactor | v1.0 | 3/3 | Complete | 2026-01-09 | |
||||
|
| 4. Model Search Dialog | v1.0 | 2/2 | Complete | 2026-01-09 | |
||||
|
| 5. Image URL Server | v1.0 | 2/2 | Complete | 2026-01-09 | |
||||
|
| 6. Video & Polish | v1.0 | 4/4 | Complete | 2026-01-11 | |
||||
|
| 7. Video Connections | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 8. Error Display | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 9. Video History | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 10. Node Autosizing | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 11. UI Polish | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 12. Model Improvements | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 13. Fix Duplicate Generations | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 14. Fix Drag-Connect Node Creation Bugs | v1.1 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 15. Test Infrastructure | v1.2 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 16. Store Modularization | v1.2 | 1/1 | Complete | 2026-01-12 | |
||||
|
| 17. Component Tests | v1.2 | 11/11 | Complete | 2026-01-13 | |
||||
|
| 18. API Route Tests | v1.2 | 5/5 | Complete | 2026-01-13 | |
||||
|
| 19. Type Refactoring | v1.2 | 2/2 | Complete | 2026-01-13 | |
||||
|
| 20. Integration Tests | v1.2 | 2/2 | Complete | 2026-01-13 | |
||||
|
| 21. Fix Image Input & Deduplication | v1.2 | 1/1 | Complete | 2026-01-13 | |
||||
|
| 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 | - | |
||||
|
| 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 | - | |
||||
|
| 29. Canvas Performance | v1.3 | 0/? | Not started | - | |
||||
@ -0,0 +1,156 @@ |
|||||
|
--- |
||||
|
phase: 25-template-explorer-ui |
||||
|
plan: 01 |
||||
|
type: execute |
||||
|
--- |
||||
|
|
||||
|
<objective> |
||||
|
Create the template explorer component architecture with cards layout and template metadata. |
||||
|
|
||||
|
Purpose: Build the foundational UI components for template browsing that scales to many templates. |
||||
|
Output: TemplateExplorerView component with TemplateCard, template metadata types, and grid layout. |
||||
|
</objective> |
||||
|
|
||||
|
<execution_context> |
||||
|
~/.claude/get-shit-done/workflows/execute-phase.md |
||||
|
~/.claude/get-shit-done/templates/summary.md |
||||
|
</execution_context> |
||||
|
|
||||
|
<context> |
||||
|
@.planning/PROJECT.md |
||||
|
@.planning/ROADMAP.md |
||||
|
@.planning/STATE.md |
||||
|
|
||||
|
**Key files:** |
||||
|
@src/lib/quickstart/templates.ts |
||||
|
@src/components/quickstart/QuickstartTemplatesView.tsx |
||||
|
@src/components/quickstart/WelcomeModal.tsx |
||||
|
@src/types/quickstart.ts |
||||
|
|
||||
|
**Current state:** |
||||
|
- 6 preset templates in templates.ts with name, description, icon, workflow |
||||
|
- QuickstartTemplatesView uses compact button layout (grid of small buttons) |
||||
|
- Community workflows fetched from /api/community-workflows |
||||
|
- WelcomeModal manages view state: initial, templates, vibe |
||||
|
|
||||
|
**Established patterns:** |
||||
|
- Template data in src/lib/quickstart/templates.ts |
||||
|
- QuickstartView type manages view navigation |
||||
|
- Tailwind CSS with neutral-* colors |
||||
|
- Icon components using inline SVG paths |
||||
|
</context> |
||||
|
|
||||
|
<tasks> |
||||
|
|
||||
|
<task type="auto"> |
||||
|
<name>Task 1: Extend template types with rich metadata</name> |
||||
|
<files>src/types/quickstart.ts, src/lib/quickstart/templates.ts</files> |
||||
|
<action> |
||||
|
1. Add TemplateMetadata interface to quickstart.ts: |
||||
|
- nodeCount: number |
||||
|
- category: 'product' | 'style' | 'composition' | 'community' |
||||
|
- tags: string[] (e.g., ['product', 'scene', 'fashion']) |
||||
|
- previewImage?: string (optional for now) |
||||
|
|
||||
|
2. Update PresetTemplate interface in templates.ts to include metadata: |
||||
|
- Add category and tags to each template |
||||
|
- Add getTemplateMetadata() function that extracts node count from workflow |
||||
|
|
||||
|
Categories for existing templates: |
||||
|
- product-shot: category='product', tags=['product', 'scene', 'placement'] |
||||
|
- model-product: category='product', tags=['product', 'model', 'fashion'] |
||||
|
- color-variations: category='product', tags=['product', 'color', 'variations'] |
||||
|
- background-swap: category='composition', tags=['composite', 'background', 'subject'] |
||||
|
- style-transfer: category='style', tags=['style', 'artistic', 'transfer'] |
||||
|
- scene-composite: category='composition', tags=['composite', 'scene', 'elements'] |
||||
|
</action> |
||||
|
<verify>TypeScript compiles without errors: npm run build</verify> |
||||
|
<done>TemplateMetadata interface exists, all preset templates have category/tags, getTemplateMetadata() returns node count</done> |
||||
|
</task> |
||||
|
|
||||
|
<task type="auto"> |
||||
|
<name>Task 2: Create TemplateCard component</name> |
||||
|
<files>src/components/quickstart/TemplateCard.tsx</files> |
||||
|
<action> |
||||
|
Create a new TemplateCard component that displays template in a card format: |
||||
|
|
||||
|
1. Props: |
||||
|
- template: PresetTemplate with metadata |
||||
|
- isLoading: boolean |
||||
|
- onClick: () => void |
||||
|
- disabled: boolean |
||||
|
|
||||
|
2. Layout (approximately 280px wide): |
||||
|
- Top section: Icon in a larger container (48x48 icon area with neutral-700/50 bg) |
||||
|
- Template name (text-sm font-medium) |
||||
|
- Description (text-xs text-neutral-400, max 2 lines with line-clamp-2) |
||||
|
- Metadata row: node count badge, category badge |
||||
|
- Tags displayed as small pills (text-[10px]) |
||||
|
|
||||
|
3. States: |
||||
|
- Default: border-neutral-700, hover:border-neutral-600, hover:bg-neutral-800/50 |
||||
|
- Loading: bg-blue-600/20 border-blue-500/50, spinner animation |
||||
|
- Disabled: opacity-50, cursor-not-allowed |
||||
|
|
||||
|
4. Use existing patterns from QuickstartTemplatesView for loading spinner SVG |
||||
|
|
||||
|
Keep the card compact but informative - focus on scannability. Use group hover for icon color transitions. |
||||
|
</action> |
||||
|
<verify>Component renders without errors in isolation (check TypeScript): npm run build</verify> |
||||
|
<done>TemplateCard.tsx exists with card layout, displays metadata, handles loading/disabled states</done> |
||||
|
</task> |
||||
|
|
||||
|
<task type="auto"> |
||||
|
<name>Task 3: Create TemplateExplorerView with grid layout</name> |
||||
|
<files>src/components/quickstart/TemplateExplorerView.tsx</files> |
||||
|
<action> |
||||
|
Create TemplateExplorerView component that replaces QuickstartTemplatesView with a full explorer layout: |
||||
|
|
||||
|
1. Layout structure (flex container): |
||||
|
- Header: Back button + "Template Explorer" title (reuse QuickstartBackButton) |
||||
|
- Main content area with card grid (grid-cols-2 on mobile, grid-cols-3 on larger) |
||||
|
- Cards use TemplateCard component |
||||
|
|
||||
|
2. State management: |
||||
|
- Templates from getAllPresets() |
||||
|
- Community workflows from /api/community-workflows |
||||
|
- Loading states for list and individual template loading |
||||
|
- Error handling (reuse existing error display pattern) |
||||
|
|
||||
|
3. Template selection: |
||||
|
- On click: fetch full workflow via /api/quickstart POST (for presets) or /api/community-workflows/[id] (for community) |
||||
|
- Pass workflow to onWorkflowSelected callback |
||||
|
- Track model usage like existing implementation |
||||
|
|
||||
|
4. For now, display all templates in single grid (filtering added in Plan 02) |
||||
|
- Presets section first with "Quick Start" header |
||||
|
- Community section with "Community" header (if any exist) |
||||
|
|
||||
|
Keep consistent with existing visual style from QuickstartTemplatesView but use card layout instead of compact buttons. |
||||
|
</action> |
||||
|
<verify>npm run build succeeds, component structure is correct</verify> |
||||
|
<done>TemplateExplorerView.tsx exists with grid of TemplateCards, fetches and displays templates, handles selection</done> |
||||
|
</task> |
||||
|
|
||||
|
</tasks> |
||||
|
|
||||
|
<verification> |
||||
|
Before declaring plan complete: |
||||
|
- [ ] `npm run build` succeeds without TypeScript errors |
||||
|
- [ ] TemplateMetadata types are properly defined |
||||
|
- [ ] TemplateCard component renders template info in card format |
||||
|
- [ ] TemplateExplorerView displays templates in grid layout |
||||
|
</verification> |
||||
|
|
||||
|
<success_criteria> |
||||
|
|
||||
|
- All tasks completed |
||||
|
- TypeScript builds without errors |
||||
|
- Template cards display name, description, node count, category, tags |
||||
|
- Grid layout adapts to screen size |
||||
|
- Ready for Plan 02 to add filtering/search |
||||
|
</success_criteria> |
||||
|
|
||||
|
<output> |
||||
|
After completion, create `.planning/phases/25-template-explorer-ui/25-01-SUMMARY.md` |
||||
|
</output> |
||||
@ -0,0 +1,149 @@ |
|||||
|
--- |
||||
|
phase: 25-template-explorer-ui |
||||
|
plan: 02 |
||||
|
type: execute |
||||
|
--- |
||||
|
|
||||
|
<objective> |
||||
|
Add left-hand filter panel with search and category filters, integrate into WelcomeModal. |
||||
|
|
||||
|
Purpose: Complete the template explorer with filtering and search capabilities, replace existing template selection. |
||||
|
Output: Fully functional template explorer with sidebar filters, search, and WelcomeModal integration. |
||||
|
</objective> |
||||
|
|
||||
|
<execution_context> |
||||
|
~/.claude/get-shit-done/workflows/execute-phase.md |
||||
|
~/.claude/get-shit-done/templates/summary.md |
||||
|
</execution_context> |
||||
|
|
||||
|
<context> |
||||
|
@.planning/PROJECT.md |
||||
|
@.planning/ROADMAP.md |
||||
|
|
||||
|
**From Plan 01:** |
||||
|
@src/types/quickstart.ts (TemplateMetadata types) |
||||
|
@src/components/quickstart/TemplateCard.tsx |
||||
|
@src/components/quickstart/TemplateExplorerView.tsx |
||||
|
|
||||
|
**Integration points:** |
||||
|
@src/components/quickstart/WelcomeModal.tsx |
||||
|
|
||||
|
**Existing patterns:** |
||||
|
- Icon-based filter buttons from ModelSearchDialog (Phase 23) |
||||
|
- Search input styling from existing modals |
||||
|
</context> |
||||
|
|
||||
|
<tasks> |
||||
|
|
||||
|
<task type="auto"> |
||||
|
<name>Task 1: Add sidebar filter panel to TemplateExplorerView</name> |
||||
|
<files>src/components/quickstart/TemplateExplorerView.tsx</files> |
||||
|
<action> |
||||
|
Restructure TemplateExplorerView to have a left sidebar with filters: |
||||
|
|
||||
|
1. Layout change: |
||||
|
- Header stays at top (back button + title) |
||||
|
- Below header: flex row with sidebar (w-48 flex-shrink-0) + main grid area |
||||
|
- Sidebar has: search input, category filters, tags section |
||||
|
|
||||
|
2. Search input: |
||||
|
- Text input with search icon (magnifying glass) |
||||
|
- Placeholder: "Search templates..." |
||||
|
- Filters templates by name and description match |
||||
|
- Debounce with 200ms delay using useRef/setTimeout pattern |
||||
|
|
||||
|
3. Category filters: |
||||
|
- "All" button (default selected) |
||||
|
- Category buttons: Product, Style, Composition, Community |
||||
|
- Use icon buttons similar to provider filter in ModelSearchDialog |
||||
|
- Single-select (only one category active at a time) |
||||
|
- Apply bg-blue-500/20 border-blue-500/50 for selected state |
||||
|
|
||||
|
4. Tags section (below categories): |
||||
|
- "Tags" label (text-xs text-neutral-500 uppercase) |
||||
|
- Show all unique tags from displayed templates |
||||
|
- Small pill buttons, multi-select |
||||
|
- Selected tags use blue styling, unselected use neutral |
||||
|
|
||||
|
5. Filtering logic: |
||||
|
- Search: filter by name OR description containing search term (case-insensitive) |
||||
|
- Category: filter by category match (or all if "All" selected) |
||||
|
- Tags: filter by ANY tag match (OR logic, inclusive) |
||||
|
- Apply all filters: search AND category AND tags |
||||
|
|
||||
|
6. Empty state: |
||||
|
- Show "No templates match your filters" message |
||||
|
- Include button to clear all filters |
||||
|
</action> |
||||
|
<verify>npm run build succeeds, filter logic is correct</verify> |
||||
|
<done>Sidebar with search, category filters, and tag filters working; templates filter correctly; empty state displayed when no matches</done> |
||||
|
</task> |
||||
|
|
||||
|
<task type="auto"> |
||||
|
<name>Task 2: Integrate TemplateExplorerView into WelcomeModal</name> |
||||
|
<files>src/components/quickstart/WelcomeModal.tsx, src/types/quickstart.ts</files> |
||||
|
<action> |
||||
|
Replace QuickstartTemplatesView with TemplateExplorerView in WelcomeModal: |
||||
|
|
||||
|
1. Update QuickstartView type in quickstart.ts: |
||||
|
- Change "templates" to "explorer" (optional, can keep "templates" for simplicity) |
||||
|
|
||||
|
2. In WelcomeModal.tsx: |
||||
|
- Import TemplateExplorerView (not QuickstartTemplatesView) |
||||
|
- Replace QuickstartTemplatesView render with TemplateExplorerView |
||||
|
- Keep same props: onBack, onWorkflowSelected |
||||
|
- Widen modal for explorer: change max-w-3xl to max-w-4xl to accommodate sidebar |
||||
|
|
||||
|
3. The modal should expand to show the new layout comfortably: |
||||
|
- Explorer has sidebar + grid, needs more horizontal space |
||||
|
- Consider adding max-h-[80vh] with overflow handling |
||||
|
|
||||
|
4. Remove QuickstartTemplatesView.tsx import (keep file for now, can clean up later) |
||||
|
</action> |
||||
|
<verify>npm run build succeeds, WelcomeModal shows TemplateExplorerView</verify> |
||||
|
<done>WelcomeModal uses TemplateExplorerView, modal sized appropriately for sidebar layout</done> |
||||
|
</task> |
||||
|
|
||||
|
<task type="checkpoint:human-verify" gate="blocking"> |
||||
|
<what-built>Template Explorer with cards layout, sidebar filters, search, and category filtering</what-built> |
||||
|
<how-to-verify> |
||||
|
1. Run: npm run dev |
||||
|
2. Open http://localhost:3000 |
||||
|
3. Click "Templates" in the welcome modal |
||||
|
4. Verify: |
||||
|
- Templates display in card grid format (not compact buttons) |
||||
|
- Each card shows name, description, node count, category, tags |
||||
|
- Left sidebar has search input and filter buttons |
||||
|
- Search filters templates as you type |
||||
|
- Category buttons filter by category |
||||
|
- Tag pills filter by tag (multi-select) |
||||
|
- Clicking a template loads it into the canvas |
||||
|
- Modal is wide enough for comfortable browsing |
||||
|
</how-to-verify> |
||||
|
<resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal> |
||||
|
</task> |
||||
|
|
||||
|
</tasks> |
||||
|
|
||||
|
<verification> |
||||
|
Before declaring phase complete: |
||||
|
- [ ] `npm run build` succeeds |
||||
|
- [ ] `npm test` passes (no broken tests) |
||||
|
- [ ] Template explorer displays in WelcomeModal |
||||
|
- [ ] Search, category, and tag filtering all work |
||||
|
- [ ] Templates can be selected and loaded |
||||
|
</verification> |
||||
|
|
||||
|
<success_criteria> |
||||
|
|
||||
|
- All tasks completed |
||||
|
- All verification checks pass |
||||
|
- Template explorer replaces old template view |
||||
|
- Filtering works correctly with search, categories, and tags |
||||
|
- UI is responsive and visually consistent |
||||
|
- Phase 25 complete |
||||
|
</success_criteria> |
||||
|
|
||||
|
<output> |
||||
|
After completion, create `.planning/phases/25-template-explorer-ui/25-02-SUMMARY.md` |
||||
|
</output> |
||||
Loading…
Reference in new issue