Skip to content

ONBOARDING_FIXES.md

Latest commit

 

History

History
149 lines (122 loc) · 7.22 KB

ONBOARDING_FIXES.md

File metadata and controls

149 lines (122 loc) · 7.22 KB

Onboarding Flow Fixes & UX Improvements

Issues Fixed

1. Modal Closing Prematurely

Problem: The onboarding modal was closing immediately when clicking local file buttons, before the universe actually loaded. This meant users saw the modal disappear but then potentially reappear if the load failed.

Solution:

  • Removed immediate handleClose() calls from local file buttons in AlphaOnboardingModal.jsx
  • Added auto-close logic in NodeCanvas.jsx that watches isUniverseLoaded, hasUniverseFile, and universeLoadingError states
  • Modal now closes automatically only when the universe successfully loads
  • Lines changed:
    • AlphaOnboardingModal.jsx:287, 305 (removed handleClose calls)
    • AlphaOnboardingModal.jsx:562 (removed handleClose from GitHub flow)
    • NodeCanvas.jsx:1230-1234 (added auto-close logic)

2. File Handle Reconnection Issue

Problem: When loading an existing local file, the file handle was stored in fileStorage.js but not communicated to universeBackend.js (which manages saves through the new universe system). This caused "reconnect to continue saving locally" prompts.

Solution:

  • Added file handle bridging after successful file creation/opening
  • After loadUniverseFromFile() completes, the file handle is retrieved from fileStorage and registered with universeBackend
  • Added 200ms delay (100ms setTimeout + 100ms internal wait) to ensure universe backend has initialized
  • Added comprehensive error handling and logging
  • Lines changed:
    • NodeCanvas.jsx:10784-10810 (createLocal handler)
    • NodeCanvas.jsx:10828-10854 (openLocal handler)

Key implementation details:

  • Uses setTimeout to avoid blocking the UI
  • Waits for universe backend to initialize before attempting to bridge
  • Logs success/failure clearly for debugging
  • Non-fatal errors (fileStorage's autosave may still work as fallback)

3. GitHub Flow Modal Behavior

Problem: When selecting GitHub with existing OAuth+App connections and clicking "Start with GitHub Sync", the modal was closing immediately before the universe loaded, creating an inconsistent UX.

Solution:

  • Removed handleClose() from the "Start with GitHub Sync" button (line 562)
  • Modal now auto-closes when the universe loads, consistent with local file behavior
  • GitNativeFederation panel opens properly for all GitHub steps (lines 10889-10890)

4. GitNativeFederation Panel Opening

Status: Already working correctly!

  • Lines 10889-10890 in NodeCanvas.jsx ensure the federation panel opens for ALL GitHub flows
  • This code runs before the step-specific logic, so it applies universally
  • Resume logic (lines 1237-1252) ensures the panel opens after OAuth/App redirects

Flow Summary

Local File Creation Flow

  1. User clicks "Create New" button
  2. File picker opens, user selects location
  3. Empty universe created and written to file
  4. File handle stored in both fileStorage and universeBackend
  5. Universe marked as loaded (hasUniverseFile: true, isUniverseLoaded: true)
  6. Modal auto-closes when load completes
  7. Auto-save enabled for seamless saving

Local File Opening Flow

  1. User clicks "Load Existing" button
  2. File picker opens, user selects file
  3. File content loaded and validated
  4. Universe data imported into store
  5. File handle stored in both fileStorage and universeBackend
  6. Universe marked as loaded
  7. Modal auto-closes when load completes
  8. Auto-save enabled for seamless saving

GitHub Flow (Existing Connections)

  1. User clicks "Start with GitHub Sync"
  2. Storage mode set to 'git'
  3. Left panel expands and switches to federation view
  4. Existing Git universe loaded (or empty state created)
  5. Universe marked as loaded
  6. Modal auto-closes when load completes

GitHub Flow (New Setup)

  1. User clicks OAuth/App buttons
  2. Storage mode set to 'git'
  3. Left panel expands and switches to federation view
  4. User redirected to GitHub for authentication
  5. After redirect, session flags trigger panel re-opening
  6. User completes setup in GitNativeFederation panel

Key Improvements

  1. Consistent UX: Modal behavior is now consistent across all paths (local and Git)
  2. No Reconnection Prompts: File handles properly bridged between systems
  3. Clear Logging: All operations log success/failure for debugging
  4. Graceful Error Handling: Non-fatal errors don't break the flow
  5. Proper Timing: Delays ensure systems are initialized before bridging
  6. Federation Panel: Always opens for Git flows as intended

New Features Added

5. Dismissable Onboarding Modal

Feature: Users can now close the onboarding modal at any time to explore Redstring, even without setting up a storage method.

Implementation:

  • Modal can be closed via backdrop click or close button
  • Closing sets redstring-alpha-welcome-seen in localStorage to prevent re-showing
  • Modal won't reappear unless user clears localStorage or has no universe setup
  • Successfully completing onboarding also marks it as seen
  • Lines changed:
    • NodeCanvas.jsx:1219-1242 (checks localStorage, marks as seen)
    • NodeCanvas.jsx:10777-10783 (marks as seen on manual close)
    • AlphaOnboardingModal.jsx:683 (enables backdrop closing)

Benefit: Users can explore the app without being forced through onboarding first. Browser-only storage works as a fallback.

6. "Connect" Button in Browser-Only Mode

Feature: When using browser-only storage (no file or Git connection), the save status indicator shows "Connect" instead of "Not Saved", and clicking it opens the GitNativeFederation panel.

Implementation:

  • SaveStatusDisplay now detects browser-only mode by checking:
    • sourceOfTruth === 'browser'
    • OR no local file handle AND no Git repo linked
  • When in browser-only mode, displays "Connect" with pointer cursor
  • Clicking opens left panel with federation view
  • Hover effect (scale 1.05) indicates it's interactive
  • Lines changed:
    • SaveStatusDisplay.jsx:6-78 (detection and state management)
    • SaveStatusDisplay.jsx:80-134 (clickable UI with hover effects)
    • NodeCanvas.jsx:10610-10615 (wires up federation panel opening)

Benefit: Clear call-to-action for users to set up persistent storage, directly accessible from the always-visible status indicator.

Testing Checklist

Core Onboarding

  • Create new local file → modal closes after creation
  • Load existing local file → modal closes after load
  • Load existing file → save changes → no reconnection prompt
  • GitHub with existing connections → modal closes, federation panel opens
  • GitHub OAuth flow → redirect works, panel opens on return
  • GitHub App flow → redirect works, panel opens on return
  • Cancel file picker → modal stays open with error message
  • File load error → modal shows error, stays open

New Features

  • Close onboarding modal via backdrop → modal doesn't reappear
  • Close onboarding modal via X button → modal doesn't reappear
  • Complete onboarding → modal doesn't reappear on refresh
  • Browser-only storage → status shows "Connect" instead of "Not Saved"
  • Click "Connect" → left panel opens with GitNativeFederation view
  • Hover over "Connect" → button scales up slightly
  • Set up file or Git → status changes from "Connect" to normal status