popiart-node-canvas/.planning/ROADMAP.md

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-23 (in progress)

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

✅ v1.0 Multi-Provider Support (Phases 1-6) - SHIPPED 2026-01-11

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:

• 01-01: Provider settings UI in ProjectSetupModal
• 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:

• 02-01: Replicate model fetching API route
• 02-02: fal.ai model fetching API route
• 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:

• 03-01: Rename NanoBanana to GenerateImage, add model selector (image models only)
• 03-02: Provider-specific execution in generate API route
• 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:

• 04-01: Floating action bar with provider icons
• 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:

• 05-01: Image serving endpoint and URL generation
• 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:

• 06-01: GenerateVideo node with video-capable model selector
• 06-02: Video playback in output node
• 06-03: Custom model parameters from provider schemas
• 06-04: Edge case handling and final polish

✅ v1.1 Improvements (Phases 7-14) - SHIPPED 2026-01-12

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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 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:

• 14-01: Normalize dynamic handle IDs and fix connection persistence

🚧 v1.2 Improvements (In Progress)

Milestone Goal: Add automated testing across the application and modularize large monolithic files for better maintainability

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:

• 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:

• 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:

• 17-01: Core Nodes (BaseNode, PromptNode, ImageInputNode)
• 17-02: Display Nodes (OutputNode, SplitGridNode, GroupNode)
• 17-03: Generate Nodes (GenerateImageNode, GenerateVideoNode)
• 17-04: Processing Nodes (LLMGenerateNode, AnnotationNode)
• 17-05: Toolbars (Header, FloatingActionBar, MultiSelectToolbar)
• 17-06: Canvas & Edges (WorkflowCanvas, EditableEdge, ReferenceEdge, EdgeToolbar)
• 17-07: Menus & Notifications (ConnectionDropMenu, Toast, CostIndicator)
• 17-08: Core Modals (ModelSearchDialog, ProjectSetupModal, CostDialog)
• 17-09: Editor Modals (PromptEditorModal, SplitGridSettingsModal, AnnotationModal)
• 17-10: Quickstart (WelcomeModal, QuickstartInitialView, QuickstartTemplatesView, PromptWorkflowView, QuickstartBackButton)
• 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:

• 18-01: File I/O routes (workflow, save-generation)
• 18-02: LLM route (Google, OpenAI providers)
• 18-03: Generate route (Gemini provider)
• 18-04: Generate route (Replicate, fal.ai providers)
• 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:

• 19-01: Extract node and annotation types
• 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: TBD

Plans:

• 20-01: TBD (run /gsd:plan-phase 20 to break down)

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:

• 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:

• 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:

• 23-01: TBD (run /gsd:plan-phase 23 to break down)

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → ... → 14 → 15 → 16 → 17 → 18 → 19 → 20 → 21 → 22 → 23

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	1/2	In Progress	-
20. Integration Tests	v1.2	0/?	Not started	-
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	0/?	Not started	-