@smartmemory/wiki-components 0.4.0 → 0.6.0

package/src/graph/lib/graphLevels.js

@@ -0,0 +1,367 @@
+// WIKI-GRAPH-LEVELS-1 c1: the level / expand data model for the graph. Pure functions (no DOM, no React, no Pixi, no
+// coordinates), so the 2D page and the later 3D renderer (WIKI-GRAPH-3D-1) share one definition of what is visible.
+//
+// Input is the flat graph `buildGraph` (wikiGraph.js) returns: doc nodes `{id, folder, color, ...}` and links `{source, target}`.
+// A level is the set of expanded folder paths and nothing else. The empty set is level 0: one node per top-level folder.
+// Expanding a folder replaces it by its children (subfolders as folder nodes, docs directly in it as doc nodes).
+// The root (docs whose folder is "") is a virtual folder with path "" and id `folder:`: collapsed at level 0 like any other,
+// expanded by `expand(set, "")`. It is a sibling of the top-level folders, not their parent.
+
+/** Id prefix of a folder node. Doc ids are used as they are, so a doc id that starts with this prefix would collide. */
+export const FOLDER_PREFIX = "folder:";
+const SEP = "\u0000";
+// The shared "other" grey (wikiGraph OTHER, kept here so this module stays import-free; the folder-colour test pins the two).
+export const OTHER_COLOUR = "#7f8ea5";
+const ROOT_LABEL = "(root)";
+
+export const folderId = (path) => FOLDER_PREFIX + path;
+export const isFolderId = (id) => typeof id === "string" && id.startsWith(FOLDER_PREFIX);
+/** The folder path of a folder node id (`folder:docs/core` gives "docs/core"). */
+export const folderPathOf = (id) => id.slice(FOLDER_PREFIX.length);
+
+const segmentsOf = (path) => String(path || "").split("/").filter(Boolean);
+const cleanPath = (path) => segmentsOf(path).join("/");
+const parentPath = (path) => { const s = segmentsOf(path); return s.length > 1 ? s.slice(0, -1).join("/") : null; };
+
+/**
+ * @typedef {{id: string, kind: "doc"|"folder", parent: string|null, degree: number, [k: string]: any}} LevelNode
+ *   Doc nodes are copies of the input node plus `kind: "doc"`. Folder nodes carry `{path, label, size, depth, color}`.
+ *   `parent` is the id of the folder node this node sits under once that folder is expanded (null for top-level folders),
+ *   so a renderer can start new children at their parent's position when animating an expand.
+ *   `degree` is the summed weight of the node's links in the view.
+ * @typedef {{source: string, target: string, weight: number, ab: number, ba: number}} LevelLink  one per node pair
+ *   (`source` sorts before `target`). `weight` = `ab` + `ba`: `ab` counts the flat links running source -> target, `ba` those
+ *   running target -> source, so a renderer can draw arrowheads (WIKI-GRAPH-ARROWS-1).
+ */
+
+/**
+ * The view graph for a level.
+ * @param {{nodes: object[], links: {source: string, target: string}[]}} graph  the flat graph (`buildGraph` output)
+ * @param {Set<string>|string[]} [expanded]  expanded folder paths; empty is level 0
+ * @param {{visible?: (docId: string) => boolean}} [opts]  applied to docs BEFORE aggregation (legend hide set, local N-hop)
+ * @returns {{nodes: LevelNode[], links: LevelLink[]}}
+ */
+export function buildLevelGraph(graph, expanded = new Set(), { visible } = {}) {
+  const open = expanded instanceof Set ? expanded : new Set([...expanded].map(cleanPath));
+  // rep of a folder: the folder node id a doc in it collapses into, or null when every ancestor is expanded (the doc shows).
+  const repOfFolder = new Map();
+  const repFor = (folder) => {
+    let r = repOfFolder.get(folder);
+    if (r !== undefined) return r;
+    const segs = segmentsOf(folder);
+    if (!segs.length) r = open.has("") ? null : folderId("");
+    else {
+      r = null;
+      let path = "";
+      for (let i = 0; i < segs.length; i++) {
+        path = i ? path + "/" + segs[i] : segs[i];
+        if (!open.has(path)) { r = folderId(path); break; }
+      }
+    }
+    repOfFolder.set(folder, r);
+    return r;
+  };
+
+  const repOfDoc = new Map(); // doc id -> view node id, for visible docs only
+  const nodes = [];
+  const folders = new Map(); // folder node id -> node
+  const colours = new Map(); // folder node id -> Map(colour -> count)
+  for (const n of graph.nodes) {
+    if (visible && !visible(n.id)) continue;
+    const rep = repFor(n.folder || "");
+    if (rep === null) {
+      repOfDoc.set(n.id, n.id);
+      nodes.push({ ...n, kind: "doc", parent: folderId(cleanPath(n.folder)), degree: 0 });
+      continue;
+    }
+    repOfDoc.set(n.id, rep);
+    let f = folders.get(rep);
+    if (!f) {
+      const path = folderPathOf(rep), segs = segmentsOf(path);
+      f = { id: rep, kind: "folder", path, label: segs.length ? segs[segs.length - 1] : ROOT_LABEL, size: 0, depth: segs.length, parent: null, color: undefined, degree: 0 };
+      const pp = parentPath(path);
+      if (pp !== null) f.parent = folderId(pp);
+      folders.set(rep, f);
+      colours.set(rep, new Map());
+    }
+    f.size++;
+    if (n.color !== undefined) { const c = colours.get(rep); c.set(n.color, (c.get(n.color) || 0) + 1); }
+  }
+  // WIKI-GRAPH-P0-LEVEL0-ZOOM-1: a folder takes the most common NAMED colour of its docs (its leading area, say), so it
+  // matches a legend row; the shared "other" grey only when none of its docs has one. Grey used to win whenever a folder's
+  // docs were spread over many small groups that all share the grey (5 of 7 top folders on the bench fixture).
+  for (const [id, f] of folders) {
+    let best = 0;
+    for (const [c, k] of colours.get(id)) if (c !== OTHER_COLOUR && k > best) { best = k; f.color = c; }
+    if (f.color === undefined && colours.get(id).has(OTHER_COLOUR)) f.color = OTHER_COLOUR;
+  }
+  const out = [...folders.values(), ...nodes];
+
+  const byId = new Map(out.map((n) => [n.id, n]));
+  const agg = new Map();
+  for (const l of graph.links) {
+    const a = repOfDoc.get(l.source), b = repOfDoc.get(l.target);
+    if (a === undefined || b === undefined || a === b) continue;
+    const key = a < b ? a + SEP + b : b + SEP + a;
+    const fwd = a < b; // runs source -> target of the aggregated link
+    const hit = agg.get(key);
+    if (hit) { hit.weight++; if (fwd) hit.ab++; else hit.ba++; }
+    else agg.set(key, { source: fwd ? a : b, target: fwd ? b : a, weight: 1, ab: fwd ? 1 : 0, ba: fwd ? 0 : 1 });
+  }
+  const links = [...agg.values()];
+  for (const l of links) { byId.get(l.source).degree += l.weight; byId.get(l.target).degree += l.weight; }
+  return { nodes: out, links };
+}
+
+/** "Show all docs": today's flat graph. The same object back when nothing is filtered, otherwise the visible docs and the
+ *  links between them (original node and link objects, no `kind` or `weight`). */
+export function showAll(graph, visible) {
+  if (!visible) return graph;
+  const keep = new Set();
+  const nodes = graph.nodes.filter((n) => visible(n.id) && keep.add(n.id));
+  return { ...graph, nodes, links: graph.links.filter((l) => keep.has(l.source) && keep.has(l.target)) };
+}
+
+/** A new expanded set with `path` added. Ancestors are not added: a folder under a collapsed ancestor stays hidden until
+ *  the ancestor is expanded too (`buildLevelGraph` walks top-down). */
+export function expand(expanded, path) {
+  return new Set([...expanded, cleanPath(path)]);
+}
+
+/** A new expanded set without `path` and without every expanded descendant of it. */
+export function collapse(expanded, path) {
+  const p = cleanPath(path);
+  const under = p ? p + "/" : null; // the root has no descendants
+  return new Set([...expanded].filter((e) => e !== p && !(under && e.startsWith(under))));
+}
+
+/** The path `upOne` would collapse: the deepest expanded path (the most recently expanded among equals), or null. */
+export function currentLevel(expanded) {
+  let best = null, depth = -1;
+  for (const e of expanded) { const d = segmentsOf(e).length; if (d >= depth) { depth = d; best = e; } }
+  return best;
+}
+
+/** Up one level: collapse the deepest expanded path. */
+export function upOne(expanded) {
+  const best = currentLevel(expanded);
+  return best === null ? new Set(expanded) : collapse(expanded, best);
+}
+
+const MAX_LEVELS = 200, MAX_LEVEL_PATH = 512;
+
+/** The `lv=` URL value: expanded paths, each percent-encoded, comma separated; the root folder is a bare `/`. */
+export const formatLevels = (expanded) => [...expanded].sort().map((p) => (p === "" ? "/" : encodeURIComponent(p))).join(",");
+
+/** Parse `lv=` (never trusted): bounded, each path decoded (a malformed one is dropped) and cleaned, and only folders that
+ *  exist (`known`: every folder path of the graph, "" for the root) whose ancestors are all expanded too are kept, so a
+ *  hand-typed value can only open real folders. `base` (WIKI-GRAPH-LEVELS-AUTOEXPAND-1) is the set the page opens already
+ *  expanded: its paths count as expanded ancestors but are not part of the result. */
+export function parseLevels(value, known, base) {
+  const raw = new Set();
+  for (const part of String(value || "").split(",").slice(0, MAX_LEVELS)) {
+    if (!part || part.length > MAX_LEVEL_PATH) continue;
+    let path;
+    try { path = decodeURIComponent(part); } catch { continue; }
+    raw.add(cleanPath(path));
+  }
+  const out = new Set();
+  const shallowFirst = [...raw].sort((a, b) => segmentsOf(a).length - segmentsOf(b).length);
+  for (const p of shallowFirst) {
+    const up = parentPath(p);
+    if ((!known || known.has(p)) && (up === null || out.has(up) || (base && base.has(up)))) out.add(p);
+  }
+  return out;
+}
+
+/** Every folder path the docs sit in or under, plus "" when a doc is in the root: what `parseLevels` accepts. */
+export function folderPaths(graph) {
+  const out = new Set();
+  for (const n of graph.nodes) {
+    const segs = segmentsOf(n.folder);
+    if (!segs.length) out.add("");
+    for (let i = 1; i <= segs.length; i++) out.add(segs.slice(0, i).join("/"));
+  }
+  return out;
+}
+
+/** The ancestor chain of a folder, top-level first, ending with the folder itself: `a/b` gives `a`, `a/b`.
+ *  Does not include an "all" entry: the page adds it. The root gives one entry with path "". */
+export function breadcrumb(path) {
+  const segs = segmentsOf(path);
+  if (!segs.length) return [{ path: "", label: ROOT_LABEL, id: folderId("") }];
+  return segs.map((label, i) => { const p = segs.slice(0, i + 1).join("/"); return { path: p, label, id: folderId(p) }; });
+}
+
+/** The page's base level (WIKI-GRAPH-LEVELS-AUTOEXPAND-1): while the view is ONE folder node, expand it, so the page never
+ *  opens on a single dot. Stops at more than one node, at a lone doc, or at an empty view; bounded by the folder count, so it
+ *  cannot loop. Not part of `lv=`: the URL holds the reader's own expansions on top of this set.
+ *  @param {{nodes: object[], links: object[]}} graph  the flat graph
+ *  @param {(docId: string) => boolean} [visible]  the same predicate the page's level view uses
+ *  @returns {Set<string>} expanded folder paths (empty when level 0 already has several nodes) */
+export function autoBase(graph, visible) {
+  let base = new Set();
+  for (let i = folderPaths(graph).size + 1; i > 0; i--) {
+    const { nodes } = buildLevelGraph(graph, base, { visible });
+    if (nodes.length !== 1 || nodes[0].kind !== "folder") break;
+    base = expand(base, nodes[0].path);
+  }
+  return base;
+}
+
+// WIKI-GRAPH-LEVELS-3D-1: depth ranges, hub folders and containment edges, on top of the model above (nothing above changes).
+//
+// A LEVEL is how deep a thing sits below what the page opens on. Level 1 is the page's opening view: the top-level folders
+// (and the "(root)" folder of the docs at the top), or, when the workspace opens auto-expanded (`autoBase`), the children of
+// the deepest base folder. A folder's sub-folders and the docs directly in it are one level below it. "Levels 1-2" draws every
+// level-1 folder as a HUB (it stays on screen, with a dashed containment edge to each of its drawn children) and every level-2
+// folder or doc as its own node, with the docs below level 2 collapsed into their level-2 folder. "Levels 2-3" is the same one
+// level down: level-1 folders are opened but not drawn. A range is [from, to] with 1 <= from <= to <= maxLevel.
+
+/** How many levels the base (autoBase) opened: the deepest base path's segment count (0 without a base). */
+export function baseOffset(base) {
+  let d = 0;
+  for (const p of base || []) d = Math.max(d, segmentsOf(p).length);
+  return d;
+}
+
+/** The level of a folder path (see above). The root folder ("") is level 1, a sibling of the top-level folders. */
+export const levelOf = (path, offset = 0) => (cleanPath(path) === "" ? 1 : segmentsOf(path).length - offset);
+
+/** The deepest level any doc sits at (a doc is one level below its folder), 0 for an empty workspace. */
+export function maxLevel(graph, offset = 0) {
+  let m = 0;
+  for (const n of graph.nodes) m = Math.max(m, levelOf(n.folder || "", offset) + 1);
+  return m;
+}
+
+/** The expanded set that shows levels `from`..`to`: the base plus every folder above level `to` (levels 1..to-1), so every
+ *  level-`to` folder is drawn collapsed with its docs inside it. `from` does not change what is expanded, only what is drawn
+ *  (`hubsFor`). `to` past the deepest level opens everything; `to` < 1 is level 1. */
+export function expandToDepth(graph, from, to, { base = null } = {}) {
+  const offset = baseOffset(base), out = new Set(base || []);
+  const top = Math.max(1, Math.round(Number(to)) || 1);
+  for (const p of folderPaths(graph)) {
+    const l = levelOf(p, offset);
+    if (l >= 1 && l < top) out.add(p);
+  }
+  return out;
+}
+
+/** The expanded folders drawn as hubs: every expanded path that is not in the base and sits at level `from` or deeper.
+ *  Shallower expanded folders are opened but not drawn (the range starts below them). */
+export function hubsFor(expanded, from = 1, { base = null } = {}) {
+  const offset = baseOffset(base), out = new Set();
+  for (const p of expanded) if (!(base && base.has(p)) && levelOf(p, offset) >= from) out.add(p);
+  return out;
+}
+
+/** `buildLevelGraph` plus hubs: every path in `hubs` that is expanded stays drawn as a folder node (`hub: true`, size = the
+ *  visible docs under it, majority colour), and `contains` holds one containment edge `{source: hub id, target: child id}`
+ *  per drawn node whose parent is a hub. Containment edges are not links: they carry no weight, add no degree and never
+ *  aggregate; `links` is exactly `buildLevelGraph`'s. A hub has no link edges (its docs are drawn on their own). */
+export function buildLevelView(graph, expanded = new Set(), { visible, hubs } = {}) {
+  const lg = buildLevelGraph(graph, expanded, { visible });
+  const open = expanded instanceof Set ? expanded : new Set([...expanded].map(cleanPath));
+  const want = new Set([...(hubs || [])].map(cleanPath).filter((p) => open.has(p)));
+  if (!want.size) return { ...lg, contains: [] };
+  const made = new Map(), colours = new Map();
+  for (const n of graph.nodes) {
+    if (visible && !visible(n.id)) continue;
+    const segs = segmentsOf(n.folder);
+    const chain = segs.length ? segs.map((_, i) => segs.slice(0, i + 1).join("/")) : [""];
+    for (const p of chain) {
+      if (!want.has(p)) continue;
+      let h = made.get(p);
+      if (!h) {
+        const ps = segmentsOf(p), pp = parentPath(p);
+        h = { id: folderId(p), kind: "folder", hub: true, path: p, label: ps.length ? ps[ps.length - 1] : ROOT_LABEL, size: 0, depth: ps.length,
+          parent: pp === null ? null : folderId(pp), color: undefined, degree: 0 };
+        made.set(p, h);
+        colours.set(p, new Map());
+      }
+      h.size++;
+      if (n.color !== undefined) { const c = colours.get(p); c.set(n.color, (c.get(n.color) || 0) + 1); }
+    }
+  }
+  for (const [p, h] of made) {
+    let best = 0;
+    for (const [c, k] of colours.get(p)) if (k > best) { best = k; h.color = c; }
+  }
+  const nodes = [...made.values(), ...lg.nodes];
+  const hubIds = new Set([...made.values()].map((h) => h.id));
+  const contains = [];
+  for (const n of nodes) if (n.parent && hubIds.has(n.parent)) contains.push({ source: n.parent, target: n.id });
+  return { nodes, links: lg.links, contains };
+}
+
+/** The view nodes a drill into folder node `id` frames: the folder itself (when drawn, as a hub) and every drawn node whose
+ *  parent it is. In the flat graph (All docs: doc nodes carry `folder` but no `parent`) it is every doc in that folder or under it.
+ *  Returns node indices into `nodes`; empty when the folder has nothing drawn (the caller fits everything). */
+export function drillTargets(nodes, id) {
+  const out = [];
+  if (!id) return out;
+  const path = isFolderId(id) ? folderPathOf(id) : null;
+  const under = (n) => path !== null && n.kind !== "folder" && n.parent === undefined && typeof n.folder === "string"
+    && (path === "" || cleanPath(n.folder) === path || cleanPath(n.folder).startsWith(path + "/"));
+  for (let i = 0; i < nodes.length; i++) if (nodes[i].id === id || nodes[i].parent === id || under(nodes[i])) out.push(i);
+  return out;
+}
+
+/** Collapse seeding: positions for folder nodes of `next` that were NOT drawn in `prev` but whose docs or sub-folders were,
+ *  each at the centroid of those visible descendants' positions (`posOf(i)` gives prev node i's [x, y(, z)]), so collapsing
+ *  pulls the children together where they were instead of jumping to a fresh seed. Returns Map(folder id -> position). */
+export function collapseCentroids(prev, posOf, next) {
+  const had = new Set(prev.map((n) => n.id));
+  const want = new Map(); // folder path -> folder id, for new folders only
+  for (const n of next) if (n.kind === "folder" && !had.has(n.id)) want.set(n.path, n.id);
+  const sums = new Map();
+  if (!want.size) return sums;
+  for (let i = 0; i < prev.length; i++) {
+    const n = prev[i], segs = segmentsOf(n.kind === "folder" ? n.path : n.folder);
+    const chain = n.kind === "folder" ? segs.slice(0, -1) : segs; // a folder is under its ancestors, a doc under its folder too
+    const paths = chain.map((_, j) => chain.slice(0, j + 1).join("/"));
+    if (n.kind !== "folder" && !segs.length) paths.push(""); // a root doc sits under the root folder
+    const p = posOf(i);
+    if (!p || p.some((v) => !Number.isFinite(v))) continue;
+    for (const path of paths) {
+      const id = want.get(path);
+      if (id === undefined) continue;
+      let s = sums.get(id);
+      if (!s) sums.set(id, (s = { k: 0, v: new Array(p.length).fill(0) }));
+      s.k++;
+      for (let d = 0; d < p.length; d++) s.v[d] += p[d];
+    }
+  }
+  const out = new Map();
+  for (const [id, s] of sums) out.set(id, s.v.map((v) => v / s.k));
+  return out;
+}
+
+/** The `lr=` URL value of a range: "2" or "1-3". */
+export const formatRange = (r) => (!r ? "" : r[0] === r[1] ? String(r[0]) : `${r[0]}-${r[1]}`);
+
+/** Parse `lr=` (never trusted): "N" or "A-B", whole numbers, clamped to 1..max, swapped when reversed. Null when empty or
+ *  malformed, or when there are no levels (max < 1): the page then uses its default. */
+export function parseRange(value, max) {
+  if (!(max >= 1)) return null;
+  const m = /^\s*(\d{1,4})\s*(?:-\s*(\d{1,4})\s*)?$/.exec(String(value ?? ""));
+  if (!m) return null;
+  const clamp = (v) => Math.max(1, Math.min(max, Number(v)));
+  const a = clamp(m[1]), b = clamp(m[2] ?? m[1]);
+  return a <= b ? [a, b] : [b, a];
+}
+
+/** The picker's level chips: toggle level `k` in the shown range and snap the selection to the range that covers it. A
+ *  click outside the range extends it to `k` (over a gap the levels between come too, `snapped`); a click on an end shrinks it
+ *  by one; a click on a middle level would leave a gap, so the range stays (`snapped`). `snapped` tells the UI to say that
+ *  levels show as a range. The last level never turns off. */
+export function toggleLevel(range, k) {
+  const [a, b] = range;
+  if (k < a) return { range: [k, b], snapped: k < a - 1 }; // 1 picked with 3-4 on: 2 comes with it
+  if (k > b) return { range: [a, k], snapped: k > b + 1 };
+  if (a === b) return { range, snapped: false };
+  if (k === a) return { range: [a + 1, b], snapped: false };
+  if (k === b) return { range: [a, b - 1], snapped: false };
+  return { range, snapped: true };
+}

package/src/graph/lib/graphOrient.js

@@ -0,0 +1,145 @@
+// WIKI-GRAPH-EXPLORE-1c-UI round 4: the 3D camera's orientation as numbers a saved view can keep (round 5 reuses this codec).
+// Orientation is relative to the fit, never absolute coordinates: azimuth and elevation in degrees round the orbit target, and
+// `k`, the camera distance as a multiple of the fit distance, so the same view still frames the same way on a different graph size.
+// Convention: offset = d * (cos el * sin az, sin el, cos el * cos az). az 0 / el 0 looks from +Z (the default view: the camera
+// starts on +Z, three-base `camera.position.set(0, 0, 400)`); az +90 looks from +X; el +90 from +Y. Pure, no three.
+
+export const DEFAULT_ORIENT = Object.freeze({ az: 0, el: 0, k: 1 });
+/** Elevation clamp: OrbitControls allows the poles themselves, where `up` x view degenerates, so a snap stops one degree short. */
+export const EL_MAX = 89;
+
+const RAD = Math.PI / 180;
+const num = (v) => typeof v === "number" && Number.isFinite(v);
+const vec = (v) => Array.isArray(v) && v.length >= 3 && num(v[0]) && num(v[1]) && num(v[2]);
+
+/** An angle wrapped into (-180, 180]. */
+export function wrapAz(a) {
+  const w = ((((a + 180) % 360) + 360) % 360) - 180; // [-180, 180)
+  return w === -180 ? 180 : w;
+}
+
+/** Any partial or bad `{az, el, k}` made whole: a missing, non-finite or (for k) non-positive field takes its default, az is
+ *  wrapped, el clamped to +-EL_MAX. Never NaN. */
+export function cleanOrient(o) {
+  const src = o && typeof o === "object" ? o : {};
+  return {
+    az: num(src.az) ? wrapAz(src.az) : DEFAULT_ORIENT.az,
+    el: num(src.el) ? Math.max(-EL_MAX, Math.min(EL_MAX, src.el)) : DEFAULT_ORIENT.el,
+    k: num(src.k) && src.k > 0 ? src.k : DEFAULT_ORIENT.k,
+  };
+}
+
+/** `{az, el, k}` of a camera at `cameraPos` looking at `target`, with `fitDist` the fit distance. A bad input, a camera on its
+ *  target or a non-positive fit distance gives the default orientation. */
+export function orientationOf(target, cameraPos, fitDist) {
+  if (!vec(target) || !vec(cameraPos) || !num(fitDist) || fitDist <= 0) return { ...DEFAULT_ORIENT };
+  const dx = cameraPos[0] - target[0], dy = cameraPos[1] - target[1], dz = cameraPos[2] - target[2];
+  const d = Math.hypot(dx, dy, dz);
+  if (!(d > 1e-9)) return { ...DEFAULT_ORIENT };
+  return cleanOrient({ az: Math.atan2(dx, dz) / RAD, el: Math.asin(Math.max(-1, Math.min(1, dy / d))) / RAD, k: d / fitDist });
+}
+
+/** The camera position for orientation `o` round `target` at fit distance `fitDist`. Bad parts fall back to the default
+ *  (target to the origin, fit distance to 1), so the result is always three finite numbers. */
+export function cameraFor(target, o, fitDist) {
+  const t = vec(target) ? target : [0, 0, 0];
+  const f = num(fitDist) && fitDist > 0 ? fitDist : 1;
+  const { az, el, k } = cleanOrient(o);
+  const d = k * f, ce = Math.cos(el * RAD);
+  return [t[0] + d * ce * Math.sin(az * RAD), t[1] + d * Math.sin(el * RAD), t[2] + d * ce * Math.cos(az * RAD)];
+}
+
+/** The orientation that looks along a gizmo axis (`+x`, `-x`, `+y`, `-y`, `+z`, `-z`), or the front (`front`); `cur` is the
+ *  current orientation. The Y axes keep the current azimuth (a pole has none: keeping it spares a spin). null for any other name. */
+export const SNAPS = Object.freeze({
+  "+x": () => ({ az: 90, el: 0 }),
+  "-x": () => ({ az: -90, el: 0 }),
+  "+y": (cur) => ({ az: cur.az, el: EL_MAX }),
+  "-y": (cur) => ({ az: cur.az, el: -EL_MAX }),
+  "+z": () => ({ az: 0, el: 0 }),
+  "-z": () => ({ az: 180, el: 0 }),
+  front: () => ({ az: 0, el: 0 }),
+});
+export function snapOrient(name, cur) {
+  const f = Object.prototype.hasOwnProperty.call(SNAPS, name) ? SNAPS[name] : null;
+  if (!f) return null;
+  const c = cleanOrient(cur);
+  return { ...f(c), k: c.k }; // the distance (k) is never changed by a snap
+}
+
+/** The three world axes as the camera sees them: `right` and `up` are the screen axes (up is up on screen), `depth` > 0 is
+ *  toward the viewer. Eye and target as for orientationOf; the camera's up is world +Y (what OrbitControls keeps). Each entry is
+ *  `{name, sx, sy, depth}` for +x, -x, +y, -y, +z, -z. A camera on its target gives the default view's axes. */
+export function gizmoAxes(target, cameraPos) {
+  let f = [0, 0, -1];
+  if (vec(target) && vec(cameraPos)) {
+    const d = [target[0] - cameraPos[0], target[1] - cameraPos[1], target[2] - cameraPos[2]], n = Math.hypot(d[0], d[1], d[2]);
+    if (n > 1e-9) f = [d[0] / n, d[1] / n, d[2] / n];
+  }
+  // right = forward x worldUp, normalised (a camera straight above or below: the x axis); up = right x forward
+  let r = [-f[2], 0, f[0]];
+  const rn = Math.hypot(r[0], r[1], r[2]);
+  r = rn > 1e-9 ? [r[0] / rn, 0, r[2] / rn] : [1, 0, 0];
+  const u = [r[1] * f[2] - r[2] * f[1], r[2] * f[0] - r[0] * f[2], r[0] * f[1] - r[1] * f[0]];
+  const out = [];
+  for (const [name, a] of [["+x", [1, 0, 0]], ["-x", [-1, 0, 0]], ["+y", [0, 1, 0]], ["-y", [0, -1, 0]], ["+z", [0, 0, 1]], ["-z", [0, 0, -1]]]) {
+    out.push({ name, sx: r[0] * a[0] + r[1] * a[1] + r[2] * a[2], sy: u[0] * a[0] + u[1] * a[1] + u[2] * a[2], depth: -(f[0] * a[0] + f[1] * a[1] + f[2] * a[2]) });
+  }
+  return out;
+}
+
+/** A point on the turn from camera position `p0` to `p1` round `t`: the direction slerps and the distance goes linearly, so a
+ *  half turn never passes through the target (a straight lerp from +Z to -Z would). `u` in [0, 1]. An antipodal pair turns
+ *  about the world Y axis (about X when it sits on Y). Bad input returns `p1`. */
+export function arcPoint(t, p0, p1, u) {
+  if (!vec(t) || !vec(p0) || !vec(p1) || !num(u)) return vec(p1) ? [p1[0], p1[1], p1[2]] : [0, 0, 0];
+  const a = [p0[0] - t[0], p0[1] - t[1], p0[2] - t[2]], b = [p1[0] - t[0], p1[1] - t[1], p1[2] - t[2]];
+  const da = Math.hypot(a[0], a[1], a[2]), db = Math.hypot(b[0], b[1], b[2]);
+  if (da < 1e-9 || db < 1e-9) return [t[0] + (b[0] - a[0]) * u + a[0], t[1] + (b[1] - a[1]) * u + a[1], t[2] + (b[2] - a[2]) * u + a[2]];
+  const ua = a.map((v) => v / da), ub = b.map((v) => v / db);
+  const dot = Math.max(-1, Math.min(1, ua[0] * ub[0] + ua[1] * ub[1] + ua[2] * ub[2]));
+  const ang = Math.acos(dot);
+  let dir;
+  if (ang < 1e-6) dir = ub;
+  else {
+    let axis;
+    if (Math.PI - ang < 1e-6) { // antipodal: any axis perpendicular to ua will do, Y unless ua is on it
+      const ay = Math.abs(ua[1]) > 0.999 ? [1, 0, 0] : [0, 1, 0];
+      axis = [ua[1] * ay[2] - ua[2] * ay[1], ua[2] * ay[0] - ua[0] * ay[2], ua[0] * ay[1] - ua[1] * ay[0]];
+      const n = Math.hypot(axis[0], axis[1], axis[2]);
+      axis = axis.map((v) => v / n);
+      // rotate ua about `axis` by pi*u: ua*cos + (axis x ua)*sin (axis is perpendicular to ua, so no parallel term)
+      const th = Math.PI * u, c = Math.cos(th), s = Math.sin(th);
+      const cr = [axis[1] * ua[2] - axis[2] * ua[1], axis[2] * ua[0] - axis[0] * ua[2], axis[0] * ua[1] - axis[1] * ua[0]];
+      dir = [ua[0] * c + cr[0] * s, ua[1] * c + cr[1] * s, ua[2] * c + cr[2] * s];
+    } else {
+      const s = Math.sin(ang), wa = Math.sin((1 - u) * ang) / s, wb = Math.sin(u * ang) / s;
+      dir = [ua[0] * wa + ub[0] * wb, ua[1] * wa + ub[1] * wb, ua[2] * wa + ub[2] * wb];
+    }
+  }
+  const d = da + (db - da) * u;
+  return [t[0] + dir[0] * d, t[1] + dir[1] * d, t[2] + dir[2] * d];
+}
+
+/** Keyboard step (WIKI-GRAPH-3D-POLISH-1 r1). Shift+Left/Right turn the azimuth, Shift+Up/Down tilt the elevation, by STEP_DEG
+ *  (el clamped to +-EL_MAX); `+`/`=` zoom in and `-`/`_` out by ZOOM_STEP (k clamped to K_MIN..K_MAX); `0` is the front view at
+ *  the current k (as the gizmo's Front). `shift` is the Shift state: only the arrows need it. Always relative to `o` (an
+ *  orientation about the orbit target), never a camera position. Unknown key: null. `o` goes through cleanOrient first. */
+export const STEP_DEG = 15;
+export const ZOOM_STEP = 0.8;
+export const K_MIN = 0.2;
+export const K_MAX = 5;
+export function stepOrient(o, key, shift = false) {
+  const c = cleanOrient(o);
+  const kz = (f) => Math.max(K_MIN, Math.min(K_MAX, c.k * f));
+  if (shift) {
+    if (key === "ArrowLeft") return cleanOrient({ ...c, az: c.az - STEP_DEG });
+    if (key === "ArrowRight") return cleanOrient({ ...c, az: c.az + STEP_DEG });
+    if (key === "ArrowUp") return cleanOrient({ ...c, el: c.el + STEP_DEG });
+    if (key === "ArrowDown") return cleanOrient({ ...c, el: c.el - STEP_DEG });
+  }
+  if (key === "+" || key === "=") return { ...c, k: kz(ZOOM_STEP) };
+  if (key === "-" || key === "_") return { ...c, k: kz(1 / ZOOM_STEP) };
+  if (key === "0") return { ...DEFAULT_ORIENT, k: c.k };
+  return null;
+}

package/src/graph/lib/graphPath.js

@@ -0,0 +1,86 @@
+// WIKI-GRAPH-EXPLORE-1c-UI round 3: the path lens, pure half (no DOM, no React, no canvas). A path lens (`@path:from:to` in the `x`
+// param) marks the shortest undirected path between two docs and never removes anything (design WIKI-GRAPH-EXPLORE-1 §3, §6).
+// The page lights the path's docs and links through the canvas `marks` (`lit`, `links`) and dims the rest at the dim level.
+import { applyLenses, normaliseLens } from "./graphExplore";
+import { drawnFor, findMatches } from "./graphFind";
+
+/** The state's path lens (the last one when the URL holds several), or null. */
+export const pathLens = (state) => [...(state?.lenses || [])].reverse().find((l) => l.lens === "path") || null;
+
+/** Set the path lens: it replaces any earlier path lens, keeps the other lenses and every step. Returns the same state when nothing
+ *  changes (an invalid pair, or the same pair again). */
+export function setPathLens(state, from, to) {
+  const lens = normaliseLens({ lens: "path", from, to });
+  if (!lens) return state;
+  const cur = pathLens(state);
+  if (cur && cur.from === lens.from && cur.to === lens.to && state.lenses.filter((l) => l.lens === "path").length === 1) return state;
+  return { ...state, lenses: [...state.lenses.filter((l) => l.lens !== "path"), lens] };
+}
+
+/** Remove lens `i` (out of range: the same state). */
+export const removeLens = (state, i) => (i < 0 || i >= state.lenses.length ? state : { ...state, lenses: state.lenses.filter((_, j) => j !== i) });
+
+/** Drop every path lens (the Esc step). Returns the same state when there is none. */
+export const clearPathLens = (state) => (state.lenses.some((l) => l.lens === "path") ? { ...state, lenses: state.lenses.filter((l) => l.lens !== "path") } : state);
+
+const norm = (t) => String(t || "").trim().toLowerCase();
+
+/** The doc a typed first argument means: the exact title (case-insensitive) when a doc has one, else the top title match, else null.
+ *  `nodes`: the graph's docs, `visible`: findMatches' predicate. */
+export function pickDoc(nodes, text, visible) {
+  const q = norm(text);
+  if (!q) return null;
+  const exact = nodes.find((n) => norm(n.title) === q && (!visible || visible(n.id)));
+  return exact || findMatches(nodes, text, visible)[0] || null;
+}
+
+/** Read the text after `path`: `{ from, left, right, hasTo }`. The first ` to ` whose two sides both read as docs splits them (an exact
+ *  title wins over a prefix match, so a title that holds "to" still works); `from` is that doc (null when none), `right` the second
+ *  argument ("" while it is not typed). With no ` to ` the whole text is the first argument. */
+export function splitPathArgs(rest, nodes, visible) {
+  const text = String(rest || "").trim();
+  const cands = [...text.matchAll(/\s+to(?=\s|$)/gi)].map((m) => ({ left: text.slice(0, m.index).trim(), right: text.slice(m.index + m[0].length).trim() }));
+  if (!cands.length) return { from: pickDoc(nodes, text, visible), left: text, right: "", hasTo: false };
+  const isExact = (c) => !!c.left && nodes.some((n) => norm(n.title) === norm(c.left) && (!visible || visible(n.id)));
+  const leftHit = (c) => !!c.left && findMatches(nodes, c.left, visible).length > 0;
+  const rightOk = (c) => !c.right || findMatches(nodes, c.right, visible).length > 0; // the second argument is empty (still typing) or names a doc
+  const any = cands.find((c) => isExact(c) && rightOk(c)) || cands.find((c) => leftHit(c) && rightOk(c)) || cands.find(isExact) || cands.find(leftHit) || cands[0];
+  return { from: pickDoc(nodes, any.left, visible), left: any.left, right: any.right, hasTo: true };
+}
+
+/** The drawn marks for a path (ordered doc ids, or null): `{ lit: Set<drawn id>, links: [a, b][], folders: string[] }`. Each path doc
+ *  shows as itself when drawn, else as the folder that holds it (graphFind drawnFor); a doc nothing draws is skipped. `links` joins
+ *  the drawn nodes of consecutive path docs (none for two docs that share a folder node). `folders`: the lit ids that are folders
+ *  standing in for hidden docs. Null when there is no path or nothing on it is drawn. */
+export function pathLit(path, drawnIds, byId) {
+  if (!path || !path.length || !drawnIds) return null;
+  const shown = path.map((id) => { const d = byId.get(id); return d ? drawnFor(d, drawnIds) : null; });
+  const lit = new Set(shown.filter((id) => id !== null));
+  if (!lit.size) return null;
+  const links = [], seen = new Set();
+  for (let i = 0; i + 1 < shown.length; i++) {
+    const a = shown[i], b = shown[i + 1];
+    if (a === null || b === null || a === b) continue;
+    const key = a < b ? `${a}\u0000${b}` : `${b}\u0000${a}`;
+    if (!seen.has(key)) { seen.add(key); links.push([a, b]); }
+  }
+  const onPath = new Set(path);
+  return { lit, links, folders: [...lit].filter((id) => !onPath.has(id)) };
+}
+
+/** What the page draws for the state's path lens: `{ lens, path, marks: { lit, links } | null, folders }`, or null with no path lens.
+ *  `path` is the ordered ids (null: no path, nothing is dimmed). */
+export function pathView(state, idx, drawnIds, byId) {
+  const lens = pathLens(state);
+  if (!lens || !idx) return null;
+  const path = applyLenses(idx, [lens]).path;
+  const lit = pathLit(path, drawnIds, byId);
+  return { lens, path, marks: lit ? { lit: lit.lit, links: lit.links } : null, folders: lit ? lit.folders : [] };
+}
+
+/** The line under the canvas when a path crosses a collapsed folder ("" when every path doc is drawn). `folders`: pathView's ids,
+ *  `title(id)` names one. */
+export function pathNote(folders, title) {
+  if (!folders.length) return "";
+  return `${folders.length === 1 ? "A folder" : `${folders.length} folders`} stand${folders.length === 1 ? "s" : ""} in for path docs: ${folders.map(title).join(", ")}. Open ${folders.length === 1 ? "it" : "them"} to see the docs.`;
+}

package/src/graph/lib/graphPin.js

@@ -0,0 +1,48 @@
+// WIKI-GRAPH-EXPLORE-1c-UI round 2: drag-to-pin on the 3D surface (3D-UX-1 REPORT row "drag-to-pin": move in the camera-facing plane
+// at the dot's depth, pin fx/fy/fz in the worker, pins per surface). The pure parts: which press arms a pin drag, when a drag has
+// started, and the pointer-to-plane math. The canvas owns the pointer events, the worker owns the pin itself (forceWorker3d `pin`).
+
+/** True when a press starts a pin drag: a plain left-button mouse press (no modifier: Shift is the lasso, Alt/Ctrl/Meta pan or menu,
+ *  touch turns) that lands on a doc, on a canvas that was given an `onPin`. `e` = {pointerType, button, shiftKey, altKey, ctrlKey, metaKey}. */
+export function pinArmed(e, onDot, enabled = true) {
+  if (!enabled || !onDot) return false;
+  if (e.pointerType === "touch") return false;
+  return (e.button ?? 0) === 0 && !e.shiftKey && !e.altKey && !e.ctrlKey && !e.metaKey;
+}
+
+/** The drag decision: a press that has moved more than `px` from where it went down is a drag, anything less stays a click. */
+export const dragStarted = (x0, y0, x, y, px) => Math.hypot(x - x0, y - y0) > px;
+
+/** The camera as the plane math wants it, from a three camera's `matrixWorld.elements` (column-major: right, up, back), its eye and
+ *  `focal` (px per world unit at distance 1, threeBase frame()). */
+export function cameraOf(elements, eye, focal) {
+  const e = elements;
+  return { eye: [eye[0], eye[1], eye[2]], right: [e[0], e[1], e[2]], up: [e[4], e[5], e[6]], forward: [-e[8], -e[9], -e[10]], focal };
+}
+
+/** The world point under screen px (x, y) on the plane facing the camera at view depth `depth` (distance along the view axis, the
+ *  projected w of a dot). A `w` x `h` px surface, y down. Inverse of graph3d `project` for that plane. */
+export function planePoint(cam, w, h, x, y, depth) {
+  const k = depth / cam.focal, a = (x - w / 2) * k, b = -(y - h / 2) * k;
+  return [0, 1, 2].map((i) => cam.eye[i] + cam.forward[i] * depth + cam.right[i] * a + cam.up[i] * b);
+}
+
+/** Where the dot goes for a pointer at (x, y): the plane point plus `offset`, the press-time gap between the dot and the plane
+ *  point under the pointer (so the dot does not jump to the pointer, it follows it 1:1). */
+export const pinTarget = (cam, w, h, x, y, depth, offset) => planePoint(cam, w, h, x, y, depth).map((v, i) => v + offset[i]);
+
+/** The offset to carry through a drag that went down at (x, y) on a dot at world `p` and view depth `depth`. */
+export const pinOffset = (cam, w, h, x, y, depth, p) => planePoint(cam, w, h, x, y, depth).map((v, i) => p[i] - v);
+
+/** Write every pin (`pins`: Map id -> [x, y, z]) into `xyz` at its doc's index (`index`: Map id -> i); an id the surface no longer has
+ *  is skipped. Returns how many it wrote. Used after a worker frame, which may carry a position older than the last pointer move. */
+export function holdPins(xyz, pins, index) {
+  let n = 0;
+  for (const [id, p] of pins) {
+    const i = index.get(id);
+    if (i === undefined) continue;
+    xyz[3 * i] = p[0]; xyz[3 * i + 1] = p[1]; xyz[3 * i + 2] = p[2];
+    n++;
+  }
+  return n;
+}