# 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 | - |