@smartmemory/wiki-components 0.5.0 → 0.6.0

package/src/graph/lib/wikiGraph.js

@@ -0,0 +1,298 @@
+// WIKI-GRAPH-VIEW-UX-1: the whole-workspace graph, Obsidian-style. Pure helpers (no DOM, no React) so the page, the
+// canvas and the tests share one definition of what is drawn. Conventions copied from @smartmemory/graph (labels
+// #cbd5e1 outlined #0f172a, labels hidden at small zoom), not the package itself: REPORT.md "Dependency decision".
+
+import { perfNow, perfSpan } from "./perf";
+import { AREA_FAMILIES, UNMAPPED, familyOf } from "./areaFamilies";
+
+/** At most this many docs are fetched and drawn; over it the page says "showing first N of total". The eng wiki has
+ *  ~4.8k docs, so it fits whole; the WebGL view (WIKI-GRAPH-OBSIDIAN-1) is benched to 50k. */
+export const MAX_NODES = 60000;
+/** Level of detail: above LOD_N nodes the graph draws small nodes, faint edges, and labels only when zoomed in. */
+export const LOD_N = 1500;
+/** Every label is drawn when the graph has at most this many nodes. */
+export const LABEL_ALL = 150;
+/** Never more than this many labels in one frame (the focused doc and its neighbours come first). */
+export const LABEL_CAP = 300;
+/** Graph colours on the dark field (`#0a0f1a`): Okabe-Ito's seven chromatic colours, which stay apart for the common kinds of
+ *  colour blindness (its black is dropped, the field is that dark). One per group, the biggest first; the rest share OTHER.
+ *  WIKI-GRAPH-3D-COLOR-SPHERES-1. */
+export const PALETTE = ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7"];
+export const OTHER = "#7f8ea5";
+/** Area mode: an area in no family (AREA_FAMILIES) is coloured and listed apart: not OTHER (that is "(no area)") and not a family colour. */
+export const UNMAPPED_COLOR = "#B9A7FF";
+const FAMILY_COLOR = new Map(Object.keys(AREA_FAMILIES).map((f, i) => [f, PALETTE[i]]));
+/** Docs outside the current scope (`by=scope`): a dim slate, so the scope's own groups stand out. */
+export const OUTSIDE = "#3b4556";
+export const OUTSIDE_KEY = "(outside)";
+const NO_AREA = "(no area)", ROOT_FOLDER = "(root)";
+
+/** The group a doc is coloured by: its area, or the first two segments of its folder ("docs/core"), or "(root)". */
+export function groupOf(item, by = "area") {
+  if (by === "area") return item.area || NO_AREA;
+  const segs = String(item.folder || "").split("/").filter(Boolean);
+  return segs.length ? segs.slice(0, 2).join("/") : ROOT_FOLDER;
+}
+
+/** `items` (graph_node rows) and `edges` ({from,to}) as drawable nodes and links. A link to a doc not in the set is
+ *  dropped (the server only sends links into the live set; a capped fetch can still leave some out). */
+export function buildGraph(items, edges, { by = "area", layout = null } = {}) {
+  const t0 = perfNow(); // the `wiki-graph:build` measure (WIKI-GRAPH-LOAD-1)
+  const counts = new Map();
+  for (const it of items) counts.set(groupOf(it, by), (counts.get(groupOf(it, by)) || 0) + 1);
+  const loose = (name) => name === NO_AREA || name === ROOT_FOLDER; // docs with no group of their own are grey, listed last
+  const familied = by === "area"; // area mode colours by family: one fixed colour per family, `family` on each (still per-area) group
+  const groups = [...counts.entries()]
+    .sort((a, b) => loose(a[0]) - loose(b[0]) || b[1] - a[1] || String(a[0]).localeCompare(String(b[0])))
+    .map(([name, count], i) => {
+      if (!familied) return { name, count, color: loose(name) ? OTHER : PALETTE[i] || OTHER };
+      if (loose(name)) return { name, count, color: OTHER };
+      const family = familyOf(name);
+      return { name, count, family, color: family === UNMAPPED ? UNMAPPED_COLOR : FAMILY_COLOR.get(family) };
+    });
+  const colour = new Map(groups.map((g) => [g.name, g.color]));
+  const nodes = items.map((it) => {
+    const group = groupOf(it, by);
+    return { id: it.doc_id, title: it.title || it.doc_id, area: it.area ?? null, folder: it.folder ?? "", group, color: colour.get(group), degree: 0 };
+  });
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  serveLayout(nodes, layout);
+  const links = [];
+  for (const e of edges) {
+    const a = byId.get(e.from), b = byId.get(e.to);
+    if (!a || !b || a === b) continue;
+    a.degree++; b.degree++;
+    links.push({ source: a.id, target: b.id });
+  }
+  perfSpan("wiki-graph:build", t0);
+  return { nodes, links, groups, byId };
+}
+
+/** WIKI-GRAPH-WARMSTART-3D-1: the host's served layout (`layout`: {xy?, xyz?}, one number pair or triple per item, in item order)
+ *  onto the nodes as `warm2` / `warm3` ([x, y] / [x, y, z]) and `warmN` (how many nodes it covers). Each canvas starts a node there
+ *  when it has no position of its own (`serverFits`). A part that is absent, the wrong length or not all finite is ignored. */
+export function serveLayout(nodes, layout) {
+  for (const [key, dims] of [["xy", 2], ["xyz", 3]]) {
+    const at = layout?.[key];
+    if (!Array.isArray(at) || at.length !== dims * nodes.length || !at.every(Number.isFinite)) continue;
+    nodes.forEach((nd, i) => { nd[dims === 3 ? "warm3" : "warm2"] = at.slice(dims * i, dims * i + dims); nd.warmN = nodes.length; });
+  }
+}
+
+/** Whether `nodes` (a canvas's drawn set) is exactly the graph the served `dims`-D layout was computed for: every node has its
+ *  position and the set is as big as the whole graph. A local graph, a level view (folders carry none) or a hidden-group subset
+ *  never fits: a layout of the whole graph stretched over a part of it is no warm start. */
+export const serverFits = (nodes, dims) => nodes.length > 0 && nodes.every((nd) => nd[dims === 3 ? "warm3" : "warm2"] && nd.warmN === nodes.length);
+
+const segs = (path) => String(path || "").split("/").filter(Boolean);
+
+// scopeColors results by scope, newest last, so `groupColor(name, scope)` can answer without the graph (CLUSTER-NORELAYOUT).
+const scopeCache = new Map();
+const SCOPE_CACHE_MAX = 8;
+
+/** Colours relative to a SCOPE (the folder the reader is looking into; "" or null is the root). A doc under the scope is
+ *  grouped by the next segment of its folder, and the group key is that child's FULL path (`core/api`), so hiding it never
+ *  leaks to a same-named folder elsewhere. Docs directly in the scope take the key `<scope>/` (label "(here)", "(root)" at
+ *  the root), which `cleanPath` can never produce. Docs outside the scope take OUTSIDE_KEY, listed last in colour OUTSIDE.
+ *  Colours go by size rank within the scope (ties by name) over the graph given, so call it on the UNFILTERED graph and
+ *  hiding never recolours; groups past the palette share OTHER.
+ *  @returns {{groups: {name: string, label: string, count: number, color: string, path: string|null}[], groupOf: Map<string, string>}}
+ *  `path` is the folder a legend drill opens (null for here / outside). */
+export function scopeColors(graph, scope = null, palette = PALETTE) {
+  const base = segs(scope), scopePath = base.join("/");
+  const counts = new Map(), groupOf = new Map();
+  let outside = 0;
+  for (const n of graph.nodes) {
+    const f = segs(n.folder);
+    let key;
+    if (f.length < base.length || base.some((s, i) => f[i] !== s)) { key = OUTSIDE_KEY; outside++; }
+    else if (f.length === base.length) key = scopePath + "/";
+    else { key = f.slice(0, base.length + 1).join("/"); }
+    groupOf.set(n.id, key);
+    if (key !== OUTSIDE_KEY) counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  const ranked = [...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]));
+  const groups = ranked.map(([name, count], i) => {
+    const here = name.endsWith("/");
+    return {
+      name, count, color: palette[i] || OTHER, path: here ? null : name,
+      label: here ? (scopePath ? "(here)" : "(root)") : name.slice(scopePath ? scopePath.length + 1 : 0),
+    };
+  });
+  if (outside) groups.push({ name: OUTSIDE_KEY, label: OUTSIDE_KEY, count: outside, color: OUTSIDE, path: null });
+  scopeCache.delete(scopePath);
+  scopeCache.set(scopePath, new Map(groups.map((g) => [g.name, g.color])));
+  if (scopeCache.size > SCOPE_CACHE_MAX) scopeCache.delete(scopeCache.keys().next().value);
+  return { groups, groupOf };
+}
+
+/** The colour a group key has under `scope`, from the last scopeColors call for that scope (the page makes it before any
+ *  consumer asks); OTHER when the scope was never coloured or the key is not in it. Same colour in 2D and 3D. */
+export function groupColor(name, scope = null) {
+  return scopeCache.get(segs(scope).join("/"))?.get(name) ?? OTHER;
+}
+
+/** `graph` (buildGraph output) with every node's `group` and `color` taken from `scoped` (scopeColors output): new node
+ *  objects, the same ids and links, so a canvas holding the old graph recolours in place with no relayout. */
+export function recolour(graph, scoped) {
+  const colour = new Map(scoped.groups.map((g) => [g.name, g.color]));
+  const nodes = graph.nodes.map((n) => { const group = scoped.groupOf.get(n.id); return { ...n, group, color: colour.get(group) }; });
+  return { ...graph, nodes, groups: scoped.groups, byId: new Map(nodes.map((n) => [n.id, n])) };
+}
+
+/** Starting positions. Clustered (`cluster`, the default): group centres on a circle, each group's docs on a sunflower
+ *  spiral around its centre; good seeds let the force layout settle in far fewer ticks. Not clustered (the Graph page's
+ *  default): every doc at a pseudo-random point of one disc, no group structure and no rings (a spiral or ring seed
+ *  survives as concentric rings when the pull is weak), deterministic by index so a reload lays out the same way; the
+ *  returned centre of every group is 0,0. Mutates `nodes` (x, y). */
+export function seedPositions(nodes, cluster = true) {
+  if (!cluster) {
+    const R = Math.max(80, Math.sqrt(nodes.length) * 9);
+    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; };
+    nodes.forEach((n, i) => { const r = R * Math.sqrt(rnd(2 * i)), a = 2 * Math.PI * rnd(2 * i + 1); n.x = Math.cos(a) * r; n.y = Math.sin(a) * r; });
+    return new Map(nodes.map((n) => [n.group, { x: 0, y: 0 }]));
+  }
+  const groups = [...new Set(nodes.map((n) => n.group))];
+  const R = Math.max(80, Math.sqrt(nodes.length) * 9);
+  const centre = new Map(groups.map((g, i) => {
+    const a = (2 * Math.PI * i) / Math.max(groups.length, 1);
+    return [g, groups.length === 1 ? { x: 0, y: 0 } : { x: Math.cos(a) * R, y: Math.sin(a) * R }];
+  }));
+  const seen = new Map();
+  const golden = Math.PI * (3 - Math.sqrt(5));
+  for (const n of nodes) {
+    const k = seen.get(n.group) || 0;
+    seen.set(n.group, k + 1);
+    const c = centre.get(n.group), r = 6 * Math.sqrt(k + 0.5);
+    n.x = c.x + Math.cos(k * golden) * r;
+    n.y = c.y + Math.sin(k * golden) * r;
+  }
+  return centre;
+}
+
+/** The ids one link away from `id`, with `id` itself. Links may carry ids or (after d3-force) node objects. */
+export function neighbourhood(links, id) {
+  const out = new Set(id ? [id] : []);
+  if (!id) return out;
+  for (const l of links) {
+    const s = typeof l.source === "object" ? l.source.id : l.source;
+    const t = typeof l.target === "object" ? l.target.id : l.target;
+    if (s === id) out.add(t);
+    else if (t === id) out.add(s);
+  }
+  return out;
+}
+
+/** Docs whose title holds `q` (case-insensitive), title-prefix matches first, then shorter titles; at most `limit`. */
+export function searchNodes(nodes, q, limit = 8) {
+  const needle = String(q || "").trim().toLowerCase();
+  if (!needle) return [];
+  const hits = [];
+  for (const n of nodes) {
+    const t = n.title.toLowerCase();
+    const at = t.indexOf(needle);
+    if (at >= 0) hits.push([at === 0 ? 0 : 1, t.length, n]);
+  }
+  hits.sort((a, b) => a[0] - b[0] || a[1] - b[1] || a[2].title.localeCompare(b[2].title));
+  return hits.slice(0, limit).map((h) => h[2]);
+}
+
+/** What one frame draws for `count` nodes at zoom `k`: node radius (screen px), edge alpha (the starting value; a drawn
+ *  frame uses edgeAlphaFor, WIKI-GRAPH-DECLUTTER-1), which labels, and `labelK`, the zoom the non-hub labels start fading
+ *  in at (0 = no fade). labels: "all" (every node in view), "zoomed" (hubs, then the rest fading in), "focus" (the lit
+ *  docs and the hubs only). */
+export function lodFor(count, k) {
+  const big = count > LOD_N;
+  const labelK = count <= LABEL_ALL ? 0 : big ? 2 : 1;
+  const labels = !labelK ? "all" : k >= labelK ? "zoomed" : "focus";
+  return { big, radius: big ? 2.5 : 4, edgeAlpha: big ? 0.07 : 0.22, labels, labelK };
+}
+
+// WIKI-GRAPH-DECLUTTER-1: the declutter rules both renderers share (the 2D overlay and bases, and the 3D base, which feeds
+// the same overlay its projection). Owner, 2026-10-20: labels only for hubs, the lit docs and what fits; never two labels
+// overlapping; the rest fade in with zoom; arrowheads never stacked on hubs (graphArrows.js); edges quieter when dense.
+
+/** One label per this many px² of the view, so a 1300 x 670 view shows at most ~36 labels besides the lit docs. */
+export const LABEL_AREA = 24000;
+/** A view never gets fewer label slots than this. */
+export const LABEL_MIN = 8;
+/** A hub: a doc with at least this many links, or a folder with at least this many docs (the level view's folder degree
+ *  is its size, GraphPage). Hubs keep their labels zoomed out; the same line as graphArrows ARROW_HUB_DEGREE (over 8). */
+export const HUB_DEGREE = 9;
+/** Non-hub labels fade from alpha 0 at lodFor's `labelK` to 1 at LABEL_FADE x labelK. */
+export const LABEL_FADE = 1.6;
+/** Below this alpha a label is not drawn at all (it would still take a slot and block others). */
+export const LABEL_ALPHA_MIN = 0.05;
+
+/** The label slots of a `w` x `h` px view: area / LABEL_AREA, at least LABEL_MIN, never over LABEL_CAP. */
+export const labelBudget = (w, h) => Math.max(LABEL_MIN, Math.min(LABEL_CAP, Math.round((Math.max(0, w) * Math.max(0, h)) / LABEL_AREA)));
+
+/** A non-hub label's alpha at zoom `k` when labels start at `k0` (lodFor labelK): 0 up to k0, rising linearly to 1 at
+ *  LABEL_FADE x k0, 1 from there on. k0 = 0 (a small graph): always 1. Never falls as k grows. */
+export function labelFade(k, k0) {
+  if (!(k0 > 0)) return 1;
+  return Math.max(0, Math.min(1, (k / k0 - 1) / (LABEL_FADE - 1)));
+}
+
+/** Edge alpha from how many links cross the view: EDGE_ALPHA.max up to `ref` links per million px², then falling with the
+ *  square root of the density, never under `min`. */
+export const EDGE_ALPHA = { max: 0.28, min: 0.05, ref: 300 };
+
+/** How many of the first `count` links (`pairs`: node index pairs) touch a `w` x `h` view: a link counts when the box of its
+ *  two ends meets the view. Node `i` is at screen (xs[stride*i] * k + x, xs[stride*i+1] * k + y) for `view` {k, x, y}: the
+ *  2D world positions (stride 2) or the 3D projection (stride 3, view {k: 1, x: 0, y: 0}). */
+export function linksInView(xs, pairs, count, view, w, h, stride = 2) {
+  const { k, x, y } = view;
+  const x0 = -x / k, y0 = -y / k, x1 = (w - x) / k, y1 = (h - y) / k;
+  let c = 0;
+  for (let e = 0; e < count; e++) {
+    const a = stride * pairs[2 * e], b = stride * pairs[2 * e + 1];
+    const ax = xs[a], ay = xs[a + 1], bx = xs[b], by = xs[b + 1];
+    if ((ax < x0 && bx < x0) || (ax > x1 && bx > x1) || (ay < y0 && by < y0) || (ay > y1 && by > y1)) continue;
+    c++;
+  }
+  return c;
+}
+
+/** The edge alpha for `inView` links crossing a `w` x `h` view (EDGE_ALPHA). Never rises as the count grows. */
+export function edgeAlphaFor(inView, w, h) {
+  const d = inView / Math.max(1e-6, (Math.max(1, w) * Math.max(1, h)) / 1e6);
+  return Math.max(EDGE_ALPHA.min, Math.min(EDGE_ALPHA.max, EDGE_ALPHA.max * Math.sqrt(EDGE_ALPHA.ref / Math.max(d, EDGE_ALPHA.ref))));
+}
+
+/** A view (screen = world * k + {x, y}) that fits every node in a `w` x `h` box with a margin. */
+export function fitView(nodes, w, h, pad = 40) {
+  if (!nodes.length) return { k: 1, x: w / 2, y: h / 2 };
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  for (const n of nodes) {
+    if (n.x < x0) x0 = n.x; if (n.x > x1) x1 = n.x;
+    if (n.y < y0) y0 = n.y; if (n.y > y1) y1 = n.y;
+  }
+  const k = Math.min(4, Math.max(0.02, Math.min((w - 2 * pad) / Math.max(x1 - x0, 1), (h - 2 * pad) / Math.max(y1 - y0, 1))));
+  return { k, x: w / 2 - ((x0 + x1) / 2) * k, y: h / 2 - ((y0 + y1) / 2) * k };
+}
+
+/** fitView over a flat positions array (x, y per node index, as the layout worker writes it): a view that fits the nodes
+ *  at indices `idx` (any iterable) in a `w` x `h` box with a margin. `sizes` (diameters per node index, optional): fit the
+ *  circles' edges, not their centres, so a big folder is shown whole (WIKI-GRAPH-P0-LEVEL0-ZOOM-1). */
+export function fitBox(pos, idx, w, h, pad = 40, sizes = null) {
+  let x0 = Infinity, y0 = Infinity, x1 = -Infinity, y1 = -Infinity;
+  for (const i of idx) {
+    const x = pos[2 * i], y = pos[2 * i + 1], r = sizes ? sizes[i] / 2 : 0;
+    if (x - r < x0) x0 = x - r; if (x + r > x1) x1 = x + r;
+    if (y - r < y0) y0 = y - r; if (y + r > y1) y1 = y + r;
+  }
+  if (x0 === Infinity) return { k: 1, x: w / 2, y: h / 2 };
+  const k = Math.min(4, Math.max(0.02, Math.min((w - 2 * pad) / Math.max(x1 - x0, 1), (h - 2 * pad) / Math.max(y1 - y0, 1))));
+  return { k, x: w / 2 - ((x0 + x1) / 2) * k, y: h / 2 - ((y0 + y1) / 2) * k };
+}
+
+/** A view centred on world point (x, y) at zoom `k`. */
+export const centreOn = (x, y, w, h, k) => ({ k, x: w / 2 - x * k, y: h / 2 - y * k });
+
+/** Zoom by `factor` keeping screen point (sx, sy) fixed, clamped to [kMin, 8]. */
+export function zoomAt(view, sx, sy, factor, kMin = 0.02) {
+  const k = Math.min(8, Math.max(kMin, view.k * factor));
+  const f = k / view.k;
+  return { k, x: sx - (sx - view.x) * f, y: sy - (sy - view.y) * f };
+}