@smartmemory/wiki-components 0.5.0 → 0.6.0

package/src/graph/pages/GraphPage.jsx

@@ -0,0 +1,703 @@
+import React, { Suspense, lazy, useEffect, useMemo, useRef, useState } from "react";
+import { Link, useAspectHint, useQuery, useSearchParams, useWiki } from "../host";
+import { useDataClient } from "../../data-client";
+import ErrorBox from "../../parts/ErrorBox";
+import { perfNow, perfSpan } from "../lib/perf";
+import { INPUT, noteUrl } from "../../lib";
+import { LOD_N, MAX_NODES, buildGraph, neighbourhood, recolour, scopeColors } from "../lib/wikiGraph";
+import {
+  DIM_DEFAULT, PARAM, PHYSICS_DEFAULTS, adjacencyOf, chooseView, DIM_MAX, formatHidden, hideEveryGroup, hopSet, localGraph, parseDim, parseHidden, parsePhysics, showEveryGroup,
+} from "../lib/graphView";
+import {
+  autoBase, baseOffset, breadcrumb, buildLevelView, currentLevel, expand, expandToDepth, folderId, folderPathOf, folderPaths, formatLevels, formatRange, hubsFor,
+  isFolderId, maxLevel, parseLevels, parseRange, upOne,
+} from "../lib/graphLevels";
+import { folderGroups } from "../lib/layoutEngine";
+import { FIND_DEBOUNCE_MS, countText, drawnFor, findMatches, hasTerm, litIds } from "../lib/graphFind";
+import { createExplorer, visiblePredicate } from "../lib/graphExplore";
+import { prefersReducedMotion, watchReducedMotion } from "../lib/reducedMotion";
+import { readIdleTurn, writeIdleTurn } from "../lib/idleTurn";
+import { addStep, chipText, clearAll, folderCounts, omniRows, parseVerb, pushRecent, readExplore, readRecent, recentKey, removeStep, withExplore, exploreUnchanged, writeStore } from "../lib/graphShell";
+import { docUnder, requestTreeSync } from "../host";
+import { lassoHits, lassoText } from "../lib/graphLasso";
+import { SAVE_FAILED, appliedText, defaultViewName, deleteView, makeView, paramsOfUrl, readViews, restorablePins, saveView } from "../lib/graphViews";
+import { clearPathLens, pathNote, pathView, removeLens, setPathLens } from "../lib/graphPath";
+import { stepOrient } from "../lib/graphOrient";
+import { useColorMode } from "../host";
+import { hueFor, setGraphMode } from "../lib/graphTheme";
+import useDebounced from "../hooks/useDebounced";
+import PageHeader from "../../parts/PageHeader";
+import GraphCanvas from "../components/wiki/GraphCanvas";
+import GraphDocPane from "../components/wiki/GraphDocPane";
+import GraphBreadcrumb from "../components/wiki/GraphBreadcrumb";
+import GraphLevelPicker from "../components/wiki/GraphLevelPicker";
+import GraphLegend from "../components/wiki/GraphLegend";
+import DocCard from "../components/wiki/DocCard";
+import { CARD_HINT, escAction, useCardVisibility } from "../lib/cardVisibility";
+import { cardAnchor } from "../lib/docCard";
+import Omnibox from "../components/wiki/graph/Omnibox";
+import FilterChips from "../components/wiki/graph/FilterChips";
+import Loading from "../../parts/Loading";
+
+const GraphCanvas3D = lazy(() => import("../components/wiki/GraphCanvas3D")); // three.js loads only when the 3D view is drawn
+
+let webgl2 = null; // the probe's answer, cached: a throwaway canvas per render would leak contexts
+/** Is WebGL2 available (3D needs it)? Probed once on a throwaway canvas. `resetWebGL2Probe` is for tests. */
+function hasWebGL2() {
+  if (webgl2 === null) {
+    try { webgl2 = !!document.createElement("canvas").getContext("webgl2"); } catch { webgl2 = false; }
+  }
+  return webgl2;
+}
+export const resetWebGL2Probe = () => { webgl2 = null; };
+let warned3d = false; // the missing-WebGL2 warning is logged once per page load
+
+const PAGE = 200; // the graph query's page size limit
+const SHOWN_NEIGHBOURS = 40;
+const PANE_DEFAULT = 50, PANE_MIN = 25, PANE_MAX = 75; // the doc pane's share of the graph surface, in percent
+const PANEL = "pointer-events-auto rounded-lg border border-neutral-200/70 bg-ground/85 backdrop-blur";
+const BUTTON = "rounded-md border border-neutral-300 px-2 py-1 text-[13px] text-ink2 hover:text-ink disabled:opacity-40";
+// A pressed toolbar toggle (WIKI-GRAPH-2D-CLUSTER-ONCE-1, owner 2026-10-22: "the button should be backgrounded when on"): a filled
+// background on top of the blue border it already had. No graph toolbar toggle had a filled style before.
+const PRESSED = "border-blue-500 bg-blue-500/15 text-ink";
+
+/** Every doc of the workspace and the links between them (WIKI-GRAPH-VIEW-UX-1): the `graph` query with no root, in ONE
+ *  request (`page: {all: true}`, revalidated by ETag; WIKI-GRAPH-LOAD-1). A host without that mode answers
+ *  `invalid_request`: then page by cursor until done or MAX_NODES docs. `total` is the workspace's doc count, so a capped
+ *  fetch can say so. Timed as the `wiki-graph:fetch` measure. */
+export async function wholeGraph(workspace, client) {
+  const t0 = perfNow();
+  let items, edges = [], total = 0, layout = null; // layout: the host's served warm start, when it holds one (WIKI-GRAPH-WARMSTART-3D-1)
+  try {
+    const r = await client.graphAll({ workspace });
+    ({ items, edges, total } = r);
+    layout = r.layout || null;
+  } catch (e) {
+    if (e?.code !== "invalid_request") throw e;
+    console.warn("wiki graph: this host does not support the one-shot graph query (page.all); paging instead");
+    items = [];
+    let cursor = null;
+    do {
+      const r = await client.graphPage({ workspace, size: PAGE, ...(cursor ? { cursor } : {}) });
+      items.push(...r.items);
+      edges.push(...(r.edges || []));
+      total = r.total ?? items.length;
+      cursor = r.next_cursor || null;
+    } while (cursor && items.length < MAX_NODES);
+  }
+  perfSpan("wiki-graph:fetch", t0);
+  return { items: items.slice(0, MAX_NODES), edges: edges || [], total: Math.max(total ?? 0, items.length), layout };
+}
+
+/** One physics slider, 0..100 (ported from the spike's GraphG6Page, e95dfeb). */
+function Slider({ label, name, value, onChange }) {
+  return (
+    <label className="flex items-center gap-2 text-xs text-ink2">
+      <span className="w-24">{label}</span>
+      <input type="range" min={0} max={100} value={value} aria-label={label} onChange={(e) => onChange(name, Number(e.target.value))} className="w-28" />
+      <span className="w-6 text-right tabular-nums text-neutral-400">{value}</span>
+    </label>
+  );
+}
+
+const NO_GROUPS = new Set(); // the level view filters the legend before it aggregates, so the canvas masks nothing
+const FOLDER_GROUP = "(folders)";
+const isFormField = (el) => !!el && (["INPUT", "SELECT", "TEXTAREA"].includes(el.tagName) || el.isContentEditable);
+
+/** A level graph as the canvas draws it: folders get a title and a size-driven radius (their doc count), docs are as they were.
+ *  `areas` (layoutEngine folderGroups): a folder's most common area, its `bubbleGroup` for the cluster bubbles and targets
+ *  (WIKI-GRAPH-CLUSTER-REGROUP-1); its legend `group` and colour stay "(folders)". */
+const forCanvas = (lg, areas) => ({
+  links: lg.links,
+  contains: lg.contains, // hub folder -> drawn child: dashed lines and layout springs, not links
+  nodes: lg.nodes.map((n) => (n.kind === "folder" ? { ...n, title: `${n.label} (${n.size})`, group: FOLDER_GROUP, degree: n.size, bubbleGroup: areas?.get(n.id) ?? null } : n)),
+});
+const HOPS_DEFAULT = 2; // WIKI-GRAPH-FOCUS-HOPS-1: a focus lights 2 hops unless the URL says otherwise
+
+const STATE_TEXT = { running: "laying out", paused: "paused", settled: "settled" };
+
+/** The whole wiki as a graph, like Obsidian's (WIKI-GRAPH-OBSIDIAN-1): every doc a dot coloured by area or folder,
+ *  sized by its links, every link a line, drawn on the GPU (Canvas2D without WebGL) and laid out in a worker. Type a
+ *  title to focus a doc, click a dot to open it, scroll to zoom, drag to pan. The legend hides groups, a focused doc
+ *  shows only its neighbourhood (the hops stepper sets how far), the sliders tune the layout live. Everything a reader set lives in the
+ *  URL (`root`, `hide`, `hops`, `by`, `size`, `repel`, `link`, `centre`, `cluster`, `outlines`), so a link reproduces the view;
+ *  `?root=<doc id>` (a doc page's "Graph" link, and every old link) opens it focused on that doc.
+ *  WIKI-GRAPH-LEVELS-1 c2: it opens at level 0, one dot per top-level folder (sized by its docs, edges by the links between
+ *  folders). Double-click a folder to open it in place, Esc or the breadcrumb to go back up, "Show all docs" (`flat=1`)
+ *  for the flat graph. The open folders live in `lv=`. */
+export const GRAPH_ASPECTS = ["product", "category", "initiative", "status"];
+
+export default function GraphPage() {
+  const { workspace } = useWiki();
+  const client = useDataClient();
+  const { resolved: colorMode } = useColorMode();
+  setGraphMode(colorMode); // before the canvases render; they are keyed by it so a switch rebuilds the bases (UI-LIGHT-MODE-LM8-1)
+  const [sp, setSp] = useSearchParams();
+    const canvas = useRef(null);
+  const focusId = sp.get(PARAM.root) || null;
+  // `by=`: absent is "scope" (colours relative to the folder you are looking into, WIKI-GRAPH-3D-COLOR-SPHERES-1); area and folder stay global.
+  const by = sp.get(PARAM.by) === "folder" ? "folder" : sp.get(PARAM.by) === "area" ? "area" : "scope";
+  const hideRaw = sp.get(PARAM.hide) || "";
+  const hidden = useMemo(() => parseHidden(hideRaw), [hideRaw]); // one Set per value: GraphCanvas compares it by identity
+  const hops = Math.max(1, Math.min(4, Math.round(Number(sp.get(PARAM.hops))) || HOPS_DEFAULT)); // the focus's lit rings and the docs a focus draws (one param)
+  const dim = parseDim(sp.get(PARAM.dim)); // how dark the unlit nodes go while something is lit (one level, 2D and 3D, URL `dim=`)
+  const sizeByDegree = sp.get(PARAM.size) !== "flat";
+  const [repelRaw, linkRaw, centreRaw] = [sp.get(PARAM.repel), sp.get(PARAM.link), sp.get(PARAM.centre)];
+  const physics = useMemo( // one object per value triple: GraphCanvas messages the layout only when a value changes
+    () => parsePhysics(new Map([[PARAM.repel, repelRaw], [PARAM.link, linkRaw], [PARAM.centre, centreRaw]])),
+    [repelRaw, linkRaw, centreRaw],
+  );
+  const flat = sp.get(PARAM.flat) === "1"; // the flat graph of every doc; off (default) is the folder levels
+  const lvRaw = sp.get(PARAM.levels) || "";
+  const cluster = sp.get(PARAM.cluster) === "1"; // 3D: move each group's nodes into its own cluster; 2D: one clustered layout, then it stays put (WIKI-GRAPH-2D-CLUSTER-ONCE-1); off (default) is the plain force layout
+  const outlines = sp.get(PARAM.outlines) === "1"; // 3D group outlines while clustered: off by default (owner addendum 2026-10-21); 2D never draws outlines
+  const [idleTurn, setIdleTurnState] = useState(readIdleTurn); // "Turn slowly when idle" (3D only): off unless the reader switched it on, this browser only, never in the URL or a saved view
+  const [reduced, setReduced] = useState(() => prefersReducedMotion());
+  useEffect(() => watchReducedMotion(setReduced), []);
+  const setIdleTurn = (on) => { setIdleTurnState(on); writeIdleTurn(on); };
+  const [panelOpen, setPanelOpen] = useState(false); // the View drawer: closed at every width until the View button opens it (owner decision 4, WIKI-GRAPH-EXPLORE-1b-SHELL)
+  const forced = sp.get(PARAM.renderer) === "canvas" ? "canvas" : null;
+  const requestedView = sp.get(PARAM.view) === "2d" ? "2d" : sp.get(PARAM.view) === "3d" ? "3d" : null;
+  const [unavailable3d, setUnavailable3d] = useState(false); // the 3D surface could not start: stay on 2D
+  const has3d = hasWebGL2();
+  const view = unavailable3d ? "2d" : chooseView({ webgl2: has3d, requested: requestedView });
+  const [lassoSel, setLassoSel] = useState(null); // the 3D lasso's selection {ids, inside, behind}: local state like the View drawer, Esc clears it (EXPLORE-1c-UI)
+  const [lassoLive, setLassoLive] = useState(null); // {inside, behind} while the Shift-drag is down
+  const [pinIds, setPinIds] = useState([]); // the 3D surface's pinned docs (drag-to-pin, EXPLORE-1c-UI r2): page state for this surface only, never in the URL or history; the canvas clears it when the surface changes
+  const lassoMarks = useMemo(() => (lassoSel || pinIds.length ? { ...(lassoSel ? { selected: new Set(lassoSel.ids) } : {}), ...(pinIds.length ? { pinned: new Set(pinIds) } : {}) } : null), [lassoSel, pinIds]); // one object per selection or pin set: the canvas relights on identity
+  useEffect(() => { if (view !== "3d") { setLassoSel(null); setLassoLive(null); setPinIds([]); } }, [view]); // no lasso or pin in 2D
+  useEffect(() => {
+    if (requestedView === "3d" && !has3d && !warned3d) {
+      warned3d = true;
+      console.warn("wiki graph: view=3d needs WebGL2, which is unavailable, drawing the 2D view instead.");
+    }
+  }, [requestedView, has3d]);
+  const docId = sp.get(PARAM.doc) || null; // the doc the right-hand pane shows (WIKI-GRAPH-DOC-PANE-1)
+  const [paneCollapsed, setPaneCollapsed] = useState(false);
+  const [panePct, setPanePct] = useState(PANE_DEFAULT);
+  const surface = useRef(null);
+  const [term, setTerm] = useState("");
+  const [layout, setLayout] = useState({ state: null, ms: null });
+
+  const q = useQuery({ queryKey: ["graph-whole", workspace], queryFn: () => wholeGraph(workspace, client), staleTime: 60_000 });
+  // The feature aspects stay greyed until WIKI-GRAPH-ASPECT-GROUP-1 groups by them; the hint says why (WIKI-FEATURE-VIEWS-1).
+  const aspectHint = useAspectHint();
+  const flatGraph = useMemo(() => (q.data ? buildGraph(q.data.items, q.data.edges, { by: by === "scope" ? "folder" : by, layout: q.data.layout }) : null), [q.data, by]);
+  const adj = useMemo(() => (flatGraph ? adjacencyOf(flatGraph.links) : null), [flatGraph]);
+  // Filter chips (WIKI-GRAPH-EXPLORE-1b-SHELL): the `x` param holds the stack; its mask is one more visibility predicate, ANDed with the legend's and the local graph's.
+  const xRaw = sp.get(PARAM.x);
+  const explore = useMemo(() => readExplore(xRaw), [xRaw]);
+  const steps = explore.state.steps;
+  const explorer = useMemo(() => (flatGraph ? createExplorer(flatGraph) : null), [flatGraph]);
+  const run = useMemo(() => (explorer && steps.length ? explorer.run(steps) : null), [explorer, steps]);
+  const stackVisible = useMemo(() => (run ? visiblePredicate(explorer.idx, run.mask) : undefined), [run, explorer]);
+  const folderCount = useMemo(() => (flatGraph ? folderCounts(flatGraph.nodes) : new Map()), [flatGraph]);
+  const focus = flatGraph && focusId ? flatGraph.byId.get(focusId) || null : null;
+  const cardAtNode = view === "3d" && !!focus; // the doc card sits at the node in 3D (DocCard); 2D keeps it in the panel (no screen-position API there)
+  const card = useCardVisibility(focusId, cardAtNode); // the card hides itself after a few seconds in 3D; Esc and the info button show/hide it (2D: the panel info, no timer)
+  // the drawn set: the whole graph, or with a focus only the docs within `hops` links of it (WIKI-GRAPH-FOCUS-HOPS-ONLY-1)
+  const localIds = useMemo(() => (focus ? hopSet(adj, focus.id, hops, flatGraph.byId) : null), [flatGraph, adj, focus, hops]);
+  // The base level: a single folder is opened for the reader (WIKI-GRAPH-LEVELS-AUTOEXPAND-1). `lv=` holds only their own expansions on top.
+  // In scope mode the keys (hence `hide=`) depend on the level, so the base ignores the legend: hide -> base -> scope -> keys -> hide would loop.
+  const baseVisible = useMemo(() => {
+    if (!flatGraph) return undefined;
+    const hide = by === "scope" ? NO_GROUPS : hidden;
+    return hide.size || localIds || stackVisible ? (id) => !hide.has(flatGraph.byId.get(id)?.group) && (!localIds || localIds.has(id)) && (!stackVisible || stackVisible(id)) : undefined;
+  }, [flatGraph, by, hidden, localIds, stackVisible]);
+  const base = useMemo(() => (flatGraph && !flat ? autoBase(flatGraph, baseVisible) : NO_GROUPS), [flatGraph, flat, baseVisible]);
+  const explicit = useMemo(() => parseLevels(lvRaw, flatGraph ? folderPaths(flatGraph) : null, base), [lvRaw, flatGraph, base]); // one Set per value, only real folders
+  const explicitOpen = useMemo(() => (base.size ? new Set([...base, ...explicit]) : explicit), [base, explicit]); // the reader's own folders, on the base
+  // The level picker (`lr=`): a depth range, 1-1 by default. Its folders open on top of the reader's own (`lv=` never holds them).
+  const offset = useMemo(() => baseOffset(base), [base]);
+  const maxLv = useMemo(() => (flatGraph ? maxLevel(flatGraph, offset) : 0), [flatGraph, offset]);
+  const rangeRaw = sp.get(PARAM.range);
+  const range = useMemo(() => parseRange(rangeRaw, maxLv) ?? [1, 1], [rangeRaw, maxLv]);
+  const rangeOpen = useMemo(() => (flatGraph && !flat && range[1] > 1 ? expandToDepth(flatGraph, range[0], range[1], { base }) : null), [flatGraph, flat, range, base]);
+  const expanded = useMemo(() => (rangeOpen ? new Set([...explicitOpen, ...rangeOpen]) : explicitOpen), [rangeOpen, explicitOpen]);
+  const [drill, setDrill] = useState(null); // {id, n}: the folder the camera fits (its drawn children); n re-aims a repeat drill
+  const drillN = useRef(0);
+  const drillInto = (id) => setDrill(id ? { id, n: ++drillN.current } : null);
+  // The scope (and the breadcrumb trail) follows the drill when there is one, else the reader's own deepest folder (never the range's, which would pick any deep folder).
+  const drillPath = drill ? folderPathOf(drill.id) : null;
+  const level = drillPath && !base.has(drillPath) ? drillPath : currentLevel(explicitOpen);
+  // Colours are relative to the scope, over the UNFILTERED graph, so hiding a group never recolours (and never relayouts).
+  const scoped = useMemo(() => (flatGraph && by === "scope" ? scopeColors(flatGraph, level) : null), [flatGraph, by, level]);
+  const graph = useMemo(() => (flatGraph && scoped ? recolour(flatGraph, scoped) : flatGraph), [flatGraph, scoped]);
+  // The level view filters docs before it aggregates them: the legend's hidden groups and the local graph's hops are one predicate.
+  const visible = useMemo(
+    () => (graph && (hidden.size || localIds || stackVisible) ? (id) => !hidden.has(graph.byId.get(id)?.group) && (!localIds || localIds.has(id)) && (!stackVisible || stackVisible(id)) : undefined),
+    [graph, hidden, localIds, stackVisible],
+  );
+  // Only the range's folders stay drawn as hubs: a folder the reader double-clicks open is replaced by its children, as before.
+  const levels = useMemo(
+    () => (graph && !flat ? buildLevelView(graph, expanded, { visible, hubs: rangeOpen ? hubsFor(rangeOpen, range[0], { base }) : undefined }) : null),
+    [graph, flat, expanded, visible, rangeOpen, range, base],
+  );
+  const drawn = useMemo(() => {
+    if (!graph) return null;
+    if (levels) return forCanvas(levels, folderGroups(levels.nodes, graph));
+    if (!localIds && !stackVisible) return graph;
+    return localGraph(graph, new Set(graph.nodes.filter((n) => (!localIds || localIds.has(n.id)) && (!stackVisible || stackVisible(n.id))).map((n) => n.id)));
+  }, [graph, levels, localIds, stackVisible]);
+  const layoutKey = `${focus ? `local:${focus.id}:${hops}` : "all"}`; // cluster is a drawing, not a layout input: toggling it never changes the key
+  const neighbours = useMemo(() => {
+    if (!graph || !focus) return [];
+    const ids = [...neighbourhood(graph.links, focus.id)].filter((id) => id !== focus.id);
+    return ids.map((id) => graph.byId.get(id)).filter(Boolean).sort((a, b) => a.title.localeCompare(b.title));
+  }, [graph, focus]);
+  // Find (WIKI-GRAPH-FIND-FILTER-LIVE-1): the debounced term sets a match set the canvases light and dim through the focus path. It is
+  // never a layout input (not in `layoutKey`), so typing posts nothing to the worker and moves nothing. Clearing skips the debounce.
+  const settledTerm = useDebounced(term, FIND_DEBOUNCE_MS);
+  const findTerm = hasTerm(term) && !parseVerb(term).verb && !parseVerb(settledTerm).verb ? settledTerm : ""; // a verb ("in core") is a filter being typed, not a title to light
+  const found = useMemo(() => (graph && hasTerm(findTerm) ? findMatches(graph.nodes, findTerm, visible) : null), [graph, findTerm, visible]);
+  const drawnIds = useMemo(() => (drawn ? new Set(drawn.nodes.map((n) => n.id)) : null), [drawn]);
+  const match = useMemo(() => (found && drawnIds ? litIds(found, drawnIds) : null), [found, drawnIds]);
+  // The path lens (EXPLORE-1c-UI r3): the shortest path over the FULL graph, lit through the canvas marks (3D) or the match set (2D); it only marks, nothing is removed.
+  const path = useMemo(() => (explorer && graph && drawnIds ? pathView(explore.state, explorer.idx, drawnIds, graph.byId) : null), [explorer, graph, drawnIds, explore.state]);
+  // A focused doc the level view collapses into a folder has no node to ring (the canvas focus index is -1): ring the folder that stands for it, as a mark.
+  // Not a focus: that would pin and regroup the folder (WIKI-GRAPH-CANVAS-FOCUS-COLLAPSED-FU-1; the card hangs from the same `cardAnchor`).
+  const focusRep = useMemo(() => { const a = cardAnchor(focus, drawnIds); return a && a !== focus.id ? a : null; }, [focus, drawnIds]);
+  const marks = useMemo(() => {
+    if (!lassoMarks && !path?.marks && !focusRep) return null;
+    const m = { ...(lassoMarks || {}), ...(path?.marks || {}) };
+    if (focusRep) m.selected = new Set([...(m.selected || []), focusRep]);
+    return m;
+  }, [lassoMarks, path, focusRep]); // 3D canvas marks: the lasso and pins, the path's lit docs and links, the collapsed focus's folder ring
+  const pathMatch = useMemo(() => (view === "2d" && path?.marks ? [...new Set([...(match || []), ...path.marks.lit])] : match), [view, path, match]);
+  const [listOpen, setListOpen] = useState(false);
+  const [omniFocus, setOmniFocus] = useState(0); // bumped by the doc card's Path to… to put the cursor in the omnibox
+  const [recent, setRecent] = useState(() => readRecent(workspace));
+  const [views, setViews] = useState(() => readViews(workspace)); // saved views (EXPLORE-1c-UI r5): newest first, this browser only
+  const [saving, setSaving] = useState(null); // the View drawer's name field: null when closed, else the text being typed
+  const [viewNote, setViewNote] = useState(""); // the status line after a save or an apply
+  const [restore, setRestore] = useState(null); // a saved view's camera and pins, waiting for the canvas to take them once its URL state has drawn
+  // Recent and views are read from per-workspace storage, and a workspace switch keeps this page mounted (WIKI-GRAPH-VIEW-WORKSPACE-FU-1): on
+  // a change, re-read both and drop the pending name field, status line and restore, all of which belong to the workspace left behind.
+  const [storeWs, setStoreWs] = useState(workspace);
+  if (storeWs !== workspace) {
+    setStoreWs(workspace);
+    setRecent(readRecent(workspace));
+    setViews(readViews(workspace));
+    setSaving(null);
+    setViewNote("");
+    setRestore(null);
+  }
+  // The omnibox's rows (docs, folders, verbs, filter previews, recent docs) for the LIVE term: row 0 is the top title match, so Enter keeps aiming at it.
+  const omniList = useMemo(
+    () => (graph ? omniRows({ text: term, nodes: graph.nodes, visible, idx: explorer?.idx ?? null, counts: folderCount, recent, views, steps, explorer, byId: graph.byId }) : []),
+    [graph, term, visible, explorer, folderCount, recent, views, steps],
+  );
+  const [aim, setAim] = useState(null); // {doc, n}: the doc the camera frames (Enter on the top match); n re-aims a repeat
+  // The drawn node for it, resolved against what is drawn NOW: a focus re-narrows the graph, so the node it sat in before (a folder) may be gone.
+  const aimId = aim && drawnIds ? drawnFor(aim.doc, drawnIds) : null;
+  const aimNode = useMemo(() => (aimId ? { id: aimId, n: aim.n } : null), [aimId, aim]);
+  const aimN = useRef(0);
+  // Badge-opened hubs ("+N", FOCUS-HOPS-1): one Set per focus; a new focus starts with none open. The Set keeps its identity
+  // until a badge is clicked, so the canvas re-rings only then.
+  const [opened, setOpened] = useState({ root: null, ids: null });
+  const open = opened.root === focusId ? opened.ids : null;
+  const onBadge = (n) => setOpened((o) => ({ root: focusId, ids: new Set([...(o.root === focusId && o.ids ? o.ids : []), n.id]) }));
+  // The id the canvas focuses: the doc, or a drawn folder (a folder may be the root, FOCUS-HOPS-1).
+  const canvasFocus = focus?.id || (focusId && drawnIds?.has(focusId) ? focusId : null);
+
+  /** Set (or with null/"" remove) URL params, replacing the history entry. */
+  const set = (patch, push = false) => setSp((prev) => {
+    const p = new URLSearchParams(prev);
+    for (const [k, v] of Object.entries(patch)) { if (v === null || v === undefined || v === "") p.delete(k); else p.set(k, String(v)); }
+    return p;
+  }, { replace: !push });
+  const setFocus = (id) => {
+    setDrill(null);
+    setAim(null);
+    // `depth` is the old page's depth control: the whole graph has no depth. No focus means the whole graph again; `hops` stays.
+    set(id ? { depth: null, [PARAM.root]: id } : { depth: null, [PARAM.root]: null });
+    setTerm("");
+  };
+  // Enter or a click on a match: select it and frame it, keeping the term so the other matches stay lit until Esc or clear.
+  const pick = (doc) => {
+    if (!doc) return;
+    setDrill(null);
+    set({ depth: null, [PARAM.root]: doc.id });
+    setListOpen(false);
+    setAim({ doc, n: ++aimN.current });
+  };
+  // Chip edits push a history entry (Back undoes one), unlike the replacing `set`; every other param rides along.
+  // A no-op edit (clear with nothing to clear, a repeated step) adds none, so Back always undoes a real change.
+  const setExplore = (next) => { if (!exploreUnchanged(sp, next)) setSp((prev) => withExplore(prev, next), { replace: false }); };
+  const onOmniAction = (row) => {
+    const a = row.action;
+    if (a.type === "fly") {
+      pick(graph.byId.get(a.id));
+      const next = pushRecent(recent, a.id);
+      setRecent(next);
+      writeStore(recentKey(workspace), next);
+    } else if (a.type === "step") { setExplore(addStep(explore.state, a.step)); setTerm(""); setListOpen(false); }
+    else if (a.type === "clear") { setExplore(clearAll(explore.state)); setListOpen(false); }
+    else if (a.type === "view") { const v = views.find((x) => x.name === a.name); if (v) applyView(v); setTerm(""); setListOpen(false); }
+    else if (a.type === "lens") { setExplore(setPathLens(explore.state, a.lens.from, a.lens.to)); setTerm(""); setListOpen(false); }
+  };
+  // Saved views: the URL goes first (its focus fly-to or fit-all sets the orbit target as today), then the orientation is applied round that
+  // target and the pins are put back (only those drawn). 2D applies the URL alone. The camera and pins are never in the URL.
+  const saveCurrent = (name) => {
+    const nm = String(name || "").trim();
+    if (!nm) return;
+    const c = view === "3d" ? canvas.current : null;
+    const r = saveView(workspace, makeView({ name: nm, url: `?${sp.toString()}`, orient: c?.orientation?.() || null, pins: c?.pinList ? c.pinList() : null }));
+    if (r.ok) setViews(r.list);
+    setSaving(null);
+    setViewNote(r.ok ? `Saved "${nm}".` : SAVE_FAILED);
+  };
+  const applyView = (v) => {
+    setDrill(null);
+    setAim(null);
+    setSp(paramsOfUrl(v.url), { replace: false });
+    setViewNote(appliedText(v, view));
+    setRestore(view === "3d" && (v.orient || v.pins?.length) ? { v } : null);
+  };
+  // The doc card's Path to…: the omnibox takes `path <title> to ` and asks for the second doc, the way it asks for any doc argument.
+  const onPathTo = (doc) => { setTerm(`path ${doc.title} to `); setListOpen(true); setOmniFocus((n) => n + 1); };
+  // 3D: a fly-to frames the doc through the canvas's own camera (fitIdx beats the focus framing) and rings it; 2D takes `aim`.
+  useEffect(() => {
+    if (view !== "3d" || !aimNode) return;
+    canvas.current?.fitTo?.([aimNode.id]);
+    canvas.current?.flash?.(aimNode.id);
+  }, [aimNode, view]);
+  useEffect(() => {
+    const c = canvas.current;
+    if (!restore || view !== "3d" || !drawnIds || !c?.applyOrient) return;
+    const { v } = restore;
+    const { pins, skipped } = restorablePins(v.pins, drawnIds);
+    if (v.orient && !c.applyOrient(v.orient)) return; // the surface is not up yet: try again when the layout moves
+    const n = v.pins ? c.setPins(pins) : 0;
+    if (n < 0 || (pins.length && n === 0 && layout.state !== "settled")) return;
+    setRestore(null);
+    setViewNote(appliedText(v, "3d", skipped + (pins.length - n)));
+  }, [restore, view, drawnIds, layout.state]);
+  // Clear the focus and keep the term and hops (a click on empty space, or Esc).
+  const clearFocus = () => { setAim(null); set({ [PARAM.root]: null }); };
+  const setDim = (v) => { const d = parseDim(v); set({ [PARAM.dim]: d === DIM_DEFAULT ? null : d }); };
+  const setHops = (h) => set({ [PARAM.hops]: h === HOPS_DEFAULT ? null : h });
+  const setHidden = (next) => set({ [PARAM.hide]: formatHidden(next) });
+  // The base is never written. In scope mode a move to another scope re-keys the legend, so the old `hide=` goes with it.
+  const setLevels = (next) => set({
+    [PARAM.levels]: formatLevels(new Set([...next].filter((p) => !base.has(p)))),
+    ...(by === "scope" && currentLevel(new Set([...base, ...next])) !== level ? { [PARAM.hide]: null } : {}),
+  });
+  // A doc opens in the pane, never by leaving the graph. Opening adds a history entry (Back closes it); following the click replaces.
+  const showDoc = (id, extra = {}) => { setPaneCollapsed(false); set({ ...extra, [PARAM.doc]: id }, !docId); }; // one set(): react-router applies a functional update to the render-time params, so two calls in a handler lose the first
+  // A double click (or Enter) opens the doc AND shows its place in the left folder tree; a single click that follows the pane does not.
+  const openDoc = (id, extra) => { showDoc(id, extra); requestTreeSync({ id }); };
+  const closeDoc = () => set({ [PARAM.doc]: null });
+  const startDrag = (e) => {
+    e.preventDefault();
+    const box = surface.current?.parentElement?.getBoundingClientRect();
+    if (!box?.width) return;
+    const move = (m) => setPanePct(Math.round(Math.max(PANE_MIN, Math.min(PANE_MAX, ((box.right - m.clientX) / box.width) * 100))));
+    const stop = () => { window.removeEventListener("pointermove", move); window.removeEventListener("pointerup", stop); };
+    window.addEventListener("pointermove", move);
+    window.addEventListener("pointerup", stop);
+  };
+  const setRange = (r) => { set({ [PARAM.range]: r[0] === 1 && r[1] === 1 ? null : formatRange(r), [PARAM.flat]: null }); setDrill(null); };
+  const showAll = () => { set({ [PARAM.flat]: flat ? null : "1" }); setDrill(null); };
+  // With a base the trail starts at it: no "All", and the first crumb goes back to the base, never to level 0.
+  const crumbs = level === null ? [] : breadcrumb(level);
+  const up = useRef(null); // the Esc handler reads the latest state through this; it stops at the base
+  const clearLasso = () => setLassoSel(null);
+  // The canvas draws and samples the polygon; the page judges it on the drawn docs' projected centres, front and back (3D-UX-1 D2).
+  const onPin = ({ ids }) => setPinIds(ids);
+  const onLasso = ({ phase, pts }) => {
+    const c = canvas.current;
+    if (phase === "cancel" || !c?.screenPositions) { setLassoLive(null); return; }
+    const hit = lassoHits(pts, c.screenPositions(), c.pivotDepth?.() ?? null);
+    if (phase === "end") { setLassoLive(null); setLassoSel(hit.inside ? hit : null); } else setLassoLive({ inside: hit.inside, behind: hit.behind });
+  };
+  const clearPath = () => setExplore(clearPathLens(explore.state));
+  const levelUp = flat ? null : explicit.size ? () => {
+    const gone = currentLevel(explicit), up1 = new Set([...base, ...upOne(explicit)]);
+    const parent = gone ? gone.split("/").slice(0, -1).join("/") : "";
+    setLevels(up1);
+    drillInto(parent && !base.has(parent) ? folderId(parent) : null); // fit the parent's children, or everything at the top
+  } : drill ? () => { // no folder of the reader's own to close: step the camera up from the drilled folder
+    const parent = folderPathOf(drill.id).split("/").slice(0, -1).join("/");
+    drillInto(parent && !base.has(parent) ? folderId(parent) : null);
+  } : null;
+  // Esc: a lasso selection first, then the pane, then (with a focus) the card's show/hide, then up a level, then the path lens (escAction)
+  up.current = { clearLasso, closeDoc, toggleCard: card.esc, up: levelUp, clearPath }[escAction({ lasso: !!lassoSel, docOpen: !!docId, focus: !!focusId, up: !!levelUp, pathLens: !!path?.lens })] || null;
+  const turn = useRef(false); // true in 3D: the keydown listener may turn and zoom the camera
+  turn.current = view === "3d";
+  const enter = useRef(null); // Enter on the focused doc opens it in the pane
+  enter.current = focus && !docId && !isFolderId(focus.id) ? () => openDoc(focus.id) : null;
+  useEffect(() => {
+    const onKey = (e) => {
+      if (isFormField(e.target)) return;
+      if (turn.current && !e.ctrlKey && !e.metaKey && !e.altKey) { // 3D keyboard turn/zoom: Shift+arrows, + - 0 (never Ctrl/Cmd/Alt: Cmd+- stays browser zoom)
+        const c = canvas.current, cur = c?.orientation?.(true), next = cur && stepOrient(cur, e.key, e.shiftKey);
+        if (next) { e.preventDefault(); c.applyOrient(next); return; }
+      }
+      if (e.key === "Escape" && up.current) up.current();
+      else if (e.key === "Enter" && !["BUTTON", "A"].includes(e.target?.tagName) && enter.current) enter.current();
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, []);
+  const onPhysics = (k, v) => set({ [PARAM[k]]: v === PHYSICS_DEFAULTS[k] ? null : v });
+  const onLayoutState = (state, ms) => setLayout({ state, ms });
+  // A click focuses the node (its hop rings light), keeps the term, and follows the pane while it is open.
+  const select = (id) => { setDrill(null); setAim(null); set({ depth: null, [PARAM.root]: id }); };
+  const onOpen = (n) => {
+    select(n.id);
+    if (docId && !isFolderId(n.id)) showDoc(n.id);
+  };
+  const onExpand = (n) => {
+    // A double click selects the doc too, so the panel's card and the pane name the same doc (a real double click clicks first, a keyboard Enter does not).
+    if (!isFolderId(n.id)) { setDrill(null); setAim(null); openDoc(n.id, { depth: null, [PARAM.root]: n.id }); return; }
+    const path = folderPathOf(n.id);
+    setLevels(expand(explicitOpen, path));
+    drillInto(n.id);
+    requestTreeSync({ id: docUnder(graph.nodes, path), folder: path }); // the folder's source comes from one of its docs
+  };
+
+  const loaded = graph?.nodes.length || 0;
+  const levelDocs = levels ? levels.nodes.reduce((t, n) => t + (n.hub ? 0 : n.kind === "folder" ? n.size : 1), 0) : 0;
+  const hiddenDocs = !drawn ? 0 : levels ? graph.nodes.filter((n) => hidden.has(n.group) && (!localIds || localIds.has(n.id))).length : drawn.nodes.filter((n) => hidden.has(n.group)).length;
+  const ready = !q.isLoading && !!graph && loaded > 0;
+  // The loaded graph fills the whole area beside the nav (WIKI-GRAPH-FULLVIEW-1, Layout's full-bleed mode): the canvas is
+  // the page, the controls float over it as panels, and only the panels take pointer events.
+  if (!ready) {
+    return (
+      <div className="h-full overflow-y-auto px-5 py-10 md:py-12">
+        <PageHeader title="Graph">
+          {graph && (
+            <>
+              {loaded} docs · {graph.links.length} links
+              {q.data.total > loaded && <> · showing first {loaded} of {q.data.total} docs</>}
+            </>
+          )}
+        </PageHeader>
+        <ErrorBox error={q.error} />
+        {q.isLoading ? <Loading /> : graph && <p className="text-sm text-neutral-400">No docs in this workspace yet.</p>}
+      </div>
+    );
+  }
+  return (
+    <div className="absolute inset-0 flex" data-testid="graph-fullview">
+     <div ref={surface} className="relative min-w-0 flex-1">
+      {view === "3d" ? (
+        <Suspense fallback={null}>
+          <GraphCanvas3D
+            key={colorMode} ref={canvas} graph={drawn} layoutKey={layoutKey} hidden={levels ? NO_GROUPS : hidden} focusId={canvasFocus} match={match} aim={aimNode} sizeByDegree={sizeByDegree}
+            physics={physics} cluster={cluster} outlines={outlines} idleTurn={idleTurn && !reduced} drill={drill} hops={hops} dim={dim} open={open} onOpen={onOpen} onExpand={onExpand} onBadge={onBadge} onBackground={clearFocus}
+            onLasso={onLasso} onPin={onPin} marks={marks} onLayoutState={onLayoutState} height="fill"
+            onUnavailable={(reason) => { console.warn(`wiki graph: the 3D view is unavailable (${reason}), drawing the 2D view instead.`); setUnavailable3d(true); }}
+          />
+        </Suspense>
+      ) : (
+        <GraphCanvas
+          key={colorMode} ref={canvas} graph={drawn} layoutKey={layoutKey} hidden={levels ? NO_GROUPS : hidden} focusId={canvasFocus} match={pathMatch} aim={aimNode} sizeByDegree={sizeByDegree}
+          physics={physics} cluster={cluster} forced={forced} drill={drill} hops={hops} dim={dim} open={open} onOpen={onOpen} onExpand={onExpand} onBadge={onBadge} onBackground={clearFocus}
+          onLayoutState={onLayoutState} height="fill"
+        />
+      )}
+      {path?.folders.length > 0 && (
+        <div className="pointer-events-none absolute bottom-10 left-1/2 max-w-[70%] -translate-x-1/2 rounded-md bg-ground/80 px-2 py-1 text-xs text-ink2" role="status" data-testid="graph-path-note">
+          {pathNote(path.folders, (id) => folderPathOf(id) || "(root)")}
+        </div>
+      )}
+      {(lassoLive || lassoSel) && (
+        <div className="pointer-events-none absolute bottom-3 left-1/2 -translate-x-1/2 rounded-md bg-ground/80 px-2 py-1 text-xs text-ink2" role="status" data-testid="graph-lasso-count">
+          {lassoLive ? lassoText(lassoLive.inside, lassoLive.behind) : `${lassoText(lassoSel.inside, lassoSel.behind).replace("inside", "selected")}. Esc clears.`}
+        </div>
+      )}
+      {viewNote && (
+        <div className="pointer-events-none absolute bottom-16 left-1/2 max-w-[70%] -translate-x-1/2 rounded-md bg-ground/80 px-2 py-1 text-xs text-ink2" role="status" data-testid="graph-view-note">{viewNote}</div>
+      )}
+      {cardAtNode && <DocCard canvas={canvas} focus={focus} anchor={cardAnchor(focus, drawnIds)} to={noteUrl(workspace, focus.id)} onPathTo={onPathTo} shown={card.shown} reduced={reduced} onHold={card.hold} onRelease={card.release} onFocusIn={card.focusIn} onFocusOut={card.focusOut} />}
+      <GraphLegend
+        groups={graph.groups} hidden={hidden} scope={by === "scope" && level ? level : null}
+        onToggle={(names) => setHidden(names.every((n) => hidden.has(n)) ? new Set([...hidden].filter((h) => !names.includes(h))) : new Set([...hidden, ...names]))}
+        onDrill={by === "scope" ? (path) => { setLevels(expand(explicitOpen, path)); drillInto(folderId(path)); } : null}
+        onAll={() => setHidden(showEveryGroup())} onNone={() => setHidden(hideEveryGroup(graph.groups))}
+      />
+      <div className="pointer-events-none absolute bottom-3 left-3 max-w-[60%] rounded-md bg-ground/70 px-2 py-1 text-xs text-neutral-400" aria-live="polite" data-layout-state={layout.state || ""}>
+        {focus && <>{levels ? levelDocs : drawn.nodes.length} docs within {hops} {hops === 1 ? "link" : "links"} of {focus.title || focus.id}. </>}
+        {hiddenDocs > 0 && <>{hiddenDocs} hidden by the legend. </>}
+        {layout.state && <>Layout {STATE_TEXT[layout.state]}{layout.state === "settled" && layout.ms != null && <> in {(layout.ms / 1000).toFixed(1)} s</>}.</>}
+      </div>
+      {/* Top overlays share one wrapping row: the Levels bar on the left, the controls panel on the right. When the surface is too narrow for both
+          (doc pane open, phone) the panel drops below the bar instead of covering it. In that case it also stops above the legend (bottom-left, up to 45%
+          tall): 15rem = the legend's 2.5rem offset + 6.5rem for the Levels bar (which can wrap to two lines) + 6rem for the find panel above it (input, count
+          line; chips add more, so the column scrolls). The left column stacks the find panel over the Levels bar. */}
+      <div data-testid="graph-overlays" className="pointer-events-none absolute inset-0 flex flex-wrap content-start items-start justify-between gap-3 p-3">
+        <div className="pointer-events-none flex max-w-[60%] flex-col items-start gap-3" data-testid="graph-left-column">
+        <div className={`${PANEL} w-80 max-w-full p-3`} data-testid="graph-find-panel">
+          <Omnibox
+            term={term} onTerm={setTerm} rows={omniList} open={listOpen} onOpenChange={setListOpen} inputClassName={INPUT}
+            countText={found ? countText(found.length) : ""} foundCount={found ? found.length : null}
+            onAction={onOmniAction} focusSignal={omniFocus} onBackspaceEmpty={() => setExplore(removeStep(explore.state, steps.length - 1))}
+          />
+          <FilterChips
+            state={explore.state} run={run} idx={explorer?.idx ?? null} explorer={explorer} ignored={explore.ignored}
+            onRemove={(i) => setExplore(removeStep(explore.state, i))} onClear={() => setExplore(clearAll(explore.state))}
+            onRemoveLens={(i) => setExplore(removeLens(explore.state, i))}
+          />
+        </div>
+        <div className={`${PANEL} flex max-w-full items-center gap-3 px-3 py-2`}>
+          {(!flat || level !== null) && <GraphBreadcrumb crumbs={crumbs} all={!base.size} onSelect={(path) => { setLevels(path === null ? new Set() : new Set(breadcrumb(path).map((c) => c.path))); drillInto(path === null || base.has(path) ? null : folderId(path)); }} />}
+          <GraphLevelPicker range={range} max={maxLv} flat={flat} onRange={setRange} onAll={showAll} />
+          {has3d && !unavailable3d && (
+            <button type="button" aria-label={view === "3d" ? "Switch to 2D view" : "Switch to 3D view"} onClick={() => set({ [PARAM.view]: view === "3d" ? "2d" : null })}
+              className={BUTTON}>{view === "3d" ? "2D" : "3D"}</button>
+          )}
+        </div>
+        </div>
+        <div data-testid="graph-controls-column" className={`pointer-events-none ml-auto flex max-w-full flex-col items-end gap-3 ${docId ? "max-h-[calc(55%-15rem)]" : "max-lg:max-h-[calc(55%-15rem)]"}`}>
+        <ErrorBox error={q.error} />
+        <section className={`${PANEL} flex min-h-0 w-80 max-w-full flex-col`} aria-label="Graph view">
+          <div className="flex items-center gap-2 p-3">
+            <div className="min-w-0 flex-1">
+              <h1 className="text-base font-semibold tracking-tight text-ink">Graph</h1>
+              <span className="block text-xs text-neutral-500">
+                {loaded} docs · {graph.links.length} links
+                {q.data.total > loaded && <> · showing first {loaded} of {q.data.total} docs</>}
+              </span>
+            </div>
+            <button type="button" onClick={() => setPanelOpen(!panelOpen)} aria-expanded={panelOpen} aria-controls="graph-controls" className={BUTTON}>
+              {panelOpen ? "Hide view" : "View"}
+            </button>
+          </div>
+          {panelOpen && (
+            <div id="graph-controls" className="min-h-0 space-y-3 overflow-y-auto border-t border-neutral-200/70 p-3">
+              <div role="group" aria-label="Hops" className="flex items-center gap-2 text-[13px] text-ink2">
+                Hops
+                <button type="button" aria-label="Fewer hops" disabled={hops <= 1} onClick={() => setHops(hops - 1)} className={BUTTON}>−</button>
+                <span data-testid="graph-hops" className="w-4 text-center text-ink">{hops}</span>
+                <button type="button" aria-label="More hops" disabled={hops >= 4} onClick={() => setHops(hops + 1)} className={BUTTON}>+</button>
+              </div>
+              <label className="flex items-center gap-2 text-[13px] text-ink2">
+                Dim
+                <input type="range" min="0" max={DIM_MAX} step="0.01" value={dim} aria-label="Dim" onChange={(e) => setDim(e.target.value)} className="min-w-0 flex-1" />
+                <span data-testid="graph-dim" className="w-9 text-right tabular-nums text-ink">{dim}</span>
+              </label>
+              <div className="flex flex-wrap items-center gap-x-3 gap-y-1.5">
+                <label className="flex w-full min-w-0 items-center gap-2 text-[13px] text-ink2">
+                  Colour by
+                  <select value={by} onChange={(e) => set({ [PARAM.by]: e.target.value === "scope" ? null : e.target.value, [PARAM.hide]: null })} aria-label="Colour by" className={`${INPUT} min-w-0 flex-1`}>
+                    <option value="scope">current level</option>
+                    <option value="area">area</option>
+                    <option value="folder">folder</option>
+                    {GRAPH_ASPECTS.map((a) => <option key={a} value={a} disabled title={aspectHint}>{`${a} (${aspectHint})`}</option>)}
+                  </select>
+                </label>
+                <label className="flex items-center gap-1.5 text-[13px] text-ink2">
+                  <input type="checkbox" checked={sizeByDegree} onChange={(e) => set({ [PARAM.size]: e.target.checked ? null : "flat" })} />
+                  Size by links
+                </label>
+              </div>
+              {view === "3d" && (
+                <label className="flex flex-wrap items-center gap-2 text-[13px] text-ink2">
+                  <input type="checkbox" checked={idleTurn && !reduced} disabled={reduced} onChange={(e) => setIdleTurn(e.target.checked)} />
+                  Turn slowly when idle
+                  {reduced && <span className="text-[12px] text-ink2">Off while your system reduces motion</span>}
+                </label>
+              )}
+              <div className="flex flex-wrap items-center gap-2">
+                <button type="button" onClick={() => canvas.current?.fit()} className={BUTTON}>Zoom to fit</button>
+                <button type="button" aria-pressed={cluster} onClick={() => set({ [PARAM.cluster]: cluster ? null : "1" })}
+                  className={`${BUTTON} ${cluster ? PRESSED : ""}`}>Cluster by group</button>
+                {view === "3d" && cluster && (
+                  <button type="button" aria-pressed={outlines} onClick={() => set({ [PARAM.outlines]: outlines ? null : "1" })}
+                    className={`${BUTTON} ${outlines ? PRESSED : ""}`}>Group outlines</button>
+                )}
+                <button type="button" disabled={layout.state !== "running"} onClick={() => canvas.current?.pause()} className={BUTTON}>Pause</button>
+                <button type="button" disabled={layout.state !== "paused"} onClick={() => canvas.current?.resume()} className={BUTTON}>Resume</button>
+                {view === "3d" && pinIds.length > 0 && (
+                  <button type="button" onClick={() => canvas.current?.releasePins?.()} className={BUTTON} data-testid="graph-release-pins">Release pins ({pinIds.length})</button>
+                )}
+                <button type="button" disabled={!layout.state} title={cluster && view === "2d" ? "Lay the groups out into clusters again, once" : undefined} onClick={() => canvas.current?.reheat()} className={BUTTON}>Reheat</button>
+              </div>
+              <div className="space-y-2" data-testid="graph-saved-views">
+                {saving === null ? (
+                  <button type="button" onClick={() => setSaving(defaultViewName(steps.map((st) => chipText(st, explorer?.idx ?? null)), views))} className={BUTTON} data-testid="graph-save-view">Save view…</button>
+                ) : (
+                  <form onSubmit={(e) => { e.preventDefault(); saveCurrent(saving); }} className="flex items-center gap-2">
+                    <input autoFocus value={saving} onChange={(e) => setSaving(e.target.value)} onKeyDown={(e) => { if (e.key === "Escape") { e.stopPropagation(); setSaving(null); } }}
+                      aria-label="View name" maxLength={80} className={`${INPUT} min-w-0 flex-1`} data-testid="graph-view-name" />
+                    <button type="submit" disabled={!saving.trim()} className={BUTTON}>Save</button>
+                    <button type="button" onClick={() => setSaving(null)} className={BUTTON}>Cancel</button>
+                  </form>
+                )}
+                {views.length > 0 && (
+                  <ul className="space-y-1" aria-label="Saved views" data-testid="graph-views">
+                    {views.map((v) => (
+                      <li key={v.name} className="flex items-center gap-1 text-[13px]" data-view={v.name}>
+                        <button type="button" onClick={() => applyView(v)} className="min-w-0 flex-1 truncate text-left text-ink hover:underline" data-testid="graph-view-apply">{v.name}</button>
+                        <button type="button" aria-label={`Delete view ${v.name}`} onClick={() => setViews(deleteView(workspace, v.name))} className={BUTTON} data-testid="graph-view-delete">×</button>
+                      </li>
+                    ))}
+                  </ul>
+                )}
+              </div>
+              {focus ? (
+                <div className="rounded-md border border-neutral-200/70 p-3">
+                  {!cardAtNode && card.shown && ( // 3D shows title, folder, area and Open note in the card at the node (DocCard); 2D keeps them here (Esc or the info button hides them)
+                    <>
+                      <h2 className="text-base font-semibold text-ink">{focus.title}</h2>
+                      <p className="mt-1 break-all font-mono text-xs text-neutral-500">{focus.folder || "(root)"}</p>
+                      {focus.area && <p className="mt-1 text-xs text-ink2">area {focus.area}</p>}
+                    </>
+                  )}
+                  <div className={`${cardAtNode || !card.shown ? "" : "mt-3 "}flex gap-3 text-[13px]`}>
+                    {!cardAtNode && card.shown && <Link to={noteUrl(workspace, focus.id)} className="text-blue-600 hover:underline">Open note</Link>}
+                    {!cardAtNode && card.shown && <button type="button" onClick={() => onPathTo(focus)} className="text-blue-600 hover:underline">Path to…</button>}
+                    <button type="button" onClick={() => setFocus(null)} className="text-neutral-500 hover:text-ink">Show whole graph</button>
+                    <button type="button" onClick={card.esc} aria-pressed={card.shown} aria-label={card.shown ? "Hide doc info" : "Show doc info"} className="text-neutral-500 hover:text-ink" data-testid="graph-card-toggle">Info</button>
+                  </div>
+                  <p className="mt-2 text-[11px] text-neutral-400" data-testid="graph-card-hint">{CARD_HINT}</p>
+                  <h3 className="mt-4 text-xs font-semibold uppercase tracking-wide text-neutral-500">Linked docs ({neighbours.length})</h3>
+                  <ul className="mt-1 space-y-0.5">
+                    {neighbours.slice(0, SHOWN_NEIGHBOURS).map((n) => (
+                      <li key={n.id}>
+                        <button type="button" onClick={() => setFocus(n.id)} className="flex w-full items-center gap-2 truncate text-left text-[13px] text-ink2 hover:text-ink">
+                          <span className="inline-block h-2 w-2 shrink-0 rounded-full" style={{ background: hueFor(n.color) }} />{n.title}
+                        </button>
+                      </li>
+                    ))}
+                  </ul>
+                  {neighbours.length > SHOWN_NEIGHBOURS && <p className="mt-1 text-xs text-neutral-400">and {neighbours.length - SHOWN_NEIGHBOURS} more</p>}
+                </div>
+              ) : (
+                <div className="text-[13px] text-ink2">
+                  {focusId && !isFolderId(focusId) && <p className="mb-3 text-amber-700">That doc is not in this graph.</p>}
+                  <p>Find a doc by title to focus it and its links.</p>
+                </div>
+              )}
+              <div>
+                <h2 className="text-xs font-semibold uppercase tracking-wide text-neutral-500">Physics</h2>
+                <div className="mt-2 space-y-1">
+                  <Slider label="Repel" name="repel" value={physics.repel} onChange={onPhysics} />
+                  <Slider label="Link distance" name="link" value={physics.link} onChange={onPhysics} />
+                  <Slider label="Centre force" name="centre" value={physics.centre} onChange={onPhysics} />
+                </div>
+              </div>
+              <p className="text-xs text-neutral-400">
+                Scroll to zoom, drag to pan, hover to light a doc&apos;s links, click a dot to follow it in the doc pane, double-click to open it.
+                {loaded > LOD_N && " Large graph: names show as you zoom in."}
+              </p>
+            </div>
+          )}
+        </section>
+        </div>
+      </div>
+     </div>
+     {docId && (
+       <>
+         {!paneCollapsed && <div role="separator" aria-orientation="vertical" aria-label="Resize doc pane" onPointerDown={startDrag} className="hidden w-1 shrink-0 cursor-col-resize bg-neutral-200/70 hover:bg-blue-400 md:block" />}
+         <div data-testid="graph-doc-pane" style={{ "--pane-w": `${panePct}%` }}
+           className={paneCollapsed ? "flex shrink-0" : "absolute inset-0 z-20 flex md:static md:inset-auto md:w-[var(--pane-w)] md:shrink-0"}>
+           <GraphDocPane workspace={workspace} id={docId} collapsed={paneCollapsed} onToggle={() => setPaneCollapsed(!paneCollapsed)} onClose={closeDoc} />
+         </div>
+       </>
+     )}
+    </div>
+  );
+}