@smartmemory/wiki-components 0.5.0 → 0.6.0

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

@@ -0,0 +1,1366 @@
+import React, { forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import { CARD_KEYS_HELP } from "../../lib/cardVisibility";
+import { DIM_DEFAULT, PHYSICS_DEFAULTS, dimBase, forceParams, layoutRadii, litOf, localKeep, nodeLooks, pickable, visibleLinks, visibleMask } from "../../lib/graphView";
+import { startLayout } from "../../lib/layoutClient";
+import { linkBuckets } from "../../lib/linkWeight";
+import { perfSpan } from "../../lib/perf";
+import { dirOf, hotHeads } from "../../lib/graphArrows";
+import { LOD_N, OTHER, lodFor } from "../../lib/wikiGraph";
+import { cameraOf, dragStarted, holdPins, pinArmed, pinOffset, pinTarget } from "../../lib/graphPin";
+import { FOV, fitDistance, fitSphere, linkArrays, nodeRadius, pickProjected, pickStack, project, refreshSameTopology, sameTopology, seed3d } from "../../lib/graph3d";
+import { robustSphere } from "../../lib/robustFit";
+import { depthCycle, dollyBy, flashRing, orbitAbout, screenList } from "../../lib/canvasPort";
+import { lassoSample } from "../../lib/graphLasso";
+import { arcPoint, cameraFor, gizmoAxes, orientationOf, snapOrient } from "../../lib/graphOrient";
+import { buttonActions, MOUSE_HELP } from "../../lib/graphPress";
+import { BUBBLE_HZ, groupBubbles, outlinesShown, placesStatically } from "../../lib/groupBubbles";
+import { prefersReducedMotion, watchReducedMotion } from "../../lib/reducedMotion";
+import { IDLE_STEP_MAX_MS, idleRate, turnAzimuth } from "../../lib/idleTurn";
+import { clusterParams, clusterShift, clusterTargets, focusShells, glide, hopRings } from "../../lib/layoutEngine";
+import { createThreeBase } from "./graph/threeBase";
+import { bubbleLabels, createBubbles3d, drawBubbleLabels } from "./graph/bubbles3d";
+import { drawOverlay } from "./graph/overlay";
+import { badgeAt, drawBadges } from "./graph/badges";
+import { containPairs, drawContainment } from "./graph/containment";
+import { drawnMemo, layoutPairs } from "../../lib/hubLines";
+import { followDone, followFor, follows } from "../../lib/camFollow";
+import { collapseCentroids, drillTargets } from "../../lib/graphLevels";
+import { graphTheme, hueFor } from "../../lib/graphTheme";
+
+// WIKI-GRAPH-3D-1: the 3D graph surface, GraphCanvas.jsx's twin. Two stacked canvases: the three.js base (threeBase.js:
+// every node, edge and arrowhead) and the same 2D overlay as 2D (overlay.js: labels, hover/focus highlight), which takes the
+// pointer (OrbitControls orbit/zoom/pan, our click/double-click/hover). The overlay is fed a projected stand-in scene: each
+// node's screen position and drawn radius from this frame's camera, divided by the effective zoom k (focal / camera-to-target
+// distance) with view {k, 0, 0}, so drawOverlay's sx/sy/rPx are the 3D projection and lodFor(visibleN, k) keeps the 2D label
+// rule. The d3-force-3d layout runs in its own worker (forceWorker3d.js through layoutClient dims 3). One rAF loop renders
+// only when the camera, the positions or the style changed. Same props, ref and bench contract as GraphCanvas
+// (`data-graph-renderer="three"`), plus `onUnavailable(reason)` when no WebGL renderer can be made: the page drops to 2D.
+const NONE = new Set();
+const TWEEN_MS = 450;
+const CLICK_PX = 3;
+const ease = (t) => 1 - (1 - t) ** 3;
+const FIT_FLOOR = 4; // fit-all never closer than focal / 4 (same cap as 2D fitBox)
+const focalFor = (h) => h / (2 * Math.tan((FOV * Math.PI) / 360)); // px per world unit at distance 1
+
+/** Frames, glide and focus (WIKI-GRAPH-CLUSTER-REGROUP-1 + WIKI-GRAPH-FOCUS-HOPS-1, owner ruling 2026-10-21: "3D regroups,
+ *  2D stays put"). Two base frames: the global layout and, with "Cluster by group" on, a clustered one laid out toward per-group
+ *  centres (layoutEngine clusterTargets, clusterParams). Cluster on saves the global frame and glides into the clustered one;
+ *  off glides straight back to the saved global frame with no simulation. A focus lights its hop rings (hopRings, `hops`, the
+ *  hub guard's "+N" badges, `open` hubs) and lays only the lit ring out onto shells round the focus (focusShells) with every
+ *  unlit node pinned; clearing it glides the ring back to the base frame. Every move is a glide (layoutEngine glide): layout
+ *  ticks write `s.goal` and the frame loop eases the drawn positions toward it. A new node set is laid out directly in the
+ *  active base frame. Typing (`match`) only relights. Group outlines are off by default in 3D (`outlines` turns on the subtle
+ *  OUTLINE_STYLE); the group names are drawn while cluster is on.
+ *  Props: GraphCanvas's (`graph, layoutKey, hidden, focusId, sizeByDegree, physics, cluster, forced, onOpen, onExpand,
+ *  onLayoutState, height`; `forced` is accepted and ignored, the page picks the surface) plus `onUnavailable(reason)`, called
+ *  once when the WebGL renderer cannot be created or its context is lost, `hops` (default 2), `open` (a Set of badge-opened
+ *  hub ids), `outlines`, `onBadge(node)` (a "+N" badge clicked) and `onBackground()` (a click on empty space). `match` and
+ *  `aim` (WIKI-GRAPH-FIND-FILTER-LIVE-1) are GraphCanvas's: the find matches lit over the dimmed base, and a camera aim at a
+ *  node. The ref exposes fit(), pause(), resume(), reheat() and focus(id).
+ *
+ *  The canvas port (WIKI-GRAPH-3D-PORT-1, EXPLORE-1b REPORT handoff item 4; the 2D canvas has none of these names yet, so they
+ *  are the contract's): `onEvent({type, id, x, y, shift, meta, alt})` with type hover | click | dblclick | context | press (x, y
+ *  relative to the surface, id null on empty space, meta = Cmd or Ctrl, press = a touch pointerdown); when it is given it
+ *  REPLACES onOpen / onExpand / onBackground (onBadge stays), and right clicks are left to the page's menu (not
+ *  preventDefaulted). An Alt-click is a click on the next node back under the pointer (canvasPort depthCycle). `marks = {lit:
+ *  Set|null, links: [a, b][], selected: Set, hoverId}` (ids) is merged into the lit set: `lit` lights those docs over the
+ *  dimmed base (null = no lens), `links` lights those links, `selected` gets its own ring, `hoverId` lights a doc as a pointer
+ *  hover would (a list row). `onHoverCard(card | null)`: the anchored hover-card feed, card = {id, x, y, r, behind, w, h} (the
+ *  hovered dot's projection and drawn radius in surface px, how many more docs are under the pointer behind it, the surface
+ *  size), called when any of it changes (every frame the dot moves) and null while dragging, on touch, or with the dot behind
+ *  the camera; place the card with canvasPort placeCard. With it the native `title` tooltip is off. Imperative: fitTo(ids)
+ *  flies the camera (~450 ms, the orbit angle kept) to frame the docs (one id: the doc and its neighbours), false when none is
+ *  drawn; flash(id) an expanding ring for ~900 ms; screenPositions(ids?) -> [{id, x, y, visible, degree}] (canvasPort
+ *  screenList); idAt(clientX, clientY) -> id | null; zoomBy(f) (f > 1 closer, tweened); keepView(id): the next focus change to
+ *  `id` (null: to none) neither fits nor frames, it only pans the doc on screen when it is off it. Pointer (3D-UX-1 D1): drag
+ *  turns round the pivot (the focused doc, else the centre of the visible docs; canvasPort orbitAbout) with a cross drawn on it
+ *  while turning; middle-drag, Cmd-drag or Option/Alt-drag pans (graphPress.js); right button never pans.
+ *
+ *  Lasso (WIKI-GRAPH-EXPLORE-1c-UI, 3D-UX-1 D2): with `onLasso({phase, pts})` given, a Shift-drag with the mouse's left button draws a
+ *  polygon instead of turning (OrbitControls is off for that press; no lasso on touch). phase = start | move | end | cancel, `pts` =
+ *  [[x, y], ...] in surface px, sampled (lib/graphLasso lassoSample) and drawn on the overlay while it lasts. `end` comes on release
+ *  after a drag; a Shift-click that never moved is `cancel` and stays a plain click. The page picks the docs: screenPositions() rows
+ *  carry `depth`, and pivotDepth() is the turn pivot's view depth (null with nothing drawn), the line between front and behind.
+ *  Drag-to-pin (round 2): with `onPin({phase: "pins", ids})` given, a plain left-drag that starts ON a dot moves it in the camera-facing
+ *  plane at its depth (lib/graphPin) and pins it (the worker holds fx/fy/fz); a press that never moves is the usual click, a drag on empty
+ *  space still turns, Shift is the lasso, Alt/middle pan, touch turns. `onPin` fires when the pinned set changes (a drop, releasePins(),
+ *  a new surface clears it). `marks.pinned` (a Set of ids) draws a pin head on each; releasePins() lets them all go; pinnedIds() lists them. */
+const GraphCanvas3D = forwardRef(function GraphCanvas3D(
+  { graph, layoutKey, hidden = NONE, focusId = null, sizeByDegree = true, physics = PHYSICS_DEFAULTS, cluster = false, drill = null, match = null, aim = null, hops = 2, dim = DIM_DEFAULT, open = null, outlines = false, idleTurn = false, marks = null, onEvent, onLasso, onPin, onHoverCard, onOpen, onExpand, onBadge, onBackground, onLayoutState, onUnavailable, 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, outlines, idleTurn, marks, onEvent, onLasso, onPin, onHoverCard, onOpen, onExpand, onBadge, onBackground, onLayoutState, onUnavailable };
+
+  useImperativeHandle(ref, () => ({
+    fit() {
+      const s = st.current;
+      if (!s) return;
+      s.fitAll = true;
+      s.fitIdx = null;
+      s.drill = null;
+      s.aim = -1;
+      s.userMoved = false;
+      placeView(s);
+    },
+    focus(id) {
+      const s = st.current;
+      if (!s?.sc || !s.index.has(id)) return;
+      s.focus = s.index.get(id);
+      s.fitAll = false;
+      s.fitIdx = null;
+      s.drill = null;
+      s.aim = -1;
+      s.userMoved = false;
+      relight(s);
+      placeView(s);
+    },
+    pause: () => st.current?.layout?.pause(),
+    resume: () => restartOr(st.current, "resume"),
+    reheat: () => restartOr(st.current, "reheat"),
+    releasePins() {
+      const s = st.current;
+      if (!s?.pins.size) return 0;
+      const n = s.pins.size;
+      s.layout?.unpin();
+      s.pins.clear();
+      s.dirty = true;
+      s.latest.current.onPin?.({ phase: "pins", ids: [] });
+      return n;
+    },
+    pinnedIds: () => [...(st.current?.pins.keys() || [])],
+    /** Saved views (round 5). `orientation(pending)`: the camera's `{az, el, k}` about its orbit target (graphOrient), or null before the camera exists; with `pending` true and a tween running, the tween's end instead (keyboard steps).
+     *  `pinList()`: each pin as `{id, x, y, z}`. `applyOrient(o)`: fly to orientation `o` round the target the camera is going to (a pending
+     *  fly-to's end, else where it is), at the current fit distance: relative, never absolute. `setPins(list)`: replace the pins with `list`
+     *  (`{id, x, y, z}`), holding each drawn one at its place; returns how many were drawn, -1 when nothing is drawn yet. */
+    orientation(pending = false) {
+      const s = st.current;
+      if (!s?.base || !s.controls) return null;
+      if (pending && s.tween) return orientationOf(s.tween.to.t, s.tween.to.p, fitDistOf(s)); // keyboard steps start from where the camera is going
+      const t = s.controls.target, c = s.base.camera.position;
+      return orientationOf([t.x, t.y, t.z], [c.x, c.y, c.z], fitDistOf(s));
+    },
+    pinList: () => [...(st.current?.pins || [])].map(([id, p]) => ({ id, x: p[0], y: p[1], z: p[2] })),
+    applyOrient(o) {
+      const s = st.current;
+      if (!s?.base || !s.controls) return false;
+      const t = s.tween?.to.t || (({ x, y, z }) => [x, y, z])(s.controls.target);
+      markUserMove(s);
+      fly(s, t, cameraFor(t, o, fitDistOf(s)), false, false);
+      return true;
+    },
+    setPins(list) {
+      const s = st.current;
+      if (!s?.sc) return -1;
+      if (s.pins.size) { s.layout?.unpin(); s.pins.clear(); }
+      let n = 0;
+      for (const p of Array.isArray(list) ? list : []) {
+        const i = s.index.get(p.id);
+        if (i === undefined || !s.sc.mask[i]) continue;
+        const at = [p.x, p.y, p.z];
+        s.pins.set(p.id, at);
+        s.sc.xyz.set(at, 3 * i);
+        s.goal?.set(at, 3 * i);
+        s.layout?.pin(i, at[0], at[1], at[2]);
+        n++;
+      }
+      s.base?.setPositions(s.sc); // a paused worker posts no tick: upload the restored spheres and links now (as dragPin does)
+      s.dirty = true;
+      s.overlayDirty = true;
+      s.latest.current.onPin?.({ phase: "pins", ids: [...s.pins.keys()] });
+      return n;
+    },
+    fitTo(ids) {
+      const s = st.current;
+      if (!s?.sc) return false;
+      const want = typeof ids === "string" ? [ids] : [...(ids || [])];
+      const idx = want.map((id) => s.index.get(id)).filter((i) => i !== undefined && s.sc.mask[i]);
+      if (!idx.length) return false;
+      s.fitIdx = idx.length === 1 ? near(s, idx[0]) : idx; // one doc: it and its neighbours (3D-UX-1 §2 "focus fly-to")
+      s.fitAll = false;
+      s.drill = null;
+      s.aim = -1;
+      s.userMoved = false;
+      placeView(s);
+      return true;
+    },
+    flash(id) {
+      const s = st.current;
+      const i = s?.index.get(id);
+      if (i === undefined) return false;
+      s.flash = { i, t0: null, ring: null };
+      s.box.dataset.graphFlash = String(id);
+      s.overlayDirty = true;
+      return true;
+    },
+    screenPositions(ids = null) {
+      const s = st.current;
+      if (!s?.sc) return [];
+      reproject(s);
+      return screenList(ids, s.index, s.scr, s.sc.mask, s.sc.degree, s.w, s.h);
+    },
+    idAt(clientX, clientY) {
+      const s = st.current;
+      if (!s?.sc) return null;
+      reproject(s);
+      const r = s.el.getBoundingClientRect(), i = pickAt(s, clientX - r.left, clientY - r.top);
+      return i >= 0 ? s.ids[i] : null;
+    },
+    pivotDepth() {
+      const s = st.current, p = s?.sc && s.base ? pivotOf(s) : null;
+      if (!p) return null;
+      const f = s.base.frame(), at = new Float32Array(3), r = new Float32Array(1);
+      project(Float32Array.from(p), [0], 1, f.vp, f.focal, s.w, s.h, at, r);
+      return at[2] > 1e-6 ? at[2] : null;
+    },
+    zoomBy(f) {
+      const s = st.current;
+      if (!s?.base || !s.controls) return;
+      const t = s.controls.target, c = s.base.camera.position;
+      const to = dollyBy([c.x, c.y, c.z], [t.x, t.y, t.z], f, s.controls.minDistance, s.controls.maxDistance);
+      s.userMoved = true; // the layout's ticks leave a zoomed camera alone, as after a wheel
+      s.fitAll = false;
+      s.fitIdx = null;
+      s.drill = null;
+      s.aim = -1;
+      fly(s, [t.x, t.y, t.z], to);
+    },
+    keepView(id) {
+      const s = st.current;
+      if (!s) return;
+      s.keep = (id ?? null) === (s.focusId ?? null) ? null : { id: id ?? null };
+    },
+  }), []);
+
+  useEffect(() => {
+    const box = wrap.current, el = over.current;
+    let octx = null;
+    try { octx = el.getContext("2d"); } catch { octx = null; }
+    const baseEl = document.createElement("canvas");
+    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,
+      base: null, controls: null, sc: null, ov: null, key: undefined, graph: null, hidden: null, sizeByDegree: null,
+      focusId: undefined, ids: [], index: new Map(), titles: [], labelW: null, off: null, adj: null, pairs: null, dirs: null,
+      visIdx: new Uint32Array(0), scr: new Float32Array(0), rpx: new Float32Array(0), cache: new Map(), layout: null,
+      physics: null, t0: 0, focus: -1, hover: -1, focusNear: [], lit: [], litLinks: [], dirty: false, overlayDirty: false,
+      userMoved: false, lastInputAt: null, idleAt: null, fitAll: false, drill: null, drillKey: "", cpairs: new Uint32Array(0), cdraw: {}, follow: null, tween: null, down: null, pin: null, pinArm: false, pins: new Map(), pinIdx: [], pointer: null, pointerMoved: false, raf: 0, alive: true, ready: false,
+      cluster: undefined, layoutTok: null, layoutState: null, resumeState: null, bubbles: null, bubbleList: [], bubbleLabels: [], bubbleAt: 0,
+      matchIds: null, match: null, dim: false, aim: -1, aimKey: "", outlines: false,
+      fitIdx: null, keep: null, flash: null, cycle: null, pivot: null, camPrev: null, pointerType: "mouse", mods: null, hoverBehind: 0, cardKey: "", selIdx: [], frameAt: null,
+      reduced: prefersReducedMotion(), frames: { global: null, clustered: null }, goal: null, glideAt: 0, focusFrame: null, phase: "global", afterGlide: null,
+      hops: 2, dimLevel: DIM_DEFAULT, open: null, openIdx: null, rings: null, ringsKey: null, capped: new Map(), badges: [], litIdx: new Uint32Array(0),
+    };
+    st.current = s;
+    let base = null;
+    try {
+      base = createThreeBase(baseEl, { w: s.w, h: s.h, dpr: s.dpr, background: graphTheme().field });
+    } catch (e) {
+      s.alive = false;
+      baseEl.remove();
+      if (st.current === s) st.current = null;
+      latest.current.onUnavailable?.(e?.message || String(e));
+      return undefined;
+    }
+    s.base = base;
+    s.bubbles = createBubbles3d(base.scene);
+    box.dataset.graphRenderer = base.kind;
+    const controls = base.controls(el);
+    s.controls = controls;
+    // Reduced motion (round 2): one flag, read at the choke points (fly, controls damping, flash ring, glide). Live: a change
+    // mid-session takes effect on the next frame. The idle turn (round 3) reads `s.reduced` too and stays off while it is true.
+    controls.enableDamping = !s.reduced;
+    const unwatchMotion = watchReducedMotion((r) => {
+      s.reduced = r;
+      controls.enableDamping = !r;
+      if (r && s.tween) { const to = s.tween.to; s.tween = null; applyCamera(s, to.t, to.p); } // a tween under way ends where it was going
+    });
+    s.gizmo = gizmoParts(box.querySelector("[data-graph-gizmo]"));
+    // The pivot (3D-UX-1 §2): OrbitControls turns round its target; while a turn drag (and its damping) runs, each of its
+    // updates is redone round s.pivot. camPrev is the camera before the update (null after a programmatic move: applyCamera).
+    const onChange = () => {
+      s.dirty = true;
+      const t = controls.target, c = base.camera.position;
+      if (s.pivot && s.camPrev) {
+        const r = orbitAbout(s.pivot, s.camPrev.c, s.camPrev.t, [c.x, c.y, c.z], [t.x, t.y, t.z]);
+        if (r) { t.set(r.t[0], r.t[1], r.t[2]); c.set(r.c[0], r.c[1], r.c[2]); base.camera.lookAt(t); }
+      }
+      s.camPrev = { c: [c.x, c.y, c.z], t: [t.x, t.y, t.z] };
+    };
+    controls.addEventListener("change", onChange);
+    const onLost = (e) => {
+      if (!s.alive) return;
+      e.preventDefault?.();
+      latest.current.onUnavailable?.("WebGL context lost");
+    };
+    baseEl.addEventListener("webglcontextlost", onLost);
+
+    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`;
+      base.resize(s.w, s.h, s.dpr);
+      if (!s.userMoved) placeView(s, true);
+      s.dirty = s.overlayDirty = true;
+    };
+    resize();
+    const ro = typeof ResizeObserver === "function" ? new ResizeObserver(resize) : null;
+    ro?.observe(box);
+    sync(s, latest.current);
+
+    const frame = (now) => {
+      s.raf = requestAnimationFrame(frame);
+      if (s.tween) stepTween(s, now);
+      if (controls.update()) s.dirty = true;
+      idleStep(s, now, !!latest.current.idleTurn);
+      if (!s.sc) return;
+      if (s.goal) stepGlide(s, now);
+      if (s.dirty) {
+        s.dirty = false;
+        drawFrame(s);
+        drawGizmo(s);
+        feedCard(s);
+        if (!s.ready) { s.ready = true; box.dataset.graphReady = "1"; perfSpan("wiki-graph:first-frame", s.t0); }
+      }
+      if (s.pointerMoved && s.pointer && !s.down) {
+        s.pointerMoved = false;
+        hoverAt(s, s.pointer[0], s.pointer[1]);
+      }
+      if (s.flash) {
+        if (s.flash.t0 === null) s.flash.t0 = now;
+        s.flash.ring = flashRing(now - s.flash.t0, s.rpx[s.flash.i] || 0, s.reduced);
+        if (!s.flash.ring) { s.flash = null; delete box.dataset.graphFlash; }
+        s.overlayDirty = true; // the ring grows every frame, and its last frame clears it
+      }
+      if (s.overlayDirty && octx) {
+        s.overlayDirty = false;
+        drawOverlay(octx, s.ov, {
+          lit: s.lit, litLinks: frontLinks(s), focus: s.focus, hover: s.hover, selected: s.selIdx, 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.ov.mask[i] && s.scr[3 * i + 2] > 1e-6, s.dim ? s.dimLevel : false) : undefined,
+        });
+        drawBubbleLabels(octx, s.bubbleLabels, s.dpr, { outlines: outlinesShown(3, s.cluster, s.outlines) });
+        s.badges = drawBadges(octx, badgeItems(s), s.dpr);
+        drawMarksOver(octx, s);
+      }
+    };
+    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 mods = (e) => ({ shift: !!e.shiftKey, meta: !!(e.metaKey || e.ctrlKey), alt: !!e.altKey });
+    const emit = (type, i, x, y, e) => latest.current.onEvent?.({ type, id: i >= 0 ? s.ids[i] : null, x, y, ...mods(e) });
+    const userMove = () => { markUserMove(s); s.tween = null; };
+    const onWheel = () => userMove();
+    // Capture on the box, so it runs before OrbitControls' own pointerdown on the overlay: an Option/Alt-drag pans (D1), and a
+    // turn (plain left drag, one finger) goes round the pivot. Any other press (a pan, a modified drag) drops the pivot.
+    const onDownCapture = (e) => {
+      if (e.target?.closest?.("[data-graph-gizmo]")) return; // the orientation gizmo is not the surface: no pivot, pin or lasso arms
+      Object.assign(controls.mouseButtons, buttonActions(e)); // the mode is fixed by this press's own flags and held for the drag
+      const t = controls.target, c = base.camera.position;
+      s.camPrev = { c: [c.x, c.y, c.z], t: [t.x, t.y, t.z] };
+      const turn = e.pointerType === "touch" || ((e.button ?? 0) === 0 && !e.altKey && !e.shiftKey && !e.ctrlKey && !e.metaKey);
+      // A plain left press ON a dot drags that dot (pin): the controls sit it out, like the lasso.
+      const [px, py] = local(e);
+      s.pinArm = pinArmed(e, !!latest.current.onPin && pickAt(s, px, py) >= 0);
+      s.pivot = turn && !s.pinArm ? pivotOf(s) : null;
+      // Shift + left mouse is the lasso (never OrbitControls' shift-pan): the controls sit this press out, onUp turns them back on.
+      s.lassoArm = !!latest.current.onLasso && e.pointerType !== "touch" && (e.button ?? 0) === 0 && e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey;
+      controls.enabled = !s.lassoArm && !s.pinArm;
+    };
+    const onDown = (e) => {
+      const [x, y] = local(e);
+      s.down = { x, y, moved: false, button: e.button ?? 0 };
+      s.pointerType = e.pointerType || "mouse";
+      s.tween = null;
+      if (s.lassoArm) {
+        s.lassoArm = false;
+        s.lasso = { pts: [[x, y]] };
+        try { el.setPointerCapture?.(e.pointerId); } catch { /* a synthetic pointer has no capture */ }
+        latest.current.onLasso({ phase: "start", pts: s.lasso.pts });
+      }
+      if (s.pinArm) { // the dot under the press, its depth and the gap to the plane point under the pointer: the drag keeps that gap
+        s.pinArm = false;
+        const i = pickAt(s, x, y), f = s.base.frame(), cam = cameraOf(s.base.camera.matrixWorld.elements, f.eye, f.focal), depth = s.scr[3 * i + 2];
+        const p = [s.sc.xyz[3 * i], s.sc.xyz[3 * i + 1], s.sc.xyz[3 * i + 2]];
+        s.pin = { i, cam, depth, offset: pinOffset(cam, s.w, s.h, x, y, depth, p), moved: false };
+        try { el.setPointerCapture?.(e.pointerId); } catch { /* a synthetic pointer has no capture */ }
+      }
+      if (e.pointerType === "touch") emit("press", pickAt(s, x, y), x, y, e); // sets the page's menu target for a long-press
+    };
+    const onMove = (e) => {
+      const [x, y] = local(e);
+      s.pointer = [x, y];
+      s.mods = mods(e);
+      if (e.pointerType) s.pointerType = e.pointerType;
+      if (s.lasso) {
+        const pts = lassoSample(s.lasso.pts, x, y);
+        if (pts !== s.lasso.pts) { s.lasso.pts = pts; s.overlayDirty = true; latest.current.onLasso?.({ phase: "move", pts }); }
+      }
+      if (s.down) {
+        if (!s.down.moved && dragStarted(s.down.x, s.down.y, x, y, CLICK_PX)) { s.down.moved = true; userMove(); feedCard(s); }
+        if (s.pin && s.down.moved) dragPin(s, x, y);
+        return;
+      }
+      s.pointerMoved = true;
+    };
+    const click = (i, x, y, e) => {
+      const L = latest.current;
+      if (L.onEvent) emit("click", i, x, y, e);
+      else if (i >= 0) L.onOpen?.(s.graph.nodes[i]);
+      else L.onBackground?.(); // empty space: the page clears the focus
+    };
+    const endLasso = (e, cancel) => { // release (or a cancelled pointer): a dragged polygon ends, a Shift-click that never moved cancels
+      const l = s.lasso;
+      s.lasso = null;
+      controls.enabled = true;
+      if (!l) return;
+      const [x, y] = e ? local(e) : [NaN, NaN];
+      const pts = lassoSample(l.pts, x, y, 0.01);
+      s.overlayDirty = true;
+      latest.current.onLasso?.({ phase: cancel || !s.down?.moved ? "cancel" : "end", pts });
+    };
+    const endPin = () => { // release or cancel: the dot stays where it was dropped, pinned; the controls come back on every exit
+      const d = s.pin;
+      s.pin = null;
+      s.pinArm = false;
+      controls.enabled = true;
+      if (d?.moved) { s.overlayDirty = true; latest.current.onPin?.({ phase: "pins", ids: [...s.pins.keys()] }); }
+    };
+    const onCancel = () => { endLasso(null, true); endPin(); s.down = null; s.lassoArm = false; };
+    const onUp = (e) => {
+      const d = s.down;
+      endLasso(e, false);
+      endPin();
+      s.down = null;
+      if (d && !d.moved && d.button === 0) { // a right or middle press is never a click (the menu, a pan)
+        const [x, y] = local(e);
+        const b = badgeAt(s.badges, x, y);
+        if (b >= 0) latest.current.onBadge?.(s.graph.nodes[b]); // a "+N" badge expands that hub alone
+        else if (e.altKey) { // one deeper per Alt-click (3D-UX-1 §2 "occlusion")
+          const { pick, state } = depthCycle(s.cycle, stackAt(s, x, y), x, y, CLICK_PX);
+          s.cycle = state;
+          click(pick, x, y, e);
+        } else {
+          s.cycle = null;
+          click(pickAt(s, x, y), x, y, e);
+        }
+      }
+      if (d?.moved) s.overlayDirty = true; // the pivot cross goes
+      s.pointerMoved = true;
+    };
+    const onDouble = (e) => {
+      const [x, y] = local(e);
+      const i = pickAt(s, x, y);
+      if (latest.current.onEvent) emit("dblclick", i, x, y, e);
+      else if (i >= 0) latest.current.onExpand?.(s.graph.nodes[i]);
+      if (i < 0) { s.fitAll = true; s.fitIdx = null; s.drill = null; s.aim = -1; s.userMoved = false; placeView(s); } // empty space: fit the whole graph, never a node's zoom
+    };
+    const onContext = (e) => {
+      const [x, y] = local(e);
+      emit("context", pickAt(s, x, y), x, y, e);
+      if (!latest.current.onEvent) e.preventDefault(); // no page menu: no browser menu either (OrbitControls did this before)
+    };
+    const onLeave = () => {
+      s.pointer = null;
+      if (s.hover >= 0) { s.hover = -1; el.title = ""; relight(s); latest.current.onEvent?.({ type: "hover", id: null, x: NaN, y: NaN, shift: false, meta: false, alt: false }); }
+      feedCard(s);
+    };
+    // Any pointer, wheel, key or touch on the surface restarts the idle clock (an idle turn is never a user move: no markUserMove).
+    const onInput = () => { s.lastInputAt = performance.now(); };
+    const INPUTS = ["pointerdown", "pointermove", "wheel", "keydown", "touchstart"];
+    for (const n of INPUTS) box.addEventListener(n, onInput, { capture: true, passive: true });
+    el.addEventListener("wheel", onWheel, { passive: true });
+    box.addEventListener("pointerdown", onDownCapture, true);
+    el.addEventListener("pointerdown", onDown);
+    el.addEventListener("contextmenu", onContext);
+    el.addEventListener("pointermove", onMove);
+    el.addEventListener("pointerup", onUp);
+    el.addEventListener("pointercancel", onCancel);
+    el.addEventListener("pointerleave", onLeave);
+    el.addEventListener("dblclick", onDouble);
+    return () => {
+      s.alive = false;
+      if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(s.raf);
+      ro?.disconnect();
+      unwatchMotion();
+      s.layout?.stop();
+      s.bubbles?.dispose();
+      controls.removeEventListener("change", onChange);
+      baseEl.removeEventListener("webglcontextlost", onLost);
+      base.destroy();
+      baseEl.remove();
+      el.removeEventListener("wheel", onWheel);
+      for (const n of INPUTS) box.removeEventListener(n, onInput, true);
+      box.removeEventListener("pointerdown", onDownCapture, true);
+      el.removeEventListener("pointerdown", onDown);
+      el.removeEventListener("contextmenu", onContext);
+      el.removeEventListener("pointermove", onMove);
+      el.removeEventListener("pointerup", onUp);
+      el.removeEventListener("pointercancel", onCancel);
+      el.removeEventListener("pointerleave", onLeave);
+      el.removeEventListener("dblclick", onDouble);
+      if (st.current === s) st.current = null;
+    };
+  }, [height]);
+
+  useEffect(() => {
+    if (st.current) sync(st.current, latest.current);
+  }, [graph, layoutKey, hidden, sizeByDegree, focusId, cluster, drill, hops, dim, open, outlines]);
+
+  // A find term: relight only, as in 2D. Nothing here touches the layout, the positions or the camera.
+  useEffect(() => {
+    const s = st.current;
+    if (!s) return;
+    s.matchIds = match;
+    rematch(s);
+    relight(s);
+  }, [match]);
+
+  // Enter on a match: aim the camera at it and its neighbours (after sync, as in 2D).
+  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.fitIdx = null;
+    s.userMoved = false;
+    s.fitAll = false;
+    s.drill = null;
+    placeView(s);
+  }, [aim]);
+
+  // The page's marks (lens lit set and links, the selection, a list row's hover): relight only, as a find term.
+  useEffect(() => {
+    if (st.current) relight(st.current);
+  }, [marks]);
+
+  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.layout.params(s.physics, s.phase === "global" ? null : clusterParams(s.physics)); // cluster and focus keep their strong pull
+  }, [physics.repel, physics.link, physics.centre]);
+
+  return (
+    <div
+      ref={wrap}
+      data-graph-surface=""
+      data-graph-view="3d"
+      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={`3D graph of ${graph.nodes.length} docs and ${graph.links.length} links`}
+        className="absolute left-0 top-0 block touch-none"
+        style={{ cursor: "grab" }}
+      />
+      <Gizmo onTurn={(name) => st.current && turnTo(st.current, name)} />
+    </div>
+  );
+});
+
+export default GraphCanvas3D;
+
+/** Bring what is drawn in line with the props `p` (the 2D sync: relayout, recolour, re-mask, resize or relight). */
+function sync(s, p) {
+  const key = p.layoutKey ?? p.graph;
+  const was = s.cluster;
+  s.cluster = !!p.cluster;
+  s.outlines = !!p.outlines;
+  let built = false;
+  if (!s.sc || key !== s.key) {
+    build(s, p);
+    built = true;
+  } else if (p.graph !== s.graph) {
+    if (sameTopology(s.ids, s.index, s.pairs, 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) { reradius(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
+  // keepView(id): a focus change to that id (a canvas click, 1b) leaves the camera where it is, only panning the doc on screen.
+  const kept = focusChanged && !built && !drilled && !!s.keep && s.keep.id === (p.focusId ?? null);
+  if (focusChanged || built) s.keep = null;
+  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 = kept;
+    s.fitAll = false;
+    s.fitIdx = null;
+  }
+  // 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) {
+    relight(s);
+    if (kept) panInto(s);
+    else placeView(s, built && !s.ready);
+  }
+  if (!built && was !== undefined && was !== s.cluster) { if (s.cluster) clusterOn(s); else clusterOff(s); }
+  else if (!built && (focusChanged || hopsChanged)) { if (s.focus >= 0) focusOn(s); else focusOff(s); }
+  else if (built && s.focus >= 0 && !busy(s)) focusOn(s); // no worker: the base frame is already final
+  rebubble(s);
+  s.dirty = s.overlayDirty = true;
+}
+
+/** A new node set: positions (this surface's cache by id, else seed3d), the arrays the base and the overlay read, and a
+ *  fresh 3D layout. */
+function build(s, p) {
+  if (s.sc) { // the cache holds the base frame (the global or clustered layout), never a focus re-layout's shells
+    const at = s.focusFrame ?? s.goal ?? s.sc.xyz;
+    if (at.length === s.sc.xyz.length) for (let i = 0; i < s.sc.n; i++) s.cache.set(s.ids[i], [at[3 * i], at[3 * i + 1], at[3 * i + 2]]);
+  }
+  const live = s.cache.size > 0; // this surface has already drawn nodes: not a first render, however disjoint the new set is
+  stopLayout(s);
+  if (s.pins.size) { s.pins.clear(); s.latest.current.onPin?.({ phase: "pins", ids: [] }); } // pins belong to one surface
+  s.frames = { global: null, clustered: null };
+  s.follow = null; // a new node set: its first layout gets a fresh follow budget (start)
+  s.goal = null;
+  s.focusFrame = null;
+  s.afterGlide = null;
+  s.rings = null;
+  s.focus = -1; // sync sets the focus of the new node set right after
+
+  const { nodes, links } = p.graph;
+  const n = nodes.length;
+  s.ids = nodes.map((nd) => nd.id);
+  s.index = new Map(s.ids.map((id, i) => [id, i]));
+  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);
+  }
+  let { xyz, warm } = seed3d(nodes, { cache: s.cache }); // cluster is not a layout input: every target is 0,0,0
+  // A node set that shares nothing with the surface, with clustering on, is placed in its group balls and never laid out
+  // (an overlapping set keeps 3D's warm clustered relayout, owner ruling 2026-10-21 "3D regroups").
+  const frozen = placesStatically({ cluster: !!p.cluster, warm, live, regroups: true });
+  if (frozen) xyz = seed3d(nodes, { cluster: true, cache: s.cache }).xyz;
+  const { pairs, dirs, weights, off, adj } = linkArrays(links, s.index, n, dirOf);
+  s.cpairs = containPairs(p.graph.contains, s.index);
+  const k = pairs.length;
+  s.pairs = pairs; s.dirs = dirs; s.weights = weights; s.off = off; s.adj = adj;
+  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);
+  const big = n > LOD_N;
+  s.sc = {
+    n, xyz, radius: new Float32Array(n), colors: new Uint32Array(n), mask: null, visPairs: new Uint32Array(k),
+    visDirs: new Uint8Array(k / 2), visWeights: new Float32Array(k / 2), visBuckets: null, visCount: 0, visibleN: n, big, edgeAlpha: lodFor(n, 1).edgeAlpha, degree, order,
+  };
+  s.ov = {
+    n, pos: new Float32Array(Math.max(2, 2 * n)), sizes: new Float32Array(n), view: { k: 1, x: 0, y: 0 }, mask: null, big,
+    colors: s.sc.colors, degree, order, visibleN: n,
+  };
+  s.scr = new Float32Array(3 * n);
+  s.ov.scr = s.scr; // the overlay picks labels with depth (labelDepth.js) from the same projection
+  s.pivotAt = new Float32Array(3);
+  s.pivotScr = new Float32Array(3);
+  s.pivotR = new Float32Array(1); // the pivot point's zero radius; its projected radius goes to pivotRo
+  s.pivotRo = new Float32Array(1);
+  s.rpx = new Float32Array(n);
+  s.key = p.layoutKey ?? p.graph;
+  s.hover = -1;
+  s.aim = -1;
+  s.fitIdx = null; // indices of the old node set
+  s.cycle = null;
+  if (s.flash) { s.flash = null; delete s.box.dataset.graphFlash; }
+  rematch(s);
+  colour(s, p);
+  reradius(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: big });
+  s.base?.setData(s.sc);
+  s.physics = { ...p.physics, cluster: false };
+  s.t0 = performance.now();
+  delete s.box.dataset.graphSettledMs;
+  if (!n) return;
+  if (frozen) { // no worker: the placed frame is the clustered frame, and cluster off lays out a global one (clusterOff)
+    s.phase = "cluster";
+    s.follow = followDone(viewKey(s)); // final already: sync frames it once, a later reheat does not
+    s.frames.clustered = copy(xyz);
+    report(s, "settled", null);
+    return;
+  }
+  start(s, { warm, phase: p.cluster ? "cluster" : "global" }); // a new node set is written directly, never glided
+}
+
+/** The group a node's bubble and cluster target count it in: a level view's folder carries its area as `bubbleGroup` (the
+ *  page's folderGroups); otherwise its legend group, and a folder without one belongs to none. */
+const bubbleGroupOf = (nd) => nd.bubbleGroup ?? (nd.kind === "folder" ? null : nd.group ?? null);
+
+/** The view a layout belongs to, for the camera's follow budget (camFollow): the cluster, focus and hops state. A reheat, a slider or
+ *  a pin keeps it; a new node set starts from a null follow (build). */
+const viewKey = (s) => `${!!s.cluster}|${s.focus}|${s.hops}`;
+
+/** A layout that is still moving nodes (a paused or settled one is not). */
+const busy = (s) => !!s.layout && s.layoutState !== "settled" && s.layoutState !== "paused";
+
+/** Start a layout. `phase`: "global" (targets 0, the user's physics), "cluster" (clusterTargets per group, clusterParams) or
+ *  "focus" (`targets` from focusShells, every unlit node `pinned`, clusterParams). `from`: the start positions (default the
+ *  drawn ones). With `glide`, ticks write `s.goal` and the frame loop eases the drawn positions toward it; without, ticks
+ *  write the drawn positions. Ticks and states from any layout but the latest are dropped, so a stopped one never moves a
+ *  node. A settled base layout (global or cluster) runs a waiting focus. */
+function start(s, { warm = true, phase = s.cluster ? "cluster" : "global", from = null, targets = null, pinned = null, glide: gl = false } = {}) {
+  const sc = s.sc, tok = {}, nodes = s.graph.nodes, pos = from || sc.xyz;
+  s.phase = phase;
+  s.follow = followFor(s.follow, viewKey(s)); // a new view follows its first layout; a reheat of the same view does not
+  s.layoutState = null;
+  if (phase === "cluster" && !targets) targets = clusterTargets(pos, 3, (i) => bubbleGroupOf(nodes[i])).targets;
+  if (gl && (!s.goal || s.goal.length !== pos.length)) s.goal = Float32Array.from(pos);
+  s.glideAt = 0;
+  s.layoutTok = tok;
+  s.layout = startLayout({
+    xy: pos, pairs: layoutPairs(s.pairs, s.cpairs), weights: s.weights, targets: targets || new Float32Array(3 * sc.n),
+    physics: s.physics, big: sc.big, warm, dims: 3, radii: layoutRadii(nodes, (i) => sc.radius[i]), pinned,
+    // Cluster and focus both pull at CLUSTER_CENTRE: at the global 0.013 the focus shells barely pull (REPORT-c3 deviation).
+    params: phase === "global" ? null : clusterParams(s.physics),
+    alpha: phase === "global" ? null : warm ? 0.6 : 1,
+    maxTicks: phase === "global" || !warm ? null : 120,
+    onTick: (next) => {
+      if (s.layoutTok !== tok || s.sc !== sc || next.length !== 3 * sc.n) return; // a frame from a layout we already replaced
+      if (gl) {
+        if (!s.goal || s.goal.length !== next.length) s.goal = new Float32Array(next.length);
+        s.goal.set(next);
+        holdPins(s.goal, s.pins, s.index); // a frame posted before the last drag move carries the older position
+        s.dirty = true;
+        return;
+      }
+      sc.xyz.set(next);
+      holdPins(sc.xyz, s.pins, s.index);
+      s.base?.setPositions(sc);
+      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
+      if (s.cluster && performance.now() - s.bubbleAt >= 1000 / BUBBLE_HZ) rebubble(s);
+      s.dirty = 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 (phase === "cluster") s.frames.clustered = Float32Array.from(gl && s.goal ? s.goal : sc.xyz);
+        if (!gl && follows(s.follow, "settled", performance.now(), s.userMoved)) placeView(s); // a glide's camera lands with the glide (stepGlide)
+        rebubble(s);
+      }
+      report(s, state, ms);
+      if (state === "settled" && phase !== "focus" && s.focus >= 0) focusOn(s); // a focus that came while this ran
+    },
+  });
+  if (s.layout) { // pins outlive a re-layout (cluster, focus, reheat): hold each at its dropped place
+    for (const [id, p] of s.pins) { const i = s.index.get(id); if (i !== undefined) s.layout.pin(i, p[0], p[1], p[2]); }
+    return;
+  }
+  s.layoutTok = null; // no Worker: the seeded layout is the layout; cluster and focus become a direct shift
+  if (!gl) s.follow.done = true; // nothing will move: the caller's placeView is the framing
+  if (phase !== "global") {
+    const to = phase === "cluster" ? clusterShift(pos, 3, (i) => bubbleGroupOf(nodes[i]), targets) : targets;
+    console.warn(`wiki graph: no layout worker, the ${phase} frame is a direct shift with no simulation (links and repulsion are not applied)`);
+    if (gl) s.goal.set(to);
+    else { sc.xyz.set(to); s.base?.setPositions(sc); }
+    if (phase === "cluster") s.frames.clustered = Float32Array.from(to);
+  }
+  report(s, "settled", null);
+}
+
+/** One pointer move of a pin drag: the dot follows the pointer in the camera-facing plane at its press-time depth. The worker holds it
+ *  there (pin), and the drawn positions (and the glide's goal) are written now so the dot does not wait for the next worker frame. */
+function dragPin(s, x, y) {
+  const d = s.pin, id = s.ids[d.i];
+  const at = pinTarget(d.cam, s.w, s.h, x, y, d.depth, d.offset);
+  d.moved = true;
+  s.pins.set(id, at);
+  s.sc.xyz.set(at, 3 * d.i);
+  s.goal?.set(at, 3 * d.i);
+  s.layout?.pin(d.i, at[0], at[1], at[2]);
+  s.base?.setPositions(s.sc);
+  s.dirty = s.overlayDirty = true;
+}
+
+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);
+}
+
+const copy = (a) => Float32Array.from(a);
+
+/** One frame of the glide: the drawn positions ease toward `s.goal` (layoutEngine glide). The camera follows at most every
+ *  150 ms (placeView restarts its tween, so every frame would hold it still). Once on the goal with no layout still moving,
+ *  the glide ends: bubbles and camera settle and `afterGlide` runs. */
+function stepGlide(s, now) {
+  const sc = s.sc;
+  if (s.goal.length !== sc.xyz.length) { s.goal = null; return; }
+  const dt = s.glideAt ? now - s.glideAt : 16;
+  s.glideAt = now;
+  const left = glide(sc.xyz, s.goal, dt, s.reduced ? 0 : undefined);
+  s.base?.setPositions(sc);
+  s.dirty = true;
+  if (s.cluster && performance.now() - s.bubbleAt >= 1000 / BUBBLE_HZ) rebubble(s);
+  if (follows(s.follow, "tick", now, s.userMoved)) placeView(s);
+  if (left > 0 || busy(s)) return;
+  s.goal = null;
+  s.glideAt = 0;
+  rebubble(s);
+  if (follows(s.follow, "settled", now, s.userMoved)) placeView(s);
+  const after = s.afterGlide;
+  s.afterGlide = null;
+  after?.();
+}
+
+/** Cluster on: keep the global frame (without any focus displacement), then lay out toward the group centres, gliding. */
+function clusterOn(s) {
+  if (!s.sc?.n) return;
+  stopLayout(s);
+  const frame = s.focusFrame ?? copy(s.goal ?? s.sc.xyz);
+  s.focusFrame = null;
+  s.afterGlide = null;
+  s.frames.global = copy(frame);
+  s.frames.clustered = null;
+  s.goal = copy(frame);
+  start(s, { phase: "cluster", from: frame, glide: true });
+}
+
+/** Cluster off: no simulation, a glide straight back to the saved global frame (it ends exactly there), then a focus is
+ *  re-applied. A node set built while clustered has no global frame: lay one out, gliding. */
+function clusterOff(s) {
+  if (!s.sc?.n) return;
+  stopLayout(s);
+  s.focusFrame = null;
+  s.phase = "global";
+  if (s.frames.global?.length === s.sc.xyz.length) {
+    s.follow = followFor(s.follow, viewKey(s)); // a view change: the camera lands with the glide
+    s.goal = copy(s.frames.global);
+    s.glideAt = 0;
+    report(s, "settled", null);
+    s.afterGlide = () => { s.frames.clustered = null; if (s.focus >= 0) focusOn(s); };
+  } else start(s, { phase: "global", glide: true });
+}
+
+/** Focus set (or its hops changed): lay out the lit rings onto shells round the focus, every unlit node pinned where it is.
+ *  Always from the saved base frame, so a previous focus's displaced nodes glide back while the new ring glides out. Waits
+ *  while a base layout is still moving (its settle calls back here). */
+function focusOn(s) {
+  const sc = s.sc;
+  if (!sc?.n || s.focus < 0) return;
+  if (s.layout && s.phase !== "focus" && busy(s)) return;
+  const rings = ringsOf(s);
+  if (!rings) return;
+  stopLayout(s);
+  if (!s.focusFrame) s.focusFrame = copy(s.goal ?? sc.xyz);
+  s.afterGlide = null;
+  const pinned = new Uint8Array(sc.n).fill(1);
+  for (const i of rings.lit) pinned[i] = 0;
+  pinned[s.focus] = 1;
+  const targets = focusShells(s.focusFrame, 3, rings.depth, s.focus, 0.9 * forceParams(s.physics).linkDistance);
+  s.goal = copy(s.focusFrame);
+  start(s, { phase: "focus", from: s.focusFrame, targets, pinned, glide: true });
+}
+
+/** Focus cleared: the displaced ring glides back to the saved base frame. */
+function focusOff(s) {
+  if (!s.focusFrame) return;
+  if (s.phase === "focus") stopLayout(s);
+  s.goal = s.focusFrame;
+  s.glideAt = 0;
+  s.focusFrame = null;
+  s.follow = followFor(s.follow, viewKey(s));
+  s.phase = s.cluster ? "cluster" : "global";
+  report(s, "settled", null);
+}
+
+/** Resume / Reheat: the running layout's verb; with none, a fresh base layout from the base frame (a focus is re-applied
+ *  when it settles). */
+function restartOr(s, verb) {
+  if (!s?.sc?.n) return;
+  if (s.layout) { s.layout[verb](); return; }
+  const from = s.focusFrame ?? copy(s.sc.xyz);
+  s.focusFrame = null;
+  s.goal = copy(from);
+  start(s, { warm: true, from, glide: true });
+}
+
+/** The group bubbles while cluster is on (none when off). Their names are always drawn; the outlines (one faint disc in the
+ *  scene plus a thin ring on the overlay, groupBubbles OUTLINE_STYLE) only with `outlines` (owner 2026-10-21: off by default
+ *  in 3D). `data-graph-bubbles` counts the outlines drawn; `data-graph-geom` holds {R, bubbles: [{c, r}]} (R = the fit radius
+ *  of the visible nodes) for the separation measurement (WIKI-GRAPH-CLUSTER-CHECK-1 run.mjs). */
+function rebubble(s) {
+  s.bubbleAt = performance.now();
+  const sc = s.sc, nodes = s.graph?.nodes;
+  s.bubbleList = s.cluster && sc && nodes
+    ? groupBubbles(sc.xyz, 3, (i) => bubbleGroupOf(nodes[i]), s.visIdx, { radiusOf: (i) => sc.radius[i] })
+      .map((b) => ({ ...b, color: sc.colors[b.members[0]] }))
+    : [];
+  const shown = outlinesShown(3, s.cluster, s.outlines) && s.bubbleList.length > 0;
+  if (shown) s.bubbles?.update(s.bubbleList); else s.bubbles?.clear();
+  s.box.dataset.graphBubbles = String(shown ? s.bubbleList.length : 0);
+  if (s.bubbleList.length) {
+    const R = fitSphere(sc.xyz, s.visIdx, sc.radius)?.r ?? 0; // exact extent, not framing: the geometry dump measures every drawn node
+    s.box.dataset.graphGeom = JSON.stringify({ R, bubbles: s.bubbleList.map((b) => ({ c: [...b.centre], r: b.radius })) });
+  } else {
+    delete s.box.dataset.graphGeom;
+    s.bubbleLabels = [];
+  }
+  s.dirty = s.overlayDirty = true;
+}
+
+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: 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 = s.ov.degree = degree;
+  s.sc.order = s.ov.order = Uint32Array.from({ length: nodes.length }, (_, i) => i).sort((a, b) => degree[b] - degree[a]);
+  reradius(s, p);
+  remask(s, p.hidden);
+  if (relooked) s.base?.setData(s.sc);
+  s.base?.setStyle(s.sc);
+  s.base?.setVisible(s.sc);
+}
+
+function reradius(s, p) {
+  const { nodes } = p.graph;
+  for (let i = 0; i < nodes.length; i++) s.sc.radius[i] = nodeRadius(nodes[i], p.sizeByDegree);
+  s.sizeByDegree = p.sizeByDegree;
+}
+
+/** The legend mask, the drawn links and the visible index list (fit and picking use it). */
+function remask(s, hidden) {
+  const sc = s.sc;
+  sc.mask = s.ov.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 the 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 = s.ov.visibleN = vis.length;
+  s.hidden = hidden;
+  s.dirty = s.overlayDirty = true;
+}
+
+/** One drawn frame: project every node through the camera, fill the overlay's stand-in scene, render the base. */
+function drawFrame(s) {
+  const { sc, ov, scr, rpx, base, controls } = s;
+  const f = base.frame();
+  s.frameAt = f;
+  s.bubbleLabels = bubbleLabels(s.bubbleList, f, s.w, s.h);
+  project(sc.xyz, sc.radius, sc.n, f.vp, f.focal, s.w, s.h, scr, rpx);
+  const t = controls.target, c = base.camera.position;
+  const k = f.focal / Math.max(1e-6, Math.hypot(c.x - t.x, c.y - t.y, c.z - t.z));
+  for (let i = 0; i < sc.n; i++) {
+    ov.pos[2 * i] = scr[3 * i] / k;
+    ov.pos[2 * i + 1] = scr[3 * i + 1] / k;
+    ov.sizes[i] = (2 * rpx[i]) / k;
+  }
+  ov.view = { k, x: 0, y: 0 };
+  // the label depth rule's pivot (the orbit target's depth) and the far edge (the deepest drawn doc)
+  s.pivotAt[0] = t.x; s.pivotAt[1] = t.y; s.pivotAt[2] = t.z;
+  project(s.pivotAt, s.pivotR, 1, f.vp, f.focal, s.w, s.h, s.pivotScr, s.pivotRo);
+  ov.pivotDepth = s.pivotScr[2] > 1e-6 ? s.pivotScr[2] : NaN;
+  let far = 0;
+  for (let i = 0; i < sc.n; i++) if (scr[3 * i + 2] > far && (!ov.mask || ov.mask[i])) far = scr[3 * i + 2];
+  ov.farDepth = far;
+  base.render(sc, { scr, focal: f.focal, eye: f.eye, k });
+  s.overlayDirty = true;
+}
+
+/** The lit links whose both ends are in front of the camera (an end behind it has no screen position). */
+function frontLinks(s) {
+  const out = [], scr = s.scr, l = s.litLinks;
+  for (let e = 0; e < l.length; e += 2) if (scr[3 * l[e] + 2] > 1e-6 && scr[3 * l[e + 1] + 2] > 1e-6) out.push(l[e], l[e + 1]);
+  return out;
+}
+
+/** The node under (x, y), from the pickable set only (graphView pickable): while something is dimmed a dimmed node is never picked. */
+function pickAt(s, x, y) {
+  if (!s.sc || !s.sc.n || !s.ready) return -1;
+  return pickProjected(s.scr, s.rpx, pickable(s.visIdx, s.litIdx, s.dim), x, y);
+}
+
+/** The "+N" badges this frame: each capped hub of the focus ring that is lit, drawn and in front of the camera. */
+function badgeItems(s) {
+  const out = [];
+  if (!s.capped.size || !s.sc) return out;
+  const lit = new Set(s.lit);
+  for (const [i, n] of s.capped) {
+    if (lit.has(i) && s.sc.mask[i] && s.scr[3 * i + 2] > 1e-6) out.push({ i, n, x: s.scr[3 * i], y: s.scr[3 * i + 1], r: s.rpx[i] });
+  }
+  return out;
+}
+
+function hoverAt(s, x, y) {
+  const i = pickAt(s, x, y);
+  const behind = i >= 0 && s.latest.current.onHoverCard ? Math.max(0, stackAt(s, x, y).length - 1) : 0;
+  if (i === s.hover && behind === s.hoverBehind) return;
+  s.hoverBehind = behind;
+  if (i !== s.hover) {
+    s.hover = i;
+    s.el.style.cursor = i >= 0 ? "pointer" : "grab";
+    s.el.title = i >= 0 && !s.latest.current.onHoverCard ? s.titles[i] : ""; // with the anchored card, no native tooltip
+    relight(s);
+    const m = s.mods || { shift: false, meta: false, alt: false };
+    s.latest.current.onEvent?.({ type: "hover", id: i >= 0 ? s.ids[i] : null, x, y, ...m });
+  }
+  feedCard(s);
+}
+
+/** A turn or zoom by the user: auto-fit stops snapping the camera back, and any focus fly-to or drill target is let go. */
+function markUserMove(s) { s.userMoved = true; s.fitAll = false; s.fitIdx = null; s.drill = null; s.aim = -1; }
+
+/** The fit distance the orientation's `k` is a multiple of: the whole drawn graph, as fit-all frames it (the current camera
+ *  distance with nothing drawn, so a turn still keeps its distance). */
+function fitDistOf(s) {
+  const c = s.sc && s.visIdx.length ? robustSphere(s.sc.xyz, s.visIdx, s.sc.radius) : null; // the same sphere fit-all frames
+  if (c) return Math.max(fitDistance(c.r, FOV, s.w / Math.max(1, s.h)), focalFor(s.h) / FIT_FLOOR);
+  const t = s.controls.target, p = s.base.camera.position;
+  return Math.hypot(p.x - t.x, p.y - t.y, p.z - t.z) || 1;
+}
+
+/** The orientation gizmo (round 4): turn the camera to look along axis `name` ("+x".."-z") or back to the front, the target and
+ *  distance kept. A user move, so auto-fit leaves it; it never touches the layout, the pins, the marks or the URL. */
+function turnTo(s, name) {
+  if (!s.base || !s.controls) return false;
+  const t = s.controls.target, c = s.base.camera.position, tgt = [t.x, t.y, t.z], fit = fitDistOf(s);
+  const want = snapOrient(name, orientationOf(tgt, [c.x, c.y, c.z], fit));
+  if (!want) return false;
+  const p = cameraFor(tgt, want, fit);
+  markUserMove(s);
+  fly(s, tgt, p, false, true);
+  return true;
+}
+
+const GIZ_KEYS = `${MOUSE_HELP}, Shift+arrows turn 15°, + / - zoom, 0 front view, ${CARD_KEYS_HELP}`;
+const GIZ = 72, GIZ_R = 24; // the gizmo's size in px and the axis length from its centre
+const AXES = [["+x", "X", "#e5484d"], ["-x", "", "#e5484d"], ["+y", "Y", "#30a46c"], ["-y", "", "#30a46c"], ["+z", "Z", "#3e63dd"], ["-z", "", "#3e63dd"]];
+const GIZ_AT = (a) => `translate(${(GIZ / 2 + a.sx * GIZ_R).toFixed(1)} ${(GIZ / 2 - a.sy * GIZ_R).toFixed(1)})`;
+
+/** The orientation gizmo: a small SVG in the corner of the 3D surface (not in the WebGL scene). Its geometry is set by drawGizmo
+ *  from the camera when the camera changes, never through React state; this only renders the six axis ends and Front. */
+function Gizmo({ onTurn }) {
+  const start = Object.fromEntries(gizmoAxes(null, null).map((a) => [a.name, a]));
+  const press = (name) => (e) => { e.stopPropagation(); onTurn(name); };
+  const key = (name) => (e) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); onTurn(name); } };
+  return (
+    <div data-graph-gizmo="" title={GIZ_KEYS} className="absolute bottom-2 right-2 flex select-none flex-col items-center" style={{ width: GIZ }}>
+      <svg width={GIZ} height={GIZ} viewBox={`0 0 ${GIZ} ${GIZ}`} role="group" aria-label={`Orientation (${GIZ_KEYS})`}>
+        {AXES.map(([name, , col]) => (
+          <line key={name} data-gizmo-line={name} x1={GIZ / 2} y1={GIZ / 2} x2={GIZ / 2 + start[name].sx * GIZ_R} y2={GIZ / 2 - start[name].sy * GIZ_R} stroke={col} strokeWidth="1.5" />
+        ))}
+        {AXES.map(([name, label, col]) => (
+          <g key={name} data-gizmo-axis={name} role="button" tabIndex={0} aria-label={`Look along ${name.toUpperCase()}`} transform={GIZ_AT(start[name])} style={{ cursor: "pointer" }} onClick={press(name)} onKeyDown={key(name)}>
+            <circle r={label ? 8 : 4.5} fill={label ? col : graphTheme().gizmoDot} stroke={col} strokeWidth="1.5" />
+            {label ? <text textAnchor="middle" dy="3.5" fontSize="10" fontWeight="600" fill="#fff" style={{ pointerEvents: "none" }}>{label}</text> : null}
+          </g>
+        ))}
+      </svg>
+      <button type="button" data-gizmo-front="" onClick={press("front")} className="rounded border border-border bg-background/80 px-1.5 text-[10px] leading-4 text-muted-foreground hover:text-foreground">Front</button>
+    </div>
+  );
+}
+
+/** The gizmo's moving parts (an axis end and its line, by name), or null when there is none. */
+function gizmoParts(root) {
+  if (!root) return null;
+  const parts = new Map();
+  for (const [name] of AXES) parts.set(name, { g: root.querySelector(`[data-gizmo-axis="${name}"]`), line: root.querySelector(`[data-gizmo-line="${name}"]`) });
+  return { root, parts, key: "" };
+}
+
+/** Redraw the gizmo from the camera, only when the camera's orientation changed since the last draw. */
+function drawGizmo(s) {
+  const gz = s.gizmo;
+  if (!gz || !s.controls) return;
+  const t = s.controls.target, c = s.base.camera.position;
+  const axes = gizmoAxes([t.x, t.y, t.z], [c.x, c.y, c.z]);
+  const f3 = (v) => (Math.abs(v) < 5e-4 ? 0 : v).toFixed(3); // never "-0.000"
+  const key = axes.map((a) => `${f3(a.sx)},${f3(a.sy)},${f3(a.depth)}`).join("|");
+  if (key === gz.key) return;
+  gz.key = key;
+  for (const a of axes) {
+    const { g, line } = gz.parts.get(a.name);
+    if (!g || !line) continue;
+    g.setAttribute("transform", GIZ_AT(a));
+    g.dataset.sx = f3(a.sx);
+    g.dataset.sy = f3(a.sy);
+    g.dataset.depth = f3(a.depth);
+    g.style.opacity = String(0.45 + 0.55 * (a.depth + 1) / 2); // the ends toward the viewer are brighter
+    line.setAttribute("x2", String(GIZ / 2 + a.sx * GIZ_R));
+    line.setAttribute("y2", String(GIZ / 2 - a.sy * GIZ_R));
+  }
+}
+
+/** Where the camera should be: fit every visible node (also after fit() until you move), or the focused doc with its
+ *  neighbours (closer than focal / 3 is never needed: 2D caps the focus zoom at 3; a doc with no neighbours at focal / 2).
+ *  Keeps the current orbit angle. Tweens over TWEEN_MS unless `snap` (or nothing was drawn yet). */
+function placeView(s, snap = false) {
+  if (!s.sc || !s.base || !s.sc.n) return;
+  const { xyz, mask } = s.sc, aspect = s.w / Math.max(1, s.h), focal = focalFor(s.h);
+  let c, d;
+  const dt = !s.fitAll && s.drill ? drillTargets(s.graph.nodes, s.drill).filter((i) => mask[i]) : []; // a drilled folder and its drawn children
+  const ft = !s.fitAll && s.fitIdx ? s.fitIdx.filter((i) => i < s.sc.n && mask[i]) : []; // fitTo(ids)
+  if (ft.length) {
+    c = robustSphere(xyz, ft, s.sc.radius);
+    if (!c) return;
+    d = Math.max(fitDistance(c.r, FOV, aspect, 1.2), focal / 3); // the focus fly-to's floor (3D-UX-1 §2)
+  } else if (dt.length) {
+    c = robustSphere(xyz, dt, s.sc.radius);
+    if (!c) return;
+    d = Math.max(fitDistance(c.r, FOV, aspect), focal / FIT_FLOOR);
+  } else if (s.fitAll || (s.aim >= 0 ? !mask[s.aim] : s.focus < 0 || !mask[s.focus])) {
+    c = robustSphere(xyz, s.visIdx, s.sc.radius); // radii in: a big folder sphere is shown whole; far-out nodes left out
+    if (!c) return;
+    d = Math.max(fitDistance(c.r, FOV, aspect), focal / FIT_FLOOR); // a tiny graph never fills the screen (2D fitBox caps its zoom at 4)
+  } else {
+    const f = s.aim >= 0 ? s.aim : s.focus; // an Enter on a find match frames it, the focus otherwise
+    const at = { x: xyz[3 * f], y: xyz[3 * f + 1], z: xyz[3 * f + 2] };
+    const around = (f === s.focus ? s.focusNear : near(s, f)).filter((i) => mask[i]);
+    if (around.length > 1) {
+      c = robustSphere(xyz, around, s.sc.radius);
+      d = c ? fitDistance(c.r, FOV, aspect, 1.2) : 0; // null: every neighbour non-finite, centre on the doc
+      if (d < focal / 3) { c = at; d = focal / 3; }
+    } else {
+      c = at; d = focal / 2;
+    }
+  }
+  const t = s.controls.target, p = s.base.camera.position;
+  let dx = p.x - t.x, dy = p.y - t.y, dz = p.z - t.z;
+  const len = Math.hypot(dx, dy, dz);
+  if (len > 1e-9) { dx /= len; dy /= len; dz /= len; } else { dx = 0; dy = 0; dz = 1; }
+  fly(s, [c.x, c.y, c.z], [c.x + dx * d, c.y + dy * d, c.z + dz * d], snap);
+}
+
+/** The idle turn (round 3, option "Turn slowly when idle", off by default): while `idleRate` says turn, one frame's share of the
+ *  azimuth round the orbit target, through applyCamera, so the frame draws; at 0 nothing is touched (the loop draws only when dirty).
+ *  A tween under way counts as input. The turn is not a user move: auto-fit and what the reader set stay as they are. */
+function idleStep(s, now, on) {
+  const dt = s.idleAt === null ? 0 : Math.min(IDLE_STEP_MAX_MS, Math.max(0, now - s.idleAt));
+  s.idleAt = now;
+  if (s.lastInputAt === null || s.tween) s.lastInputAt = now;
+  if (!s.sc || !s.ready) return;
+  const hidden = typeof document !== "undefined" && document.visibilityState === "hidden";
+  const rate = idleRate({ on, reduced: s.reduced, now, lastInputAt: s.lastInputAt, tweening: !!s.tween, hidden, dragging: !!s.down });
+  if (!rate || !dt) return;
+  const t = s.controls.target, c = s.base.camera.position;
+  applyCamera(s, [t.x, t.y, t.z], turnAzimuth([t.x, t.y, t.z], [c.x, c.y, c.z], (rate * dt) / 1000));
+  s.overlayDirty = true; // labels follow the camera
+}
+
+/** Move the camera to target `t` and position `p`: a TWEEN_MS tween, or at once with `snap`, before the first frame, or with reduced motion (every caller cuts). */
+function fly(s, t, p, snap = false, arc = false) {
+  const to = { t, p };
+  if (snap || s.reduced || !s.ready) { s.tween = null; applyCamera(s, to.t, to.p); return; }
+  const ct = s.controls.target, cp = s.base.camera.position;
+  s.tween = { from: { t: [ct.x, ct.y, ct.z], p: [cp.x, cp.y, cp.z] }, to, t0: null, arc };
+}
+
+/** keepView: the focused doc off screen (or behind the camera) is panned to the centre, the angle and distance kept. */
+function panInto(s) {
+  if (!s.sc || !s.base || s.focus < 0 || !s.sc.mask[s.focus]) return;
+  reproject(s);
+  const f = s.focus, x = s.scr[3 * f], y = s.scr[3 * f + 1];
+  if (s.scr[3 * f + 2] > 1e-6 && x >= 0 && x <= s.w && y >= 0 && y <= s.h) return;
+  const t = s.controls.target, c = s.base.camera.position, xyz = s.sc.xyz;
+  const at = [xyz[3 * f], xyz[3 * f + 1], xyz[3 * f + 2]];
+  fly(s, at, [at[0] + c.x - t.x, at[1] + c.y - t.y, at[2] + c.z - t.z]);
+}
+
+/** The projection now (screenPositions, idAt and keepView may be asked between frames). */
+function reproject(s) {
+  if (!s.sc || !s.base) return;
+  const f = s.base.frame();
+  project(s.sc.xyz, s.sc.radius, s.sc.n, f.vp, f.focal, s.w, s.h, s.scr, s.rpx);
+}
+
+/** The pivot: the focused doc when it is drawn, else the centre of the visible docs (3D-UX-1 §2). Null with nothing drawn. */
+function pivotOf(s) {
+  const sc = s.sc;
+  if (!sc?.n) return null;
+  if (s.focus >= 0 && sc.mask[s.focus]) return [sc.xyz[3 * s.focus], sc.xyz[3 * s.focus + 1], sc.xyz[3 * s.focus + 2]];
+  const c = robustSphere(sc.xyz, s.visIdx, sc.radius); // the centre of the mass, as fit-all frames it
+  return c ? [c.x, c.y, c.z] : null;
+}
+
+/** The hits under (x, y) front to back, from the pickable set only (pickAt's rule), so the stack's head is what a plain click picks. */
+function stackAt(s, x, y) {
+  if (!s.sc || !s.sc.n || !s.ready) return [];
+  return pickStack(s.scr, s.rpx, pickable(s.visIdx, s.litIdx, s.dim), x, y);
+}
+
+/** The anchored hover-card feed (3D-UX-1 §2 "hover card"): the hovered dot's projection, or null while dragging, on touch, or
+ *  with the dot hidden or behind the camera. Sent only when it changed (rounded to whole px). */
+function feedCard(s) {
+  const cb = s.latest.current.onHoverCard;
+  if (!cb) return;
+  const i = s.hover;
+  const show = i >= 0 && !!s.sc?.mask?.[i] && s.scr[3 * i + 2] > 1e-6 && !s.down?.moved && s.pointerType !== "touch";
+  const card = show ? { id: s.ids[i], x: s.scr[3 * i], y: s.scr[3 * i + 1], r: s.rpx[i], behind: s.hoverBehind, w: s.w, h: s.h } : null;
+  const key = card ? `${card.id}|${Math.round(card.x)}|${Math.round(card.y)}|${Math.round(card.r)}|${card.behind}|${card.w}|${card.h}` : "";
+  if (key === s.cardKey) return;
+  s.cardKey = key;
+  cb(card);
+}
+
+/** Over the overlay: the selection's rings are drawn by drawOverlay; here the flash ring and, while turning, the pivot cross. */
+function drawMarksOver(ctx, s) {
+  ctx.setTransform(s.dpr, 0, 0, s.dpr, 0, 0);
+  const fl = s.flash;
+  if (fl?.ring && s.scr[3 * fl.i + 2] > 1e-6) {
+    ctx.globalAlpha = fl.ring.alpha;
+    ctx.strokeStyle = graphTheme().hot;
+    ctx.lineWidth = 2;
+    ctx.beginPath();
+    ctx.arc(s.scr[3 * fl.i], s.scr[3 * fl.i + 1], fl.ring.radius, 0, 2 * Math.PI);
+    ctx.stroke();
+    ctx.globalAlpha = 1;
+  }
+  for (const i of s.pinIdx) { // a pin head on each pinned dot, top right
+    if (!(s.scr[3 * i + 2] > 1e-6) || !s.sc.mask[i]) continue;
+    const r = Math.max(3, s.rpx[i]), hx = s.scr[3 * i] + r * 0.7, hy = s.scr[3 * i + 1] - r * 0.7;
+    ctx.beginPath();
+    ctx.arc(hx, hy, 3.5, 0, 2 * Math.PI);
+    ctx.fillStyle = graphTheme().hot;
+    ctx.fill();
+    ctx.strokeStyle = graphTheme().focusRing;
+    ctx.lineWidth = 1;
+    ctx.stroke();
+  }
+  if (s.lasso && s.lasso.pts.length > 1) { // the lasso polygon, closed back to its first point as it will be judged
+    ctx.beginPath();
+    s.lasso.pts.forEach(([x, y], k) => (k ? ctx.lineTo(x, y) : ctx.moveTo(x, y)));
+    ctx.closePath();
+    ctx.fillStyle = graphTheme().lassoFill;
+    ctx.fill();
+    ctx.strokeStyle = graphTheme().hot;
+    ctx.lineWidth = 1.5;
+    ctx.setLineDash([5, 4]);
+    ctx.stroke();
+    ctx.setLineDash([]);
+  }
+  if (s.pivot && s.down?.moved && s.frameAt) {
+    const at = new Float32Array(3), r = new Float32Array(1);
+    project(Float32Array.from(s.pivot), [0], 1, s.frameAt.vp, s.frameAt.focal, s.w, s.h, at, r);
+    if (at[2] > 1e-6) {
+      ctx.strokeStyle = graphTheme().focusRing;
+      ctx.lineWidth = 1.5;
+      ctx.beginPath();
+      ctx.moveTo(at[0] - 7, at[1]); ctx.lineTo(at[0] + 7, at[1]);
+      ctx.moveTo(at[0], at[1] - 7); ctx.lineTo(at[0], at[1] + 7);
+      ctx.stroke();
+    }
+  }
+}
+
+function stepTween(s, now) {
+  const tw = s.tween;
+  if (tw.t0 === null) tw.t0 = now;
+  const u = ease(Math.min(1, (now - tw.t0) / TWEEN_MS));
+  const mix = (a, b) => [a[0] + (b[0] - a[0]) * u, a[1] + (b[1] - a[1]) * u, a[2] + (b[2] - a[2]) * u];
+  applyCamera(s, mix(tw.from.t, tw.to.t), tw.arc ? arcPoint(tw.to.t, tw.from.p, tw.to.p, u) : mix(tw.from.p, tw.to.p)); // a gizmo turn goes round the target, never through it
+  if (u >= 1) s.tween = null;
+}
+
+function applyCamera(s, t, p) {
+  s.camPrev = null; // a programmatic move is never redone round the pivot; it ends the pivot unless a press is still down
+  if (!s.down) s.pivot = null;
+  s.controls.target.set(t[0], t[1], t[2]);
+  s.base.camera.position.set(p[0], p[1], p[2]);
+  s.controls.update();
+  s.dirty = true;
+}
+
+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 (as in 2D). */
+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 same rule as 2D) 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();
+  // The page's marks (WIKI-GRAPH-3D-PORT-1): a list row's hover stands in for the pointer's, a lens lights its docs and links.
+  const mk = s.latest.current.marks, at = (id) => s.index.get(id);
+  const markHover = mk?.hoverId != null && at(mk.hoverId) !== undefined ? at(mk.hoverId) : -1;
+  const hover = s.hover >= 0 ? s.hover : markHover;
+  const out = litOf({ focus: s.focus, hover, near: (i) => near(s, i), match: s.match, focusLit: rings ? s.focusNear : null });
+  let { lit, links, dim } = out;
+  if (mk?.lit) {
+    const all = new Set(lit);
+    for (const id of mk.lit) { const i = at(id); if (i !== undefined) all.add(i); }
+    lit = [...all];
+    dim = true; // a lens lights over the dimmed base, as a find term
+  }
+  if (mk?.links?.length) {
+    links = [...links];
+    for (const [a, b] of mk.links) { const i = at(a), j = at(b); if (i !== undefined && j !== undefined) links.push(i, j); }
+  }
+  s.selIdx = mk?.selected ? [...mk.selected].map(at).filter((i) => i !== undefined) : [];
+  s.pinIdx = mk?.pinned ? [...mk.pinned].map(at).filter((i) => i !== undefined) : [];
+  if (mk?.pinned) s.box.dataset.graphPinned = String(s.pinIdx.length); else delete s.box.dataset.graphPinned;
+  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 || hover >= 0 ? hotHeads(s.pairs, s.dirs, [s.focus, hover]) : null;
+  dimBase(s.baseEl, dim, s.dimLevel);
+  s.box.dataset.graphLit = s.match || mk?.lit ? String(s.lit.length) : "";
+  if (mk?.selected) s.box.dataset.graphSelected = String(s.selIdx.length); else delete s.box.dataset.graphSelected;
+  s.overlayDirty = true;
+}
+
+/** 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;
+}