@smartmemory/wiki-components 0.5.0 → 0.6.0

package/src/graph/components/wiki/graph/containment.js

@@ -0,0 +1,49 @@
+// WIKI-GRAPH-LEVELS-3D-1: the dashed lines from a hub folder to the nodes it contains (graphLevels `contains`). Drawn on the
+// 2D overlay canvas under the labels, for both surfaces, so a hub reads as the parent of what sits around it. They are not
+// links: no arrowheads, no weight, no hover lighting.
+import { graphTheme } from "../../../lib/graphTheme";
+export const CONTAIN_COLOUR = "#94a3b8";
+export const CONTAIN_ALPHA = 0.35;
+export const CONTAIN_DIM = 0.12; // while a node is lit the containment lines step back
+const DASH = [4, 4];
+
+/** Flat index pairs `[a0, b0, a1, b1, ...]` of the containment edges `[{source, target}]` (ids) over `index` (id -> node index);
+ *  an edge with an end that is not drawn is skipped. */
+export function containPairs(contains, index) {
+  const out = [];
+  for (const c of contains || []) {
+    const a = index.get(c.source), b = index.get(c.target);
+    if (a !== undefined && b !== undefined) out.push(a, b);
+  }
+  return Uint32Array.from(out);
+}
+
+/** The line alpha for a `dim` state: false (or absent) is undimmed, a number is a level clamped to [0, CONTAIN_DIM], anything else truthy is lit. */
+export function containAlpha(dim) {
+  if (typeof dim === "number") return Number.isFinite(dim) ? Math.min(CONTAIN_DIM, Math.max(0, dim)) : CONTAIN_DIM;
+  return dim ? CONTAIN_DIM : CONTAIN_ALPHA;
+}
+
+/** Draw the containment pairs `cp` on `ctx`: dashed, one path. `sx(i)` / `sy(i)`: screen position of node i; `ok(i)`: false for
+ *  a node that is hidden or behind the camera (its edges are skipped). `dim`: `false` = nothing is lit, so the full alpha; `true` = a node is lit, so fainter; a number is the
+ *  base's dim level (0 = fully dimmed, never brighter than the dimmed nodes), so zero stays zero, never the undimmed branch. */
+export function drawContainment(ctx, cp, sx, sy, ok, dim = false) {
+  if (!cp || !cp.length) return 0;
+  ctx.save();
+  ctx.globalAlpha = containAlpha(dim);
+  ctx.strokeStyle = graphTheme().contain;
+  ctx.lineWidth = 1;
+  ctx.setLineDash(DASH);
+  ctx.beginPath();
+  let n = 0;
+  for (let e = 0; e < cp.length; e += 2) {
+    const a = cp[e], b = cp[e + 1];
+    if (!ok(a) || !ok(b)) continue;
+    ctx.moveTo(sx(a), sy(a));
+    ctx.lineTo(sx(b), sy(b));
+    n++;
+  }
+  ctx.stroke();
+  ctx.restore();
+  return n;
+}

package/src/graph/components/wiki/graph/overlay.js

@@ -0,0 +1,134 @@
+// WIKI-GRAPH-OBSIDIAN-1: the 2D overlay above either base layer (pixiBase.js / canvasBase.js): the hover/focus highlight
+// (lit links, lit nodes with their rings) and the labels, nothing else. It is redrawn only when the view, the positions or
+// the lit set change, and a hover touches only this canvas, never the 50k nodes underneath. The dimming of everything
+// else is the base canvas's CSS opacity (GraphCanvas.jsx). Colours, font and label rules are today's (GraphCanvas before
+// this unit): labels #cbd5e1 outlined #0f172a at 12px, titles cut at 32 characters; which labels show is pickLabels'
+// (WIKI-GRAPH-DECLUTTER-1: a budget per view, hubs first, fade with zoom, never two overlapping).
+import { drawRadius, pickLabels } from "../../../lib/graphView";
+import { LABEL_CAP, labelBudget, lodFor } from "../../../lib/wikiGraph";
+import { pickDepthLabels } from "../../../lib/labelDepth";
+import { ARROW_CAP, fillHotArrows } from "../../../lib/graphArrows";
+import { graphTheme } from "../../../lib/graphTheme";
+
+export const HOT = "#2bb1ff";
+export const FOCUS_RING = "#ffffff";
+export const SELECT_RING = "#facc15"; // WIKI-GRAPH-3D-PORT-1: a selected doc's own ring (the port's `marks.selected`)
+export const LABEL = "#cbd5e1", LABEL_OUTLINE = "#0f172a";
+export const LABEL_FONT = "12px Inter, ui-sans-serif, system-ui, sans-serif";
+export const LABEL_MAX = 32;
+
+const hotTris = new Float32Array(6 * ARROW_CAP);
+const NO_ORDER = new Uint32Array(0);
+const hex = (c) => (typeof c === "number" ? `#${c.toString(16).padStart(6, "0")}` : c);
+/** A title as the label shows it: at most LABEL_MAX characters, the rest an ellipsis. */
+export const labelText = (title) => (title.length > LABEL_MAX ? title.slice(0, LABEL_MAX - 1) + "…" : title);
+
+/** Draw one overlay frame on `ctx` (a 2D context of a w x h CSS px canvas at `dpr`) for scene `sc` (the arrays both bases
+ *  read, plus `degree`, `order` = node indices best-linked first, and `visibleN` = how many nodes the legend shows).
+ *  `lit`: node indices to highlight (focus, hover and their neighbours); `litLinks`: index pairs (two entries per link)
+ *  touching the focus or the hover; `focus` / `hover`: an index or -1; `titles`: per index; `labelW`: per-index label
+ *  width cache (NaN = not measured yet), filled here. `heads`: hotHeads() of the focus and the hover, drawn in HOT at the
+ *  lit rings whatever the zoom (WIKI-GRAPH-DECLUTTER-1: the base never puts heads on a hub). Labels follow pickLabels (budget
+ *  per view, hubs, fade with zoom, no overlaps). `under(ctx, sx, sy)`: drawn right after the clear, below everything else
+ *  (WIKI-GRAPH-LEVELS-3D-1: the containment edges). `litOnly`: the base is dimmed (selection focus or a find term,
+ *  WIKI-GRAPH-FIND-FILTER-LIVE-1), so only the lit docs get labels, never the dimmed hubs. `selected`: node indices that get
+ *  their own SELECT_RING outside the dot (WIKI-GRAPH-3D-PORT-1 marks.selected; none by default). Returns the labels drawn
+ *  ([{i, x, y, a}], in draw order) so tests can read them. `sc.scr` (3 floats per node: x, y, depth), `sc.pivotDepth` and
+ *  `sc.farDepth` switch the labels to the depth rule (labelDepth.js, the 3D scene only). */
+export function drawOverlay(ctx, sc, { lit, litLinks, focus = -1, hover = -1, titles, labelW, dpr, w, h, heads = null, under, litOnly = false, selected = null }) {
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  ctx.clearRect(0, 0, w, h);
+  if (!sc || !sc.n) return [];
+  const { pos, view: v, mask, sizes, big, colors } = sc;
+  const sx = (i) => pos[2 * i] * v.k + v.x, sy = (i) => pos[2 * i + 1] * v.k + v.y;
+  const rPx = (i) => drawRadius(sizes[i], v.k, big) * v.k;
+  if (under) under(ctx, sx, sy);
+
+  if (litLinks && litLinks.length) {
+    ctx.strokeStyle = graphTheme().hot;
+    ctx.lineWidth = 1.5;
+    ctx.beginPath();
+    for (let e = 0; e < litLinks.length; e += 2) {
+      const a = litLinks[e], b = litLinks[e + 1];
+      if (!mask[a] || !mask[b]) continue;
+      ctx.moveTo(sx(a), sy(a));
+      ctx.lineTo(sx(b), sy(b));
+    }
+    ctx.stroke();
+  }
+
+  const ring = (i) => rPx(i) * (i === focus ? 1.8 : 1.2);
+  if (heads && heads.length) {
+    const t = fillHotArrows(heads, (i) => [sx(i), sy(i), ring(i)], mask, hotTris);
+    if (t) {
+      ctx.fillStyle = graphTheme().hot;
+      ctx.beginPath();
+      for (let o = 0; o < 6 * t; o += 6) {
+        ctx.moveTo(hotTris[o], hotTris[o + 1]);
+        ctx.lineTo(hotTris[o + 2], hotTris[o + 3]);
+        ctx.lineTo(hotTris[o + 4], hotTris[o + 5]);
+        ctx.closePath();
+      }
+      ctx.fill();
+    }
+  }
+
+  for (const i of lit) {
+    if (!mask[i]) continue;
+    const x = sx(i), y = sy(i);
+    if (x < -50 || x > w + 50 || y < -50 || y > h + 50) continue;
+    ctx.beginPath();
+    ctx.arc(x, y, ring(i), 0, 2 * Math.PI);
+    ctx.fillStyle = hex(colors[i]);
+    ctx.fill();
+    ctx.lineWidth = 2;
+    ctx.strokeStyle = i === focus ? graphTheme().focusRing : graphTheme().hot;
+    ctx.stroke();
+  }
+
+  if (selected && selected.length) {
+    ctx.lineWidth = 2;
+    ctx.strokeStyle = graphTheme().selectRing;
+    for (const i of selected) {
+      if (!mask[i]) continue;
+      const x = sx(i), y = sy(i);
+      if (x < -50 || x > w + 50 || y < -50 || y > h + 50) continue;
+      ctx.beginPath();
+      ctx.arc(x, y, ring(i) + 4, 0, 2 * Math.PI);
+      ctx.stroke();
+    }
+  }
+
+  ctx.font = LABEL_FONT;
+  ctx.textAlign = "center";
+  ctx.lineJoin = "round";
+  const width = (i) => {
+    if (!(labelW[i] >= 0)) labelW[i] = ctx.measureText(labelText(titles[i])).width;
+    return labelW[i];
+  };
+  const deg = sc.degree;
+  const lod = lodFor(sc.visibleN ?? sc.n, v.k);
+  const at = (i) => [sx(i), sy(i), rPx(i)];
+  // WIKI-GRAPH-3D-POLISH-1 round 4: a scene with a projection (`sc.scr`, the 3D one) picks labels with depth (labelDepth.js); the
+  // 2D scene has none and keeps pickLabels exactly.
+  const labels = sc.scr
+    ? pickDepthLabels({
+      scr: sc.scr, mask, always: selected && selected.length ? [...lit, ...selected] : lit, order: litOnly ? NO_ORDER : sc.order, pivot: sc.pivotDepth, far: sc.farDepth,
+      focus, hover, mode: lod.labels, cap: LABEL_CAP, budget: labelBudget(w, h), at, width, w, h, degree: deg, k: v.k, labelK: lod.labelK,
+    })
+    : pickLabels({
+      lead: [...lit].sort((a, b) => (b === focus) - (a === focus) || (b === hover) - (a === hover) || deg[b] - deg[a]), order: litOnly ? NO_ORDER : sc.order, mode: lod.labels,
+      cap: LABEL_CAP, budget: labelBudget(w, h), mask, w, h, width, degree: deg, k: v.k, labelK: lod.labelK, at,
+    });
+  ctx.lineWidth = 3;
+  ctx.strokeStyle = graphTheme().labelOutline;
+  ctx.fillStyle = graphTheme().label;
+  for (const { i, x, y, a } of labels) {
+    const t = labelText(titles[i]);
+    if (a < 1) ctx.globalAlpha = a;
+    ctx.strokeText(t, x, y);
+    ctx.fillText(t, x, y);
+    if (a < 1) ctx.globalAlpha = 1;
+  }
+  return labels;
+}

package/src/graph/components/wiki/graph/pixiBase.js

@@ -0,0 +1,210 @@
+// WIKI-GRAPH-OBSIDIAN-1: the graph's base layer on the GPU (Pixi v8 WebGL): every edge and every node, nothing else.
+// Labels and the hover/focus highlight are drawn on the 2D overlay above it (overlay.js), so a hover never restyles
+// 50k sprites. Nodes: one ParticleContainer of white-circle particles (tint = colour, scale = size), all properties
+// static, re-uploaded only after a position frame, a zoom or a restyle, so a pan is only a transform. Edges: one Mesh with
+// our own line-list shader; its vertex buffer IS the node positions array and its index buffer the drawn links as node
+// index pairs, so a position frame is one buffer upload and a legend toggle one index upload.
+// Pixi's own ticker and event system are not used: GraphCanvas runs one requestAnimationFrame loop for both layers.
+import { Container, Geometry, GlProgram, Mesh, Particle, ParticleContainer, Shader, Texture, autoDetectRenderer } from "pixi.js";
+import { ARROW_CAP, arrowsFor, fillArrows } from "../../../lib/graphArrows";
+import { CORE, HALO, LOOK, SHELL_ALPHA, drawRadius } from "../../../lib/graphView";
+import { edgeAlphaFor, linksInView } from "../../../lib/wikiGraph";
+import { fillThickLinks, linkBuckets, thickBuffers, thickCount } from "../../../lib/linkWeight";
+import { graphTheme } from "../../../lib/graphTheme";
+
+// GLSL ES 1.00 (runs on WebGL 1 and 2). Pixi binds the matrices by name: uProjectionMatrix and uWorldTransformMatrix from
+// the global uniform group (100), uTransformMatrix and uColor (the mesh's tint x alpha, premultiplied) from the mesh's
+// local group (101): pixi.js lib/scene/mesh/gl/GlMeshAdaptor.mjs execute(), lib/scene/mesh/shared/MeshPipe.mjs.
+const VERTEX = `attribute vec2 aPosition;
+uniform mat3 uProjectionMatrix;
+uniform mat3 uWorldTransformMatrix;
+uniform mat3 uTransformMatrix;
+void main() {
+  mat3 m = uProjectionMatrix * uWorldTransformMatrix * uTransformMatrix;
+  gl_Position = vec4((m * vec3(aPosition, 1.0)).xy, 0.0, 1.0);
+}`;
+const FRAGMENT = `uniform vec4 uColor;
+void main() { gl_FragColor = uColor; }`;
+
+const TEX = 64; // the circle texture's size; a particle at scale 1 is TEX world units wide
+const ARROW_ALPHA = 0.75;
+const THICK_START = 4096; // quads the links wider than a hairline (linkWeight.js buckets 2..) start with; the buffers grow to draw them all (thickBuffers)
+
+function circleTexture() {
+  const c = document.createElement("canvas");
+  c.width = c.height = TEX;
+  const g = c.getContext("2d");
+  g.fillStyle = "#ffffff";
+  g.beginPath();
+  g.arc(TEX / 2, TEX / 2, TEX / 2 - 1, 0, 2 * Math.PI);
+  g.fill();
+  return Texture.from(c);
+}
+
+/** A WebGL base on `canvas`. Rejects when Pixi cannot make a WebGL renderer (the caller falls back to Canvas2D). */
+export async function createPixiBase(canvas, { w, h, dpr, background }) {
+  const EDGE = graphTheme().edgeHex; // by the mode the base is built in (the canvas is keyed by it)
+  const renderer = await autoDetectRenderer({
+    preference: ["webgl"], canvas, width: w, height: h, resolution: dpr, autoDensity: true, antialias: true, background,
+    hello: false, eventFeatures: { move: false, globalMove: false, click: false, wheel: false },
+  });
+  const stage = new Container();
+  stage.eventMode = "none";
+  stage.interactiveChildren = false;
+  const world = new Container();
+  stage.addChild(world);
+  const texture = circleTexture();
+  const shader = new Shader({ glProgram: GlProgram.from({ vertex: VERTEX, fragment: FRAGMENT, name: "wiki-graph-edges" }) });
+  let particles = null, mesh = null, all = [], lastK = 0;
+  // Looks (graphView LOOK, the same as 3D): a folder is a translucent full-size shell particle under a solid CORE particle, a hub
+  // has a white particle HALO x its size under it. `rims` are those extra particles ({p, i, f}: node i, size factor f), drawn first.
+  let rims = [];
+  // Arrowheads: one more Mesh (triangle list, same shader) whose vertex buffer holds the heads of the links in view, in world
+  // units. Rebuilt on a position frame, a zoom, a legend change, or a pan past `ARROW_MARGIN` px (heads are culled to the view
+  // grown by that much), never on a small pan, so a pan stays a transform.
+  const ARROW_MARGIN = 200;
+  const tris = new Float32Array(6 * ARROW_CAP), triIndex = Uint32Array.from({ length: 3 * ARROW_CAP }, (_, i) => i);
+  let alphaAt = null, alphaStale = true; // edge alpha from the links in view, redone on stale or a real move
+  // Links wider than a hairline (WIKI-GRAPH-LEVEL-WEIGHTS-FU-1): a line-list mesh is always 1 px, so bucket 1 stays in `mesh` and
+  // buckets 2.. are one triangle-list mesh of quads, `bucket` screen px wide in world units, rebuilt with the arrows.
+  let tb = thickBuffers(null, THICK_START);
+  let thick = null, thickStale = true, thickK = 0;
+  let arrows = null, arrowAt = null, arrowStale = true, last = null, box = { w, h };
+
+  const rescale = (sc) => {
+    const { sizes, view, big, n } = sc;
+    for (let i = 0; i < n; i++) { const p = all[i]; p.scaleX = p.scaleY = (2 * drawRadius(sizes[i], view.k, big) * (sc.looks?.[i] === LOOK.FOLDER ? CORE : 1)) / TEX; }
+    for (const { p, i, f } of rims) p.scaleX = p.scaleY = (2 * drawRadius(sizes[i], view.k, big) * f) / TEX;
+    lastK = view.k;
+    particles.update();
+  };
+  const restyle = (sc) => {
+    for (let i = 0; i < sc.n; i++) all[i].tint = sc.colors[i];
+    for (const { p, i, f } of rims) p.tint = f === HALO ? graphTheme().haloHex : sc.colors[i];
+    rescale(sc);
+  };
+  const revisible = (sc) => {
+    const kids = [];
+    for (const r of rims) if (sc.mask[r.i]) kids.push(r.p);
+    for (let i = 0; i < sc.n; i++) if (sc.mask[i]) kids.push(all[i]);
+    particles.particleChildren = kids;
+    particles.update();
+    const bk = sc.visBuckets || linkBuckets(null, sc.visCount), thin = new Uint32Array(2 * (bk.start[2] - bk.start[1]));
+    for (let j = bk.start[1]; j < bk.start[2]; j++) { const e = 2 * bk.idx[j], o = 2 * (j - bk.start[1]); thin[o] = sc.visPairs[e]; thin[o + 1] = sc.visPairs[e + 1]; }
+    mesh.geometry.indexBuffer.data = thin.length ? thin : new Uint32Array(2);
+    mesh.visible = thin.length > 0;
+    arrowStale = true; alphaStale = true; thickStale = true;
+  };
+
+  const rethick = (sc) => {
+    if (!thickStale && thickK === sc.view.k) return; // positions, the legend or the zoom changed: the quads' world width is px / k
+    thickStale = false; thickK = sc.view.k;
+    const bk = sc.visBuckets;
+    const need = bk ? thickCount(bk) : 0;
+    if (need > tb.cap) { tb = thickBuffers(tb, need); thick.geometry.getBuffer("aPosition").data = tb.quads; } // never drop the overflow: grow
+    const q = need > 0 ? fillThickLinks(sc.pos, sc.visPairs, bk, sc.view.k, tb.quads, tb.cap) : 0;
+    thick.visible = q > 0;
+    if (!q) return;
+    thick.geometry.indexBuffer.data = tb.index.subarray(0, 6 * q);
+    thick.geometry.getBuffer("aPosition").update();
+  };
+
+  const rearrow = (sc) => {
+    const v = sc.view, on = arrowsFor(sc.visibleN ?? sc.n, v.k, sc.big);
+    if (mesh && (alphaStale || !alphaAt || alphaAt.k !== v.k || Math.abs(alphaAt.x - v.x) > ARROW_MARGIN / 2 || Math.abs(alphaAt.y - v.y) > ARROW_MARGIN / 2)) {
+      alphaStale = false;
+      alphaAt = { x: v.x, y: v.y, k: v.k };
+      mesh.alpha = thick.alpha = edgeAlphaFor(linksInView(sc.pos, sc.visPairs, sc.visCount, v, box.w, box.h), box.w, box.h);
+    }
+    rethick(sc);
+    if (!on) { arrows.visible = false; arrowAt = null; return; }
+    const moved = !arrowAt || arrowAt.k !== v.k || Math.abs(arrowAt.x - v.x) > ARROW_MARGIN / 2 || Math.abs(arrowAt.y - v.y) > ARROW_MARGIN / 2;
+    if (!arrowStale && !moved) return;
+    arrowStale = false;
+    arrowAt = { x: v.x, y: v.y, k: v.k };
+    const t = fillArrows(sc, v, box.w, box.h, tris, ARROW_MARGIN);
+    arrows.visible = t > 0;
+    if (!t) return;
+    arrows.geometry.indexBuffer.data = triIndex.subarray(0, 3 * t);
+    arrows.geometry.getBuffer("aPosition").update();
+  };
+
+  return {
+    kind: "webgl",
+    renderer,
+    /** A new node set: rebuild the particles and the edge mesh. */
+    setData(sc) {
+      if (particles) { world.removeChild(particles); particles.destroy({ children: false }); }
+      if (mesh) { world.removeChild(mesh); mesh.geometry.destroy(); mesh.destroy({ children: false }); }
+      if (arrows) { world.removeChild(arrows); arrows.geometry.destroy(); arrows.destroy({ children: false }); }
+      all = new Array(sc.n);
+      for (let i = 0; i < sc.n; i++) all[i] = new Particle({ texture, x: sc.pos[2 * i], y: sc.pos[2 * i + 1], anchorX: 0.5, anchorY: 0.5 });
+      rims = [];
+      for (let i = 0; i < sc.n; i++) {
+        const look = sc.looks?.[i];
+        if (look !== LOOK.FOLDER && look !== LOOK.HUB) continue;
+        const alpha = look === LOOK.FOLDER ? SHELL_ALPHA : 1;
+        rims.push({ p: new Particle({ texture, x: sc.pos[2 * i], y: sc.pos[2 * i + 1], anchorX: 0.5, anchorY: 0.5, alpha }), i, f: look === LOOK.FOLDER ? 1 : HALO });
+      }
+      particles = new ParticleContainer({ texture, dynamicProperties: { position: false, vertex: false, rotation: false, uvs: false, color: false } });
+      const geometry = new Geometry({
+        attributes: { aPosition: { buffer: sc.pos, format: "float32x2" } },
+        indexBuffer: sc.visCount ? sc.visPairs.subarray(0, 2 * sc.visCount) : new Uint32Array(2),
+        topology: "line-list",
+      });
+      mesh = new Mesh({ geometry, shader });
+      mesh.tint = EDGE;
+      alphaStale = true;
+      if (thick) { world.removeChild(thick); thick.geometry.destroy(); thick.destroy({ children: false }); }
+      thick = new Mesh({
+        geometry: new Geometry({ attributes: { aPosition: { buffer: tb.quads, format: "float32x2" } }, indexBuffer: tb.index.subarray(0, 3), topology: "triangle-list" }),
+        shader,
+      });
+      thick.tint = EDGE;
+      thick.visible = false;
+      arrows = new Mesh({
+        geometry: new Geometry({ attributes: { aPosition: { buffer: tris, format: "float32x2" } }, indexBuffer: triIndex.subarray(0, 3), topology: "triangle-list" }),
+        shader,
+      });
+      arrows.tint = EDGE;
+      arrows.alpha = ARROW_ALPHA;
+      arrows.visible = false;
+      arrowStale = true;
+      world.addChild(mesh, thick, arrows, particles);
+      restyle(sc);
+      revisible(sc);
+    },
+    setStyle: restyle,
+    setVisible: revisible,
+    /** A position frame: `sc.pos` was rewritten in place. */
+    setPositions(sc) {
+      for (let i = 0; i < sc.n; i++) { const p = all[i]; p.x = sc.pos[2 * i]; p.y = sc.pos[2 * i + 1]; }
+      for (const { p, i } of rims) { p.x = sc.pos[2 * i]; p.y = sc.pos[2 * i + 1]; }
+      particles.update();
+      mesh.geometry.getBuffer("aPosition").update();
+      arrowStale = true; alphaStale = true; thickStale = true;
+    },
+    setView(sc) {
+      last = sc;
+      world.position.set(sc.view.x, sc.view.y);
+      world.scale.set(sc.view.k);
+      if (particles && sc.view.k !== lastK) rescale(sc); // keeps the minimum screen size of a node on zoom-out
+    },
+    resize(w2, h2, dpr2) { box = { w: w2, h: h2 }; arrowStale = true; alphaStale = true; thickStale = true; renderer.resize(w2, h2, dpr2); },
+    render() {
+      if (arrows && last) rearrow(last);
+      renderer.render(stage);
+      return true;
+    },
+    destroy() {
+      particles?.destroy({ children: false });
+      mesh?.geometry.destroy();
+      arrows?.geometry.destroy();
+      thick?.geometry.destroy();
+      stage.destroy({ children: true });
+      shader.destroy();
+      texture.destroy(true);
+      renderer.destroy({ removeView: false });
+    },
+  };
+}

package/src/graph/components/wiki/graph/threeBase.js

@@ -0,0 +1,231 @@
+// WIKI-GRAPH-3D-1: the 3D graph's base layer, the three.js analogue of pixiBase.js: every node, every edge and the
+// arrowheads, nothing else. Labels and the hover/focus highlight stay on the 2D overlay (overlay.js), fed the camera
+// projection by GraphCanvas3D.jsx, so a hover never touches the 50k instances. Nodes: one InstancedMesh of icosahedra (80
+// triangles at most: smooth normals, and the detail steps down with the node count, `sphereDetail`) with per-instance colour; a
+// hidden doc is a zero-scale instance, so the count never changes. A folder is a solid core (0.4 x radius) in a translucent
+// shell (its own InstancedMesh, folders only), a hub gets a white back-face halo (its own InstancedMesh, hubs only). Edges: one LineSegments whose position buffer is rewritten on a position frame; a legend toggle only moves the draw
+// range. Arrowheads: one InstancedMesh of cones, refilled per drawn frame from the projection (fillArrows3d), capped at
+// ARROW_CAP. three's own render loop is not used: GraphCanvas3D runs one requestAnimationFrame loop and renders when dirty.
+// destroy() disposes every geometry and material and forces the context loss, so toggling 2D/3D never leaks a context.
+import {
+  AmbientLight, Color, ConeGeometry, DirectionalLight, DynamicDrawUsage, IcosahedronGeometry, InstancedMesh, LineBasicMaterial,
+  LineSegments, BufferAttribute, BufferGeometry, BackSide, MOUSE, Matrix4, MeshBasicMaterial, MeshLambertMaterial, Object3D, PerspectiveCamera,
+  Scene, TOUCH, WebGLRenderer,
+} from "three";
+import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+import { LineMaterial } from "three/addons/lines/LineMaterial.js";
+import { LineSegments2 } from "three/addons/lines/LineSegments2.js";
+import { LineSegmentsGeometry } from "three/addons/lines/LineSegmentsGeometry.js";
+import { LINK_BUCKETS, linkBuckets } from "../../../lib/linkWeight";
+import { ARROW_CAP, arrowsFor } from "../../../lib/graphArrows";
+import { edgeAlphaFor, linksInView } from "../../../lib/wikiGraph";
+import { FOV, SHELL_DETAIL, fillArrows3d, sphereDetail, writeInstances, writeLinkPositionsBy, writeSubset } from "../../../lib/graph3d";
+import { HALO, LOOK, SHELL_ALPHA } from "../../../lib/graphView";
+import { graphTheme } from "../../../lib/graphTheme";
+
+const ARROW_ALPHA = 0.75; // pixiBase ARROW_ALPHA
+const ARROW_MARGIN = 200; // heads are culled to the view grown by this many px (pixiBase)
+const NEAR = 0.5, FAR = 1e6;
+const ID_VIEW = { k: 1, x: 0, y: 0 }; // the projection is already in screen px
+
+/** A WebGL2 base on `canvas`. Throws when three cannot make a WebGL renderer (the caller tells the page to drop to 2D). */
+export function createThreeBase(canvas, { w, h, dpr, background }) {
+  const EDGE = graphTheme().edgeHex; // by the mode the base is built in (the canvas is keyed by it)
+  const renderer = new WebGLRenderer({ canvas, antialias: true, powerPreference: "high-performance" });
+  renderer.setPixelRatio(Math.min(dpr || 1, 2));
+  renderer.setSize(w, h);
+  renderer.setClearColor(new Color(background), 1);
+  const scene = new Scene();
+  const camera = new PerspectiveCamera(FOV, w / Math.max(1, h), NEAR, FAR);
+  camera.position.set(0, 0, 400);
+  // Lights ride on the camera (spike values), so the side facing you is always lit, whichever way you orbit.
+  scene.add(new AmbientLight(0xffffff, 1.4));
+  const sun = new DirectionalLight(0xffffff, 1.6), aim = new Object3D();
+  sun.position.set(0.5, 1, 0);
+  aim.position.set(0, 0, -1);
+  sun.target = aim;
+  camera.add(sun, aim);
+  scene.add(camera);
+
+  const nodeMat = new MeshLambertMaterial({ color: 0xffffff });
+  const shellMat = new MeshLambertMaterial({ color: 0xffffff, transparent: true, opacity: SHELL_ALPHA, depthWrite: false });
+  const haloMat = new MeshBasicMaterial({ color: graphTheme().haloHex, side: BackSide });
+  const lineMat = new LineBasicMaterial({ color: EDGE, transparent: true, opacity: 0.22, depthWrite: false });
+  const arrowMat = new MeshBasicMaterial({ color: EDGE, transparent: true, opacity: ARROW_ALPHA, depthWrite: false });
+  const cone = new ConeGeometry(1, 1, 6).translate(0, -0.5, 0); // apex at the origin, base at y = -1 (graph3d arrowMatrix)
+  const arrows = new InstancedMesh(cone, arrowMat, ARROW_CAP);
+  arrows.instanceMatrix.setUsage(DynamicDrawUsage);
+  arrows.count = 0;
+  arrows.frustumCulled = false;
+  scene.add(arrows);
+
+  // Links wider than a hairline (WIKI-GRAPH-LEVEL-WEIGHTS-FU-1): WebGL lines are 1 px, so bucket 1 stays in `lines` and each wider
+  // bucket (linkWeight.js) is a LineSegments2 whose LineMaterial draws `bucket` screen px, refilled with the link positions.
+  const thickMats = [];
+  for (let b = 2; b <= LINK_BUCKETS; b++) thickMats[b] = new LineMaterial({ color: EDGE, linewidth: b, transparent: true, opacity: 0.22, depthWrite: false });
+  const thick = [];
+  const edgeOpacity = (o) => { lineMat.opacity = o; for (const m of thickMats) if (m) m.opacity = o; };
+  let shells = null, shellGeo = null, shellIdx = [], halos = null, haloGeo = null, haloIdx = [];
+  let nodes = null, nodeGeo = null, detail = -1, lines = null, linePos = null, controls = null;
+  const tint = new Color(), vp = new Matrix4(), eye = [0, 0, 0];
+  let box = { w, h };
+
+  const restyle = (sc) => {
+    for (let i = 0; i < sc.n; i++) nodes.setColorAt(i, tint.setHex(sc.colors[i]));
+    if (nodes.instanceColor) nodes.instanceColor.needsUpdate = true;
+    if (shells) {
+      shellIdx.forEach((i, j) => shells.setColorAt(j, tint.setHex(sc.colors[i])));
+      shells.instanceColor.needsUpdate = true;
+    }
+    reinstance(sc);
+  };
+  const reinstance = (sc) => {
+    writeInstances(nodes.instanceMatrix.array, sc.xyz, sc.radius, sc.mask, sc.n, sc.looks);
+    nodes.instanceMatrix.needsUpdate = true;
+    if (shells) { writeSubset(shells.instanceMatrix.array, sc.xyz, sc.radius, sc.mask, shellIdx, 1); shells.instanceMatrix.needsUpdate = true; }
+    if (halos) { writeSubset(halos.instanceMatrix.array, sc.xyz, sc.radius, sc.mask, haloIdx, HALO); halos.instanceMatrix.needsUpdate = true; }
+  };
+  /** An InstancedMesh of `count` unit spheres of `geo` that moves every frame (never frustum-culled). */
+  const sphereMesh = (geo, mat, count) => {
+    const m = new InstancedMesh(geo, mat, Math.max(1, count));
+    m.count = count;
+    m.instanceMatrix.setUsage(DynamicDrawUsage);
+    m.frustumCulled = false;
+    scene.add(m);
+    return m;
+  };
+  const relink = (sc) => {
+    const bk = sc.visBuckets || linkBuckets(null, sc.visCount), n1 = bk.start[2] - bk.start[1];
+    writeLinkPositionsBy(linePos, sc.xyz, sc.visPairs, bk.idx, bk.start[1], bk.start[2]);
+    lines.geometry.attributes.position.needsUpdate = true;
+    lines.geometry.setDrawRange(0, 2 * n1);
+    lines.visible = n1 > 0;
+    for (let b = 2; b <= LINK_BUCKETS; b++) {
+      const cnt = bk.start[b + 1] - bk.start[b], seg = thick[b];
+      seg.visible = cnt > 0;
+      if (cnt) seg.geometry.setPositions(writeLinkPositionsBy(new Float32Array(6 * cnt), sc.xyz, sc.visPairs, bk.idx, bk.start[b], bk.start[b + 1]));
+    }
+  };
+
+  return {
+    kind: "three",
+    renderer,
+    camera,
+    scene, // WIKI-GRAPH-CLUSTER-NORELAYOUT-1: the group bubbles (bubbles3d.js) add their own meshes
+    /** OrbitControls on `el` (the overlay canvas, which takes the pointer), damped, zooming to the cursor. WIKI-GRAPH-3D-PORT-1
+     *  (3D-UX-1 D1): plain drag turns, middle-drag pans (GraphCanvas3D makes a Cmd or Option/Alt drag pan too, lib/graphPress.js), the right
+     *  button does nothing here (it stays the node menu: on mac `contextmenu` fires on press, so a right-drag pan would open
+     *  menus); one finger turns, two fingers zoom and pan. OrbitControls' own `contextmenu` listener is removed: it
+     *  preventDefaults every right click, which would stop the page's Radix node menu from opening (GraphCanvas3D listens itself). */
+    controls(el) {
+      controls?.dispose();
+      controls = new OrbitControls(camera, el);
+      controls.enableDamping = true;
+      controls.dampingFactor = 0.12;
+      controls.zoomToCursor = true;
+      controls.minDistance = 1;
+      controls.maxDistance = FAR / 4;
+      controls.mouseButtons = { LEFT: MOUSE.ROTATE, MIDDLE: MOUSE.PAN, RIGHT: -1 };
+      controls.touches = { ONE: TOUCH.ROTATE, TWO: TOUCH.DOLLY_PAN };
+      if (typeof controls._onContextMenu === "function") el.removeEventListener("contextmenu", controls._onContextMenu);
+      else console.warn("wiki graph: OrbitControls has no _onContextMenu (three changed): right clicks stay preventDefaulted, a page node menu will not open");
+      return controls;
+    },
+    /** A new node set: rebuild the node instances and the edge buffer. */
+    setData(sc) {
+      const want = sphereDetail(sc.n);
+      if (nodes) { scene.remove(nodes); nodes.dispose(); }
+      if (want !== detail) { nodeGeo?.dispose(); nodeGeo = new IcosahedronGeometry(1, want); detail = want; }
+      for (const m of [shells, halos]) if (m) { scene.remove(m); m.dispose(); }
+      shellGeo?.dispose(); haloGeo?.dispose();
+      shells = halos = shellGeo = haloGeo = null;
+      shellIdx = []; haloIdx = [];
+      for (let i = 0; i < sc.n; i++) {
+        if (sc.looks?.[i] === LOOK.FOLDER) shellIdx.push(i);
+        else if (sc.looks?.[i] === LOOK.HUB) haloIdx.push(i);
+      }
+      if (shellIdx.length) { shellGeo = new IcosahedronGeometry(1, shellIdx.length > 300 ? 4 : SHELL_DETAIL); shells = sphereMesh(shellGeo, shellMat, shellIdx.length); }
+      if (haloIdx.length) { haloGeo = new IcosahedronGeometry(1, Math.min(want, 4)); halos = sphereMesh(haloGeo, haloMat, haloIdx.length); }
+      nodes = new InstancedMesh(nodeGeo, nodeMat, Math.max(1, sc.n));
+      nodes.count = sc.n;
+      nodes.instanceMatrix.setUsage(DynamicDrawUsage);
+      nodes.frustumCulled = false; // positions move every frame; the bounding sphere three would cache goes stale
+      scene.add(nodes);
+      if (lines) { scene.remove(lines); lines.geometry.dispose(); }
+      linePos = new Float32Array(Math.max(6, 3 * sc.visPairs.length));
+      const g = new BufferGeometry();
+      g.setAttribute("position", new BufferAttribute(linePos, 3).setUsage(DynamicDrawUsage));
+      lines = new LineSegments(g, lineMat);
+      lines.frustumCulled = false;
+      for (let b = 2; b <= LINK_BUCKETS; b++) {
+        if (thick[b]) { scene.remove(thick[b]); thick[b].geometry.dispose(); }
+        thick[b] = new LineSegments2(new LineSegmentsGeometry(), thickMats[b]);
+        thick[b].frustumCulled = false;
+        thick[b].visible = false;
+        scene.add(thick[b]);
+      }
+      edgeOpacity(sc.edgeAlpha);
+      scene.add(lines);
+      arrows.count = 0;
+      restyle(sc);
+      relink(sc);
+    },
+    /** Colours or radii changed. */
+    setStyle: restyle,
+    /** The legend mask changed: hidden instances go to scale 0, the drawn links shrink to the visible ones. */
+    setVisible(sc) { reinstance(sc); relink(sc); },
+    /** A position frame: `sc.xyz` was rewritten in place. */
+    setPositions(sc) { reinstance(sc); relink(sc); },
+    /** The camera for this frame: `vp` (projection x view, column-major), the eye position and `focal` (px per world unit at
+     *  distance 1), the inputs of graph3d project() and fillArrows3d. */
+    frame() {
+      camera.updateMatrixWorld();
+      vp.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
+      eye[0] = camera.position.x; eye[1] = camera.position.y; eye[2] = camera.position.z;
+      return { vp: vp.elements, eye, focal: (camera.projectionMatrix.elements[5] * box.h) / 2 };
+    },
+    resize(w2, h2, dpr2) {
+      box = { w: w2, h: h2 };
+      for (const m of thickMats) m?.resolution.set(w2, h2);
+      renderer.setPixelRatio(Math.min(dpr2 || 1, 2));
+      renderer.setSize(w2, h2);
+      camera.aspect = w2 / Math.max(1, h2);
+      camera.updateProjectionMatrix();
+    },
+    /** Draw one frame. `view`: {scr, focal, eye, k} from this frame's projection; arrowheads are refilled when arrowsFor
+     *  allows them at the effective zoom `k`. */
+    render(sc, view) {
+      // edge opacity follows the links DRAWN in view (the projection, stride 3), never the node count (WIKI-GRAPH-DECLUTTER-1)
+      if (sc && view?.scr) edgeOpacity(edgeAlphaFor(linksInView(view.scr, sc.visPairs, sc.visCount, ID_VIEW, box.w, box.h, 3), box.w, box.h));
+      if (nodes && sc && view && arrowsFor(sc.visibleN ?? sc.n, view.k, sc.big)) {
+        arrows.count = fillArrows3d(sc, view.scr, view.focal, box.w, box.h, view.eye, arrows.instanceMatrix.array, ARROW_MARGIN);
+        arrows.instanceMatrix.needsUpdate = arrows.count > 0;
+      } else {
+        arrows.count = 0;
+      }
+      renderer.render(scene, camera);
+      return true;
+    },
+    destroy() {
+      controls?.dispose();
+      nodes?.dispose();
+      shells?.dispose();
+      halos?.dispose();
+      shellGeo?.dispose();
+      haloGeo?.dispose();
+      shellMat.dispose();
+      haloMat.dispose();
+      nodeGeo?.dispose();
+      lines?.geometry.dispose();
+      arrows.dispose();
+      cone.dispose();
+      nodeMat.dispose();
+      for (const seg of thick) seg?.geometry.dispose();
+      for (const m of thickMats) m?.dispose();
+      lineMat.dispose();
+      arrowMat.dispose();
+      renderer.dispose();
+      renderer.forceContextLoss();
+    },
+  };
+}

package/src/graph/hooks/useDebounced.js

@@ -0,0 +1,11 @@
+import { useEffect, useState } from "react";
+
+/** `value`, settled for `ms`: it follows `value` once `value` has stopped changing for `ms` milliseconds. */
+export default function useDebounced(value, ms) {
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setSettled(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return settled;
+}