Viewport & Camera
The canvas viewport (pan and zoom) is controlled by two things: a static defaultViewport that
sets the empty-canvas starting point, and per-tab viewport records in the store that restore
each tab’s camera on switch and frame a freshly loaded graph. Position changes are additionally
snapped to the grid. This page documents all three, and the bug the design exists to avoid.
Grid snapping
Section titled “Grid snapping”Every node position change snaps to a fixed grid: GRID_SIZE = 24 and snapPosition live in
src/lib/graph/operations.ts (pure, unit-testable). Snapping is applied at three points:
- the
onNodesChangechokepoint — every React Flow position change routed through the store, - vertex creation (
addVertexAt), - hydration (
hydrateDocumentsnaps on load, so old/non-aligned docs migrate to the grid).
GRID_SIZE must match the canvas background — GraphEditor.tsx renders
<Background variant={BackgroundVariant.Dots} gap={GRID_SIZE}>, so every snapped position lands on
a dot. The same component also renders <Controls /> and <MiniMap />. GRID_SIZE and the
PASTE_OFFSET_STEP/IMPORT_OFFSET_STEP constants are separate: the paste/import offsets are
coincidentally grid-sized, but don’t change one expecting the other to follow.
The bug this design fixes
Section titled “The bug this design fixes”A bare <ReactFlow fitView> prop writes fitViewQueued: true into xyflow’s internal store once at
mount. That queued fit only executes when nodesInitialized becomes true — which requires nodes to
be measured (have real width/height).
On an empty graph there are no nodes to measure, so nodesInitialized never flips, and
fitViewQueued stays true indefinitely. The instant the user adds the first vertex, it gets
measured → the stale queued fit finally fires → the camera zooms in and snaps that vertex to center.
That disruptive jump is why the app does not use the bare fitView prop — and with tabs the
trap would be re-armed on every switch to an empty tab, which is why the explicit mechanism below
applies the same gate per tab.
The empty-canvas start: defaultViewport
Section titled “The empty-canvas start: defaultViewport”GraphEditor.tsx sets an explicit starting viewport:
<ReactFlow // … defaultViewport={{ x: 0, y: 0, zoom: 2 }}>Because the bare fitView prop is absent, nothing else computes the initial transform — so
defaultViewport is the sole determinant of where an empty canvas begins. It starts at zoom 2
(origin at {0, 0}), so a fresh canvas feels close-in rather than far-out.
This only affects the empty-canvas start. A tab whose camera was never moved falls back to the fit path below; a tab with a recorded camera restores it exactly.
Per-tab viewports
Section titled “Per-tab viewports”Every TabRecord carries a session-only viewport: { x, y, zoom } | null — null until the user
moves the camera. GraphEditor.tsx records the camera on every move end and restores it whenever
the active tab changes (including the initial hydrate):
<ReactFlow // Record pan/zoom into the active tab's record. onMoveEnd={(_, viewport) => commitViewport(viewport)} // …/>
// On tab switch (or hydrate): restore the incoming tab's camera.useEffect(() => { if (!activeTabId) return; const tab = useGraphStore.getState().tabs.find((t) => t.id === activeTabId); if (!tab) return; if (tab.viewport) { reactFlow.setViewport(tab.viewport); } else if (tab.nodes.length > 0) { reactFlow.fitView({ duration: 400 }); }}, [activeTabId, reactFlow]);commitViewport (a store action) writes the viewport into the active tab’s record — a tabs-array
change, so it never lands on the undo stack (the viewport isn’t partialized) and it rides the
debounced autosave like any other tab mutation.
The fit fallback fires only when the tab is non-empty — the same gate the old hydrate-based
refit had. A fresh empty tab stays at defaultViewport (zoom 2), and placing its first vertex is
just “append a node”, with no camera change. That is what prevents the stale-snap bug above: the
automatic paths never fit an empty canvas.
Viewports are session-only: they are not part of the v2 document, so a reload starts every tab
at defaultViewport and re-fits the non-empty ones.
The three framing paths
Section titled “The three framing paths”| Trigger | Mechanism | Frames empty graph? |
|---|---|---|
| Empty canvas start | defaultViewport (zoom 2) |
n/a — this is the empty start |
| Tab whose camera was never moved | activeTabId effect → fitView() (non-empty gate) |
no (gated on nodes) |
| Tab with a recorded camera | activeTabId effect → setViewport(viewport) |
n/a — exact restore |
| Import a graph | importJson() → merge at viewport centre |
n/a — no camera change |
Manual F key |
useKeyboardShortcuts → fitView({ padding: 0.1 }) |
yes (user-initiated) |
Only the manual F shortcut fits an empty graph — and that’s intentional, since the user asked
for it. The automatic paths never do.
Why not just fitView?
Section titled “Why not just fitView?”To summarize the design choice: the bare fitView prop’s queue is fire-and-forget with a hidden
dependency on node measurement; the activeTabId effect is an explicit, conditional,
immediately-resolving call — and commitViewport keeps the camera honest per tab. Swapping the
mechanism removes the hidden dependency:
Bare fitView prop |
activeTabId effect | |
|---|---|---|
| When does it fire? | Whenever nodes finally initialize | Exactly when the store changes activeTabId |
| State left behind? | fitViewQueued lingers true on empty graph |
none — fitView() runs and returns |
| Empty-graph behavior | Trap armed, springs on first node | never called |
This is why the non-empty gate in the effect and the absence of the fitView prop are a pair —
removing either one alone reintroduces the snap.
Where this fits
Section titled “Where this fits”- State Management — the tabs/
activeTabIdmachinery that owns the per-tab viewport records. - Onboarding — the other action
hydrate()takes (opening the intro guide).