@smartmemory/wiki-components 0.4.0 → 0.6.0

package/src/graph/lib/idleTurn.js

@@ -0,0 +1,31 @@
+// WIKI-GRAPH-3D-POLISH-1 round 3: "Turn slowly when idle", the 3D graph's one self-moving option. Owner rule "no idle auto-spin":
+// the camera turns by itself ONLY when the reader switched this on, it is OFF by default, and nothing turns it on for them. Pure of
+// React and three: the rule (`idleRate`), the azimuth step (`turnAzimuth`) and the stored preference (`readIdleTurn`).
+import { readStore, writeStore } from "./graphShell";
+
+export const IDLE_DELAY_MS = 10000; // no input for this long before the turn starts
+export const IDLE_DEG_PER_S = 4; // slow: a full turn in 90 s
+export const IDLE_TURN_KEY = "wiki.graph.idleTurn"; // per viewer, in localStorage: never in the URL or a saved view
+export const IDLE_STEP_MAX_MS = 100; // one frame never turns more than this long (a hidden-tab gap or a paused loop must not jump)
+
+/** Degrees per second the camera should turn right now, or 0. Turns only when the option is on (`on === true`), reduced motion is
+ *  off, nothing tweens, nothing is dragged, the tab is visible and the last input is older than IDLE_DELAY_MS. */
+export function idleRate({ on, reduced, now, lastInputAt, tweening, hidden, dragging } = {}) {
+  if (on !== true || reduced || tweening || hidden || dragging) return 0;
+  if (!Number.isFinite(now) || !Number.isFinite(lastInputAt)) return 0;
+  return now - lastInputAt >= IDLE_DELAY_MS ? IDLE_DEG_PER_S : 0;
+}
+
+/** The camera position `deg` further round the vertical axis through `target`: azimuth only, distance and elevation unchanged
+ *  (the same az as graphOrient `orientationOf`: atan2(dx, dz)). Bad input comes back unchanged. */
+export function turnAzimuth(target, cameraPos, deg) {
+  const ok = (v) => Array.isArray(v) && v.length === 3 && v.every(Number.isFinite);
+  if (!ok(target) || !ok(cameraPos) || !Number.isFinite(deg)) return cameraPos;
+  const a = (deg * Math.PI) / 180, c = Math.cos(a), sn = Math.sin(a);
+  const dx = cameraPos[0] - target[0], dz = cameraPos[2] - target[2];
+  return [target[0] + dx * c + dz * sn, cameraPos[1], target[2] + dz * c - dx * sn];
+}
+
+/** The stored choice, shape-checked: only the boolean `true` is on; anything else (missing, "true", 1, {}, null) is off. */
+export const readIdleTurn = () => readStore(IDLE_TURN_KEY, false) === true;
+export const writeIdleTurn = (on) => writeStore(IDLE_TURN_KEY, on === true);

package/src/graph/lib/labelDepth.js

@@ -0,0 +1,59 @@
+// WIKI-GRAPH-3D-POLISH-1 round 4: which labels the 3D graph shows, with depth. Far-side labels painted over near dots were the
+// main 3D clutter (3D-UX-1 REPORT.md "labels in depth"). Each frame the candidates are the always-shown docs (lit, focused,
+// hovered, selected) plus the docs nearer than the pivot (the orbit target); they are packed front to back so near labels win a
+// collision (the same box rule as the 2D overlay: createLabelPacker), and drawn back to front with an opacity that falls with
+// depth. The screen font stays 12 px (overlay.js). Pure: no canvas, no measuring beyond the `width` it is handed.
+import { createLabelPacker } from "./graphView";
+import { HUB_DEGREE, LABEL_ALPHA_MIN, labelFade } from "./wikiGraph";
+
+/** The lowest opacity a label gets: an always-shown label at the far edge of the scene. */
+export const DEPTH_FLOOR = 0.35;
+const NEAR_MIN = 1e-6; // a depth at or under this is behind the camera (graph3d.project)
+
+/** A label's depth opacity: 1 at or nearer than `pivot`, falling linearly to DEPTH_FLOOR at `far`, never outside
+ *  [DEPTH_FLOOR, 1]. No usable pivot or far edge (not finite, far not past the pivot) means 1. */
+export function depthOpacity(depth, pivot, far) {
+  if (!Number.isFinite(pivot) || !(far > pivot) || !(depth > pivot)) return 1;
+  return Math.max(DEPTH_FLOOR, Math.min(1, 1 - ((1 - DEPTH_FLOOR) * (depth - pivot)) / (far - pivot)));
+}
+
+let pool = new Uint32Array(256); // the candidate buffer, reused every frame
+
+/** The labels of one 3D frame, in DRAW order (back to front): [{i, x, y, a}] (centre x, baseline y, alpha = fade x depth opacity).
+ *  `scr`: the projection, three floats per doc (x, y, depth); a doc with a NaN or non-positive depth has no label. `always`:
+ *  doc indices that are shown whatever their depth (lit, selected; `focus` and `hover` are packed before the rest of them, so
+ *  neither is dropped by a nearer neighbour). `order`: doc indices best-linked first (the hubs are its prefix); ordinary labels
+ *  follow pickLabels' mode rules (`mode`, `degree`, `k`, `labelK`) but only for docs nearer than `pivot` (a non-finite pivot
+ *  turns the depth rule off). Ordinary labels stop at min(cap, budget) in all (the nearest kept); always-shown ones are exempt
+ *  from the depth filter, the fade and the budget, up to `cap`, yet still lose a collision to an always-shown label that is
+ *  nearer (or is the focus or hover). `at(i)`: [sx, sy, rPx]; `width(i)`: label px width. Cost: one linear pass over `order`,
+ *  a sort of the on-screen candidates (a reused typed-array buffer), a linear packing pass, a sort of the (at most cap) picks. */
+export function pickDepthLabels({ scr, mask, always, order, pivot, far, focus = -1, hover = -1, mode, cap, budget = cap, at, width, w, h, degree = null, k = 1, labelK = 0 }) {
+  if (!scr || !scr.length) return [];
+  const depth = (i) => scr[3 * i + 2];
+  const usable = (i) => depth(i) > NEAR_MIN && (!mask || !!mask[i]); // false for NaN and for an index off the end
+  const onScreen = (i) => scr[3 * i] >= -50 && scr[3 * i] <= w + 50 && scr[3 * i + 1] >= -20 && scr[3 * i + 1] <= h + 20;
+  const { out, place } = createLabelPacker({ at, width, w, h, mask });
+  const seen = new Set(), lead = [];
+  for (const i of always || []) if (!seen.has(i) && usable(i)) { seen.add(i); lead.push(i); }
+  const pin = (i) => (i === focus || i === hover ? 1 : 0);
+  lead.sort((a, b) => pin(b) - pin(a) || depth(a) - depth(b));
+  for (const i of lead) { if (out.length >= cap) break; place(i, depthOpacity(depth(i), pivot, far)); }
+
+  const limit = Math.min(cap, budget), fade = labelFade(k, labelK), gate = Number.isFinite(pivot);
+  let m = 0;
+  for (const i of order || []) {
+    if (seen.has(i)) continue;
+    const hub = !!degree && degree[i] >= HUB_DEGREE;
+    if (mode !== "all" && !hub && (mode === "focus" || fade < LABEL_ALPHA_MIN)) break; // the hubs are the order's prefix
+    if (!usable(i) || (gate && depth(i) > pivot) || !onScreen(i)) continue;
+    if (m === pool.length) { const g = new Uint32Array(2 * m); g.set(pool); pool = g; }
+    pool[m++] = i;
+  }
+  const near = pool.subarray(0, m).sort((a, b) => depth(a) - depth(b));
+  for (let t = 0; t < m && out.length < limit; t++) {
+    const i = near[t];
+    place(i, mode === "all" || (!!degree && degree[i] >= HUB_DEGREE) ? 1 : fade);
+  }
+  return out.sort((a, b) => depth(b.i) - depth(a.i)); // packed in priority order (pinned first), drawn back to front
+}

package/src/graph/lib/layoutClient.js

@@ -0,0 +1,69 @@
+// WIKI-GRAPH-OBSIDIAN-1: the main thread's side of the layout worker (forceWorker.js). Builds every message the worker
+// gets, so "a slider moves -> the worker gets `params`" is a unit test, with the Worker factory injectable. Without a
+// Worker (jsdom, a browser that blocks them) there is no layout: the seeded positions are drawn as they are.
+// WIKI-GRAPH-3D-1: `dims` 3 talks to forceWorker3d.js instead (positions `xyz`, three floats a node); the messages are shared.
+// WIKI-GRAPH-CLUSTER-REGROUP-1: `init` may carry `pinned` (Uint8Array, nodes fixed where they start), and a caller may pass
+// raw worker `params` (already d3 values, e.g. layoutEngine clusterParams), `alpha` and `maxTicks` in place of the defaults.
+import { forceParams, maxTicksFor, progressMsFor } from "./graphView";
+
+export const WARM_ALPHA = 0.3; // a re-layout that starts from cached positions needs far less heat than a cold start
+
+export const messages = {
+  init: ({ xy, pairs, targets, physics, big, warm, dims = 2, radii = null, pinned = null, weights = null, params = null, alpha = null, maxTicks = null }) => ({
+    type: "init", [dims === 3 ? "xyz" : "xy"]: xy, links: pairs, targets, params: params || forceParams(physics), progressMs: progressMsFor(xy.length / dims),
+    maxTicks: maxTicks ?? maxTicksFor(big), alpha: alpha ?? (warm ? WARM_ALPHA : 1), big, ...(radii ? { radii } : {}), ...(pinned ? { pinned } : {}), ...(weights ? { weights } : {}),
+  }),
+  params: (physics, raw = null) => ({ type: "params", params: raw || forceParams(physics) }),
+  weights: (weights) => ({ type: "weights", weights }),
+  contain: (pairs, lead) => ({ type: "contain", pairs, lead }),
+  pause: () => ({ type: "pause" }),
+  resume: () => ({ type: "resume" }),
+  reheat: () => ({ type: "reheat" }),
+  pin: (i, x, y, z) => ({ type: "pin", i, x, y, z }),
+  unpin: (idx = null) => ({ type: "unpin", ...(idx ? { idx } : {}) }),
+  stop: () => ({ type: "stop" }),
+};
+
+export const defaultWorker = () => (typeof Worker === "function"
+  ? new Worker(new URL("./forceWorker.js", import.meta.url), { type: "module" })
+  : null);
+export const defaultWorker3d = () => (typeof Worker === "function"
+  ? new Worker(new URL("./forceWorker3d.js", import.meta.url), { type: "module" })
+  : null);
+
+/** Start a layout. `onTick(xy, alpha, ticks)` per position frame, `onState(state, ms)` on running|paused|settled.
+ *  Returns null when no Worker can be made. `xy` is copied, so the caller keeps its own positions array. `dims` 3: `xy`
+ *  and `targets` hold x, y, z per node and the 3D worker lays them out (onTick gets xyz). `radii` (graphView layoutRadii,
+ *  copied): the drawn radius per node, which the worker keeps apart. `pinned` (Uint8Array, copied): nodes that never move.
+ *  `weights` (Float32Array, copied): one aggregated-link weight per leading pair of `pairs` (linkWeight.js sets the link strength; the
+ *  rest, containment springs, are 1); `layout.weights(w)` replaces them live without reheating,
+ *  and `layout.contain(pairs, lead)` replaces the containment springs (every pair after the first `lead` links) the same way.
+ *  `params` / `alpha` / `maxTicks`: raw overrides of forceParams(physics), the warm alpha and maxTicksFor(big). */
+export function startLayout({ xy, pairs, targets, physics, big, warm, dims = 2, radii = null, pinned = null, weights = null, params = null, alpha = null, maxTicks = null, onTick, onState }, makeWorker = dims === 3 ? defaultWorker3d : defaultWorker) {
+  let worker = null;
+  try { worker = makeWorker(); } catch (e) { console.warn("wiki graph: the layout worker could not start, the graph stays at its seeded layout:", e?.message || e); }
+  if (!worker) return null;
+  worker.onmessage = (e) => {
+    const m = e.data;
+    if (m.type === "tick") onTick?.(m.xy ?? m.xyz, m.alpha, m.ticks);
+    else if (m.type === "state") onState?.(m.state, m.ms);
+  };
+  worker.onerror = (e) => { console.warn("wiki graph: the layout worker failed, the graph stays where it is:", e?.message || e); onState?.("settled", null); };
+  const send = (m) => worker.postMessage(m);
+  const own = new Float32Array(xy), ownTargets = new Float32Array(targets), ownPairs = new Uint32Array(pairs);
+  const ownRadii = radii ? new Float32Array(radii) : null, ownPinned = pinned ? new Uint8Array(pinned) : null;
+  const ownWeights = weights ? new Float32Array(weights) : null;
+  worker.postMessage(messages.init({ xy: own, pairs: ownPairs, targets: ownTargets, physics, big, warm, dims, radii: ownRadii, pinned: ownPinned, weights: ownWeights, params, alpha, maxTicks }),
+    [own.buffer, ownTargets.buffer, ownPairs.buffer, ...(ownRadii ? [ownRadii.buffer] : []), ...(ownPinned ? [ownPinned.buffer] : []), ...(ownWeights ? [ownWeights.buffer] : [])]);
+  return {
+    params: (p, raw = null) => send(messages.params(p, raw)),
+    weights: (w) => send(messages.weights(new Float32Array(w))),
+    contain: (pairs, lead) => send(messages.contain(new Uint32Array(pairs), lead)),
+    pause: () => send(messages.pause()),
+    resume: () => send(messages.resume()),
+    reheat: () => send(messages.reheat()),
+    pin: (i, x, y, z) => send(messages.pin(i, x, y, z)), // 3D only (forceWorker3d): hold doc i at (x, y, z)
+    unpin: (idx = null) => send(messages.unpin(idx ? Uint32Array.from(idx) : null)), // release those docs, or every pin
+    stop: () => { send(messages.stop()); worker.terminate?.(); },
+  };
+}

package/src/graph/lib/layoutEngine.js

@@ -0,0 +1,184 @@
+// WIKI-GRAPH-CLUSTER-REGROUP-1 + WIKI-GRAPH-FOCUS-HOPS-1: the graph's layout engine, pure (no DOM, no worker), shared by
+// both canvases. Owner ruling 2026-10-21: "3D regroups, 2D stays put", so only the 3D canvas feeds the position parts
+// (clusterTargets, focusShells, glide) to the worker; the lit-set parts (hopRings, focusFindLit, folderGroups) serve both.
+//
+// The model: a *frame* is the set of positions every other state eases back to. There are two, `global` (the plain force
+// layout) and `clustered` (the same graph re-laid out with every node pulled hard to its group's centre, centres spread
+// apart). A focus re-lays out only its lit neighbourhood inside the active frame, with the dimmed rest pinned; clearing it
+// eases the lit set back to the active frame. Every move goes through `glide`, never a snap.
+import { forceParams } from "./graphView";
+import { fibonacciSphere, seedRadius } from "./graph3d";
+
+/** Hub guard: a hop ring stops expanding past a node that would add more than this many unseen nodes ("+N" badge). */
+export const HUB_CAP = 150;
+
+const nbrsOf = (adj) => (id) => (adj.get ? adj.get(id) : adj[id]) || [];
+
+/** The focus's lit neighbourhood: a ring-by-ring BFS from `root` out to `hops` links. The root always expands. Any other
+ *  node with more than `cap` unseen neighbours is not expanded; it goes into `capped` with that count (its "+N" badge).
+ *  Ids in `open` (badge-clicked) always expand. `adj`: a Map id -> neighbour ids, or an array indexed by node.
+ *  Returns {lit: Set, depth: Map id -> hop, capped: Map id -> hidden count}. An undefined/null root lights nothing. */
+export function hopRings(adj, root, hops, { cap = HUB_CAP, open = null } = {}) {
+  const lit = new Set(), depth = new Map(), capped = new Map();
+  if (root === null || root === undefined) return { lit, depth, capped };
+  const nbrs = nbrsOf(adj);
+  lit.add(root); depth.set(root, 0);
+  let frontier = [root];
+  for (let h = 0; h < hops && frontier.length; h++) {
+    const next = [];
+    for (const id of frontier) {
+      const fresh = new Set();
+      for (const n of nbrs(id)) if (!lit.has(n)) fresh.add(n);
+      if (id !== root && fresh.size > cap && !(open && open.has(id))) { capped.set(id, fresh.size); continue; }
+      for (const n of fresh) if (!lit.has(n)) { lit.add(n); depth.set(n, h + 1); next.push(n); }
+    }
+    frontier = next;
+  }
+  return { lit, depth, capped };
+}
+
+/** Find + focus: with a find term (`matchIds` not null) a node is lit only if it is in both the hop set and the matches;
+ *  the focus itself is always lit. Without a term, the hop set as it is. */
+export function focusFindLit(hopLit, matchIds, focusId) {
+  if (!matchIds) return new Set(hopLit);
+  const out = new Set();
+  for (const id of hopLit) if (matchIds.has(id)) out.add(id);
+  if (focusId !== null && focusId !== undefined) out.add(focusId);
+  return out;
+}
+
+/** A level-view folder's area for the cluster bubbles: the most common `group` among the docs under its `path` (the
+ *  folder itself and every subfolder), ties broken by group name; a folder with no docs gets null. `levelNodes`: the
+ *  level view's nodes (only `kind: "folder"` ones are looked at); `flatGraph`: the doc graph ({nodes: [{folder, group}]}).
+ *  Returns a Map folder id -> group (or null). Bubble membership only: legend rows and colours are unchanged. */
+export function folderGroups(levelNodes, flatGraph) {
+  const tally = new Map(); // folder path -> Map group -> count
+  const bump = (path, g) => {
+    let t = tally.get(path);
+    if (!t) tally.set(path, (t = new Map()));
+    t.set(g, (t.get(g) || 0) + 1);
+  };
+  for (const d of flatGraph?.nodes || []) {
+    if (d.kind === "folder" || d.group === null || d.group === undefined) continue;
+    const segs = String(d.folder || "").split("/").filter(Boolean);
+    bump("", d.group);
+    for (let k = 1; k <= segs.length; k++) bump(segs.slice(0, k).join("/"), d.group);
+  }
+  const out = new Map();
+  for (const f of levelNodes || []) {
+    if (f.kind !== "folder") continue;
+    const path = String(f.path || "").split("/").filter(Boolean).join("/");
+    let best = null, bestK = 0;
+    for (const [g, k] of tally.get(path) || []) if (k > bestK || (k === bestK && String(g) < String(best))) { best = g; bestK = k; }
+    out.set(f.id, best);
+  }
+  return out;
+}
+
+/** The clustered frame's forceX/Y/Z strength (the default slider gives 0.05): strong, so each group packs round its own
+ *  centre while links still pull across. */
+export const CLUSTER_CENTRE = 0.25;
+/** forceParams with the strong cluster pull: the worker params of the clustered frame. */
+export const clusterParams = (physics) => ({ ...forceParams(physics), centre: CLUSTER_CENTRE });
+
+/** The clustered frame's per-node targets (Float32Array, `dims` floats a node). Group centres sit on a Fibonacci sphere
+ *  (3D) or a circle (2D) round the current centroid, largest group first (ties by name), far enough apart that the
+ *  largest group's ball (radius rMax = 14 * cbrt(size)) clears its neighbour: R = max(seedRadius(n), 1.8 * rMax / spacing),
+ *  spacing sqrt(4π/G) on the sphere, 2π/G on the circle. A node whose `groupOf(i)` is null targets the centroid.
+ *  Returns {targets, centres: Map group -> [x, y(, z)], R}. */
+export function clusterTargets(pos, dims, groupOf) {
+  const n = Math.floor(pos.length / dims), c = new Array(dims).fill(0);
+  for (let i = 0; i < n; i++) for (let k = 0; k < dims; k++) c[k] += pos[dims * i + k] / Math.max(1, n);
+  const size = new Map();
+  for (let i = 0; i < n; i++) {
+    const g = groupOf(i);
+    if (g !== null && g !== undefined) size.set(g, (size.get(g) || 0) + 1);
+  }
+  const groups = [...size.entries()].sort((a, b) => b[1] - a[1] || (String(a[0]) < String(b[0]) ? -1 : 1));
+  const G = groups.length, rMax = G ? 14 * Math.cbrt(groups[0][1]) : 0;
+  const spacing = dims === 3 ? Math.sqrt((4 * Math.PI) / Math.max(1, G)) : (2 * Math.PI) / Math.max(1, G);
+  const R = G > 1 ? Math.max(seedRadius(n), (1.8 * rMax) / spacing) : 0;
+  const centres = new Map();
+  groups.forEach(([g], j) => {
+    if (dims === 3) {
+      const [x, y, z] = fibonacciSphere(j, G);
+      centres.set(g, [c[0] + R * x, c[1] + R * y, c[2] + R * z]);
+    } else {
+      const a = (2 * Math.PI * j) / Math.max(1, G);
+      centres.set(g, [c[0] + R * Math.cos(a), c[1] + R * Math.sin(a)]);
+    }
+  });
+  const targets = new Float32Array(n * dims);
+  for (let i = 0; i < n; i++) {
+    const t = centres.get(groupOf(i)) || c;
+    for (let k = 0; k < dims; k++) targets[dims * i + k] = t[k];
+  }
+  return { targets, centres, R };
+}
+
+/** The no-Worker stand-in for the clustered frame: each group moves rigidly so its centroid lands on its target (every
+ *  member shares one target, clusterTargets). Nodes with no group stay where they are. Returns a new Float32Array. */
+export function clusterShift(pos, dims, groupOf, targets) {
+  const n = Math.floor(pos.length / dims), out = Float32Array.from(pos), sum = new Map();
+  for (let i = 0; i < n; i++) {
+    const g = groupOf(i);
+    if (g === null || g === undefined) continue;
+    let a = sum.get(g);
+    if (!a) sum.set(g, (a = { i, c: new Float64Array(dims), k: 0 }));
+    for (let d = 0; d < dims; d++) a.c[d] += pos[dims * i + d];
+    a.k++;
+  }
+  for (let i = 0; i < n; i++) {
+    const a = sum.get(groupOf(i));
+    if (!a) continue;
+    for (let d = 0; d < dims; d++) out[dims * i + d] += targets[dims * a.i + d] - a.c[d] / a.k;
+  }
+  return out;
+}
+
+/** The focus re-layout's targets (Float32Array, `dims` floats a node): the focus stays where it is; a lit node at hop d
+ *  targets focus + unit(node - focus) * d * shellR (a node on top of the focus takes a Fibonacci direction); every other
+ *  node targets its own position (the worker pins it anyway). `depth`: Map node index -> hop. shellR: 0.9 * link distance. */
+export function focusShells(pos, dims, depth, focusIdx, shellR) {
+  const t = Float32Array.from(pos), n = Math.floor(pos.length / dims), f = [];
+  for (let k = 0; k < dims; k++) f.push(pos[dims * focusIdx + k]);
+  let j = 0;
+  for (const [i, d] of depth) {
+    if (i === focusIdx || i < 0 || i >= n || !d) continue;
+    const v = [];
+    let len = 0;
+    for (let k = 0; k < dims; k++) { v.push(pos[dims * i + k] - f[k]); len += v[k] * v[k]; }
+    len = Math.sqrt(len);
+    if (len < 1e-6) {
+      const u = fibonacciSphere(j++, Math.max(2, depth.size));
+      for (let k = 0; k < dims; k++) v[k] = u[k];
+      len = Math.hypot(...v) || 1;
+    }
+    for (let k = 0; k < dims; k++) t[dims * i + k] = f[k] + (v[k] / len) * d * shellR;
+  }
+  return t;
+}
+
+/** The time constant (ms) of every eased move: about 600 ms to look settled (5% left after 3 tau). */
+export const GLIDE_TAU = 180;
+/** Below this distance (world units) a glide snaps to its goal, so it ends exactly there. */
+export const GLIDE_SNAP = 0.05;
+
+/** One eased step of `cur` toward `goal` (same length, in place): an exponential approach over `dt` ms. Values within
+ *  GLIDE_SNAP of their goal snap onto it. `idx` (optional): only those node indices (with `dims`) move. Returns the
+ *  largest distance left on any coordinate; 0 means `cur` equals `goal` exactly. `tau` 0 (reduced motion) jumps: every value
+ *  lands on its goal in this one step. */
+export function glide(cur, goal, dt, tau = GLIDE_TAU, idx = null, dims = 1) {
+  const jump = !(tau > 0);
+  const k = jump ? 1 : 1 - Math.exp(-Math.max(0, dt) / tau);
+  let left = 0;
+  const step = (j) => {
+    const d = goal[j] - cur[j];
+    if (jump || Math.abs(d) <= GLIDE_SNAP) { cur[j] = goal[j]; return; }
+    cur[j] += d * k;
+    left = Math.max(left, Math.abs(goal[j] - cur[j]));
+  };
+  if (idx) { for (const i of idx) for (let c = 0; c < dims; c++) step(dims * i + c); }
+  else for (let j = 0; j < cur.length; j++) step(j);
+  return left;
+}

package/src/graph/lib/linkWeight.js

@@ -0,0 +1,67 @@
+// WIKI-GRAPH-LEVEL-WEIGHTS-FU-1: the ONE mapping from an aggregated link's `weight` (graphLevels: how many doc links a folder
+// link stands for) to what is drawn and laid out, shared by the layout workers, the Canvas2D, Pixi and three.js bases.
+//
+// One level t in [0, 1] on a log scale (weight 1 -> 0, WEIGHT_SAT or more -> 1), then two bounded outputs:
+//   width    WIDTH_MIN..WIDTH_MAX screen px  (1 px at weight 1, 2.66 at 10, 4 at 64+)
+//   strength STRENGTH_BASE..STRENGTH_MAX     (d3 link strength: 0.15 at weight 1, 0.32 at 10, 0.45 at 64+)
+// Flat (doc-level, weight 1) links map to exactly today's 1 px and 0.15. A missing, non-finite or < 1 weight counts as 1.
+//
+// Drawn widths are whole px buckets (widthBucket: 1..LINK_BUCKETS), so a renderer draws a few passes, not one width a link.
+export const WEIGHT_SAT = 64;
+export const WIDTH_MIN = 1, WIDTH_MAX = 4;
+export const STRENGTH_BASE = 0.15, STRENGTH_MAX = 0.45;
+export const LINK_BUCKETS = WIDTH_MAX;
+
+const LOG_SAT = Math.log2(WEIGHT_SAT);
+const level = (w) => { const x = Number(w); return x > 1 ? Math.min(1, Math.log2(x) / LOG_SAT) : 0; };
+
+export const linkWidth = (w) => WIDTH_MIN + (WIDTH_MAX - WIDTH_MIN) * level(w);
+export const linkStrength = (w) => STRENGTH_BASE + (STRENGTH_MAX - STRENGTH_BASE) * level(w);
+export const widthBucket = (w) => Math.round(linkWidth(w));
+
+/** The drawn links (`count` of them, `weights` one per drawn link, null = all 1) grouped by width bucket: `idx` holds link
+ *  numbers, bucket b (1..LINK_BUCKETS) is `idx[start[b] .. start[b + 1])`, in link order within a bucket. */
+export function linkBuckets(weights, count) {
+  const start = new Uint32Array(LINK_BUCKETS + 2), idx = new Uint32Array(count);
+  const bucket = new Uint8Array(count);
+  for (let e = 0; e < count; e++) { const b = weights ? widthBucket(weights[e]) : 1; bucket[e] = b; start[b + 1]++; }
+  start[1] = 0;
+  for (let b = 1; b <= LINK_BUCKETS; b++) start[b + 1] += start[b];
+  const fill = start.slice();
+  for (let e = 0; e < count; e++) idx[fill[bucket[e]]++] = e;
+  return { idx, start };
+}
+
+/** How many quads the links of buckets 2.. of `buckets` need (one a link). */
+export const thickCount = (buckets) => buckets.start[LINK_BUCKETS + 1] - buckets.start[2];
+
+/** Quad and index buffers with room for `need` quads (12 floats and 6 identity indices each). `cur` ({ quads, index, cap }) is kept
+ *  while it fits, else the capacity grows to `need` or twice itself, so a renderer draws every thick link and never drops the overflow. */
+export function thickBuffers(cur, need) {
+  if (cur && cur.cap >= need) return cur;
+  const cap = Math.max(1, need, cur ? 2 * cur.cap : 0);
+  return { cap, quads: new Float32Array(12 * cap), index: Uint32Array.from({ length: 6 * cap }, (_, i) => i) };
+}
+
+/** Triangle-list quads (12 floats = 2 triangles a link, world units) for the links of buckets 2.. at zoom `k`, so each is
+ *  `bucket` screen px wide: the Pixi base's thick links (its line-list mesh draws hairlines only). `pos`: x, y per node,
+ *  `pairs`: the drawn index pairs, `buckets`: linkBuckets of them. At most `cap` quads (a caller sizes `out` with thickBuffers
+ *  so the cap is never reached); links past it are not drawn, and that is one console.warn naming how many. Returns how many were written. */
+export function fillThickLinks(pos, pairs, buckets, k, out, cap) {
+  let q = 0, lost = 0;
+  for (let b = 2; b <= LINK_BUCKETS; b++) {
+    const half = b / (2 * k);
+    for (let j = buckets.start[b]; j < buckets.start[b + 1]; j++) {
+      const e = 2 * buckets.idx[j], a = pairs[e], c = pairs[e + 1];
+      const ax = pos[2 * a], ay = pos[2 * a + 1], bx = pos[2 * c], by = pos[2 * c + 1];
+      const dx = bx - ax, dy = by - ay, len = Math.hypot(dx, dy);
+      if (!(len > 0)) continue;
+      if (q >= cap) { lost++; continue; }
+      const nx = (-dy / len) * half, ny = (dx / len) * half, o = 12 * q++;
+      out[o] = ax + nx; out[o + 1] = ay + ny; out[o + 2] = ax - nx; out[o + 3] = ay - ny; out[o + 4] = bx + nx; out[o + 5] = by + ny;
+      out[o + 6] = ax - nx; out[o + 7] = ay - ny; out[o + 8] = bx - nx; out[o + 9] = by - ny; out[o + 10] = bx + nx; out[o + 11] = by + ny;
+    }
+  }
+  if (lost) console.warn(`wiki graph: ${lost} weighted link${lost === 1 ? "" : "s"} not drawn, the thick-link buffer holds ${cap}`);
+  return q;
+}

package/src/graph/lib/orphanPull.js

@@ -0,0 +1,10 @@
+// WIKI-GRAPH-FIT-HIDDEN-1 r4: the orphan pull both layout workers (forceWorker.js 2D, forceWorker3d.js 3D) share. One definition, no copy.
+// WIKI-GRAPH-FIT-HIDDEN-1 r3: an unlinked node feels only the repulsion of the whole graph (legend-hidden areas included) and the
+// weak centre pull, so it settled in a ring outside everything and a fit of the visible docs shrank their linked core to a dot.
+// It is pulled to its centre this many times harder, so it settles inside the mass. Linked nodes keep the centre pull they had.
+export const ORPHAN_PULL = 12;
+/** Mark the nodes no link or containment spring touches (`free`), the ones the centre pulls ORPHAN_PULL times harder. */
+export function markFree(nodes, links) {
+  for (const nd of nodes) nd.free = true;
+  for (const l of links) { nodes[l.source.index ?? l.source].free = false; nodes[l.target.index ?? l.target].free = false; }
+}

package/src/graph/lib/perf.js

@@ -0,0 +1,14 @@
+// Timing marks for the graph page (WIKI-GRAPH-LOAD-1): `performance.measure` entries named `wiki-graph:<phase>`, read in the
+// console with `performance.getEntriesByType("measure")`. Nothing is sent anywhere. A runtime without the User Timing
+// API (old jsdom) records nothing.
+
+export const perfNow = () => globalThis.performance?.now?.() ?? Date.now();
+
+/** Record `name` as a measure from `start` (a perfNow() reading) to now. */
+export function perfSpan(name, start) {
+  try {
+    globalThis.performance?.measure?.(name, { start, end: perfNow() });
+  } catch {
+    // a runtime whose measure() takes no options object: no entry, no error
+  }
+}

package/src/graph/lib/reducedMotion.js

@@ -0,0 +1,36 @@
+// WIKI-GRAPH-3D-POLISH-1 round 2: the one source of truth for `prefers-reduced-motion: reduce`. Pure of React and three, so the
+// 3D canvas (and a later 2D fix, or the idle-turn option) reads the same answer. A missing `matchMedia` (jsdom, old browsers)
+// or a throwing one means motion stays ON: this never throws.
+
+export const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+
+function queryOf(win) {
+  try {
+    const w = win === undefined ? (typeof window === "undefined" ? undefined : window) : win;
+    return typeof w?.matchMedia === "function" ? w.matchMedia(REDUCED_MOTION_QUERY) || null : null;
+  } catch {
+    return null;
+  }
+}
+
+/** True when the user asked the system for reduced motion. False when it cannot be read. */
+export function prefersReducedMotion(win) {
+  return queryOf(win)?.matches === true;
+}
+
+/** Calls `cb(reduced)` whenever the setting changes (not once at the start). Returns the unsubscribe function, a no-op when
+ *  there is nothing to listen to. */
+export function watchReducedMotion(cb, win) {
+  const mql = queryOf(win);
+  if (!mql) return () => {};
+  const on = (e) => cb(e && typeof e.matches === "boolean" ? e.matches : mql.matches === true);
+  if (typeof mql.addEventListener === "function") {
+    mql.addEventListener("change", on);
+    return () => mql.removeEventListener?.("change", on);
+  }
+  if (typeof mql.addListener === "function") { // Safari before 14
+    mql.addListener(on);
+    return () => mql.removeListener?.(on);
+  }
+  return () => {};
+}

package/src/graph/lib/robustFit.js

@@ -0,0 +1,62 @@
+// WIKI-GRAPH-FIT-HIDDEN-1: an outlier-proof fit, the one helper per dimension every automatic framing path uses (2D fit(), focus,
+// drill, find aim and the fit-until-you-move re-fits; the same in 3D). A few far-out nodes no longer shrink the view to a tiny
+// cluster or pull its centre off the mass: per axis the 2nd-98th percentile of the node centres is taken (one sort per axis), widened
+// by a fence of FIT_FENCE x that span, and a node outside it on any axis is left out (at least one node per side is cut from
+// FIT_TRIM_MIN nodes up, so the fence alone decides whether that node is far enough out to drop). The raw fit (fitBox / fitSphere) then runs over
+// the nodes kept, so radii are added after trimming and a big folder that is kept is shown whole.
+import { fitSphere } from "./graph3d";
+import { fitBox } from "./wikiGraph";
+
+/** Under this many (finite) nodes nothing is trimmed: a small set is framed whole, so a 3-node fit still shows all 3. From 20 up
+ *  the percentile cut is at least one node per side (2% of n is under one node until n = 51), so one far-out neighbour in a focus
+ *  or drill set of 20-50 is still left out; under 20 the one-node cut would decide too much of the view. */
+export const FIT_TRIM_MIN = 20;
+/** The tail cut per side and axis: 2%, so up to 2% of the visible set on each side can sit anywhere without moving the view. */
+export const FIT_TRIM_Q = 0.02;
+/** The fence past the 2nd-98th percentile, as a share of that span. A clean cluster's outer 2% stays in (a force-layout disc reaches
+ *  about 1.05 x its p98, WIKI-GRAPH-FIT-HIDDEN-1 handoff-r1), and a clean 20-node set loses its edge node on a side only when that node
+ *  is a quarter of the span past the next one (about 0.75^19 = 0.4% per side and axis; at 0.1 it was 13%). The cost: a halo up to a
+ *  quarter span out still widens the view, at most 1.5 x for a round cluster. The owner's far-out nodes sit many spans out. */
+export const FIT_FENCE = 0.25;
+
+let lastWarn = "";
+
+/** The indices of `idx` to frame: non-finite positions (any of `stride` coords per node in `xs`) or sizes are skipped with one
+ *  console.warn naming the count (repeated only when the count changes, so the re-fits on every layout tick do not flood the
+ *  console); then, from FIT_TRIM_MIN nodes up, the nodes outside the fenced 2nd-98th percentile on any axis are left out. */
+export function robustIdx(xs, stride, idx, sizes = null, what = "fit") {
+  const ok = [];
+  let bad = 0;
+  for (const i of idx) {
+    let fine = !sizes || Number.isFinite(sizes[i]);
+    for (let a = 0; fine && a < stride; a++) fine = Number.isFinite(xs[stride * i + a]);
+    if (fine) ok.push(i); else bad++;
+  }
+  const msg = bad ? `${what}: skipped ${bad} node(s) with a non-finite position or size` : "";
+  if (msg && msg !== lastWarn) console.warn(msg);
+  lastWarn = msg;
+  const n = ok.length;
+  if (n < FIT_TRIM_MIN) return ok;
+  const lo = new Float64Array(stride), hi = new Float64Array(stride), v = new Float64Array(n);
+  const a0 = Math.max(1, Math.floor(FIT_TRIM_Q * (n - 1))), a1 = Math.min(n - 2, Math.ceil((1 - FIT_TRIM_Q) * (n - 1)));
+  for (let a = 0; a < stride; a++) {
+    for (let j = 0; j < n; j++) v[j] = xs[stride * ok[j] + a];
+    v.sort();
+    const f = (v[a1] - v[a0]) * FIT_FENCE;
+    lo[a] = v[a0] - f; hi[a] = v[a1] + f;
+  }
+  return ok.filter((i) => {
+    for (let a = 0; a < stride; a++) { const x = xs[stride * i + a]; if (x < lo[a] || x > hi[a]) return false; }
+    return true;
+  });
+}
+
+/** fitBox over the nodes robustIdx keeps: `pos` x, y per node index, `sizes` diameters per node index (or null). */
+export function robustBox(pos, idx, w, h, pad = 40, sizes = null) {
+  return fitBox(pos, robustIdx(pos, 2, idx, sizes, "robustBox"), w, h, pad, sizes);
+}
+
+/** fitSphere over the nodes robustIdx keeps: `xyz` x, y, z per node index, `radius` per node index (or null). Null when none is kept. */
+export function robustSphere(xyz, idx, radius = null) {
+  return fitSphere(xyz, robustIdx(xyz, 3, idx, radius, "robustSphere"), radius);
+}