@smartmemory/wiki-components 0.4.0 → 0.6.0

package/src/graph/components/wiki/GraphCanvas.jsx

@@ -0,0 +1,663 @@
+import React, { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { quadtree } from "d3-quadtree";
+import { FALLBACK_WARNING, PHYSICS_DEFAULTS, SIZE_MAX, DIM_DEFAULT, chooseRenderer, dimBase, drawRadius, layoutRadii, levelSize, litOf, localKeep, nodeLooks, pickable, visibleLinks, visibleMask } from "../../lib/graphView";
+import { startLayout } from "../../lib/layoutClient";
+import { perfSpan } from "../../lib/perf";
+import { dirOf, hotHeads } from "../../lib/graphArrows";
+import { LOD_N, OTHER, centreOn, lodFor, seedPositions, serverFits, zoomAt } from "../../lib/wikiGraph";
+import { robustBox } from "../../lib/robustFit";
+import { layout2d, placeAppearing } from "../../lib/groupBubbles";
+import { linkArrays, refreshSameTopology } from "../../lib/graph3d";
+import { linkBuckets } from "../../lib/linkWeight";
+import { createCanvasBase } from "./graph/canvasBase";
+import { drawOverlay } from "./graph/overlay";
+import { containPairs, drawContainment } from "./graph/containment";
+import { drawnMemo, layoutPairs } from "../../lib/hubLines";
+import { followDone, followFor, follows } from "../../lib/camFollow";
+import { badgeAt, drawBadges } from "./graph/badges";
+import { clusterParams, clusterShift, clusterTargets, hopRings } from "../../lib/layoutEngine";
+import { collapseCentroids, drillTargets } from "../../lib/graphLevels";
+import { graphTheme, hueFor } from "../../lib/graphTheme";
+
+// WIKI-GRAPH-OBSIDIAN-1: the graph surface. Two stacked canvases: the base (every edge and node, on the GPU through Pixi
+// when the browser has WebGL, else our Canvas2D drawing) and the 2D overlay on top (labels, hover/focus highlight; it
+// takes the pointer events). The d3-force layout runs in a worker (layoutClient.js), so the main thread only copies
+// positions in and draws. One requestAnimationFrame loop redraws whichever layer is dirty. Pixi is imported lazily, so
+// the Canvas2D fallback never downloads it. Bench contract (bench/bench.mjs): the `[data-graph-surface]` box gets
+// `data-graph-info`, `data-graph-renderer`, `data-graph-ready` on its first drawn frame and `data-graph-settled-ms` when
+// the worker reports the layout settled; the overlay canvas is the surface's last canvas.
+const NONE = new Set();
+const GOLDEN = Math.PI * (3 - Math.sqrt(5));
+let warned = false; // the fallback warning is logged once per page load, not once per graph
+
+/** Is WebGL available? Probed on a throwaway canvas: a canvas that once gave a webgl context can never give a 2D one. */
+function hasWebGL() {
+  try {
+    const c = document.createElement("canvas");
+    return !!(c.getContext("webgl2") || c.getContext("webgl"));
+  } catch {
+    return false;
+  }
+}
+
+/** `graph` ({nodes, links} from buildGraph, the drawn subset); `layoutKey` names the layout: a new key re-lays-out (warm
+ *  from cached positions by id), a new graph under the same key (colour by area/folder) only recolours. `hidden`: legend
+ *  groups not drawn. `physics`: slider values, sent to the running layout live. `cluster` (WIKI-GRAPH-2D-CLUSTER-ONCE-1, owner
+ *  2026-10-22; was a hull per group with the layout frozen in place): turning it on runs ONE clustered layout (each group pulled
+ *  to its own centre, layoutEngine clusterTargets/clusterParams, the same frame 3D uses) until it settles, then stops it. After
+ *  that nothing moves and no layout message is posted (hover, focus, find, legend filter, resize, a same-topology refresh, a
+ *  slider); a new node set that overlaps the drawn one only places its new docs beside their group (placeAppearing). Reheat
+ *  re-runs the clustered layout once; turning it off moves nothing and Resume / Reheat offer the plain layout again. The rule is
+ *  groupBubbles `layout2d`. No group outline is drawn in 2D. `forced`: `?renderer=` ("canvas" forces
+ *  the fallback). `onOpen(node)` on a click, `onExpand(node)` on a double click (WIKI-GRAPH-LEVELS-1: the page opens a folder); `onLayoutState(state, ms)` on running|paused|settled. The ref exposes
+ *  fit() (fit the whole graph until you move it), pause(), resume() and reheat(). `height`: pixels, or "fill" to take the
+ *  container's whole height and follow it (WIKI-GRAPH-FULLVIEW-1). WIKI-GRAPH-FIND-FILTER-LIVE-1: `match` (ids, or null with
+ *  no find term) lights those nodes and dims the rest through the focus treatment (relight), never a layout pass; `aim`
+ *  ({id, n}: n re-aims) frames the camera on that node and its neighbours until you move it, without changing the focus.
+ *  WIKI-GRAPH-FOCUS-HOPS-1 (2D, no position change): a focus lights its hop rings (layoutEngine hopRings, `hops`, default
+ *  2), the hub guard caps a big hub with a "+N" badge (`onBadge(node)` on a click; `open` is the page's Set of opened hub
+ *  ids), a click on empty space calls `onBackground()`, and the camera frames the lit rings. Cluster by group places a folder
+ *  by its `bubbleGroup` (the page's folderGroups). */
+const GraphCanvas = forwardRef(function GraphCanvas(
+  { graph, layoutKey, hidden = NONE, focusId = null, sizeByDegree = true, physics = PHYSICS_DEFAULTS, cluster = false, forced = null, drill = null, match = null, aim = null, hops = 2, dim = DIM_DEFAULT, open = null, onOpen, onExpand, onBadge, onBackground, onLayoutState, height = 680 },
+  ref,
+) {
+  const fill = height === "fill";
+  const wrap = useRef(null);
+  const over = useRef(null);
+  const st = useRef(null);
+  const latest = useRef(null);
+  latest.current = { graph, layoutKey, hidden, focusId, sizeByDegree, physics, cluster, drill, match, aim, hops, dim, open, onOpen, onExpand, onBadge, onBackground, onLayoutState };
+
+  useImperativeHandle(ref, () => ({
+    fit() {
+      const s = st.current;
+      if (!s) return;
+      s.fitAll = true;
+      s.drill = null;
+      s.aim = -1;
+      s.userMoved = false;
+      placeView(s);
+    },
+    pause: () => st.current?.layout?.pause(),
+    resume: () => restartOr(st.current, "resume"),
+    reheat: () => restartOr(st.current, "reheat"),
+  }), []);
+
+  useEffect(() => {
+    const box = wrap.current, el = over.current;
+    let octx = null;
+    try { octx = el.getContext("2d"); } catch { octx = null; } // jsdom has no canvas: nothing is drawn, nothing breaks
+    const baseEl = document.createElement("canvas"); // made here, not by React: a failed WebGL try may need a fresh one
+    baseEl.style.cssText = "position:absolute;left:0;top:0;pointer-events:none";
+    box.insertBefore(baseEl, el);
+    const s = {
+      box, el, baseEl, octx, latest, w: box.clientWidth || 800, h: fill ? box.clientHeight || 680 : height, dpr: window.devicePixelRatio || 1,
+      view: { k: 1, x: 0, y: 0 }, base: null, sc: null, key: undefined, graph: null, hidden: null, sizeByDegree: null,
+      focusId: undefined, ids: [], index: new Map(), titles: [], labelW: null, off: null, adj: null, pairs: null,
+      visIdx: new Uint32Array(0), cache: new Map(), layout: null, physics: null, t0: 0, focus: -1, hover: -1,
+      focusNear: [], lit: [], litLinks: [], tree: null, baseDirty: false, overlayDirty: false, userMoved: false, fitAll: false, drill: null, drillKey: "", cpairs: new Uint32Array(0), cdraw: {}, follow: null,
+      drag: null, raf: 0, alive: true, ready: false, cluster: undefined, layoutTok: null, layoutState: null, resumeState: null,
+      clustered: false, matchIds: null, match: null, aim: -1, aimKey: "",
+      hops: 2, dimLevel: DIM_DEFAULT, open: null, rings: null, ringsKey: null, capped: new Map(), badges: [], litIdx: new Uint32Array(0),
+    };
+    st.current = s;
+
+    const attach = (base) => {
+      if (!s.alive) { base.destroy(); return; }
+      s.base = base;
+      box.dataset.graphRenderer = base.kind;
+      if (s.sc) { base.setData(s.sc); base.setView(s.sc); }
+      dimBase(s.baseEl, !!s.dim, s.dimLevel); // a fallback base is a fresh canvas: it takes the current dim
+      s.baseDirty = true;
+    };
+    const fallback = (why) => {
+      if (!warned) { warned = true; console.warn(FALLBACK_WARNING, why || ""); }
+      let target = baseEl;
+      if (why) { // the WebGL try may have claimed this canvas: draw on a fresh one
+        target = baseEl.cloneNode();
+        baseEl.replaceWith(target);
+        s.baseEl = target;
+      }
+      attach(createCanvasBase(target, { w: s.w, h: s.h, dpr: s.dpr, background: graphTheme().field }));
+    };
+    if (chooseRenderer({ webgl: hasWebGL(), forced }) === "webgl") {
+      import("./graph/pixiBase")
+        .then((m) => m.createPixiBase(baseEl, { w: s.w, h: s.h, dpr: s.dpr, background: graphTheme().field }))
+        .then(attach, (e) => { if (s.alive) fallback(e?.message || String(e)); });
+    } else {
+      fallback(null);
+    }
+
+    const resize = () => {
+      s.w = box.clientWidth || s.w;
+      if (fill) s.h = box.clientHeight || s.h;
+      s.dpr = window.devicePixelRatio || 1;
+      el.width = Math.round(s.w * s.dpr);
+      el.height = Math.round(s.h * s.dpr);
+      el.style.width = `${s.w}px`;
+      el.style.height = `${s.h}px`;
+      s.base?.resize(s.w, s.h, s.dpr);
+      if (!s.userMoved) placeView(s);
+      s.baseDirty = s.overlayDirty = true;
+    };
+    resize();
+    const ro = typeof ResizeObserver === "function" ? new ResizeObserver(resize) : null;
+    ro?.observe(box);
+    sync(s, latest.current);
+
+    const frame = () => {
+      s.raf = requestAnimationFrame(frame);
+      if (s.baseDirty && s.base && s.sc) {
+        s.baseDirty = false;
+        if (s.base.render() && !s.ready) { s.ready = true; box.dataset.graphReady = "1"; perfSpan("wiki-graph:first-frame", s.t0); }
+      }
+      if (s.overlayDirty && octx) {
+        s.overlayDirty = false;
+        drawOverlay(octx, s.sc, {
+          lit: s.lit, litLinks: s.litLinks, focus: s.focus, hover: s.hover, titles: s.titles, labelW: s.labelW, dpr: s.dpr, w: s.w, h: s.h, heads: s.hotHeads, litOnly: s.dim,
+          under: s.cpairs.length ? (c, sx, sy) => drawContainment(c, drawnMemo(s.cdraw, s.cpairs, [s.hover, s.focus]), sx, sy, (i) => s.sc.mask[i], s.dim ? s.dimLevel : false) : undefined,
+        });
+        s.badges = drawBadges(octx, badgeItems(s), s.dpr);
+      }
+    };
+    if (typeof requestAnimationFrame === "function") s.raf = requestAnimationFrame(frame);
+
+    const local = (e) => { const r = el.getBoundingClientRect(); return [e.clientX - r.left, e.clientY - r.top]; };
+    const moved = (v) => { s.userMoved = true; s.fitAll = false; s.drill = null; s.aim = -1; setView(s, v); };
+    const onWheel = (e) => {
+      e.preventDefault();
+      const [x, y] = local(e);
+      moved(zoomAt(s.view, x, y, Math.exp(-e.deltaY * 0.0015)));
+    };
+    const onDown = (e) => {
+      const [x, y] = local(e);
+      s.drag = { x, y, vx: s.view.x, vy: s.view.y, moved: false };
+      el.setPointerCapture?.(e.pointerId);
+    };
+    const onMove = (e) => {
+      const [x, y] = local(e);
+      if (s.drag) {
+        const dx = x - s.drag.x, dy = y - s.drag.y;
+        if (!s.drag.moved && Math.hypot(dx, dy) > 3) s.drag.moved = true;
+        if (s.drag.moved) moved({ ...s.view, x: s.drag.vx + dx, y: s.drag.vy + dy });
+        return;
+      }
+      const i = pickAt(s, x, y);
+      if (i !== s.hover) {
+        s.hover = i;
+        el.style.cursor = i >= 0 ? "pointer" : "grab";
+        el.title = i >= 0 ? s.titles[i] : "";
+        relight(s);
+      }
+    };
+    const onUp = (e) => {
+      const d = s.drag;
+      s.drag = null;
+      if (d && !d.moved) {
+        const [x, y] = local(e);
+        const b = badgeAt(s.badges, x, y);
+        const i = b >= 0 ? -1 : pickAt(s, x, y);
+        if (b >= 0) latest.current.onBadge?.(s.graph.nodes[b]); // a "+N" badge expands that hub alone
+        else if (i >= 0) latest.current.onOpen?.(s.graph.nodes[i]);
+        else latest.current.onBackground?.(); // empty space: the page clears the focus
+      }
+    };
+    const onDouble = (e) => {
+      const [x, y] = local(e);
+      const i = pickAt(s, x, y);
+      if (i >= 0) latest.current.onExpand?.(s.graph.nodes[i]);
+      else { s.fitAll = true; s.drill = null; s.aim = -1; s.userMoved = false; placeView(s); } // empty space: fit the whole graph, never a node's zoom
+    };
+    const onLeave = () => {
+      if (s.hover >= 0) { s.hover = -1; el.title = ""; relight(s); }
+    };
+    el.addEventListener("wheel", onWheel, { passive: false });
+    el.addEventListener("pointerdown", onDown);
+    el.addEventListener("pointermove", onMove);
+    el.addEventListener("pointerup", onUp);
+    el.addEventListener("pointerleave", onLeave);
+    el.addEventListener("dblclick", onDouble);
+    return () => {
+      s.alive = false;
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(s.raf);
+      ro?.disconnect();
+      s.layout?.stop();
+      s.base?.destroy();
+      s.baseEl.remove();
+      el.removeEventListener("wheel", onWheel);
+      el.removeEventListener("pointerdown", onDown);
+      el.removeEventListener("pointermove", onMove);
+      el.removeEventListener("pointerup", onUp);
+      el.removeEventListener("pointerleave", onLeave);
+      el.removeEventListener("dblclick", onDouble);
+      if (st.current === s) st.current = null;
+    };
+  }, [forced, height]);
+
+  // Data, legend, sizing and focus: `sync` diffs against what is drawn and does the least work (relayout, recolour,
+  // re-mask or relight).
+  useEffect(() => {
+    if (st.current) sync(st.current, latest.current);
+  }, [graph, layoutKey, hidden, sizeByDegree, focusId, cluster, drill, hops, dim, open]);
+
+  // A find term (WIKI-GRAPH-FIND-FILTER-LIVE-1): relight only. Nothing here touches the layout, the positions or the view.
+  useEffect(() => {
+    const s = st.current;
+    if (!s) return;
+    s.matchIds = match;
+    rematch(s);
+    relight(s);
+  }, [match]);
+
+  // Enter on a match: frame it (after sync, so a focus set in the same render is already in place).
+  useEffect(() => {
+    const s = st.current;
+    const key = aim ? `${aim.id}#${aim.n}` : "";
+    if (!s || key === s.aimKey) return;
+    s.aimKey = key;
+    s.aim = aim && s.index.has(aim.id) ? s.index.get(aim.id) : -1;
+    if (s.aim < 0) return;
+    s.userMoved = false;
+    s.fitAll = false;
+    s.drill = null;
+    placeView(s);
+  }, [aim]);
+
+  // Sliders: the running layout gets the new parameters (and reheats); nothing restarts. With cluster on the values are only
+  // kept (a params message reheats), and the next layout uses them.
+  useEffect(() => {
+    const s = st.current;
+    if (!s?.physics) return;
+    const p = latest.current.physics;
+    if (p.repel === s.physics.repel && p.link === s.physics.link && p.centre === s.physics.centre) return;
+    s.physics = { ...p, cluster: false };
+    if (s.layout && !s.cluster) s.layout.params(s.physics);
+  }, [physics.repel, physics.link, physics.centre]);
+
+  return (
+    <div
+      ref={wrap}
+      data-graph-surface=""
+      className={`relative w-full overflow-hidden ${fill ? "h-full" : "rounded-lg"}`}
+      style={{ height: fill ? undefined : height, background: graphTheme().field }}
+    >
+      <canvas
+        ref={over}
+        role="img"
+        aria-label={`Graph of ${graph.nodes.length} docs and ${graph.links.length} links`}
+        className="absolute left-0 top-0 block touch-none"
+        style={{ cursor: "grab" }}
+      />
+    </div>
+  );
+});
+
+export default GraphCanvas;
+
+const endOf = (end) => (typeof end === "object" && end ? end.id : end);
+
+/** Does `p.graph` hold the same nodes (ids, in order) and the same links (the index pairs the scene draws, in order) as the
+ *  scene? Only then may a new graph object take the recolour path; any change to the node set OR the links rebuilds
+ *  topology (WIKI-GRAPH-REFRESH-FU-1). */
+function sameTopology(s, graph) {
+  const { nodes, links } = graph;
+  if (nodes.length !== s.sc.n || !nodes.every((n, i) => n.id === s.ids[i])) return false;
+  let k = 0;
+  for (const l of links) {
+    const a = s.index.get(endOf(l.source)), b = s.index.get(endOf(l.target));
+    if (a === undefined || b === undefined) continue; // build skips these too
+    if (s.pairs[k++] !== a || s.pairs[k++] !== b) return false;
+  }
+  return k === s.pairs.length;
+}
+
+/** Bring what is drawn in line with the props `p`. */
+function sync(s, p) {
+  const key = p.layoutKey ?? p.graph;
+  const was = s.cluster;
+  s.cluster = !!p.cluster;
+  if (was !== s.cluster) s.clustered = false; // a toggle: the clustered layout has to run (again) before anything stays put
+  let built = false;
+  if (!s.sc || key !== s.key) {
+    build(s, p);
+    built = true;
+  } else if (p.graph !== s.graph) {
+    if (sameTopology(s, p.graph)) recolour(s, p);
+    else { build(s, p); built = true; }
+  }
+  if (!built && p.hidden !== s.hidden) { remask(s, p.hidden); s.base?.setVisible(s.sc); }
+  if (!built && p.sizeByDegree !== s.sizeByDegree) { resize(s, p); s.base?.setStyle(s.sc); }
+  const drillKey = p.drill ? `${p.drill.id}#${p.drill.n}` : ""; // a repeat drill into the same folder re-aims (the nonce differs)
+  const drilled = drillKey !== s.drillKey;
+  if (drilled) { s.drillKey = drillKey; s.drill = p.drill ? p.drill.id : null; }
+  const hops = p.hops ?? 2, open = p.open ?? null;
+  const hopsChanged = hops !== s.hops || open !== s.open, focusChanged = p.focusId !== s.focusId;
+  s.hops = hops;
+  s.open = open;
+  const dimLevel = p.dim ?? DIM_DEFAULT;
+  if (dimLevel !== s.dimLevel) { s.dimLevel = dimLevel; if (s.baseEl) dimBase(s.baseEl, !!s.dim, dimLevel); s.overlayDirty = true; } // one dim level, 2D and 3D
+  if (built || drilled || focusChanged) {
+    s.focusId = p.focusId;
+    s.focus = p.focusId != null && s.index.has(p.focusId) ? s.index.get(p.focusId) : -1;
+    s.userMoved = false;
+    s.fitAll = false;
+  }
+  // WIKI-GRAPH-LOCAL-HOPS-RECULL-1: a focus draws only its rings, so anything that moves the rings (a new node
+  // set, the focus, hops, an opened hub) re-culls here, before the relight and the framing read the mask.
+  const cull = localKeep(s.focus, ringsOf(s)), culled = cull !== s.cull;
+  if (culled) { s.cull = cull; remask(s, p.hidden); s.base?.setVisible(s.sc); }
+  if (built || drilled || focusChanged || hopsChanged || culled) { // 2D relights and reframes only: no node moves (owner ruling 2026-10-21)
+    relight(s);
+    placeView(s);
+  }
+  if (!built && was !== undefined && was !== s.cluster) { if (s.cluster) clusterOn(s); else clusterOff(s); }
+  s.baseDirty = s.overlayDirty = true;
+}
+
+/** A new node set: positions (cached by id, else seeded), the arrays both bases read, and a fresh layout, unless cluster is
+ *  on, its clustered layout already settled here and some node already has a position: then nothing is laid out and only the
+ *  new nodes are placed, beside their group (layout2d). */
+function build(s, p) {
+  if (s.sc) for (let i = 0; i < s.sc.n; i++) s.cache.set(s.ids[i], [s.sc.pos[2 * i], s.sc.pos[2 * i + 1]]);
+  stopLayout(s);
+  const { nodes, links } = p.graph;
+  const n = nodes.length;
+  if (s.graph) { // a collapse: the new folder starts where its children were, not at a fresh seed
+    const old = s.graph.nodes;
+    for (const [id, c] of collapseCentroids(old, (i) => s.cache.get(old[i].id), nodes)) s.cache.set(id, c);
+  }
+  seedPositions(nodes, false); // cluster is not a layout input: every target is 0,0
+  const pos = new Float32Array(Math.max(2, 2 * n)), known = new Uint8Array(n);
+  s.ids = nodes.map((nd) => nd.id);
+  s.index = new Map(s.ids.map((id, i) => [id, i]));
+  let warm = false, cached = false; // cached: a position from this surface (its cache or a cached parent), not the host's fit
+  const served = serverFits(nodes, 2); // the host's settled layout of exactly this graph (WIKI-GRAPH-WARMSTART-3D-1)
+  const born = new Map(); // parent id -> children placed under it so far
+  for (let i = 0; i < n; i++) {
+    const nd = nodes[i];
+    let c = s.cache.get(nd.id);
+    if (!c && nd.parent && s.cache.has(nd.parent)) { // a folder was just opened: its children start where it was, fanned out a little
+      const [px, py] = s.cache.get(nd.parent), j = (born.get(nd.parent) || 0) + 1, r = 6 * Math.sqrt(j);
+      born.set(nd.parent, j);
+      c = [px + Math.cos(j * GOLDEN) * r, py + Math.sin(j * GOLDEN) * r];
+    }
+    if (c) cached = true;
+    if (!c && served) c = nd.warm2;
+    if (c) { pos[2 * i] = c[0]; pos[2 * i + 1] = c[1]; warm = true; known[i] = 1; } else { pos[2 * i] = nd.x; pos[2 * i + 1] = nd.y; }
+  }
+  // links as index pairs, direction flags and incidence lists (CSR, so a node's neighbours are a slice): the shared linkArrays
+  const { pairs: used, dirs, weights, off, adj } = linkArrays(links, s.index, n, dirOf);
+  const k = used.length;
+  s.pairs = used; s.dirs = dirs; s.weights = weights; s.off = off; s.adj = adj;
+  s.cpairs = containPairs(p.graph.contains, s.index); // hub -> contained node: layout springs and dashed lines (a giant hub: neither by default, hubLines), never links
+  const run = layout2d({ event: "build", cluster: !!p.cluster, clustered: s.clustered, warm: cached });
+  if (!run) placeAppearing(pos, 2, known, used, (i) => bubbleGroupOf(nodes[i]), { groupFirst: true }); // the clusters stay put: new docs join their group
+  else if (run === "cluster") s.clustered = false;
+  const degree = Uint32Array.from(nodes, (nd) => nd.degree || 0);
+  const order = Uint32Array.from({ length: n }, (_, i) => i).sort((a, b) => degree[b] - degree[a]);
+  s.titles = nodes.map((nd) => nd.title);
+  s.labelW = new Float32Array(n).fill(NaN);
+  s.sc = {
+    n, pos, colors: new Uint32Array(n), sizes: new Float32Array(n), mask: null, visPairs: new Uint32Array(k), visDirs: new Uint8Array(k / 2), visWeights: new Float32Array(k / 2), visBuckets: null, visCount: 0,
+    visibleN: n, view: s.view, big: n > LOD_N, edgeAlpha: lodFor(n, 1).edgeAlpha, degree, order,
+  };
+  s.key = p.layoutKey ?? p.graph;
+  s.hover = -1;
+  s.aim = -1;
+  rematch(s);
+  colour(s, p);
+  resize(s, p);
+  s.cull = null; // the old rings are indices into the old node set: sync re-culls once the focus is placed in this one
+  remask(s, p.hidden);
+  s.box.dataset.graphInfo = JSON.stringify({ nodes: n, links: k / 2, lod: s.sc.big });
+  s.base?.setData(s.sc);
+  s.base?.setView(s.sc);
+  s.physics = { ...p.physics, cluster: false };
+  s.t0 = performance.now();
+  delete s.box.dataset.graphSettledMs;
+  if (!n) return;
+  s.follow = followFor(null, s.key); // a new node set: its first layout gets a fresh follow budget; Resume / Reheat later keep it (2D has no other view state that moves nodes)
+  if (!run) { s.follow = followDone(s.key); report(s, "settled", null); return; }
+  start(s, warm, run);
+}
+
+/** The group a node is clustered with: the page's `bubbleGroup` (a folder's area, folderGroups), else its legend group; a
+ *  folder without one belongs to none. Same rule as 3D. */
+const bubbleGroupOf = (nd) => nd.bubbleGroup ?? (nd.kind === "folder" ? null : nd.group ?? null);
+
+/** Start a layout over the current positions. `phase` "global": targets 0,0 and the user's physics; "cluster": each group's
+ *  docs pulled to its own centre (clusterTargets, clusterParams' strong pull, a short warm run like 3D's), and the layout is
+ *  STOPPED once it settles, so nothing posts or moves after it (WIKI-GRAPH-2D-CLUSTER-ONCE-1). Ticks and states from any
+ *  layout but the latest are dropped, so a stopped one can never move a node. */
+function start(s, warm, phase = "global") {
+  const sc = s.sc, tok = {}, clustering = phase === "cluster";
+  s.layoutTok = tok;
+  const targets = clustering ? clusterTargets(sc.pos, 2, (i) => bubbleGroupOf(s.graph.nodes[i])).targets : new Float32Array(2 * sc.n);
+  s.layout = startLayout({
+    xy: sc.pos, pairs: layoutPairs(s.pairs, s.cpairs), weights: s.weights, targets, physics: s.physics, big: sc.big, warm,
+    params: clustering ? clusterParams(s.physics) : null, alpha: clustering ? (warm ? 0.6 : 1) : null, maxTicks: clustering && warm ? 120 : null,
+    radii: layoutRadii(s.graph.nodes, (i) => sc.sizes[i] / 2),
+    onTick: (xy) => {
+      if (s.layoutTok !== tok || s.sc !== sc || xy.length !== sc.pos.length) return; // a frame from a layout we already replaced
+      sc.pos.set(xy);
+      s.base?.setPositions(sc);
+      s.tree = null;
+      if (follows(s.follow, "tick", performance.now(), s.userMoved)) placeView(s); // WIKI-GRAPH-DRIFT-LONG-EDGES-1: a bounded follow, never after the first settle
+      s.baseDirty = s.overlayDirty = true;
+    },
+    onState: (state, ms) => {
+      if (s.layoutTok !== tok || s.sc !== sc) return;
+      if (state === "settled") {
+        s.box.dataset.graphSettledMs = String(Math.round(performance.now() - s.t0));
+        perfSpan("wiki-graph:settle", s.t0);
+        if (follows(s.follow, "settled", performance.now(), s.userMoved)) placeView(s);
+        if (clustering) { stopLayout(s); s.clustered = true; } // the one clustered layout is done: from here on nothing moves
+      }
+      report(s, state, ms);
+    },
+  });
+  if (s.layout) return;
+  s.layoutTok = null;
+  s.follow = followDone(s.key);
+  if (clustering) { // no Worker: each group moves rigidly onto its centre, once
+    console.warn("wiki graph: no layout worker, the 2D clustered layout is a direct shift with no simulation (links and repulsion are not applied)");
+    sc.pos.set(clusterShift(sc.pos, 2, (i) => bubbleGroupOf(s.graph.nodes[i]), targets));
+    s.base?.setPositions(sc);
+    s.tree = null;
+    s.clustered = true;
+    placeView(s);
+    s.baseDirty = s.overlayDirty = true;
+  }
+  report(s, "settled", null); // no Worker: the seeded (or shifted) layout is the layout
+}
+
+function stopLayout(s) {
+  s.layout?.stop();
+  s.layout = null;
+  s.layoutTok = null;
+}
+
+function report(s, state, ms) {
+  s.layoutState = state;
+  s.latest.current.onLayoutState?.(state, ms);
+}
+
+/** Cluster turned on: stop the plain layout where it is and run the clustered one once (a new view: the camera follows it
+ *  once). What Resume / Reheat offer once it is off again: a plain layout that had not settled can be resumed. */
+function clusterOn(s) {
+  s.resumeState = s.layout && s.layoutState !== "settled" ? "paused" : "settled";
+  stopLayout(s);
+  if (!s.sc?.n || layout2d({ event: "toggle", cluster: true }) !== "cluster") return;
+  s.follow = followFor(null, `${String(s.key)}#cluster`);
+  start(s, true, "cluster");
+}
+
+/** Cluster turned off: nothing moves (a clustered layout still running stops where it is); the controls get back the state the
+ *  plain layout had when cluster went on. */
+function clusterOff(s) {
+  stopLayout(s);
+  report(s, s.resumeState || "settled", null);
+}
+
+/** Resume / Reheat. Cluster on: Resume continues a paused clustered layout, Reheat (the relayout button) re-runs it once from
+ *  where the docs are. Cluster off: the plain layout, a fresh one when there is none. */
+function restartOr(s, verb) {
+  if (!s || !s.sc?.n) return;
+  if (layout2d({ event: "relayout", cluster: s.cluster }) === "cluster") {
+    if (verb === "resume" && s.layout) { s.layout.resume(); return; }
+    stopLayout(s);
+    s.clustered = false;
+    start(s, true, "cluster");
+    return;
+  }
+  if (s.layout) s.layout[verb]();
+  else start(s, true);
+}
+
+/** Colours (and the legend groups they come from) for the current node set. */
+function colour(s, p) {
+  const { nodes } = p.graph;
+  for (let i = 0; i < nodes.length; i++) s.sc.colors[i] = parseInt(hueFor(nodes[i].color || OTHER).slice(1), 16);
+  s.graph = p.graph;
+  // WIKI-GRAPH-3D-COLOR-SPHERES-1: doc / folder / hub looks (graphView nodeLooks); true when a hub or folder changed, which the base must rebuild for.
+  const looks = nodeLooks(nodes), old = s.sc.looks;
+  s.sc.looks = looks;
+  return !old || old.some((v, i) => v !== looks[i]);
+}
+
+/** Same nodes and links, new graph object (colour by area or folder, a folder's size): recolour, resize and re-mask, no relayout. */
+function recolour(s, p) {
+  const relooked = colour(s, p);
+  refreshSameTopology(s, p.graph, dirOf);
+  s.layout?.weights(s.weights); // new link strengths for the next ticks; positions stay where they are (refreshSameTopology also sent any new containment pairs)
+  const { nodes } = p.graph, degree = Uint32Array.from(nodes, (nd) => nd.degree || 0);
+  s.sc.degree = degree;
+  s.sc.order = Uint32Array.from({ length: nodes.length }, (_, i) => i).sort((a, b) => degree[b] - degree[a]);
+  resize(s, p);
+  if (relooked) s.base?.setData(s.sc);
+  s.base?.setStyle(s.sc);
+  remask(s, p.hidden);
+  s.base?.setVisible(s.sc);
+}
+
+function resize(s, p) {
+  const { nodes } = p.graph;
+  for (let i = 0; i < nodes.length; i++) s.sc.sizes[i] = levelSize(nodes[i], p.sizeByDegree); // a folder by its docs (3D's rule)
+  s.sizeByDegree = p.sizeByDegree;
+}
+
+/** The legend mask, the drawn links and the visible index list (fit and hit testing use it). */
+function remask(s, hidden) {
+  const sc = s.sc;
+  sc.mask = visibleMask(s.graph.nodes, hidden, s.cull); // s.cull: a focus's rings (localKeep), else null
+  sc.visCount = visibleLinks(s.pairs, sc.mask, sc.visPairs, s.dirs, sc.visDirs, s.weights, sc.visWeights);
+  sc.visBuckets = linkBuckets(sc.visWeights, sc.visCount); // the width passes every base draws (linkWeight.js)
+  const vis = [];
+  for (let i = 0; i < sc.n; i++) if (sc.mask[i]) vis.push(i);
+  s.visIdx = Uint32Array.from(vis);
+  sc.visibleN = vis.length;
+  s.hidden = hidden;
+  s.tree = null;
+  s.overlayDirty = s.baseDirty = true;
+}
+
+function setView(s, v) {
+  s.view = v;
+  if (s.sc) { s.sc.view = v; s.base?.setView(s.sc); }
+  s.baseDirty = s.overlayDirty = true;
+}
+
+/** Fit everything (also after fit() until you move), or the focused doc with its neighbours (centred on it when it has
+ *  none), as today. Every frame goes through robustBox (WIKI-GRAPH-FIT-HIDDEN-1): a few far-out nodes never shrink or off-centre it. */
+function placeView(s) {
+  if (!s.sc) return;
+  const { pos, mask } = s.sc;
+  const dt = !s.fitAll && s.drill ? drillTargets(s.graph.nodes, s.drill).filter((i) => mask[i]) : []; // a drilled folder and its drawn children
+  if (dt.length) { setView(s, robustBox(pos, dt, s.w, s.h, 60, s.sc.sizes)); return; }
+  const at = s.aim >= 0 ? s.aim : s.focus; // an Enter on a find match frames it, the focus otherwise
+  if (s.fitAll || at < 0 || !mask[at]) { setView(s, robustBox(pos, s.visIdx, s.w, s.h, 40, s.sc.sizes)); return; }
+  const fx = pos[2 * at], fy = pos[2 * at + 1];
+  const around = (at === s.focus ? s.focusNear : near(s, at)).filter((i) => mask[i]);
+  const fit = robustBox(pos, around, s.w, s.h, 60, s.sc.sizes);
+  setView(s, around.length > 1 ? (fit.k > 3 ? centreOn(fx, fy, s.w, s.h, 3) : fit) : centreOn(fx, fy, s.w, s.h, 2));
+}
+
+/** Node index `i` with its neighbours. */
+function near(s, i) {
+  const out = [i];
+  for (let e = s.off[i]; e < s.off[i + 1]; e++) out.push(s.adj[e]);
+  return out;
+}
+
+/** The find matches as node indices of the drawn set (null with no term); ids not drawn are skipped. */
+function rematch(s) {
+  s.match = s.matchIds ? s.matchIds.map((id) => s.index.get(id)).filter((i) => i !== undefined) : null;
+}
+
+/** The lit set and its links (graphView litOf: the focus's hop rings, hover with its neighbours, or the find matches) and the base dim. */
+function relight(s) {
+  if (!s.sc) return;
+  const rings = ringsOf(s);
+  s.focusNear = rings ? [...rings.lit] : [];
+  s.capped = rings ? rings.capped : new Map();
+  const { lit, links, dim } = litOf({ focus: s.focus, hover: s.hover, near: (i) => near(s, i), match: s.match, focusLit: rings ? s.focusNear : null });
+  s.lit = lit;
+  s.litIdx = Uint32Array.from(lit.filter((i) => s.sc.mask[i]));
+  s.litLinks = links;
+  s.dim = dim;
+  s.hotHeads = s.focus >= 0 || s.hover >= 0 ? hotHeads(s.pairs, s.dirs, [s.focus, s.hover]) : null;
+  dimBase(s.baseEl, dim, s.dimLevel);
+  s.box.dataset.graphLit = s.match ? String(s.lit.length) : "";
+  s.overlayDirty = true;
+}
+
+/** The visible node under screen point (x, y), or -1: the nearest within its drawn radius (at least 6 screen px). */
+function hitTest(s, x, y) {
+  const sc = s.sc;
+  if (!sc || !sc.n) return -1;
+  const { pos, view: v, sizes, big } = sc;
+  if (!s.tree) s.tree = quadtree().x((i) => pos[2 * i]).y((i) => pos[2 * i + 1]).addAll(s.visIdx);
+  const wx = (x - v.x) / v.k, wy = (y - v.y) / v.k;
+  const i = s.tree.find(wx, wy, Math.max(drawRadius(SIZE_MAX, v.k, big), 6 / v.k));
+  if (i === undefined) return -1;
+  const r = Math.max(drawRadius(sizes[i], v.k, big), 6 / v.k);
+  return (pos[2 * i] - wx) ** 2 + (pos[2 * i + 1] - wy) ** 2 <= r * r ? i : -1;
+}
+
+/** The node under (x, y), from the pickable set only (graphView pickable): nothing dimmed, the quadtree over every visible node;
+ *  something dimmed, the nearest lit node within its drawn radius, so a dimmed node is never picked. */
+function pickAt(s, x, y) {
+  if (!s.sc) return -1;
+  if (!s.dim) return hitTest(s, x, y);
+  const { pos, view: v, sizes, big } = s.sc, wx = (x - v.x) / v.k, wy = (y - v.y) / v.k;
+  let best = -1, bd = Infinity;
+  for (const i of pickable(s.visIdx, s.litIdx, true)) {
+    const r = Math.max(drawRadius(sizes[i], v.k, big), 6 / v.k), d = (pos[2 * i] - wx) ** 2 + (pos[2 * i + 1] - wy) ** 2;
+    if (d <= r * r && d < bd) { best = i; bd = d; }
+  }
+  return best;
+}
+
+/** The "+N" badges this frame: each capped hub of the focus ring that is lit and drawn, at its screen position. */
+function badgeItems(s) {
+  const out = [];
+  if (!s.capped.size || !s.sc) return out;
+  const lit = new Set(s.lit), { pos, view: v, sizes, big } = s.sc;
+  for (const [i, n] of s.capped) {
+    if (lit.has(i) && s.sc.mask[i]) out.push({ i, n, x: pos[2 * i] * v.k + v.x, y: pos[2 * i + 1] * v.k + v.y, r: drawRadius(sizes[i], v.k, big) * v.k });
+  }
+  return out;
+}
+
+/** The focus's hop rings (layoutEngine hopRings, the hub guard capping big hubs), cached on focus, hops, opened hubs and
+ *  node set. Null with no focus. `s.open` holds the page's badge-opened ids. */
+function ringsOf(s) {
+  if (!s.sc || s.focus < 0) { s.rings = null; s.ringsKey = null; return null; }
+  const key = [s.focus, s.hops, s.open, s.sc];
+  if (s.rings && s.ringsKey && key.every((v, k) => v === s.ringsKey[k])) return s.rings;
+  const open = s.open ? new Set([...s.open].map((id) => s.index.get(id)).filter((i) => i !== undefined)) : null;
+  s.rings = hopRings({ get: (i) => near(s, i) }, s.focus, s.hops, { open });
+  s.ringsKey = key;
+  return s.rings;
+}