@smartmemory/wiki-components 0.4.0 → 0.6.0

package/src/graph/lib/graph3d.js

@@ -0,0 +1,330 @@
+// WIKI-GRAPH-3D-1: the 3D graph view's pure helpers (no three.js, no DOM, no React), shared by GraphCanvas3D.jsx, its
+// three.js base (components/wiki/graph/threeBase.js), the Graph page and the tests: which surface draws, 3D seeds, node
+// radii, bounding sphere and camera distance, the screen projection that picking, labels and arrowheads all read, the
+// instance matrices, the link segments and the arrowhead cones.
+//
+// Matrices are three.js layout (column-major Float32Array(16)): `vp` = projection x view. A projected node is
+// [sx, sy, cw] in CSS px plus `cw`, its clip w (the distance in front of the camera); cw <= 0 is behind the camera.
+import { CORE, LOOK, folderRadius, levelSize } from "./graphView";
+import { containPairs } from "../components/wiki/graph/containment";
+import { springPairs } from "./hubLines";
+import { serverFits } from "./wikiGraph";
+import { ARROW, ARROW_CAP, MUTUAL, TO_SOURCE, TO_TARGET, headOn, hotHeads } from "./graphArrows";
+
+export const FOV = 50; // vertical field of view, degrees
+export const PICK_MIN_PX = 6; // the 2D quadtree's tolerance: a pick lands within max(6 px, the drawn radius)
+// Sphere smoothness by node count (WIKI-GRAPH-3D-COLOR-SPHERES-1): three's IcosahedronGeometry(1, d) has 20*(d+1)^2 triangles with
+// smooth normals, so the "polygon" look is only the silhouette. One row per size class; the thresholds are set by the frame
+// harness (report), the folder shell is always SHELL_DETAIL (few of them, drawn big).
+export const SPHERE_ROWS = [[2000, 6], [8000, 3], [20000, 2]]; // [up to this many nodes, detail]; above the last row: SPHERE_FLOOR
+export const SPHERE_FLOOR = 1;
+export const SHELL_DETAIL = 8;
+export const sphereDetail = (n) => (SPHERE_ROWS.find(([max]) => n <= max) || [0, SPHERE_FLOOR])[1];
+export const OFF = -1e6; // where a node behind the camera "projects": off every screen, so labels and rings skip it
+const GOLDEN = Math.PI * (3 - Math.sqrt(5));
+
+/** Which surface draws the graph: "3d" by default when the browser has WebGL2, "2d" for `?view=2d`, for the Canvas2D
+ *  override (`?renderer=canvas`) and without WebGL2. */
+export function chooseView({ param = null, webgl2 = false, forced = null }) {
+  if (param === "2d" || forced === "canvas") return "2d";
+  return webgl2 ? "3d" : "2d";
+}
+
+/** Point `i` of `n` spread evenly over the unit sphere (Fibonacci lattice). */
+export function fibonacciSphere(i, n) {
+  const y = n <= 1 ? 0 : 1 - (2 * (i + 0.5)) / n, r = Math.sqrt(Math.max(0, 1 - y * y)), a = i * GOLDEN;
+  return [Math.cos(a) * r, y, Math.sin(a) * r];
+}
+
+// Deterministic per-index uniform in [0, 1) (the same hash as seedPositions' 2D disc), so a reload lays out the same way.
+const rnd = (i) => {
+  let h = Math.imul(i + 1, 0x9e3779b1) ^ 0x85ebca6b;
+  h = Math.imul(h ^ (h >>> 15), 0x2c1b3c6d);
+  h = Math.imul(h ^ (h >>> 12), 0x297a2d39);
+  return ((h ^ (h >>> 15)) >>> 0) / 4294967296;
+};
+
+/** The radius of the seed ball (and of the ring of group centres) for `n` docs. */
+export const seedRadius = (n) => Math.max(80, 14 * Math.cbrt(n));
+
+/** Starting positions for `nodes` in 3D, without touching the nodes: {xyz, targets, warm}. A node with a cached position
+ *  (`cache`: id -> [x, y, z], this surface's earlier layout) starts there. A level-view child whose `parent` folder is
+ *  cached starts at the folder, fanned out a little, so opening a folder grows out of it. Everything else: clustered, group
+ *  centres on a Fibonacci sphere and each group's docs in a small ball round it (targets = the centre); not clustered, a
+ *  deterministic point in one ball (targets 0, 0, 0). A node with neither, in a set that is the whole graph the host served a 3D
+ *  layout for (`nd.warm3`, wikiGraph serveLayout and serverFits), starts at its served position: a settled start, the first
+ *  visit's wait gone (WIKI-GRAPH-WARMSTART-3D-1). `warm`: any node was placed from the cache or the served layout. */
+export function seed3d(nodes, { cluster = false, cache = null } = {}) {
+  const n = nodes.length, xyz = new Float32Array(Math.max(3, 3 * n)), targets = new Float32Array(3 * n);
+  const R = seedRadius(n);
+  const groups = [...new Set(nodes.map((nd) => nd.group))];
+  const centre = new Map(groups.map((g, i) => {
+    if (!cluster || groups.length === 1) return [g, [0, 0, 0]];
+    const [x, y, z] = fibonacciSphere(i, groups.length);
+    return [g, [x * R, y * R, z * R]];
+  }));
+  const seen = new Map(), born = new Map();
+  const served = serverFits(nodes, 3);
+  let warm = false;
+  for (let i = 0; i < n; i++) {
+    const nd = nodes[i], c = centre.get(nd.group);
+    targets[3 * i] = c[0]; targets[3 * i + 1] = c[1]; targets[3 * i + 2] = c[2];
+    let p = cache?.get(nd.id);
+    if (!p && nd.parent && cache?.has(nd.parent)) { // a folder was just opened: its children start where it was
+      const q = cache.get(nd.parent), j = (born.get(nd.parent) || 0) + 1, [ux, uy, uz] = fibonacciSphere(j, j + 8), r = 6 * Math.cbrt(j);
+      born.set(nd.parent, j);
+      p = [q[0] + ux * r, q[1] + uy * r, q[2] + uz * r];
+    }
+    if (!p && served) p = nd.warm3;
+    if (p) { xyz[3 * i] = p[0]; xyz[3 * i + 1] = p[1]; xyz[3 * i + 2] = p[2]; warm = true; continue; }
+    if (cluster) {
+      const k = seen.get(nd.group) || 0, [ux, uy, uz] = fibonacciSphere(k, k + 16), r = 6 * Math.cbrt(k + 0.5);
+      seen.set(nd.group, k + 1);
+      xyz[3 * i] = c[0] + ux * r; xyz[3 * i + 1] = c[1] + uy * r; xyz[3 * i + 2] = c[2] + uz * r;
+    } else {
+      const r = R * Math.cbrt(rnd(3 * i)), y = 1 - 2 * rnd(3 * i + 1), s = Math.sqrt(1 - y * y), a = 2 * Math.PI * rnd(3 * i + 2);
+      xyz[3 * i] = Math.cos(a) * s * r; xyz[3 * i + 1] = y * r; xyz[3 * i + 2] = Math.sin(a) * s * r;
+    }
+  }
+  return { xyz, targets, warm };
+}
+
+export { folderRadius }; // WIKI-GRAPH-P0-LEVEL0-ZOOM-1: log-scaled and capped, shared with 2D (graphView.js)
+
+/** A node's world radius: half its level-view diameter (graphView levelSize: a folder by its docs, a doc by its links);
+ *  all the smallest size with "Size by links" off. */
+export function nodeRadius(node, sizeByDegree = true) {
+  return levelSize(node, sizeByDegree) / 2;
+}
+
+/** Bounding sphere of the nodes at indices `idx`: centroid and the largest distance from it, to the far side of each
+ *  node's sphere when `radius` (per node index) is given, so a fit shows big spheres whole. Null when `idx` is empty. */
+export function fitSphere(xyz, idx, radius = null) {
+  let cx = 0, cy = 0, cz = 0, c = 0;
+  for (const i of idx) { cx += xyz[3 * i]; cy += xyz[3 * i + 1]; cz += xyz[3 * i + 2]; c++; }
+  if (!c) return null;
+  cx /= c; cy /= c; cz /= c;
+  let far = 0;
+  for (const i of idx) {
+    const dx = xyz[3 * i] - cx, dy = xyz[3 * i + 1] - cy, dz = xyz[3 * i + 2] - cz;
+    const d = Math.sqrt(dx * dx + dy * dy + dz * dz) + (radius ? radius[i] : 0);
+    if (d > far) far = d;
+  }
+  return { x: cx, y: cy, z: cz, r: far };
+}
+
+/** Camera distance that shows a sphere of radius `r` whole, with `pad` (1.1 = 10% margin), at vertical FOV `fov` degrees
+ *  and `aspect` w/h (the narrower of the two FOVs decides). */
+export function fitDistance(r, fov = FOV, aspect = 1, pad = 1.1) {
+  const v = (fov * Math.PI) / 360, hz = Math.atan(Math.tan(v) * aspect), half = Math.min(v, hz);
+  return (Math.max(r, 1) * pad) / Math.sin(half);
+}
+
+/** Project nodes 0..n-1 through `vp` onto a w x h CSS px screen: `scr` [sx, sy, cw] per node, `rpx` the drawn radius in
+ *  px (`focal` = projection[5] * h / 2, px per world unit at distance 1). A node behind the camera gets cw <= 0 and OFF. */
+export function project(xyz, radius, n, vp, focal, w, h, scr, rpx) {
+  const e = vp;
+  for (let i = 0; i < n; i++) {
+    const x = xyz[3 * i], y = xyz[3 * i + 1], z = xyz[3 * i + 2];
+    const cw = e[3] * x + e[7] * y + e[11] * z + e[15];
+    if (cw <= 1e-6) { scr[3 * i] = OFF; scr[3 * i + 1] = OFF; scr[3 * i + 2] = cw; rpx[i] = 0; continue; }
+    scr[3 * i] = ((e[0] * x + e[4] * y + e[8] * z + e[12]) / cw + 1) * w / 2;
+    scr[3 * i + 1] = (1 - (e[1] * x + e[5] * y + e[9] * z + e[13]) / cw) * h / 2;
+    scr[3 * i + 2] = cw;
+    rpx[i] = (radius[i] * focal) / cw;
+  }
+}
+
+/** The node under screen point (x, y), or -1: among the visible indices `vis`, those in front of the camera whose
+ *  projected centre is within max(PICK_MIN_PX, drawn radius), the front-most (smallest cw). */
+export function pickProjected(scr, rpx, vis, x, y) {
+  let best = -1, bz = Infinity;
+  for (const i of vis) {
+    const cw = scr[3 * i + 2];
+    if (cw <= 1e-6 || cw >= bz) continue;
+    const r = Math.max(PICK_MIN_PX, rpx[i]), dx = scr[3 * i] - x, dy = scr[3 * i + 1] - y;
+    if (dx * dx + dy * dy <= r * r) { bz = cw; best = i; }
+  }
+  return best;
+}
+
+/** Every node under screen point (x, y), front to back (WIKI-GRAPH-3D-PORT-1: the Alt-click depth cycle and the hover card's
+ *  "+k behind"): the same hit test as pickProjected, so its first entry is pickProjected's answer. */
+export function pickStack(scr, rpx, vis, x, y) {
+  const hits = [];
+  for (const i of vis) {
+    const cw = scr[3 * i + 2];
+    if (cw <= 1e-6) continue;
+    const r = Math.max(PICK_MIN_PX, rpx[i]), dx = scr[3 * i] - x, dy = scr[3 * i + 1] - y;
+    if (dx * dx + dy * dy <= r * r) hits.push(i);
+  }
+  return hits.sort((a, b) => scr[3 * a + 2] - scr[3 * b + 2] || a - b);
+}
+
+/** Instance matrices (16 floats each, column-major) for nodes 0..n-1: uniform scale = radius, translation = position.
+ *  A node hidden by `mask` (0) gets scale 0, so it draws nothing and the instance count never changes. `looks` (optional):
+ *  a folder's solid core is CORE x its radius (its shell is drawn by writeSubset). */
+export function writeInstances(mat, xyz, radius, mask, n, looks = null) {
+  for (let i = 0; i < n; i++) {
+    const b = 16 * i, r = !mask || mask[i] ? radius[i] * (looks && looks[i] === LOOK.FOLDER ? CORE : 1) : 0;
+    mat[b] = r; mat[b + 1] = 0; mat[b + 2] = 0; mat[b + 3] = 0;
+    mat[b + 4] = 0; mat[b + 5] = r; mat[b + 6] = 0; mat[b + 7] = 0;
+    mat[b + 8] = 0; mat[b + 9] = 0; mat[b + 10] = r; mat[b + 11] = 0;
+    mat[b + 12] = xyz[3 * i]; mat[b + 13] = xyz[3 * i + 1]; mat[b + 14] = xyz[3 * i + 2]; mat[b + 15] = 1;
+  }
+}
+
+/** Instance matrices for the nodes `idx` only (a folder's shell, a hub's halo): instance j is node idx[j], scaled by
+ *  radius x `factor`; 0 when masked out. */
+export function writeSubset(mat, xyz, radius, mask, idx, factor = 1) {
+  for (let j = 0; j < idx.length; j++) {
+    const i = idx[j], b = 16 * j, r = !mask || mask[i] ? radius[i] * factor : 0;
+    mat[b] = r; mat[b + 1] = 0; mat[b + 2] = 0; mat[b + 3] = 0;
+    mat[b + 4] = 0; mat[b + 5] = r; mat[b + 6] = 0; mat[b + 7] = 0;
+    mat[b + 8] = 0; mat[b + 9] = 0; mat[b + 10] = r; mat[b + 11] = 0;
+    mat[b + 12] = xyz[3 * i]; mat[b + 13] = xyz[3 * i + 1]; mat[b + 14] = xyz[3 * i + 2]; mat[b + 15] = 1;
+  }
+}
+
+/** Line segment ends (6 floats a link) for the first `count` index pairs of `pairs` into `out`. Returns `count`. */
+export function writeLinkPositions(out, xyz, pairs, count) {
+  for (let e = 0; e < count; e++) {
+    const a = 3 * pairs[2 * e], b = 3 * pairs[2 * e + 1], o = 6 * e;
+    out[o] = xyz[a]; out[o + 1] = xyz[a + 1]; out[o + 2] = xyz[a + 2];
+    out[o + 3] = xyz[b]; out[o + 4] = xyz[b + 1]; out[o + 5] = xyz[b + 2];
+  }
+  return count;
+}
+
+/** Line segment ends (6 floats a link) into `out` for the links `idx[from..to)` (link numbers, a linkWeight.js bucket), in that
+ *  order. Returns `out`. */
+export function writeLinkPositionsBy(out, xyz, pairs, idx, from, to) {
+  for (let j = from; j < to; j++) {
+    const e = 2 * idx[j], a = 3 * pairs[e], b = 3 * pairs[e + 1], o = 6 * (j - from);
+    out[o] = xyz[a]; out[o + 1] = xyz[a + 1]; out[o + 2] = xyz[a + 2];
+    out[o + 3] = xyz[b]; out[o + 4] = xyz[b + 1]; out[o + 5] = xyz[b + 2];
+  }
+  return out;
+}
+
+/** One cone arrowhead from node a to node b as an instance matrix written at `mat[o..o+15]`: the cone's apex sits on b's
+ *  sphere (`rb` world units from its centre), it points along a -> b and is ARROW.len x 2*ARROW.half screen px at b's
+ *  depth (`pxW` = world units per px there). `side` (+1, 0) moves a mutual link's head off the shared line, sideways on
+ *  screen (`eye`: the camera position), so the two heads of a pair never overlap. The cone geometry has its apex at the
+ *  origin and its base at y = -1, radius 1. False when there is no room between the spheres for a head. */
+export function arrowMatrix(xyz, a, b, ra, rb, pxW, side, eye, mat, o) {
+  const ax = xyz[3 * a], ay = xyz[3 * a + 1], az = xyz[3 * a + 2], bx = xyz[3 * b], by = xyz[3 * b + 1], bz = xyz[3 * b + 2];
+  let ux = bx - ax, uy = by - ay, uz = bz - az;
+  const d = Math.hypot(ux, uy, uz), len = ARROW.len * pxW, half = ARROW.half * pxW;
+  if (!(d - ra - rb > len)) return false;
+  ux /= d; uy /= d; uz /= d;
+  // p: any unit vector across the link; q = p x u completes a right-handed frame (p, u, q), so the cone's faces keep their
+  // winding (a mirrored matrix would show its back faces). The cone is round, so which p does not matter.
+  let px = Math.abs(ux) < 0.9 ? 0 : -uz, py = Math.abs(ux) < 0.9 ? uz : 0, pz = Math.abs(ux) < 0.9 ? -uy : ux; // u x (1,0,0) or u x (0,1,0)
+  const pl = Math.hypot(px, py, pz); px /= pl; py /= pl; pz /= pl;
+  const qx = py * uz - pz * uy, qy = pz * ux - px * uz, qz = px * uy - py * ux;
+  let tx = bx - ux * rb, ty = by - uy * rb, tz = bz - uz * rb;
+  if (side) { // sideways on screen: across both the link and the line of sight
+    const vx = tx - eye[0], vy = ty - eye[1], vz = tz - eye[2];
+    let sx = uy * vz - uz * vy, sy = uz * vx - ux * vz, sz = ux * vy - uy * vx;
+    const sl = Math.hypot(sx, sy, sz);
+    if (sl > 0) { const f = (side * ARROW.offset * pxW) / sl; sx *= f; sy *= f; sz *= f; tx += sx; ty += sy; tz += sz; }
+  }
+  mat[o] = px * half; mat[o + 1] = py * half; mat[o + 2] = pz * half; mat[o + 3] = 0;
+  mat[o + 4] = ux * len; mat[o + 5] = uy * len; mat[o + 6] = uz * len; mat[o + 7] = 0;
+  mat[o + 8] = qx * half; mat[o + 9] = qy * half; mat[o + 10] = qz * half; mat[o + 11] = 0;
+  mat[o + 12] = tx; mat[o + 13] = ty; mat[o + 14] = tz; mat[o + 15] = 1;
+  return true;
+}
+
+/** The arrowheads of one frame as cone instance matrices into `mat` (room for `cap`). The 2D rules, applied to the
+ *  projection (`scr`, from project()): a link gets heads only when both ends are in front of the camera, it touches the
+ *  screen grown by `margin` px, and it is at least ARROW.minLink px long on screen; heads at the target end (TO_TARGET), at
+ *  the source end too for a level link with counts both ways (TO_SOURCE), offset when MUTUAL, never on a hub (headOn,
+ *  WIKI-GRAPH-DECLUTTER-1). `sc`: xyz, radius, visPairs, visDirs, visCount, degree (optional). `focal`: px per world unit at distance 1. Returns how many heads were written. */
+export function fillArrows3d(sc, scr, focal, w, h, eye, mat, margin = 0, cap = ARROW_CAP) {
+  const { xyz, radius, visPairs, visDirs, visCount, degree } = sc;
+  const x0 = -margin, y0 = -margin, x1 = w + margin, y1 = h + margin;
+  let t = 0;
+  for (let e = 0; e < visCount && t < cap; e++) {
+    const a = visPairs[2 * e], b = visPairs[2 * e + 1];
+    const wa = scr[3 * a + 2], wb = scr[3 * b + 2];
+    if (wa <= 1e-6 || wb <= 1e-6) continue;
+    const sax = scr[3 * a], say = scr[3 * a + 1], sbx = scr[3 * b], sby = scr[3 * b + 1];
+    if ((sax < x0 && sbx < x0) || (sax > x1 && sbx > x1) || (say < y0 && sby < y0) || (say > y1 && sby > y1)) continue;
+    if (!(Math.hypot(sbx - sax, sby - say) >= ARROW.minLink)) continue;
+    const f = visDirs ? visDirs[e] : TO_TARGET, side = f & MUTUAL ? 1 : 0;
+    if ((f & TO_TARGET) && (!degree || headOn(degree[b])) && arrowMatrix(xyz, a, b, radius[a], radius[b], wb / focal, side, eye, mat, 16 * t)) t++;
+    if (t < cap && (f & TO_SOURCE) && (!degree || headOn(degree[a])) && arrowMatrix(xyz, b, a, radius[b], radius[a], wa / focal, side, eye, mat, 16 * t)) t++;
+  }
+  return t;
+}
+
+const endOf = (end) => (typeof end === "object" && end ? end.id : end);
+
+/** Does `graph` hold the same node ids (in order) and the same drawn index pairs (in order) as the scene (`ids`, `index`,
+ *  `pairs`)? Only then may a new graph object recolour in place; any change to the nodes or links rebuilds (the 2D rule,
+ *  WIKI-GRAPH-REFRESH-FU-1). */
+export function sameTopology(ids, index, pairs, graph) {
+  const { nodes, links } = graph;
+  if (nodes.length !== ids.length || !nodes.every((n, i) => n.id === ids[i])) return false;
+  let k = 0;
+  for (const l of links) {
+    const a = index.get(endOf(l.source)), b = index.get(endOf(l.target));
+    if (a === undefined || b === undefined) continue;
+    if (pairs[k++] !== a || pairs[k++] !== b) return false;
+  }
+  return k === pairs.length;
+}
+
+/** The link arrays the scene draws for `links` over nodes indexed by `index` (n nodes): index `pairs`, direction flags
+ *  `dirs` (graphArrows dirOf, plus MUTUAL when the reverse link exists) and the incidence lists (CSR `off`/`adj`) that make
+ *  a node's neighbours a slice, and `weights` (one per link, 1 for a flat link). Links with an end outside the set are skipped. */
+export function linkArrays(links, index, n, dirOf) {
+  const pairs = new Uint32Array(2 * links.length), count = new Uint32Array(n + 1), dirs = new Uint8Array(links.length);
+  const weights = new Float32Array(links.length).fill(1);
+  const seen = new Set();
+  let k = 0;
+  for (const l of links) {
+    const a = index.get(endOf(l.source)), b = index.get(endOf(l.target));
+    if (a === undefined || b === undefined) continue;
+    dirs[k / 2] = dirOf(l);
+    if (l.weight > 1) weights[k / 2] = l.weight; // an aggregated folder link's crossings (linkWeight.js); a flat link is 1
+    seen.add(a * n + b);
+    pairs[k++] = a; pairs[k++] = b;
+    count[a + 1]++; count[b + 1]++;
+  }
+  for (let e = 0; e < k; e += 2) if (seen.has(pairs[e + 1] * n + pairs[e])) dirs[e / 2] |= MUTUAL;
+  const used = pairs.subarray(0, k);
+  for (let i = 0; i < n; i++) count[i + 1] += count[i];
+  const off = count.slice(), adj = new Uint32Array(k), fill = count.slice(0, n);
+  for (let e = 0; e < k; e += 2) { adj[fill[used[e]]++] = used[e + 1]; adj[fill[used[e + 1]]++] = used[e]; }
+  return { pairs: used, dirs: dirs.subarray(0, k / 2), weights: weights.subarray(0, k / 2), off, adj };
+}
+
+/** WIKI-GRAPH-RENDER-FU-A: a same-topology refresh can change only the containment pairs (`graph.contains`, a hub's folder members), which
+ *  `sameTopology` ignores. Store the new `cpairs` (the dashed lines draw from `s.cpairs`) and, when they differ, send the layout its
+ *  new containment springs after the `s.pairs` links, no reheat (like the weights). Returns whether they changed. */
+export function refreshContain(s, cpairs) {
+  const old = s.cpairs, same = !!old && old.length === cpairs.length && old.every((v, i) => v === cpairs[i]);
+  s.cpairs = cpairs; // the dashed lines redraw from this
+  if (!same) s.layout?.contain(springPairs(cpairs), s.pairs.length / 2); // and the layout's containment springs follow (a giant hub has none, hubLines), no reheat
+  return !same;
+}
+
+/** WIKI-GRAPH-3D-ARROW-REFRESH-FU-1 (both canvases): the state a same-topology refresh (a new graph object, same node ids and
+ *  same drawn pairs) must rebuild because the new graph can change it without changing the layout key: the per-link direction
+ *  flags (a level link's counts each way, so one head becomes two), the per-link weights (WIKI-GRAPH-LEVEL-WEIGHTS-FU-1: width
+ *  and layout strength; the caller re-masks for the drawn widths and tells the layout), the heads of the focused or hovered doc derived from
+ *  them, the containment pairs (refreshContain), and the cached label widths of any doc whose title changed. `s`: ids/index/pairs/titles/labelW/focus/hover scene
+ *  state; the caller re-masks afterwards, which copies `s.dirs` into the drawn flags. */
+export function refreshSameTopology(s, graph, dirOf) {
+  const { nodes, links } = graph;
+  const arrays = linkArrays(links, s.index, nodes.length, dirOf);
+  s.dirs = arrays.dirs;
+  s.weights = arrays.weights;
+  refreshContain(s, containPairs(graph.contains, s.index));
+  for (let i = 0; i < nodes.length; i++) if (nodes[i].title !== s.titles[i]) s.labelW[i] = NaN;
+  s.titles = nodes.map((nd) => nd.title);
+  s.hotHeads = s.focus >= 0 || s.hover >= 0 ? hotHeads(s.pairs, s.dirs, [s.focus, s.hover]) : null;
+}

package/src/graph/lib/graphArrows.js

@@ -0,0 +1,108 @@
+// WIKI-GRAPH-ARROWS-1: arrowheads on graph links, as pure geometry shared by both base layers (pixiBase.js on the GPU,
+// canvasBase.js on Canvas2D). Links are directed (`LINKS_TO`, source -> target); a level view's folder -> folder link is one
+// line per pair carrying a count each way, drawn with a head at each end that has one. Heads are a fixed size on screen, sit
+// at the node's drawn radius, are hidden below a zoom threshold (like labels) and culled to the view with a per-frame cap.
+import { LABEL_ALL } from "./wikiGraph";
+import { drawRadius } from "./graphView";
+
+/** Head size and spacing, screen px. `minLink`: a link drawn shorter than this on screen gets no head. `offset`: how far a
+ *  mutual link's heads move off the shared line (to opposite sides) so they never sit on top of each other. */
+export const ARROW = { len: 8, half: 3.5, minLink: 16, offset: 3 };
+/** Never more heads than this in one frame (like LABEL_CAP for labels). */
+export const ARROW_CAP = 3000;
+
+/** Per-link flags: head at the target end, head at the source end, a mutual flat link (offset its head). */
+export const TO_TARGET = 1, TO_SOURCE = 2, MUTUAL = 4;
+
+/** WIKI-GRAPH-DECLUTTER-1: no head is drawn on a node with more links than this (a hub), where heads would stack into a grey
+ *  clump; the overlay draws the heads of the focused or hovered doc's links instead (hotHeads, fillHotArrows). */
+export const ARROW_HUB_DEGREE = 8;
+
+/** May the base layer put a head on node `tip` (degree `tipDegree`)? Not on a hub. `lit`: the link touches the focus or the
+ *  hover, which always gets its heads. */
+export const headOn = (tipDegree, lit = false) => lit || !(tipDegree > ARROW_HUB_DEGREE);
+
+/** Do heads draw at all for `count` nodes at zoom `k`? Few nodes: always; more: from the same zoom labels turn on at
+ *  (1, or 2 on a big graph, lodFor in wikiGraph.js), because below that the links are too short and dense to read a head on. */
+export function arrowsFor(count, k, big) {
+  return count <= LABEL_ALL || k >= (big ? 2 : 1);
+}
+
+/** The flags of one link: `l.ab` / `l.ba` (a level view's counts each way) when present, else a flat link: head at its target. */
+export function dirOf(l) {
+  if (l.ab === undefined && l.ba === undefined) return TO_TARGET;
+  return (l.ab > 0 ? TO_TARGET : 0) | (l.ba > 0 ? TO_SOURCE : 0);
+}
+
+/** One head pointing from (ax,ay) to (bx,by), its tip at node b's edge (`rb` world units from b's centre), written as 3
+ *  points (6 floats) into `out` at `o`. `side` (+1/-1/0) moves it off the line. False when the link is too short on screen
+ *  (< ARROW.minLink) or has no room between the two nodes (`ra`, `rb`) for a head. */
+export function arrowTriangle(ax, ay, bx, by, ra, rb, k, side, out, o) {
+  const dx = bx - ax, dy = by - ay, d = Math.hypot(dx, dy);
+  if (!(d * k >= ARROW.minLink) || d - ra - rb <= ARROW.len / k) return false;
+  const ux = dx / d, uy = dy / d, px = -uy, py = ux, off = (side * ARROW.offset) / k;
+  const tx = bx - ux * rb + px * off, ty = by - uy * rb + py * off;
+  const cx = tx - (ux * ARROW.len) / k, cy = ty - (uy * ARROW.len) / k, h = ARROW.half / k;
+  out[o] = tx; out[o + 1] = ty;
+  out[o + 2] = cx + px * h; out[o + 3] = cy + py * h;
+  out[o + 4] = cx - px * h; out[o + 5] = cy - py * h;
+  return true;
+}
+
+/** The heads of the drawn links that touch the view, as triangles (6 floats each) in world units into `out` (room for
+ *  ARROW_CAP), never on a hub (headOn). `sc`: pos, sizes, big, visPairs, visDirs, visCount, degree (optional); `view` {x, y, k}; the view box is w x h screen px grown by
+ *  `margin` px each side. Returns how many triangles were written. */
+export function fillArrows(sc, view, w, h, out, margin = 0, cap = ARROW_CAP) {
+  const { pos, sizes, big, visPairs, visDirs, visCount, degree } = sc;
+  const k = view.k;
+  const x0 = (-margin - view.x) / k, y0 = (-margin - view.y) / k, x1 = (w + margin - view.x) / k, y1 = (h + margin - view.y) / k;
+  let t = 0;
+  for (let e = 0; e < visCount && t < cap; e++) {
+    const a = visPairs[2 * e], b = visPairs[2 * e + 1];
+    const ax = pos[2 * a], ay = pos[2 * a + 1], bx = pos[2 * b], by = pos[2 * b + 1];
+    if ((ax < x0 && bx < x0) || (ax > x1 && bx > x1) || (ay < y0 && by < y0) || (ay > y1 && by > y1)) continue;
+    const f = visDirs ? visDirs[e] : TO_TARGET, side = f & MUTUAL ? 1 : 0;
+    const ra = drawRadius(sizes[a], k, big), rb = drawRadius(sizes[b], k, big);
+    if ((f & TO_TARGET) && (!degree || headOn(degree[b])) && arrowTriangle(ax, ay, bx, by, ra, rb, k, side, out, 6 * t)) t++;
+    if (t < cap && (f & TO_SOURCE) && (!degree || headOn(degree[a])) && arrowTriangle(bx, by, ax, ay, rb, ra, k, side, out, 6 * t)) t++;
+  }
+  return t;
+}
+
+/** The heads of the links touching the docs in `hot` (the focus and the hover; -1 is skipped), as [from, to, side]
+ *  triples, one per head: a flat link's head points at its target, a level link's at each end with a count. `pairs` and
+ *  `dirs`: every link of the scene (the overlay checks the legend mask when it draws). Computed when the lit set changes. */
+export function hotHeads(pairs, dirs, hot) {
+  const out = [], m = pairs.length / 2;
+  const isHot = (i) => hot.includes(i);
+  for (let e = 0; e < m; e++) {
+    const a = pairs[2 * e], b = pairs[2 * e + 1];
+    if (!isHot(a) && !isHot(b)) continue;
+    const f = dirs ? dirs[e] : TO_TARGET, side = f & MUTUAL ? 1 : 0;
+    if (f & TO_TARGET) out.push(a, b, side);
+    if (f & TO_SOURCE) out.push(b, a, side);
+  }
+  return out;
+}
+
+/** Screen-space triangles (6 floats each, px) into `out` for the `heads` triples: `at(i)` gives [sx, sy, rPx] (rPx = the
+ *  drawn radius, so a head's tip touches the ring the overlay draws). A head whose ends are hidden (`mask`), or that would
+ *  sit within one head's width of another head on the same node, is skipped, so heads never stack even on a hub. Returns
+ *  how many were written (at most `cap`). */
+export function fillHotArrows(heads, at, mask, out, cap = ARROW_CAP) {
+  const seen = new Map(); // tip -> angles of the heads already on it
+  let t = 0;
+  for (let h = 0; h < heads.length && t < cap; h += 3) {
+    const a = heads[h], b = heads[h + 1], side = heads[h + 2];
+    if (mask && (!mask[a] || !mask[b])) continue;
+    const [ax, ay, ra] = at(a), [bx, by, rb] = at(b);
+    if (!(Math.abs(ax) < 1e5 && Math.abs(bx) < 1e5 && Math.abs(ay) < 1e5 && Math.abs(by) < 1e5)) continue; // an end behind the 3D camera
+    const ang = Math.atan2(ay - by, ax - bx), gap = 2 * Math.asin(Math.min(1, ARROW.half / (rb + ARROW.len)));
+    const on = seen.get(b);
+    if (on && on.some((o) => { const d = Math.abs(o - ang) % (2 * Math.PI); return Math.min(d, 2 * Math.PI - d) < gap; })) continue;
+    if (!arrowTriangle(ax, ay, bx, by, ra, rb, 1, side, out, 6 * t)) continue;
+    if (on) on.push(ang); else seen.set(b, [ang]);
+    t++;
+  }
+  return t;
+}