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.
The once-per-browser gate
Section titled “The once-per-browser gate”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 writtenexport function markIntroSeen(): void; // sets the flag to "1"; SSR no-opexport function shouldShowIntro(): boolean; // !hasSeenIntro(), and false on SSRThe 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 wiring
Section titled “The store wiring”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.
The stepper dialog
Section titled “The stepper dialog”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 innerIntroSteppercomponent thatIntroGuideDialogmounts fresh on each open (key="intro-stepper"). ItsuseState(0)initializer handles the reset, avoiding theset-state-in-effectlint rule that firingsetStep(0)in an effect would trip. - The platform modifier is resolved at render via
modifierSymbol()fromsrc/lib/keyboard/shortcuts, so ⌘ vs Ctrl renders correctly.
Reopening from Help
Section titled “Reopening from Help”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.
Where this fits
Section titled “Where this fits”- State Management —
isIntroOpenin 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.