Skip to content

Onboarding

The first-run intro guide is a 4-step stepper that auto-opens the first time a user loads the app, then never again — unless they reopen it from the Help dialog. It spans three layers (a localStorage gate, a store flag, and a dialog component), so this page collects the contract in one place.

src/lib/onboarding/intro.ts owns the gate — a pure, SSR-guarded localStorage module mirroring the conventions of src/lib/serialisation/storage.ts:

export const INTRO_LOCAL_STORAGE_KEY = "graph-board-seen-intro";
export function hasSeenIntro(): boolean; // false on SSR or before the flag is written
export function markIntroSeen(): void; // sets the flag to "1"; SSR no-op
export function shouldShowIntro(): boolean; // !hasSeenIntro(), and false on SSR

The flag is stamped at open time, not at close time — the key design decision. The store calls markIntroSeen() in the same block that sets isIntroOpen = true, so the intro shows exactly once even if the user force-closes the tab mid-tour, reloads during the stepper, or dismisses it via Esc/backdrop. Any close path (Esc, backdrop click, “Got it”) already counts as “seen”.

shouldShowIntro() returns false during SSR (typeof window === "undefined") — auto-opening a modal is inherently client-only, and the explicit guard prevents a hydration mismatch where the server renders closed and the client pops the modal open.

The store (src/store/graph-store.ts) holds a single UI flag and two actions, paralleling the Help dialog’s isHelpOpen / openHelp / closeHelp:

isIntroOpen: boolean;
openIntro: () => void; // set({ isIntroOpen: true })
closeIntro: () => void; // set({ isIntroOpen: false })

The auto-open happens in hydrate(), right after the graph is loaded and the undo history is cleared:

if (shouldShowIntro()) {
markIntroSeen();
set({ isIntroOpen: true });
}

isIntroOpen is not reset by reset() or importJson — the intro is a once-per-browser flag, independent of the document lifecycle. New graphs and imports won’t re-trigger it.

src/components/graph-editor/IntroGuideDialog.tsx is a controlled, presentational dialog (isOpen / onClose) that mirrors the visual and a11y shape of the other dialogs: backdrop click closes, Escape closes (with stopPropagation so the global shortcuts hook doesn’t also see it), and the primary button is auto-focused on open.

It is a 4-step carousel:

Step Concept Icon
1 Place a vertex — press V, click the canvas MousePointer2
2 Connect vertices — press E, click two vertices GitBranch
3 Edit the phase — double-click a label Pencil
4 Compute & get help — ⌘/Ctrl+Enter, ? Calculator

Implementation notes worth knowing if you touch it:

  • The dialog never touches localStorage. It is purely presentational — the store owns the “seen” stamp. This keeps it consistent with the sibling dialogs and means any close path is correct by construction.
  • State resets by remount, not by effect. The stepper state (step) lives in an inner IntroStepper component that IntroGuideDialog mounts fresh on each open (key="intro-stepper"). Its useState(0) initializer handles the reset, avoiding the set-state-in-effect lint rule that firing setStep(0) in an effect would trip.
  • The platform modifier is resolved at render via modifierSymbol() from src/lib/keyboard/shortcuts, so ⌘ vs Ctrl renders correctly.

The Help dialog (HelpDialog.tsx, titled “Help”) has a “Show intro guide” button at the top of its body. Clicking it closes Help first (so the intro isn’t stacked behind a modal) and then opens the intro via an onShowIntro?: () => void prop. The orchestration lives in GraphEditor.tsx, which passes openIntro to the Help dialog — the dialog itself stays presentational, like the ConfirmationDialog onConfirm pattern.

  • State Management — isIntroOpen in the store-shape list, and why UI flags like it live in the store rather than component state.
  • Viewport & Camera — the other thing hydrate() does besides open the intro.