Skip to content

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.

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 onNodesChange chokepoint — every React Flow position change routed through the store,
  • vertex creation (addVertexAt),
  • hydration (hydrateDocument snaps 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.

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.

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.

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):

GraphEditor.tsx
<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.

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.

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.

  • State Management — the tabs/activeTabId machinery that owns the per-tab viewport records.
  • Onboarding — the other action hydrate() takes (opening the intro guide).