popiart-node-canvas

History

Willie 8008801402 feat: Tutorial improvements with mock execution and organized demonstration (#112 ) * feat(49-01): add FTUX types and localStorage helpers - Create src/types/ftux.ts with FTUXStep, FTUXModalProps, FTUXStepProps - Add FTUX_COMPLETED_KEY to localStorage keys - Add getFTUXCompleted() and setFTUXCompleted() helpers - Follow existing localStorage pattern with server-safe checks * feat(49-02): create tutorial state management with Zustand - TutorialStep interface with id, message, highlightSelector, requiredAction - FTUXState with tutorialActive, currentTutorialStep, tutorialSteps, lockedFeatures - Actions: startTutorial, skipTutorial, completeCurrentStep, nextTutorialStep, resetTutorial - setFTUXCompleted/getFTUXCompleted localStorage helpers - Initial tutorial steps (5 steps, placeholders for Plan 03) * feat(49-01): build FTUXModal container and step components - Create FTUXModal.tsx: 4-step modal with navigation, skip confirmation - Create FTUXWelcomeStep.tsx: Welcome screen with project intro - Create FTUXApiKeysStep.tsx: Provider list with .env status checking - Create FTUXModelDefaultsStep.tsx: Model selection via ModelSearchDialog - Create FTUXReadyStep.tsx: Completion screen with tutorial option - Follow WelcomeModal and ProjectSetupModal patterns - Use Tailwind neutral-800 theme throughout - Step indicators show progress (1-4) - Back button hidden on step 1 - Skip confirmation shows nested dialog overlay * feat(49-02): build typewriter hook and tutorial UI components - useTypewriter hook with 50ms/char animation and isComplete flag - TutorialMessage component with typewriter animation and dark backdrop - ElementHighlight component with pulsing blue ring (2px border, 8px blur) - Three-layer highlight: dimmed overlay (bg-black/60), blue ring (z-91), clickable window (z-92) - TutorialOverlay coordinator with action detection (add-image-node, connect-nodes, run-workflow) - Skip tutorial button in top-right corner - pulse-ring keyframes added to globals.css - Uses React portals for correct z-index stacking * feat(49-03): replace WelcomeModal with FTUXModal in app entry point - Import FTUXModal, getFTUXCompleted, setFTUXCompleted, useFTUXStore - Add SSR-safe showFTUX state (initialized via useEffect) - Render FTUXModal when showFTUX=true - onComplete callback sets showFTUX=false and marks FTUX complete - onStartTutorial callback hides modal and starts tutorial via ftuxStore - WelcomeModal still available via logo click (not removed, just not on first visit) * feat(49-03): integrate tutorial overlay and add data-tutorial attributes WorkflowCanvas.tsx: - Import TutorialOverlay and useFTUXStore - Get tutorialActive and lockedFeatures from ftuxStore - Apply dimming (opacity-30 + pointer-events-none) to Background, Controls, MiniMap when tutorial active - Render TutorialOverlay component after AnnotationModal FloatingActionBar.tsx: - Add optional dataTutorial prop to NodeButton interface - Add data-tutorial="image-button" to Image input button - Add data-tutorial="output-button" to Output button - These attributes allow ElementHighlight to target buttons during tutorial * fix(49-03): resolve Zustand SSR hydration issue in WorkflowCanvas - Replace direct useFTUXStore hook call with useState + useEffect pattern - Subscribe to ftuxStore on client-side only via useEffect - Initialize state with getState() after subscription - Prevents 'getServerSnapshot should be cached' error during SSR - Prevents 'Maximum update depth exceeded' infinite loop * chore(49-03): add FTUX testing override to always show modal - Force setShowFTUX(true) to bypass localStorage check - Allows repeated testing without clearing localStorage each time - Added clear TODO comment to revert before production - Original production code commented out for easy restoration * ux(49-03): improve FTUX modal copy and layout based on user testing FTUXModal.tsx: - Increase modal width from max-w-[520px] to max-w-[640px] for better readability FTUXWelcomeStep.tsx: - Remove large banana icon (w-20 h-20) for cleaner look - Change headline from "Welcome to Node Banana" to "Let's get set up." - Keep workflow description, update subtext to "This will only take a few quick steps." FTUXApiKeysStep.tsx: - Simplify description to emphasize .env.local security benefit - New: "Add your API keys here, or save them to .env.local to keep them secure across sessions." - Remove mention of settings (cleaner messaging) FTUXModelDefaultsStep.tsx: - Remove redundant "You can always change these later" from main description - Remove "These defaults are applied when creating nodes" from footer (redundant) - Keep single mention: "You can skip this step and configure them later in settings." FTUXReadyStep.tsx: - Remove large green checkmark icon (w-16 h-16 circular bg) - Keep "All Set Up!" headline and description - Keep both tutorial buttons unchanged * ux(49-03): remove redundant .env.local text below API keys list - Remove duplicate messaging at bottom of FTUXApiKeysStep - Top description already mentions .env.local security benefit - Cleaner, less repetitive UI * copy(49-03): rewrite FTUX copy for clarity and conciseness Applied principles: Clear, Concise, Consistent, Useful, Human FTUXWelcomeStep: - Headline: "Let's get set up." → "Let's get started." - Body: Simplified from wordy workflow/pipeline jargon to clear action Old: "Build AI workflows visually with nodes and connections. Create complex image and video generation pipelines by connecting simple building blocks." New: "Connect AI models like building blocks to generate images, videos, and more." - Removed defensive subtext ("This will only take a few quick steps") FTUXApiKeysStep: - Description: Clearer security benefit, less technical Old: "Add your API keys here, or save them to .env.local to keep them secure across sessions." New: "Add keys to use AI providers. For security, save them to your .env.local file instead of the browser." FTUXModelDefaultsStep: - Headline: "Default Models (Optional)" → "Choose Your Models (Optional)" - Description: Removed redundant "by default when creating new nodes" Old: "Choose which AI models to use by default when creating new nodes." New: "Pick which AI models to use for images and videos." - Removed defensive footer text ("You can skip...") FTUXReadyStep: - Headline: "All Set Up!" → "You're ready!" - Body: Removed jargon and redundancy Old: "You're ready to start building workflows. Would you like a quick tutorial to get started?" New: "Want a quick tutorial?" - Buttons: "Skip Tutorial" → "Skip", "Start Tutorial" → "Show me how" * fix(49-03): remove double scrollbar in API Keys step - Remove max-h-[380px] overflow-y-auto from provider list container - FTUXModal already has overflow-y-auto on content area (line 112) - Provider list now scrolls with rest of modal content, not separately - Fixes nested scroll container causing double scrollbar * copy(49-03): clarify browser storage in API Keys step - Make it explicit that adding keys in UI = stored in browser - Parenthetical "(stored in browser)" right after action - "for better security" instead of "For security" flows better - Clearer tradeoff between convenience (browser) and security (.env.local) Old: "Add keys to use AI providers. For security, save them to your .env.local file instead of the browser." New: "Add keys here to use AI providers (stored in browser), or save them to your .env.local file for better security." * copy(49-03): add "across sessions" to API Keys security benefit - Change "better security" to "better security across sessions" - Makes the persistence benefit of .env.local more explicit - Clarifies why file storage is better than browser storage New: "Add keys here to use AI providers (stored in browser), or save them to your .env.local file for better security across sessions." * fix(49-03): save API keys entered during FTUX onboarding Problem: API keys entered in FTUX modal were stored in local state only and disappeared when modal closed, requiring users to re-enter them. Original plan decision (49-01): "API key inputs not persisted during FTUX flow" Rationale: "Setup is informational only, actual persistence happens in ProjectSetupModal" This created broken UX - users entered keys expecting them to work. Solution: - Import useWorkflowStore and updateProviderApiKey function - Create handleKeyChange that saves to localStorage immediately via updateProviderApiKey - Replace direct setLocalKeys with handleKeyChange in input onChange - Keys now persist automatically as user types (saved as null if empty) Impact: Users can now enter API keys during onboarding and they'll be available immediately in the app without re-entry. Deviation: Auto-fix bug (Rule 1) - keys not persisting broke user expectations * fix(49-03): close FTUX modal and center tutorial message Issue 1 - FTUX modal still visible after starting tutorial: - Add setFTUXCompleted(true) to handleStartTutorial - Ensures modal won't re-render even with testing override - Modal now properly closes before tutorial starts Issue 2 - Tutorial message overlapping floating action bar: - Change TutorialMessage position from bottom-4 to center of screen - Use top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 for true center - Message now displays prominently in center, not at bottom - Update comment: "contextual placement" → "center of screen for maximum visibility" Before: bottom-4 left-1/2 -translate-x-1/2 (bottom center) After: top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 (true center) * fix(49-03): close WelcomeModal when starting tutorial Problem: WelcomeModal (original quickstart modal with "New Project", "Load Workflow", etc.) remained visible when user clicked "Show me how" to start tutorial, blocking the tutorial UI. Root cause: WelcomeModal is controlled by workflowStore.showQuickstart state and was not being closed when tutorial started. Solution: - Import setShowQuickstart from useWorkflowStore - Add setShowQuickstart(false) to handleStartTutorial - WelcomeModal now closes before tutorial overlay appears Now when tutorial starts, both FTUXModal and WelcomeModal are closed, allowing tutorial overlay to display without obstruction. * fix(49-03): implement complete tutorial progression flow Problem: Tutorial stuck on "Let's cook." message without progressing. Root causes: 1. Step 1 (welcome) had no requiredAction, so action detection never triggered 2. Steps 3-5 were placeholder steps with no content or actions 3. No auto-advance logic for informational steps Solution: ftuxStore.ts - Replace placeholder steps with real tutorial: - Step 1: "Let's cook." (welcome, auto-advances after 3s) - Step 2: "Click the Image button to add an image node." (highlights image button, requires add-image-node) - Step 3: "Now add an Output node to see your results." (highlights output button, requires add-output-node) - Step 4: "You're all set! Connect nodes to build workflows, or press Cmd+Enter to run." (completion, auto-advances) - Add "add-output-node" to TutorialStep requiredAction type TutorialOverlay.tsx - Add auto-advance and output detection: - Steps without requiredAction now auto-advance after 3 seconds (typewriter completes ~2s) - Add detection for "add-output-node" action (checks for node.type === "output") - Early return cleanup timer to prevent memory leaks Tutorial now flows: Welcome → Add Image → Add Output → Complete Each step progresses based on user action or auto-advances for info steps. * fix(49-03): make tutorial highlighted elements clickable and visible Problem 1: Floating action bar was darkened during tutorial even though it contains the highlighted image button that user needs to see and click. Problem 2: Image button was not clickable - Layer 3 "clickable window" was blocking clicks instead of allowing them through. Root cause: ElementHighlight had full-screen dimmed overlay (Layer 1) blocking clicks, and Layer 3 created an empty div that blocked the actual element. Solution - Use box-shadow cutout technique: - Remove solid dimmed overlay (bg-black/60) - Remove Layer 3 entirely (not needed) - Use box-shadow: "0 0 0 9999px rgba(0, 0, 0, 0.6)" on positioned div - Creates dimmed overlay with cutout hole where highlighted element is - Highlighted element remains fully visible (not dimmed) - Highlighted element is fully clickable (no overlay blocking it) - Everything else gets dimmed FloatingActionBar.tsx: - Import useFTUXStore (prepared for future use) - Add tutorial state awareness (not currently used but ready for expansion) ElementHighlight.tsx: - Replace full-screen overlay + clickable window with box-shadow cutout - Simpler 2-layer approach: dimmed background with hole + blue ring - All pointer-events-none, so nothing blocks the actual DOM element * fix(49-03): resolve Zustand SSR hydration issue in FloatingActionBar Error: "The result of getServerSnapshot should be cached to avoid an infinite loop" at FloatingActionBar (src/components/FloatingActionBar.tsx:345:58) Same issue as WorkflowCanvas - direct useFTUXStore hook call during SSR. Solution (identical pattern to WorkflowCanvas fix): - Replace direct useFTUXStore hook with useState + useEffect pattern - Initialize with false defaults (SSR-safe, no hydration mismatch) - Subscribe to ftuxStore on client-side only via useEffect - Initialize state with getState() after subscription - Return cleanup function to unsubscribe on unmount Before: const { tutorialActive, lockedFeatures } = useFTUXStore(...) After: useState + useEffect subscription (client-side only) This prevents the SSR hydration error while maintaining reactive updates. * chore(49-03): restore production FTUX localStorage check - Remove testing override that forced FTUX to show every time - Restore production code: if (!getFTUXCompleted()) { setShowFTUX(true); } - Remove TODO comment about reverting - FTUX now only shows on first visit as intended * feat(tutorial): add connection drop menu workflow steps Extend the FTUX tutorial with 4 new steps that teach users how to use the connection drop menu workflow pattern: Step 6: Drag from output handle - Prompts user to drag from the image node's output handle - Tracks drag start via onConnectStart handler Step 7: Release in empty space - Prompts user to release to show the connection drop menu - Tracks menu appearance via handleConnectEnd Step 8: Explain connection menu - Highlights the drop menu with blue ring - Explains it shows compatible nodes - Requires click to continue Step 9: Select Generate Image - Highlights "Generate Image" button in menu - Tracks nanoBanana selection via handleMenuSelect - Only advances when selected from menu (not FloatingActionBar) Step 10: Tutorial complete - Shows completion message with workflow tips - Auto-advances after 3s and marks FTUX done Implementation details: - Add 3 new requiredAction types to TutorialStep interface - Add 3 state tracking flags to FTUXState (connectionDragStarted, etc.) - Add tutorial tracking in WorkflowCanvas connection lifecycle - Add data-tutorial attributes for highlighting menu elements - Import OnConnectStart type and create handleConnectStart handler - Track menu appearance and nanoBanana selection with tutorialActive guards Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * refactor(tutorial): simplify drag-and-drop flow Combine drag and drop instructions into a single step and immediately highlight the Generate Image button when the context menu appears: Changes: - Combine step 6 (drag) and step 7 (drop) into one: "Drag from the output handle and drop into empty space" - Remove step 8 (explain menu) - go straight to highlighting Generate Image - Step 6 now waits for menu to appear (show-connection-menu) - Step 7 highlights Generate Image button immediately (add-nanoBanana-from-menu) Removed unused tracking: - Remove start-connection-drag requiredAction type - Remove connectionDragStarted state flag and setter - Remove handleConnectStart callback from WorkflowCanvas - Remove onConnectStart prop from ReactFlow - Remove OnConnectStart import New flow is cleaner and more direct: Step 5: Explain outputs (click to continue) Step 6: Drag and drop to show menu (auto-advance) Step 7: Select Generate Image (auto-advance) Step 8: Complete Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(tutorial): highlight Generate Image button immediately Combine drag-and-drop and selection steps into one to ensure the Generate Image button is highlighted as soon as the connection menu appears. Problem: - Previous flow had two separate steps (drag-drop, then select) - 1 second delay between menu appearing and Generate Image highlighting - Output handle was highlighted while menu was already visible (confusing) Solution: - Single step: "Drag from the output handle and drop into empty space. Then select 'Generate Image'." - highlightSelector targets the Generate Image button from the start - ElementHighlight polls every 500ms, so highlights button immediately when menu appears (no delay) - Cleaner UX: instruction → action → immediate visual feedback Removed: - show-connection-menu requiredAction (no longer needed) - connectionMenuShown state flag and setter - Tutorial tracking in handleConnectEnd New flow: - Step 5: Explain outputs (click to continue) - Step 6: Drag, drop, select Generate Image (highlight on button, auto-advance) - Step 7: Complete Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(tutorial): increase highlight z-index above connection menu The ElementHighlight component was rendering at z-index 91, but the ConnectionDropMenu is at z-index 100, causing the highlight ring to appear behind the menu. Change: Increase ElementHighlight z-index from 91 to 101 This ensures the pulsing blue ring appears on top of the menu while still allowing clicks through (pointer-events-none). Z-index stack: - ElementHighlight: 101 (above menu) - ConnectionDropMenu: 100 - Skip tutorial button: 94 - TutorialMessage: 93 - Click overlay: 92 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(tutorial): highlight output handle when prompting drag action Split the combined step back into two sequential steps with proper highlights and instant transition between them. Problem: - Single step told user to "Drag from the output handle" but highlighted the Generate Image button (which doesn't exist yet) - Confusing visual feedback - wrong element highlighted for the instruction Solution: - Step 6: "Drag from the output handle and drop into empty space." - Highlights: node-output-handle - Action: show-connection-menu - advanceDelay: 0ms (instant transition) - Step 7: "Select 'Generate Image' to add an AI image generation node." - Highlights: generate-image-option - Action: add-nanoBanana-from-menu - advanceDelay: 1000ms (default) New feature: advanceDelay property - Added to TutorialStep interface - Configurable delay before advancing to next step after action completes - Default: 1000ms (preserves existing behavior) - Step 6 uses 0ms for instant transition when menu appears Flow: 1. User sees output handle highlighted → drags and drops 2. Menu appears → step advances instantly (0ms delay) 3. Generate Image button immediately highlighted 4. User clicks → tutorial advances after 1s Restored: - show-connection-menu requiredAction - connectionMenuShown state and setter - Tutorial tracking in handleConnectEnd Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(tutorial): subscribe to ftux state for action detection The action detection useEffect wasn't re-running when connectionMenuShown or nanoBananaAddedFromMenu changed because these states weren't in the dependency array. Problem: - User drags and drops → menu appears - setConnectionMenuShown(true) updates ftuxStore - But action detection useEffect doesn't re-run (missing dependency) - Step doesn't advance to highlight Generate Image button Solution: - Subscribe to connectionMenuShown and nanoBananaAddedFromMenu at component level - Use these subscribed values instead of getState() calls - Add them to useEffect dependency array Now when these states change: 1. Component re-renders with new values 2. useEffect re-runs due to dependency change 3. Action is detected as completed 4. Step advances with configured delay (0ms for instant transition) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * feat(tutorial): add prompt node and connection steps Extend tutorial with steps 8-9 to teach users: - Adding nodes via FloatingActionBar (different from connection menu) - Connecting nodes by dragging between existing handles Changes: - Add data-tutorial="prompt-button" to Prompt button - Add data-tutorial="prompt-output-handle" to Prompt output handle - Add "add-prompt-node" to requiredAction types - Add step 8: Add Prompt node via FloatingActionBar - Add step 9: Connect Prompt to Generate Image node - Update step 10 (complete) message for clarity - Add action detection for add-prompt-node in TutorialOverlay Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(tutorial): wait for prompt node connection in step 9 Step 9 was advancing immediately because it checked for ANY edges, but an edge already existed from step 7 (Image → Generate Image). Changes: - Add "connect-prompt-node" requiredAction type - Update step 9 to use "connect-prompt-node" instead of "connect-nodes" - Add detection logic that specifically checks for edges FROM prompt nodes - Track edges in TutorialOverlay component state for reactive detection - Add edges to useEffect dependency array Now step 9 correctly waits for user to connect the prompt node before advancing to the completion step. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * feat: prevent node overlap on creation with automatic collision detection Implements AABB collision detection to automatically place new nodes in collision-free positions. When users add nodes via FloatingActionBar or keyboard shortcuts, the system now finds the nearest free position using a spiral search pattern (right, down, left, up, diagonals). Changes: - Add spatialLayout.ts with rectanglesIntersect() and findNearestFreePosition() - Update addNode() to use collision detection before placing nodes - Remove random offset from FloatingActionBar for more deterministic placement - Use consistent 20px gap (COLLISION_GAP) matching existing STACK_GAP pattern Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * feat(tutorial): extend FTUX with content setup and resource guidance Add four new tutorial steps to guide users through completing their first workflow: - Prompt users to add text to the Prompt node - Prompt users to add an image to the Image node - Instruct users to run the workflow with Cmd/Ctrl+Enter - Inform users about saving projects, templates, and Discord community This ensures users complete a full workflow cycle during onboarding and know where to find help and resources. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(tutorial): remove emojis from tutorial messages Remove decorative emojis from the save-and-resources and completion steps for a cleaner, more professional appearance. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix(tutorial): improve viewport zoom timing with auto-populated nodes Increase timeout from 400ms to 600ms and improve viewport setting logic to ensure proper 0.7 zoom level when tutorial image node is added with pre-loaded base64 data. Fetch fresh nodes from store and extend animation duration for smoother transition. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * feat(tutorial): delay auto-population until after prompt connection Change tutorial flow to create empty nodes initially and auto-populate with sample content only after the prompt node is connected to generate. This maintains hands-on learning while still removing friction. Changes: - Nodes created empty during tutorial - Auto-populate after "connect-prompt-node" step completes - Switch sample image: model.png → owl.jpg - Update prompt: "wearing aviator sunglasses and a leather jacket" - Add nodesPopulated ref to prevent duplicate population Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * feat(tutorial): improve messaging, dual highlights, and pulsing animation - Change welcome message: "Let's cook" → "Let's go over the basics" - Add dual highlight for connect-prompt step: both prompt output and generate text input handles are now highlighted simultaneously - Position connect-prompt message on left side of screen - Update ElementHighlight to support array of selectors - Add data-tutorial attribute to generate node's text input handle - Pulsing animation already present via pulse-ring animation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * feat(tutorial): implement mock execution and organized node demonstration - Add mock workflow execution to save API costs during tutorial - Mock execution simulates 5-second generation time with edge animations - Loads pre-made owl aviator image instead of calling Gemini API - Provides realistic experience without incurring charges - Implement visible workflow tree demonstration - Automatically builds branching workflow after mock execution - Video branch: Prompt → Generate Video → Output - LLM branch: Prompt → LLM → Generate Image #2 → Output - Clean horizontal layout with 350px spacing between nodes - Vertical separation of ±350px for clear branch distinction - Improve user experience - Auto-close run menu when advancing past tutorial steps - Unlock canvas navigation after demonstration completes - Zoom to 0.35 with centered viewport for complete tree overview - Updated LLM prompt for nightclub scene generation - Add tutorial assets - Add owl aviator image (public/tutorial/owl-aviator.png) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> * fix: restore .env.example file Restore .env.example that was accidentally deleted in commit 9be881c. This file is needed as a reference for users to set up their environment. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>	3 months ago
..
owl-aviator.png	feat: Tutorial improvements with mock execution and organized demonstration (#112)	3 months ago

feat: Tutorial improvements with mock execution and organized demonstration (#112 )

* feat(49-01): add FTUX types and localStorage helpers

- Create src/types/ftux.ts with FTUXStep, FTUXModalProps, FTUXStepProps
- Add FTUX_COMPLETED_KEY to localStorage keys
- Add getFTUXCompleted() and setFTUXCompleted() helpers
- Follow existing localStorage pattern with server-safe checks

* feat(49-02): create tutorial state management with Zustand

- TutorialStep interface with id, message, highlightSelector, requiredAction
- FTUXState with tutorialActive, currentTutorialStep, tutorialSteps, lockedFeatures
- Actions: startTutorial, skipTutorial, completeCurrentStep, nextTutorialStep, resetTutorial
- setFTUXCompleted/getFTUXCompleted localStorage helpers
- Initial tutorial steps (5 steps, placeholders for Plan 03)

* feat(49-01): build FTUXModal container and step components

- Create FTUXModal.tsx: 4-step modal with navigation, skip confirmation
- Create FTUXWelcomeStep.tsx: Welcome screen with project intro
- Create FTUXApiKeysStep.tsx: Provider list with .env status checking
- Create FTUXModelDefaultsStep.tsx: Model selection via ModelSearchDialog
- Create FTUXReadyStep.tsx: Completion screen with tutorial option
- Follow WelcomeModal and ProjectSetupModal patterns
- Use Tailwind neutral-800 theme throughout
- Step indicators show progress (1-4)
- Back button hidden on step 1
- Skip confirmation shows nested dialog overlay

* feat(49-02): build typewriter hook and tutorial UI components

- useTypewriter hook with 50ms/char animation and isComplete flag
- TutorialMessage component with typewriter animation and dark backdrop
- ElementHighlight component with pulsing blue ring (2px border, 8px blur)
- Three-layer highlight: dimmed overlay (bg-black/60), blue ring (z-91), clickable window (z-92)
- TutorialOverlay coordinator with action detection (add-image-node, connect-nodes, run-workflow)
- Skip tutorial button in top-right corner
- pulse-ring keyframes added to globals.css
- Uses React portals for correct z-index stacking

* feat(49-03): replace WelcomeModal with FTUXModal in app entry point

- Import FTUXModal, getFTUXCompleted, setFTUXCompleted, useFTUXStore
- Add SSR-safe showFTUX state (initialized via useEffect)
- Render FTUXModal when showFTUX=true
- onComplete callback sets showFTUX=false and marks FTUX complete
- onStartTutorial callback hides modal and starts tutorial via ftuxStore
- WelcomeModal still available via logo click (not removed, just not on first visit)

* feat(49-03): integrate tutorial overlay and add data-tutorial attributes

WorkflowCanvas.tsx:
- Import TutorialOverlay and useFTUXStore
- Get tutorialActive and lockedFeatures from ftuxStore
- Apply dimming (opacity-30 + pointer-events-none) to Background, Controls, MiniMap when tutorial active
- Render TutorialOverlay component after AnnotationModal

FloatingActionBar.tsx:
- Add optional dataTutorial prop to NodeButton interface
- Add data-tutorial="image-button" to Image input button
- Add data-tutorial="output-button" to Output button
- These attributes allow ElementHighlight to target buttons during tutorial

* fix(49-03): resolve Zustand SSR hydration issue in WorkflowCanvas

- Replace direct useFTUXStore hook call with useState + useEffect pattern
- Subscribe to ftuxStore on client-side only via useEffect
- Initialize state with getState() after subscription
- Prevents 'getServerSnapshot should be cached' error during SSR
- Prevents 'Maximum update depth exceeded' infinite loop

* chore(49-03): add FTUX testing override to always show modal

- Force setShowFTUX(true) to bypass localStorage check
- Allows repeated testing without clearing localStorage each time
- Added clear TODO comment to revert before production
- Original production code commented out for easy restoration

* ux(49-03): improve FTUX modal copy and layout based on user testing

FTUXModal.tsx:
- Increase modal width from max-w-[520px] to max-w-[640px] for better readability

FTUXWelcomeStep.tsx:
- Remove large banana icon (w-20 h-20) for cleaner look
- Change headline from "Welcome to Node Banana" to "Let's get set up."
- Keep workflow description, update subtext to "This will only take a few quick steps."

FTUXApiKeysStep.tsx:
- Simplify description to emphasize .env.local security benefit
- New: "Add your API keys here, or save them to .env.local to keep them secure across sessions."
- Remove mention of settings (cleaner messaging)

FTUXModelDefaultsStep.tsx:
- Remove redundant "You can always change these later" from main description
- Remove "These defaults are applied when creating nodes" from footer (redundant)
- Keep single mention: "You can skip this step and configure them later in settings."

FTUXReadyStep.tsx:
- Remove large green checkmark icon (w-16 h-16 circular bg)
- Keep "All Set Up!" headline and description
- Keep both tutorial buttons unchanged

* ux(49-03): remove redundant .env.local text below API keys list

- Remove duplicate messaging at bottom of FTUXApiKeysStep
- Top description already mentions .env.local security benefit
- Cleaner, less repetitive UI

* copy(49-03): rewrite FTUX copy for clarity and conciseness

Applied principles: Clear, Concise, Consistent, Useful, Human

FTUXWelcomeStep:
- Headline: "Let's get set up." → "Let's get started."
- Body: Simplified from wordy workflow/pipeline jargon to clear action
  Old: "Build AI workflows visually with nodes and connections. Create complex image and video generation pipelines by connecting simple building blocks."
  New: "Connect AI models like building blocks to generate images, videos, and more."
- Removed defensive subtext ("This will only take a few quick steps")

FTUXApiKeysStep:
- Description: Clearer security benefit, less technical
  Old: "Add your API keys here, or save them to .env.local to keep them secure across sessions."
  New: "Add keys to use AI providers. For security, save them to your .env.local file instead of the browser."

FTUXModelDefaultsStep:
- Headline: "Default Models (Optional)" → "Choose Your Models (Optional)"
- Description: Removed redundant "by default when creating new nodes"
  Old: "Choose which AI models to use by default when creating new nodes."
  New: "Pick which AI models to use for images and videos."
- Removed defensive footer text ("You can skip...")

FTUXReadyStep:
- Headline: "All Set Up!" → "You're ready!"
- Body: Removed jargon and redundancy
  Old: "You're ready to start building workflows. Would you like a quick tutorial to get started?"
  New: "Want a quick tutorial?"
- Buttons: "Skip Tutorial" → "Skip", "Start Tutorial" → "Show me how"

* fix(49-03): remove double scrollbar in API Keys step

- Remove max-h-[380px] overflow-y-auto from provider list container
- FTUXModal already has overflow-y-auto on content area (line 112)
- Provider list now scrolls with rest of modal content, not separately
- Fixes nested scroll container causing double scrollbar

* copy(49-03): clarify browser storage in API Keys step

- Make it explicit that adding keys in UI = stored in browser
- Parenthetical "(stored in browser)" right after action
- "for better security" instead of "For security" flows better
- Clearer tradeoff between convenience (browser) and security (.env.local)

Old: "Add keys to use AI providers. For security, save them to your .env.local file instead of the browser."
New: "Add keys here to use AI providers (stored in browser), or save them to your .env.local file for better security."

* copy(49-03): add "across sessions" to API Keys security benefit

- Change "better security" to "better security across sessions"
- Makes the persistence benefit of .env.local more explicit
- Clarifies why file storage is better than browser storage

New: "Add keys here to use AI providers (stored in browser), or save them to your .env.local file for better security across sessions."

* fix(49-03): save API keys entered during FTUX onboarding

Problem: API keys entered in FTUX modal were stored in local state only
and disappeared when modal closed, requiring users to re-enter them.

Original plan decision (49-01): "API key inputs not persisted during FTUX flow"
Rationale: "Setup is informational only, actual persistence happens in ProjectSetupModal"

This created broken UX - users entered keys expecting them to work.

Solution:
- Import useWorkflowStore and updateProviderApiKey function
- Create handleKeyChange that saves to localStorage immediately via updateProviderApiKey
- Replace direct setLocalKeys with handleKeyChange in input onChange
- Keys now persist automatically as user types (saved as null if empty)

Impact: Users can now enter API keys during onboarding and they'll be
available immediately in the app without re-entry.

Deviation: Auto-fix bug (Rule 1) - keys not persisting broke user expectations

* fix(49-03): close FTUX modal and center tutorial message

Issue 1 - FTUX modal still visible after starting tutorial:
- Add setFTUXCompleted(true) to handleStartTutorial
- Ensures modal won't re-render even with testing override
- Modal now properly closes before tutorial starts

Issue 2 - Tutorial message overlapping floating action bar:
- Change TutorialMessage position from bottom-4 to center of screen
- Use top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 for true center
- Message now displays prominently in center, not at bottom
- Update comment: "contextual placement" → "center of screen for maximum visibility"

Before: bottom-4 left-1/2 -translate-x-1/2 (bottom center)
After: top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 (true center)

* fix(49-03): close WelcomeModal when starting tutorial

Problem: WelcomeModal (original quickstart modal with "New Project", "Load Workflow",
etc.) remained visible when user clicked "Show me how" to start tutorial, blocking the
tutorial UI.

Root cause: WelcomeModal is controlled by workflowStore.showQuickstart state and was not
being closed when tutorial started.

Solution:
- Import setShowQuickstart from useWorkflowStore
- Add setShowQuickstart(false) to handleStartTutorial
- WelcomeModal now closes before tutorial overlay appears

Now when tutorial starts, both FTUXModal and WelcomeModal are closed, allowing tutorial
overlay to display without obstruction.

* fix(49-03): implement complete tutorial progression flow

Problem: Tutorial stuck on "Let's cook." message without progressing.

Root causes:
1. Step 1 (welcome) had no requiredAction, so action detection never triggered
2. Steps 3-5 were placeholder steps with no content or actions
3. No auto-advance logic for informational steps

Solution:

ftuxStore.ts - Replace placeholder steps with real tutorial:
- Step 1: "Let's cook." (welcome, auto-advances after 3s)
- Step 2: "Click the Image button to add an image node." (highlights image button, requires add-image-node)
- Step 3: "Now add an Output node to see your results." (highlights output button, requires add-output-node)
- Step 4: "You're all set! Connect nodes to build workflows, or press Cmd+Enter to run." (completion, auto-advances)
- Add "add-output-node" to TutorialStep requiredAction type

TutorialOverlay.tsx - Add auto-advance and output detection:
- Steps without requiredAction now auto-advance after 3 seconds (typewriter completes ~2s)
- Add detection for "add-output-node" action (checks for node.type === "output")
- Early return cleanup timer to prevent memory leaks

Tutorial now flows: Welcome → Add Image → Add Output → Complete
Each step progresses based on user action or auto-advances for info steps.

* fix(49-03): make tutorial highlighted elements clickable and visible

Problem 1: Floating action bar was darkened during tutorial even though it
contains the highlighted image button that user needs to see and click.

Problem 2: Image button was not clickable - Layer 3 "clickable window" was
blocking clicks instead of allowing them through.

Root cause: ElementHighlight had full-screen dimmed overlay (Layer 1) blocking
clicks, and Layer 3 created an empty div that blocked the actual element.

Solution - Use box-shadow cutout technique:
- Remove solid dimmed overlay (bg-black/60)
- Remove Layer 3 entirely (not needed)
- Use box-shadow: "0 0 0 9999px rgba(0, 0, 0, 0.6)" on positioned div
- Creates dimmed overlay with cutout hole where highlighted element is
- Highlighted element remains fully visible (not dimmed)
- Highlighted element is fully clickable (no overlay blocking it)
- Everything else gets dimmed

FloatingActionBar.tsx:
- Import useFTUXStore (prepared for future use)
- Add tutorial state awareness (not currently used but ready for expansion)

ElementHighlight.tsx:
- Replace full-screen overlay + clickable window with box-shadow cutout
- Simpler 2-layer approach: dimmed background with hole + blue ring
- All pointer-events-none, so nothing blocks the actual DOM element

* fix(49-03): resolve Zustand SSR hydration issue in FloatingActionBar

Error: "The result of getServerSnapshot should be cached to avoid an infinite loop"
at FloatingActionBar (src/components/FloatingActionBar.tsx:345:58)

Same issue as WorkflowCanvas - direct useFTUXStore hook call during SSR.

Solution (identical pattern to WorkflowCanvas fix):
- Replace direct useFTUXStore hook with useState + useEffect pattern
- Initialize with false defaults (SSR-safe, no hydration mismatch)
- Subscribe to ftuxStore on client-side only via useEffect
- Initialize state with getState() after subscription
- Return cleanup function to unsubscribe on unmount

Before: const { tutorialActive, lockedFeatures } = useFTUXStore(...)
After: useState + useEffect subscription (client-side only)

This prevents the SSR hydration error while maintaining reactive updates.

* chore(49-03): restore production FTUX localStorage check

- Remove testing override that forced FTUX to show every time
- Restore production code: if (!getFTUXCompleted()) { setShowFTUX(true); }
- Remove TODO comment about reverting
- FTUX now only shows on first visit as intended

* feat(tutorial): add connection drop menu workflow steps

Extend the FTUX tutorial with 4 new steps that teach users how to use the
connection drop menu workflow pattern:

Step 6: Drag from output handle
- Prompts user to drag from the image node's output handle
- Tracks drag start via onConnectStart handler

Step 7: Release in empty space
- Prompts user to release to show the connection drop menu
- Tracks menu appearance via handleConnectEnd

Step 8: Explain connection menu
- Highlights the drop menu with blue ring
- Explains it shows compatible nodes
- Requires click to continue

Step 9: Select Generate Image
- Highlights "Generate Image" button in menu
- Tracks nanoBanana selection via handleMenuSelect
- Only advances when selected from menu (not FloatingActionBar)

Step 10: Tutorial complete
- Shows completion message with workflow tips
- Auto-advances after 3s and marks FTUX done

Implementation details:
- Add 3 new requiredAction types to TutorialStep interface
- Add 3 state tracking flags to FTUXState (connectionDragStarted, etc.)
- Add tutorial tracking in WorkflowCanvas connection lifecycle
- Add data-tutorial attributes for highlighting menu elements
- Import OnConnectStart type and create handleConnectStart handler
- Track menu appearance and nanoBanana selection with tutorialActive guards

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* refactor(tutorial): simplify drag-and-drop flow

Combine drag and drop instructions into a single step and immediately
highlight the Generate Image button when the context menu appears:

Changes:
- Combine step 6 (drag) and step 7 (drop) into one: "Drag from the output
  handle and drop into empty space"
- Remove step 8 (explain menu) - go straight to highlighting Generate Image
- Step 6 now waits for menu to appear (show-connection-menu)
- Step 7 highlights Generate Image button immediately (add-nanoBanana-from-menu)

Removed unused tracking:
- Remove start-connection-drag requiredAction type
- Remove connectionDragStarted state flag and setter
- Remove handleConnectStart callback from WorkflowCanvas
- Remove onConnectStart prop from ReactFlow
- Remove OnConnectStart import

New flow is cleaner and more direct:
Step 5: Explain outputs (click to continue)
Step 6: Drag and drop to show menu (auto-advance)
Step 7: Select Generate Image (auto-advance)
Step 8: Complete

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tutorial): highlight Generate Image button immediately

Combine drag-and-drop and selection steps into one to ensure the Generate
Image button is highlighted as soon as the connection menu appears.

Problem:
- Previous flow had two separate steps (drag-drop, then select)
- 1 second delay between menu appearing and Generate Image highlighting
- Output handle was highlighted while menu was already visible (confusing)

Solution:
- Single step: "Drag from the output handle and drop into empty space. Then
  select 'Generate Image'."
- highlightSelector targets the Generate Image button from the start
- ElementHighlight polls every 500ms, so highlights button immediately when
  menu appears (no delay)
- Cleaner UX: instruction → action → immediate visual feedback

Removed:
- show-connection-menu requiredAction (no longer needed)
- connectionMenuShown state flag and setter
- Tutorial tracking in handleConnectEnd

New flow:
- Step 5: Explain outputs (click to continue)
- Step 6: Drag, drop, select Generate Image (highlight on button, auto-advance)
- Step 7: Complete

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tutorial): increase highlight z-index above connection menu

The ElementHighlight component was rendering at z-index 91, but the
ConnectionDropMenu is at z-index 100, causing the highlight ring to
appear behind the menu.

Change: Increase ElementHighlight z-index from 91 to 101

This ensures the pulsing blue ring appears on top of the menu while
still allowing clicks through (pointer-events-none).

Z-index stack:
- ElementHighlight: 101 (above menu)
- ConnectionDropMenu: 100
- Skip tutorial button: 94
- TutorialMessage: 93
- Click overlay: 92

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tutorial): highlight output handle when prompting drag action

Split the combined step back into two sequential steps with proper highlights
and instant transition between them.

Problem:
- Single step told user to "Drag from the output handle" but highlighted
  the Generate Image button (which doesn't exist yet)
- Confusing visual feedback - wrong element highlighted for the instruction

Solution:
- Step 6: "Drag from the output handle and drop into empty space."
  - Highlights: node-output-handle
  - Action: show-connection-menu
  - advanceDelay: 0ms (instant transition)

- Step 7: "Select 'Generate Image' to add an AI image generation node."
  - Highlights: generate-image-option
  - Action: add-nanoBanana-from-menu
  - advanceDelay: 1000ms (default)

New feature: advanceDelay property
- Added to TutorialStep interface
- Configurable delay before advancing to next step after action completes
- Default: 1000ms (preserves existing behavior)
- Step 6 uses 0ms for instant transition when menu appears

Flow:
1. User sees output handle highlighted → drags and drops
2. Menu appears → step advances instantly (0ms delay)
3. Generate Image button immediately highlighted
4. User clicks → tutorial advances after 1s

Restored:
- show-connection-menu requiredAction
- connectionMenuShown state and setter
- Tutorial tracking in handleConnectEnd

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tutorial): subscribe to ftux state for action detection

The action detection useEffect wasn't re-running when connectionMenuShown
or nanoBananaAddedFromMenu changed because these states weren't in the
dependency array.

Problem:
- User drags and drops → menu appears
- setConnectionMenuShown(true) updates ftuxStore
- But action detection useEffect doesn't re-run (missing dependency)
- Step doesn't advance to highlight Generate Image button

Solution:
- Subscribe to connectionMenuShown and nanoBananaAddedFromMenu at component level
- Use these subscribed values instead of getState() calls
- Add them to useEffect dependency array

Now when these states change:
1. Component re-renders with new values
2. useEffect re-runs due to dependency change
3. Action is detected as completed
4. Step advances with configured delay (0ms for instant transition)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(tutorial): add prompt node and connection steps

Extend tutorial with steps 8-9 to teach users:
- Adding nodes via FloatingActionBar (different from connection menu)
- Connecting nodes by dragging between existing handles

Changes:
- Add data-tutorial="prompt-button" to Prompt button
- Add data-tutorial="prompt-output-handle" to Prompt output handle
- Add "add-prompt-node" to requiredAction types
- Add step 8: Add Prompt node via FloatingActionBar
- Add step 9: Connect Prompt to Generate Image node
- Update step 10 (complete) message for clarity
- Add action detection for add-prompt-node in TutorialOverlay

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tutorial): wait for prompt node connection in step 9

Step 9 was advancing immediately because it checked for ANY edges,
but an edge already existed from step 7 (Image → Generate Image).

Changes:
- Add "connect-prompt-node" requiredAction type
- Update step 9 to use "connect-prompt-node" instead of "connect-nodes"
- Add detection logic that specifically checks for edges FROM prompt nodes
- Track edges in TutorialOverlay component state for reactive detection
- Add edges to useEffect dependency array

Now step 9 correctly waits for user to connect the prompt node
before advancing to the completion step.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat: prevent node overlap on creation with automatic collision detection

Implements AABB collision detection to automatically place new nodes in collision-free positions. When users add nodes via FloatingActionBar or keyboard shortcuts, the system now finds the nearest free position using a spiral search pattern (right, down, left, up, diagonals).

Changes:
- Add spatialLayout.ts with rectanglesIntersect() and findNearestFreePosition()
- Update addNode() to use collision detection before placing nodes
- Remove random offset from FloatingActionBar for more deterministic placement
- Use consistent 20px gap (COLLISION_GAP) matching existing STACK_GAP pattern

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(tutorial): extend FTUX with content setup and resource guidance

Add four new tutorial steps to guide users through completing their first workflow:
- Prompt users to add text to the Prompt node
- Prompt users to add an image to the Image node
- Instruct users to run the workflow with Cmd/Ctrl+Enter
- Inform users about saving projects, templates, and Discord community

This ensures users complete a full workflow cycle during onboarding and know where to find help and resources.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tutorial): remove emojis from tutorial messages

Remove decorative emojis from the save-and-resources and completion steps for a cleaner, more professional appearance.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(tutorial): improve viewport zoom timing with auto-populated nodes

Increase timeout from 400ms to 600ms and improve viewport setting logic
to ensure proper 0.7 zoom level when tutorial image node is added with
pre-loaded base64 data. Fetch fresh nodes from store and extend animation
duration for smoother transition.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(tutorial): delay auto-population until after prompt connection

Change tutorial flow to create empty nodes initially and auto-populate
with sample content only after the prompt node is connected to generate.
This maintains hands-on learning while still removing friction.

Changes:
- Nodes created empty during tutorial
- Auto-populate after "connect-prompt-node" step completes
- Switch sample image: model.png → owl.jpg
- Update prompt: "wearing aviator sunglasses and a leather jacket"
- Add nodesPopulated ref to prevent duplicate population

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(tutorial): improve messaging, dual highlights, and pulsing animation

- Change welcome message: "Let's cook" → "Let's go over the basics"
- Add dual highlight for connect-prompt step: both prompt output and
  generate text input handles are now highlighted simultaneously
- Position connect-prompt message on left side of screen
- Update ElementHighlight to support array of selectors
- Add data-tutorial attribute to generate node's text input handle
- Pulsing animation already present via pulse-ring animation

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* feat(tutorial): implement mock execution and organized node demonstration

- Add mock workflow execution to save API costs during tutorial
  - Mock execution simulates 5-second generation time with edge animations
  - Loads pre-made owl aviator image instead of calling Gemini API
  - Provides realistic experience without incurring charges

- Implement visible workflow tree demonstration
  - Automatically builds branching workflow after mock execution
  - Video branch: Prompt → Generate Video → Output
  - LLM branch: Prompt → LLM → Generate Image #2 → Output
  - Clean horizontal layout with 350px spacing between nodes
  - Vertical separation of ±350px for clear branch distinction

- Improve user experience
  - Auto-close run menu when advancing past tutorial steps
  - Unlock canvas navigation after demonstration completes
  - Zoom to 0.35 with centered viewport for complete tree overview
  - Updated LLM prompt for nightclub scene generation

- Add tutorial assets
  - Add owl aviator image (public/tutorial/owl-aviator.png)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix: restore .env.example file

Restore .env.example that was accidentally deleted in commit 9be881c.
This file is needed as a reference for users to set up their environment.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

3 months ago

owl-aviator.png

feat: Tutorial improvements with mock execution and organized demonstration (#112)

3 months ago