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
..
sample-images	Update model-product template image and style-transfer prompt	6 months ago
template-thumbnails	feat: Template Explorer, Comment Navigation, and Output Node Improvements	6 months ago
tutorial	feat: Tutorial improvements with mock execution and organized demonstration (#112)	3 months ago
banana_icon.png	header	7 months ago
node-banana.png	docs: redesign README with hero layout and updated screenshot	4 months ago