@smartmemory/wiki-components 0.4.0 → 0.6.0

package/src/graph/lib/graphView.js

@@ -0,0 +1,343 @@
+// WIKI-GRAPH-OBSIDIAN-1: the Obsidian-style graph view's pure helpers (no DOM, no React, no Pixi), shared by the page,
+// the canvas, both renderers and the tests: legend state, local graph, degree sizing, physics, label picking, renderer
+// choice. Groups, colours and degrees come from buildGraph (wikiGraph.js). Ported from the spike's g6Graph.js (e95dfeb).
+import { HUB_DEGREE, LABEL_ALPHA_MIN, labelFade } from "./wikiGraph";
+
+/** URL params the view keeps its state in, so a link reproduces what the reader saw. `root` is the focused doc (today's
+ *  meaning, kept); a focus narrows the graph to `hops` links around it (the old `local` param is gone and ignored).
+ *  `doc` (WIKI-GRAPH-DOC-PANE-1) is the doc the right-hand pane shows; absent means no pane. `x` (WIKI-GRAPH-EXPLORE-1b-SHELL) is
+ *  the filter chips' explore state (graphExplore encodeX); a change to it pushes a history entry. No param holds a camera angle:
+ *  a shared link opens on the default view (owner). */
+export const PARAM = {
+  hide: "hide", root: "root", hops: "hops", by: "by", size: "size", repel: "repel", link: "link", centre: "centre", cluster: "cluster",
+  renderer: "renderer", levels: "lv", flat: "flat", view: "view", doc: "doc", range: "lr", outlines: "outlines", dim: "dim", x: "x",
+};
+
+/** Hidden legend groups in the URL: `hide=a,b` (names URI-encoded one by one, so a comma in a name survives). */
+export function parseHidden(value) {
+  if (!value) return new Set();
+  return new Set(String(value).split(",").filter(Boolean).map((s) => {
+    try { return decodeURIComponent(s); } catch { return s; }
+  }));
+}
+export const formatHidden = (hidden) => [...hidden].sort().map(encodeURIComponent).join(",");
+
+/** Toggle one legend group by its literal name (a group may be called "all" or "none"). Returns a new Set. */
+export function toggleGroup(hidden, group) {
+  const next = new Set(hidden);
+  if (next.has(group)) next.delete(group); else next.add(group);
+  return next;
+}
+/** The legend's bulk commands, apart from the group names: show every group, hide every group. */
+export const showEveryGroup = () => new Set();
+export const hideEveryGroup = (groups) => new Set(groups.map((g) => g.name));
+
+const endId = (end) => (typeof end === "object" && end ? end.id : end);
+
+/** Undirected adjacency: id -> Set of neighbour ids. */
+export function adjacencyOf(links) {
+  const adj = new Map();
+  const add = (a, b) => { let s = adj.get(a); if (!s) adj.set(a, (s = new Set())); s.add(b); };
+  for (const l of links) {
+    const s = endId(l.source), t = endId(l.target);
+    if (s === t) continue;
+    add(s, t); add(t, s);
+  }
+  return adj;
+}
+
+/** The ids within `hops` links of `root` (root included). hops <= 0 is the root alone; an unknown root is empty. */
+export function hopSet(adj, root, hops, known = null) {
+  if (!root || (known && !known.has(root))) return new Set();
+  const seen = new Set([root]);
+  let frontier = [root];
+  for (let h = 0; h < hops && frontier.length; h++) {
+    const next = [];
+    for (const id of frontier) for (const n of adj.get(id) || []) if (!seen.has(n)) { seen.add(n); next.push(n); }
+    frontier = next;
+  }
+  return seen;
+}
+
+/** The local graph: only nodes inside `local` (a hop set), and only links whose two ends are both kept. */
+export function localGraph(graph, local) {
+  if (!local) return { nodes: graph.nodes, links: graph.links };
+  const nodes = graph.nodes.filter((n) => local.has(n.id));
+  const links = graph.links.filter((l) => local.has(endId(l.source)) && local.has(endId(l.target)));
+  return { nodes, links };
+}
+
+/** Per node index: 1 drawn, 0 hidden by the legend or, with `keep` (a Set of node indices, localKeep), outside it. A link is
+ *  drawn only when both its ends are. */
+export function visibleMask(nodes, hidden, keep = null) {
+  const mask = new Uint8Array(nodes.length);
+  for (let i = 0; i < nodes.length; i++) mask[i] = hidden.has(nodes[i].group) || (keep && !keep.has(i)) ? 0 : 1;
+  return mask;
+}
+
+/** WIKI-GRAPH-LOCAL-HOPS-RECULL-1: the nodes a focus may draw, or null (no cull). With a focus
+ *  drawn (WIKI-GRAPH-FOCUS-HOPS-ONLY-1: always, no toggle), only the focus's hop rings (`rings`, layoutEngine hopRings as the canvas lights them, hub guard and opened hubs
+ *  included): a node outside them is hidden, never drawn dimmed. The page's hopSet narrowing has no hub guard and runs over the
+ *  doc graph, so on its own it keeps nodes past a capped hub (and level-view hubs with no links) that the rings never light.
+ *  With no focus the whole graph is drawn. Both canvases mask through this one rule. */
+export function localKeep(focus, rings) {
+  return focus >= 0 && rings ? rings.lit : null;
+}
+
+/** WIKI-GRAPH-DIM-NO-PICK-1: the nodes a pointer may pick. While anything is dimmed (a focus, a hover or a find match) only the
+ *  lit nodes take pointer events, so a dimmed node under the cursor is as good as empty canvas (even when nothing is lit);
+ *  with nothing dimmed every visible node is pickable. Both renderers' hit tests, hover, cursor, click, double-click, press and
+ *  the 3D depth stack go through this one rule. `vis`, `lit`: node-index arrays (lit already limited to the visible set). */
+export function pickable(vis, lit, dim) {
+  return dim ? lit : vis;
+}
+
+/** The lit set both canvases draw over the dimmed base: the selection-focus treatment, one rule for 2D and 3D. `focus` /
+ *  `hover`: node index or -1; `near(i)`: i and its neighbours. With no `match`: the focus and the hover, each with its
+ *  neighbours, and their links. With a `match` (WIKI-GRAPH-FIND-FILTER-LIVE-1: node indices of a find term, possibly
+ *  empty) the matches are what is lit, plus the focus and the hover themselves (the focus is always lit), and only the
+ *  focus's and the hover's links to a lit node are drawn hot. `dim`: the base steps back (anything lit, or a find term).
+ *  WIKI-GRAPH-FOCUS-HOPS-1: `focusLit` (node indices within X hops of the focus, layoutEngine hopRings) replaces the
+ *  focus's one-hop `near`: every node in it is lit and every link with both ends in it is hot. With a `match` too, a node
+ *  is lit only if it is in both (layoutEngine focusFindLit), the focus always. */
+export function litOf({ focus, hover, near, match = null, focusLit = null }) {
+  const lit = new Set(), links = [];
+  const ring = focus >= 0 && focusLit ? new Set(focusLit) : null;
+  const ringLinks = () => {
+    for (const a of ring) {
+      if (!lit.has(a)) continue;
+      for (const b of near(a)) if (b > a && ring.has(b) && lit.has(b)) links.push(a, b);
+    }
+  };
+  if (match) {
+    if (ring) { for (const i of match) if (ring.has(i)) lit.add(i); } else for (const i of match) lit.add(i);
+    for (const c of [focus, hover]) if (c >= 0) lit.add(c);
+    if (ring) ringLinks();
+    for (const c of ring ? [hover] : [focus, hover]) {
+      if (c < 0) continue;
+      for (const j of near(c)) if (j !== c && lit.has(j)) links.push(c, j);
+    }
+  } else {
+    if (ring) { for (const i of ring) lit.add(i); ringLinks(); }
+    for (const c of ring ? [hover] : [focus, hover]) {
+      if (c < 0) continue;
+      for (const j of near(c)) { lit.add(j); if (j !== c) links.push(c, j); }
+    }
+  }
+  return { lit: [...lit], links, dim: !!match || lit.size > 0 };
+}
+
+/** How the base looks while something is lit (selection focus or a find term; owner 2026-10-21: near invisible, opacity `dim`
+ *  and fully desaturated, with only the lit docs labelled, which the overlay's `litOnly` does). One level for 2D and 3D,
+ *  the find filter and the focus: `dim` (URL `?dim=`), 0 to DIM_MAX, default DIM_DEFAULT. */
+export const DIM_DEFAULT = 0.05, DIM_MAX = 0.5, DIM_FILTER = "saturate(0)";
+/** The `dim` URL value as a level: missing or not a number is the default, anything else clamped to [0, DIM_MAX]. */
+export function parseDim(raw) {
+  if (raw === null || raw === undefined || raw === "") return DIM_DEFAULT;
+  const n = Number(raw);
+  return Number.isFinite(n) ? Math.min(DIM_MAX, Math.max(0, n)) : DIM_DEFAULT;
+}
+export function dimBase(el, on, dim = DIM_DEFAULT) {
+  el.style.opacity = on ? String(dim) : "";
+  el.style.filter = on ? DIM_FILTER : "";
+}
+
+/** The drawn links as index pairs (two entries per link) into `out`; returns how many links were written.
+ *  With `dirs` (one arrow flag per link, graphArrows.js) and `outDirs`, the flags of the drawn links are copied alongside;
+ *  likewise `weights` and `outWeights` (linkWeight.js). */
+export function visibleLinks(pairs, mask, out, dirs = null, outDirs = null, weights = null, outWeights = null) {
+  let k = 0;
+  for (let i = 0; i < pairs.length; i += 2) {
+    const a = pairs[i], b = pairs[i + 1];
+    if (mask[a] && mask[b]) {
+      if (dirs && outDirs) outDirs[k / 2] = dirs[i / 2];
+      if (weights && outWeights) outWeights[k / 2] = weights[i / 2];
+      out[k++] = a; out[k++] = b;
+    }
+  }
+  return k / 2;
+}
+
+/** Node diameter in world px from its degree: sqrt growth like Obsidian, so a hub is big but never swallows the view.
+ *  `byDegree` false draws every node at the smallest size. */
+export const SIZE_MIN = 4, SIZE_MAX = 40;
+export function nodeSize(degree, byDegree = true) {
+  if (!byDegree) return SIZE_MIN;
+  const d = Math.max(0, Number(degree) || 0);
+  return Math.min(SIZE_MAX, SIZE_MIN + 2.2 * Math.sqrt(d));
+}
+/** A node never draws smaller than this on screen (px radius), however far you zoom out; smaller on a big graph. */
+export const minScreenRadius = (big) => (big ? 1.25 : 2);
+/** The radius in world units a node is drawn at for zoom `k`. */
+export const drawRadius = (size, k, big) => Math.max(size / 2, minScreenRadius(big) / k);
+
+/** Physics sliders: 0..100 each, mapped to force parameters by `forceParams`. */
+export const PHYSICS_DEFAULTS = { repel: 50, link: 30, centre: 30 };
+export function parsePhysics(sp) {
+  const out = { ...PHYSICS_DEFAULTS };
+  for (const k of Object.keys(PHYSICS_DEFAULTS)) {
+    const raw = sp.get(PARAM[k]);
+    const v = Number(raw);
+    if (raw !== null && raw !== "" && Number.isFinite(v)) out[k] = Math.max(0, Math.min(100, Math.round(v)));
+  }
+  return out;
+}
+
+/** Slider values -> d3-force parameters, the only place the sliders get their meaning. */
+export function forceParams({ repel, link, centre, cluster = true }) {
+  return {
+    charge: -(2 + repel * 0.6), // forceManyBody strength
+    linkDistance: 6 + link * 0.9,
+    // forceX/forceY strength. Clustering on: towards the doc's group centre, 0.05 at the default (today's). Off: towards 0,0
+    // and weak (0.013 at the default), just enough to keep unlinked components from drifting off, so links do the layout.
+    centre: cluster ? 0.002 + centre * 0.0016 : 0.001 + centre * 0.0004,
+  };
+}
+
+// WIKI-GRAPH-P0-LEVEL0-ZOOM-1: the folder level's node size, shared by the 3D and 2D views. A folder's radius (world units)
+// grows with the log of its doc count, so 1 doc and 3,559 docs differ ~6x and never swamp the view, and it is capped at
+// FOLDER_R_CAP, a fraction of the default link distance, so a sphere never dwarfs the gap a link is drawn across. The
+// layout keeps them apart (layoutRadii: link distance is surface to surface, plus collide), and fit counts the radii.
+export const FOLDER_R_MIN = 3, FOLDER_R_LOG = 2;
+export const FOLDER_R_CAP = 0.6 * forceParams(PHYSICS_DEFAULTS).linkDistance; // 19.8 at the default sliders
+/** A folder's radius from its doc count (0 or missing counts as 1): FOLDER_R_MIN + FOLDER_R_LOG * ln(size), at most `cap`. */
+export function folderRadius(size, cap = FOLDER_R_CAP) {
+  return Math.min(cap, FOLDER_R_MIN + FOLDER_R_LOG * Math.log(Math.max(1, Number(size) || 1)));
+}
+/** A level-view node's diameter (world units, nodeSize's unit): a folder by its doc count, a doc by its links. */
+export function levelSize(node, byDegree = true) {
+  if (node?.kind === "folder") return byDegree ? 2 * folderRadius(node.size) : SIZE_MIN;
+  return nodeSize(node?.degree, byDegree);
+}
+/** The radii the layout must keep apart (link distance surface to surface, collide), or null: only a scene with a folder
+ *  node gets them, so the flat docs view lays out exactly as before. `radius(i)` is node i's drawn radius. */
+export function layoutRadii(nodes, radius) {
+  if (!nodes.some((nd) => nd.kind === "folder")) return null;
+  return Float32Array.from(nodes, (_, i) => radius(i));
+}
+/** The extra spacing collide keeps between two spheres that have no link (world units). */
+export const COLLIDE_GAP = 4;
+/** Past this many nodes the layout skips the collide force (its tree costs as much as the many-body one); the
+ *  surface-to-surface link distance still holds. */
+export const COLLIDE_N = 3000;
+
+/** The link distance a layout worker sets for slider distance `d`: from surface to surface when `radii` are given (so a
+ *  link between two big folders stays visible), else `d` itself. */
+export const linkDistanceFn = (d, radii) => (radii ? (l) => d + radii[l.source.index] + radii[l.target.index] : d);
+/** The collide force's per-node radius: the drawn radius plus half COLLIDE_GAP (two spheres keep a full gap). */
+export const collideRadiusFn = (radii) => (nd) => radii[nd.index] + COLLIDE_GAP / 2;
+
+/** How often the worker posts positions: ~100 ms at 5k docs, ~1 s at 50k (each post copies every position). */
+export const progressMsFor = (n) => Math.max(33, Math.min(1000, Math.round(n / 50)));
+/** The layout cools over this many ticks (fewer on a big graph, whose clustered seeds are most of the layout already). */
+export const maxTicksFor = (big) => (big ? 160 : 300);
+
+export const LABEL_CELL = 48;
+const LABEL_H = 12, LABEL_DESC = 3, LABEL_PAD = 2, LABEL_GAP = 8;
+/** The collision half of pickLabels, shared with the 3D depth picker (labelDepth.js): `place(i, a)` puts doc i's label at the
+ *  first free spot (above, below, right, left of its dot) and records it in `out` as {i, x, y, a}; either way the dot blocks
+ *  every later label. Same box rule for both renderers, so no new measuring. */
+export function createLabelPacker({ at, width, w, h, mask }) {
+  const out = [], cells = new Map();
+  const span = (b, f) => {
+    const cx0 = Math.max(-32000, Math.floor(b[0] / LABEL_CELL)), cx1 = Math.min(32000, Math.floor(b[2] / LABEL_CELL));
+    const cy0 = Math.max(-32000, Math.floor(b[1] / LABEL_CELL)), cy1 = Math.min(32000, Math.floor(b[3] / LABEL_CELL));
+    for (let cy = cy0; cy <= cy1; cy++) for (let cx = cx0; cx <= cx1; cx++) if (f((cy + 32768) * 65536 + cx + 32768)) return true;
+    return false;
+  };
+  const free = (b) => !span(b, (key) => {
+    const l = cells.get(key);
+    if (l) for (const o of l) if (b[0] < o[2] && b[2] > o[0] && b[1] < o[3] && b[3] > o[1]) return true;
+    return false;
+  });
+  const take = (b) => span(b, (key) => { const l = cells.get(key); if (l) l.push(b); else cells.set(key, [b]); return false; });
+  const box = (x, y, lw) => [x - lw / 2 - LABEL_PAD, y - LABEL_H, x + lw / 2 + LABEL_PAD, y + LABEL_DESC];
+  const place = (i, a) => {
+    if (mask && !mask[i]) return;
+    const [sx, sy, r] = at(i);
+    if (sx < -50 || sx > w + 50 || sy < -20 || sy > h + 20) return;
+    const lw = width(i);
+    const spots = [ // [centre x, baseline y]: above, below, right, left of the dot
+      [sx, sy - (r + LABEL_GAP)], [sx, sy + r + LABEL_H + LABEL_PAD], [sx + r + 4 + lw / 2 + LABEL_PAD, sy + 4], [sx - r - 4 - lw / 2 - LABEL_PAD, sy + 4],
+    ];
+    for (const [x, y] of spots) {
+      const b = box(x, y, lw);
+      if (!free(b)) continue;
+      take(b);
+      out.push({ i, x, y, a });
+      break;
+    }
+    take([sx - r, sy - r, sx + r, sy + r]); // later (lower-priority) labels never cover this dot
+  };
+  return { out, place };
+}
+
+/** Labels for one frame, in screen space (WIKI-GRAPH-DECLUTTER-1; both renderers, the 3D one through its projection).
+ *  Who gets a label, in priority order: the lit docs `lead` (focus, hover, then their neighbours; up to `cap`), then the
+ *  hubs (`degree` >= HUB_DEGREE) best-linked first, then, in "zoomed" mode, the rest best-linked first, fading in with zoom
+ *  (labelFade(k, labelK)). Docs past the lead stop at `budget` labels in all (labelBudget of the view). `mode` is lodFor's
+ *  `labels`: "focus" = the lead and the hubs only, "all" = everyone at full alpha. `order` is node indices best-linked first
+ *  (so the hubs are its prefix); `at(i)` gives [sx, sy, rPx]; `width(i)` the label's px width.
+ *  Collision: a label tries above its dot, then below, right and left, and takes the first spot that overlaps no drawn
+ *  label and no dot of a doc that came before it; a doc with no free spot gets no label. A uniform grid of LABEL_CELL px
+ *  cells holds the boxes, so a frame is linear in the docs looked at, not quadratic. Returns [{i, x, y, a}]: the text's
+ *  centre x, its baseline y, its alpha. */
+export function pickLabels({ lead, order, mode, cap, budget = cap, at, width, w, h, mask, degree = null, k = 1, labelK = 0 }) {
+  const { out, place: one } = createLabelPacker({ at, width, w, h, mask });
+  const leadSet = new Set();
+  for (const i of lead) { if (out.length >= cap) return out; leadSet.add(i); one(i, 1); }
+  const limit = Math.min(cap, budget), fade = labelFade(k, labelK);
+  for (const i of order) {
+    if (out.length >= limit) break;
+    if (leadSet.has(i)) continue;
+    const hub = !!degree && degree[i] >= HUB_DEGREE;
+    if (mode === "all") { one(i, 1); continue; }
+    if (hub) { one(i, 1); continue; }
+    if (mode === "focus" || fade < LABEL_ALPHA_MIN) break; // past the hubs: only zoomed in, once they are visible at all
+    one(i, fade);
+  }
+  return out;
+}
+
+/** Which renderer draws the graph: WebGL (Pixi) when the browser has it, else our Canvas2D drawing. `?renderer=canvas`
+ *  forces the fallback (the bench and reviewers use it). */
+export function chooseRenderer({ webgl, forced = null }) {
+  if (forced === "canvas") return "canvas";
+  return webgl ? "webgl" : "canvas";
+}
+
+/** WIKI-GRAPH-3D-1: which surface draws the graph. 3D is the main renderer (WebGL2 present and `view=2d` not asked), 2D
+ *  otherwise. `view=3d` without WebGL2 is still 2D (the page logs why once). */
+export const chooseView = ({ webgl2, requested = null }) => (requested === "2d" || !webgl2 ? "2d" : "3d");
+
+/** The one warning the fallback logs: what is lost without WebGL. */
+export const FALLBACK_WARNING = "wiki graph: WebGL is unavailable, drawing with Canvas2D instead. Lost: GPU drawing, so every "
+  + "frame is redrawn in full and panning a large graph is slower.";
+
+// WIKI-GRAPH-3D-COLOR-SPHERES-1: how a node LOOKS, one function for 3D and 2D so the two views never disagree. A doc is a plain
+// solid sphere in its group colour, a folder is a glass shell (translucent, full radius) round a solid core, a hub (one of the
+// best-linked docs) wears a white halo.
+export const LOOK = { DOC: 0, FOLDER: 1, HUB: 2 };
+export const HUB_SHARE = 0.02, HUB_MAX = 60, HUB_MIN_DEGREE = 8;
+/** The node indices that are hubs: docs only (never a folder), the best-linked first, at most ceil(2%) of the docs and 60,
+ *  and only with degree >= 8, so a sparse graph has none. Ties go to the lower index. */
+export function hubIndices(nodes) {
+  const docs = [];
+  for (let i = 0; i < nodes.length; i++) if (nodes[i].kind !== "folder" && (nodes[i].degree || 0) >= HUB_MIN_DEGREE) docs.push(i);
+  const total = nodes.reduce((t, nd) => t + (nd.kind === "folder" ? 0 : 1), 0);
+  docs.sort((a, b) => nodes[b].degree - nodes[a].degree || a - b);
+  return docs.slice(0, Math.min(HUB_MAX, Math.ceil(HUB_SHARE * total)));
+}
+/** One look per node (Uint8Array of LOOK values) for `nodes`, hubs from `hubIndices` unless given. */
+export function nodeLooks(nodes, hubs = hubIndices(nodes)) {
+  const out = new Uint8Array(nodes.length);
+  for (let i = 0; i < nodes.length; i++) out[i] = nodes[i].kind === "folder" ? LOOK.FOLDER : LOOK.DOC;
+  for (const i of hubs) out[i] = LOOK.HUB;
+  return out;
+}
+/** A folder's solid core is this fraction of its shell's radius. */
+export const CORE = 0.4;
+/** A hub's halo reaches this multiple of the doc's radius. */
+export const HALO = 1.3;
+/** The folder shell's opacity. */
+export const SHELL_ALPHA = 0.35;

package/src/graph/lib/graphViews.js

@@ -0,0 +1,103 @@
+// WIKI-GRAPH-EXPLORE-1c-UI round 5: saved views, a per-viewer list in this browser (design 11.3 a). Pure, no React, no three.
+// An entry is `{name, url, savedAt}` and, saved in 3D, `orient: {az, el, k}` (graphOrient: orientation round the orbit target, distance as a
+// multiple of the fit, never absolute coordinates) and `pins: [{id, x, y, z}]`. Camera and pins are never in the share URL.
+// Everything read back from storage is untrusted: its shape is checked here and a bad entry is dropped, never thrown on.
+import { cleanOrient } from "./graphOrient";
+import { readStoredList, writeStore } from "./graphShell";
+
+export const VIEWS_MAX = 50;
+export const SAVE_FAILED = "Couldn't save on this browser";
+const num = (v) => typeof v === "number" && Number.isFinite(v);
+
+/** The saved-views store key, one list per workspace. */
+export const viewsKey = (workspace) => `wiki.graph.views.${workspace}`;
+
+/** A pin read from storage: a non-empty string id and three finite numbers, else null. */
+export function cleanPin(p) {
+  return p && typeof p === "object" && typeof p.id === "string" && p.id && num(p.x) && num(p.y) && num(p.z) ? { id: p.id, x: p.x, y: p.y, z: p.z } : null;
+}
+
+/** One entry read from storage, made whole or null: it needs a non-empty string name, a string url and a finite savedAt. `orient`
+ *  (an object) goes through cleanOrient, a non-array `pins` is dropped, bad pins are dropped. */
+export function cleanView(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  if (typeof v.name !== "string" || !v.name.trim() || typeof v.url !== "string" || !num(v.savedAt)) return null;
+  const out = { name: v.name, url: v.url, savedAt: v.savedAt };
+  if (v.orient && typeof v.orient === "object" && !Array.isArray(v.orient)) out.orient = cleanOrient(v.orient);
+  if (Array.isArray(v.pins)) out.pins = v.pins.map(cleanPin).filter(Boolean);
+  return out;
+}
+
+/** A views list read from storage: a non-array is `[]`, a bad entry is dropped, a repeated name keeps its first (newest) entry, at most VIEWS_MAX. */
+export function cleanViews(raw) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const out = [];
+  for (const e of raw) {
+    const v = cleanView(e);
+    if (v && !seen.has(v.name)) { seen.add(v.name); out.push(v); }
+  }
+  return out.slice(0, VIEWS_MAX);
+}
+
+export const VIEWS_DISCARDED = "Graph: saved views in this browser were malformed and were dropped.";
+/** The stored views, newest first, shape-checked. Never throws; malformed stored state warns once with fixed text. */
+export const readViews = (workspace) => readStoredList(viewsKey(workspace), VIEWS_DISCARDED, (e) => cleanView(e) !== null, cleanViews);
+
+/** `list` with `entry` added at the front: a view of the same name is replaced, and past `max` the oldest go. */
+export const addView = (list, entry, max = VIEWS_MAX) => [entry, ...(Array.isArray(list) ? list : []).filter((v) => v.name !== entry.name)].slice(0, max);
+/** `list` without the view called `name`. */
+export const removeView = (list, name) => (Array.isArray(list) ? list : []).filter((v) => v.name !== name);
+
+/** A new entry. `url` is the page's own address (path and query, no origin). `orient` and `pins` are kept only when given (a 3D save); the
+ *  orientation is cleaned and the pins shape-checked, so the entry is always one `cleanView` would accept. */
+export function makeView({ name, url, orient, pins, now = Date.now() }) {
+  return cleanView({ name: String(name || "").trim(), url, savedAt: now, ...(orient ? { orient } : {}), ...(pins ? { pins } : {}) });
+}
+
+/** The name offered for a save: the chips' text joined, else `View <n>` (the first n not taken). */
+export function defaultViewName(chipTexts, list) {
+  const taken = new Set((Array.isArray(list) ? list : []).map((v) => v.name));
+  const chips = (chipTexts || []).filter(Boolean).join(", ").slice(0, 60);
+  if (chips) return chips;
+  let n = 1;
+  while (taken.has(`View ${n}`)) n++;
+  return `View ${n}`;
+}
+
+/** Save `entry` into the workspace's list: `{ok, list}`. When storage refuses, ok is false and `list` is the unchanged one. */
+export function saveView(workspace, entry) {
+  const cur = readViews(workspace);
+  const next = addView(cur, entry);
+  return writeStore(viewsKey(workspace), next) ? { ok: true, list: next } : { ok: false, list: cur };
+}
+/** Delete the view `name` from the workspace's list; returns the list now stored (the old one when storage refuses). */
+export function deleteView(workspace, name) {
+  const cur = readViews(workspace);
+  const next = removeView(cur, name);
+  return writeStore(viewsKey(workspace), next) ? next : cur;
+}
+
+/** The pins of a view that can be restored: only ids drawn in the restored view. `{pins, skipped}` (skipped = how many were not drawn). */
+export function restorablePins(pins, drawnIds) {
+  const list = Array.isArray(pins) ? pins : [];
+  const kept = list.filter((p) => drawnIds?.has?.(p.id));
+  return { pins: kept, skipped: list.length - kept.length };
+}
+
+/** The query part of a saved url as URLSearchParams (the page applies this; the path is ignored). A url with no query gives empty params. */
+export function paramsOfUrl(url) {
+  const s = String(url ?? "");
+  const q = s.indexOf("?");
+  if (q < 0) return new URLSearchParams();
+  const h = s.indexOf("#", q);
+  return new URLSearchParams(s.slice(q + 1, h < 0 ? undefined : h));
+}
+
+/** The status line after applying a view; `view` is "3d" or "2d", `skipped` the pins not drawn. */
+export function appliedText(v, view, skipped = 0) {
+  const parts = [`Applied "${v.name}".`];
+  if (view !== "3d" && (v.orient || v.pins?.length)) parts.push("Camera and pins apply in 3D only.");
+  if (view === "3d" && skipped > 0) parts.push(`${skipped} pinned ${skipped === 1 ? "doc is" : "docs are"} not in this view: skipped.`);
+  return parts.join(" ");
+}

package/src/graph/lib/groupBubbles.js

@@ -0,0 +1,128 @@
+// The "Cluster by group" helpers both canvases share. Pure: no three, no Pixi, no DOM.
+//
+// 3D (WIKI-GRAPH-CLUSTER-REGROUP-1): a clustered layout, plus an optional faint sphere round each group (`groupBubbles`,
+// `outlinesShown`). 2D (WIKI-GRAPH-2D-CLUSTER-ONCE-1, owner 2026-10-22: "it shouldn't show outlines in 2D but rather relayout
+// once then not relayout dynamically after that"): ONE clustered layout, then the positions stay put (`layout2d`); no outline
+// is ever drawn in 2D. Was WIKI-GRAPH-CLUSTER-NORELAYOUT-1: a hull round each group and the layout frozen where it was.
+//
+// Also the frozen-layout seeding: a doc that appears while the layout stays put (a filter, a level change, a data refresh) is
+// placed by `placeAppearing` from the docs that already have positions, and nothing else moves.
+
+export const BUBBLE_MIN_DOCS = 4; // a group with fewer visible docs gets no bubble
+export const BUBBLE_QUANTILE = 0.85; // the bubble reaches this share of its docs; outliers stay outside
+export const BUBBLE_HZ = 4; // while positions change, bubbles are recomputed at most this often
+// The one group-outline style for both surfaces (owner 2026-10-21, REGROUP addendum: the old shading was a defect). Was: 3D a
+// BackSide sphere at opacity 0.07 plus a FrontSide rim at 0.025 (about 0.09 a bubble, 7 overlapping bubbles stacked into one
+// blob), 2D a hull fill at 0.06 with a 0.3 line. Now: one flat layer at `fill`, a thin ring at `line`, `width` CSS px.
+export const OUTLINE_STYLE = Object.freeze({ fill: 0.04, line: 0.3, width: 1 });
+
+/** Whether group outlines are drawn: never with cluster off, never in 2D (WIKI-GRAPH-2D-CLUSTER-ONCE-1: the clusters show the
+ *  groups by position); in 3D only with the `outlines` toggle (`?outlines=1`), off by default. */
+export const outlinesShown = (dims, cluster, outlines = false) => !!cluster && dims === 3 && !!outlines;
+
+const GOLDEN = Math.PI * (3 - Math.sqrt(5));
+
+/** The bubble of each group: `[{group, centre, radius, members}]`, sorted by group name. `pos`: positions, `dims` (2 or 3)
+ *  floats a node. `groupOf(i)`: node i's group, or null for a node that belongs to none (a level view's folder). `visibleIdx`:
+ *  the visible node indices; hidden docs never count. `radiusOf(i)`: node i's world radius (0 when absent). `centre` is the
+ *  members' mean; `radius` the `quantile` (nearest rank) of each member's distance from it plus its own radius. A group with
+ *  fewer than `minDocs` visible members has no bubble. `members` holds every visible member, inside the radius or not. */
+export function groupBubbles(pos, dims, groupOf, visibleIdx, { minDocs = BUBBLE_MIN_DOCS, quantile = BUBBLE_QUANTILE, radiusOf = null } = {}) {
+  const byGroup = new Map();
+  for (const i of visibleIdx) {
+    const g = groupOf(i);
+    if (g === null || g === undefined) continue;
+    let l = byGroup.get(g);
+    if (!l) byGroup.set(g, (l = []));
+    l.push(i);
+  }
+  const out = [];
+  for (const [group, members] of byGroup) {
+    if (members.length < minDocs) continue;
+    const centre = new Array(dims).fill(0);
+    for (const i of members) for (let d = 0; d < dims; d++) centre[d] += pos[dims * i + d];
+    for (let d = 0; d < dims; d++) centre[d] /= members.length;
+    const reach = members.map((i) => {
+      let s = 0;
+      for (let d = 0; d < dims; d++) s += (pos[dims * i + d] - centre[d]) ** 2;
+      return Math.sqrt(s) + (radiusOf ? radiusOf(i) : 0);
+    }).sort((a, b) => a - b);
+    const radius = reach[Math.min(reach.length - 1, Math.max(0, Math.ceil(quantile * reach.length) - 1))];
+    out.push({ group, centre, radius, members });
+  }
+  return out.sort((a, b) => (a.group < b.group ? -1 : a.group > b.group ? 1 : 0));
+}
+
+/** Positions for the nodes that have none, without moving any node that has one (the frozen layout's seeding). `pos`: `dims`
+ *  floats a node, rewritten only at nodes whose `known[i]` is 0. A node is placed, in order of preference, at the mean of its
+ *  known neighbours (`pairs`: node index pairs), else at the mean of the known docs of its group (`groupOf`), else at the
+ *  mean of every known node; nodes that land on the same spot are fanned out a little round it (golden angle). With no known
+ *  node at all nothing is written (the caller keeps its seed). Returns the number of nodes placed. `groupFirst` (2D cluster,
+ *  WIKI-GRAPH-2D-CLUSTER-ONCE-1): the group's mean comes before the neighbours', so a new doc lands beside its own cluster even
+ *  when it links into another one. */
+export function placeAppearing(pos, dims, known, pairs, groupOf, { groupFirst = false } = {}) {
+  const n = known.length;
+  const sum = (idx) => {
+    if (!idx.length) return null;
+    const c = new Array(dims).fill(0);
+    for (const i of idx) for (let d = 0; d < dims; d++) c[d] += pos[dims * i + d];
+    return c.map((v) => v / idx.length);
+  };
+  const all = [], byGroup = new Map(), nbr = new Map();
+  for (let i = 0; i < n; i++) {
+    if (!known[i]) continue;
+    all.push(i);
+    const g = groupOf(i);
+    if (g !== null && g !== undefined) { if (!byGroup.has(g)) byGroup.set(g, []); byGroup.get(g).push(i); }
+  }
+  if (!all.length) return 0;
+  for (let e = 0; e < pairs.length; e += 2) {
+    const a = pairs[e], b = pairs[e + 1];
+    if (known[a] && !known[b]) { if (!nbr.has(b)) nbr.set(b, []); nbr.get(b).push(a); }
+    if (known[b] && !known[a]) { if (!nbr.has(a)) nbr.set(a, []); nbr.get(a).push(b); }
+  }
+  const everyone = sum(all), groupMean = new Map(), crowd = new Map();
+  let placed = 0;
+  for (let i = 0; i < n; i++) {
+    if (known[i]) continue;
+    const g = groupOf(i);
+    const ofGroup = () => {
+      if (g === null || g === undefined || !byGroup.has(g)) return null;
+      if (!groupMean.has(g)) groupMean.set(g, sum(byGroup.get(g)));
+      return groupMean.get(g);
+    };
+    const ofNbrs = () => (nbr.has(i) ? sum(nbr.get(i)) : null);
+    const c = (groupFirst ? ofGroup() || ofNbrs() : ofNbrs() || ofGroup()) || everyone;
+    const key = c.join(","), j = (crowd.get(key) || 0) + 1, r = 6 * Math.sqrt(j), a = j * GOLDEN;
+    crowd.set(key, j);
+    const off = dims === 3 ? [Math.cos(a) * r, Math.sin(a) * r, ((j % 2) ? 1 : -1) * 0.5 * r] : [Math.cos(a) * r, Math.sin(a) * r];
+    for (let d = 0; d < dims; d++) pos[dims * i + d] = c[d] + off[d];
+    placed++;
+  }
+  return placed;
+}
+
+/** 3D (WIKI-GRAPH-CLUSTER-DISJOINT-FU-1): is a new node set (a build) placed statically, with no layout run? Never with cluster
+ *  off. With cluster on (owner 2026-10-21 "3D regroups"), a set that overlaps the cache (`warm`) gets a warm clustered relayout and
+ *  a surface's first render is laid out, so only a disjoint set on a live surface is static. `live`: this surface has drawn nodes
+ *  before; `warm`: any node or parent was found in the cache. 2D has its own rule, `layout2d`. */
+export function placesStatically({ cluster, warm, live }) {
+  return !!cluster && live && !warm;
+}
+
+/** WIKI-GRAPH-2D-CLUSTER-ONCE-1: which layout the 2D canvas runs on `event`: "global" (the plain force layout), "cluster" (ONE
+ *  grouped layout: each group pulled to its own centre, run until it settles, then stopped) or null (no layout message at all,
+ *  nothing moves). Owner 2026-10-22: "relayout once then not relayout dynamically after that".
+ *  - "build" (a new node set): cluster off, "global". Cluster on: null when the clustered layout already settled on this surface
+ *    (`clustered`) and some node of the new set has a position here (`warm`: in the cache or under a cached parent), so the old
+ *    docs stay and only the new ones are placed beside their group; otherwise (a first render, a disjoint set, or a clustered
+ *    layout still running) "cluster".
+ *  - "toggle": cluster turned on, "cluster"; turned off, null (nothing moves; Resume / Reheat offer the plain layout again).
+ *  - "relayout" (the Reheat button): "cluster" with cluster on, else "global".
+ *  - anything else (hover, focus, find, legend filter, resize, a same-topology refresh, a slider): null. */
+export function layout2d({ event, cluster, clustered = false, warm = false }) {
+  if (event === "build") return !cluster ? "global" : clustered && warm ? null : "cluster";
+  if (event === "toggle") return cluster ? "cluster" : null;
+  if (event === "relayout") return cluster ? "cluster" : "global";
+  return null;
+}

package/src/graph/lib/hubLines.js

@@ -0,0 +1,51 @@
+// WIKI-GRAPH-DRIFT-LONG-EDGES-1: which containment pairs (hub -> child, graphLevels `contains`) are layout springs and which are
+// drawn, one rule for both canvases and both workers' callers.
+//
+// Measured (units/WIKI-GRAPH-DRIFT-LONG-EDGES-1/report.md, owner shape: a "units" hub with 1500 children, four small hubs, 1166
+// real links): every containment pair was a spring at the flat-link strength and a dashed line. The giant hub's 1500 springs
+// pulled every child onto one shell round it (3D R90 219 with them, 358 without) and its spokes were 0.8 R90 long, so the canvas
+// showed hundreds of dashed lines across the whole graph plus concentric rings. No spring setting makes 1500 spokes short.
+// So: a hub with more than HUB_SPRING_MAX children has no springs (its children are laid out by their own links) and draws its
+// lines only while it, or the child at the other end, is hovered or focused. A smaller hub keeps both: its children sit round it
+// (spoke median about one real-link median) and the lines read as "these are mine".
+export const HUB_SPRING_MAX = 50;
+
+/** Children per hub index over the flat pairs `cp` ([hub0, child0, hub1, child1, ...]). */
+export function hubCounts(cp) {
+  const out = new Map();
+  for (let e = 0; e < cp.length; e += 2) out.set(cp[e], (out.get(cp[e]) || 0) + 1);
+  return out;
+}
+
+const big = (counts, h) => (counts.get(h) || 0) > HUB_SPRING_MAX;
+
+/** The pairs of `cp` that are layout springs: those of a hub with at most HUB_SPRING_MAX children. */
+export function springPairs(cp, counts = hubCounts(cp)) {
+  const out = [];
+  for (let e = 0; e < cp.length; e += 2) if (!big(counts, cp[e])) out.push(cp[e], cp[e + 1]);
+  return Uint32Array.from(out);
+}
+
+/** The pairs of `cp` drawn as dashed lines: a small hub's always, a giant hub's only when an end is in `active` (node indices:
+ *  the hover, the focus; negative ones are ignored). */
+export function drawnPairs(cp, counts = hubCounts(cp), active = []) {
+  const on = new Set(active.filter((i) => i >= 0)), out = [];
+  for (let e = 0; e < cp.length; e += 2) {
+    const a = cp[e], b = cp[e + 1];
+    if (!big(counts, a) || on.has(a) || on.has(b)) out.push(a, b);
+  }
+  return Uint32Array.from(out);
+}
+
+/** drawnPairs for the overlay, which redraws every frame: recomputed only when `cp` or the active ends change (`memo` holds it). */
+export function drawnMemo(memo, cp, active) {
+  const key = active.join(",");
+  if (memo.cp !== cp || memo.key !== key) { memo.cp = cp; memo.key = key; memo.out = drawnPairs(cp, hubCounts(cp), active); }
+  return memo.out;
+}
+
+/** The pairs a layout worker gets: the real links `pairs`, then the springs of the containment pairs `cp` (springPairs). */
+export function layoutPairs(pairs, cp) {
+  const sp = springPairs(cp);
+  return sp.length ? Uint32Array.from([...pairs, ...sp]) : pairs;
+}