docs(25): create phase plan for Template Explorer UI

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>
6 months ago · 8e4a121b04
3 changed files with 767 additions and 0 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@ -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 | - |
--- a/.planning/phases/25-template-explorer-ui/25-01-PLAN.md
+++ b/.planning/phases/25-template-explorer-ui/25-01-PLAN.md
@ -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>
--- a/.planning/phases/25-template-explorer-ui/25-02-PLAN.md
+++ b/.planning/phases/25-template-explorer-ui/25-02-PLAN.md
@ -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>