@smartmemory/wiki-components 0.5.0 → 0.6.0

package/src/graph/lib/graphExplore.js

@@ -0,0 +1,546 @@
+// WIKI-GRAPH-EXPLORE-1a: the filter engine behind the Graph page's sentence row. Pure (no DOM, no fetch, no Pixi): a directed index
+// of the FULL graph, every filter step as a function over byte masks, lenses that only mark, the `x` URL codec, the sentence text,
+// the empty-state hint and the arrow-key neighbour picker. Design: smart-memory-docs docs/features/WIKI-GRAPH-EXPLORE-1/design.md
+// §5-§8. The output plugs into LEVELS as `visible` (graphLevels.js `buildLevelGraph(graph, expanded, { visible })`).
+
+const NO_AREA = "(no area)"; // same label wikiGraph.js `groupOf` gives a doc with no area
+export const VERSION = 1;
+export const MAX_HOPS = 4;
+/** Longest `x` value and most steps decoded; anything past them is counted as ignored, never thrown on. */
+export const MAX_X_LENGTH = 20000;
+export const MAX_STEPS = 64;
+/** Share says "too big for a link" past either of these (design §6). */
+export const SHARE_MAX_IDS = 200;
+export const SHARE_MAX_URL = 6000;
+
+/** The verbs the omnibox offers: label -> step template. Owner decision 2: "Children of" is `near`, hops 1 (linked either way). */
+export const VERBS = [
+  { label: "Children of", op: "near", hops: 1 },
+  { label: "Links from it", op: "from", hops: 1 },
+  { label: "Links to it", op: "to", hops: 1 },
+  { label: "Near (N hops)", op: "near", hops: 2 },
+  { label: "Plus one hop", op: "grow", hops: 1 },
+  { label: "Inside folder", op: "in" },
+  { label: "Linked at least", op: "degree" },
+  { label: "Orphans", op: "orphans" },
+  { label: "Area", op: "area" },
+  { label: "Kind", op: "kind" },
+  { label: "Changed within", op: "modified" },
+  { label: "Matching text", op: "match" },
+  { label: "Keep selection", op: "only" },
+];
+
+/** A step from a verb label plus the arguments the omnibox collected (`id`, `path`, `min`, `names`, `q`, `ids`, `hops`, `within`...).
+ *  Returns null for an unknown label. The result is a plain Step (not validated: `normaliseStep` does that). */
+export function verbToStep(label, args = {}) {
+  const v = VERBS.find((x) => x.label === label);
+  if (!v) return null;
+  const { label: _l, ...tpl } = v;
+  return { ...tpl, ...args };
+}
+
+const clampHops = (h) => Math.max(1, Math.min(MAX_HOPS, Math.round(Number(h)) || 1));
+const isStr = (v) => typeof v === "string" && v !== "";
+const strList = (v) => (Array.isArray(v) ? v.filter((s) => typeof s === "string" && s !== "") : []);
+const num = (v) => (v === undefined || v === null || v === "" ? undefined : Number.isFinite(Number(v)) ? Number(v) : NaN);
+const dateOk = (s) => typeof s === "string" && !Number.isNaN(Date.parse(s));
+
+/** Validate one step. Returns a clean copy, or null when it cannot be applied (the caller counts it as ignored). */
+export function normaliseStep(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const out = { op: raw.op };
+  switch (raw.op) {
+    case "in": if (typeof raw.path !== "string") return null; out.path = raw.path.replace(/^\/+|\/+$/g, ""); break;
+    case "from": case "to": case "near":
+      if (!isStr(raw.id)) return null;
+      out.id = raw.id; out.hops = clampHops(raw.hops); break;
+    case "degree": {
+      const min = num(raw.min), max = num(raw.max);
+      if (Number.isNaN(min) || Number.isNaN(max) || (min === undefined && max === undefined)) return null;
+      if (min !== undefined) out.min = min;
+      if (max !== undefined) out.max = max;
+      break;
+    }
+    case "orphans": break;
+    case "area": case "kind": {
+      const names = strList(raw.names);
+      if (!names.length) return null;
+      out.names = names; break;
+    }
+    case "modified": {
+      if (raw.within !== undefined && !/^\d{1,4}d$/.test(String(raw.within))) return null;
+      if (raw.since !== undefined && !dateOk(raw.since)) return null;
+      if (raw.until !== undefined && !dateOk(raw.until)) return null;
+      if (raw.within === undefined && raw.since === undefined && raw.until === undefined) return null;
+      for (const k of ["since", "until", "within"]) if (raw[k] !== undefined) out[k] = String(raw[k]);
+      break;
+    }
+    case "match": if (!isStr(raw.q)) return null; out.q = raw.q; break;
+    case "only": { const ids = strList(raw.ids); if (!ids.length) return null; out.ids = ids; break; }
+    case "grow": out.hops = 1; break;
+    default: return null;
+  }
+  if (raw.not === true) out.not = true;
+  return out;
+}
+
+export function normaliseLens(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  if (raw.lens === "highlight" && isStr(raw.q)) return { lens: "highlight", q: raw.q };
+  if (raw.lens === "path" && isStr(raw.from) && isStr(raw.to)) return { lens: "path", from: raw.from, to: raw.to };
+  return null;
+}
+
+// ---------------------------------------------------------------------------------------------------------------- index
+
+/** The directed index of the FULL graph (`buildGraph`'s `{nodes, links}`): node order = `graph.nodes`, links in CSR form both ways.
+ *  Built once per fetch. Self links and links to unknown ids are skipped; degree = in + out, the same count `buildGraph` keeps. */
+export function buildIndex(graph) {
+  const nodes = graph.nodes, n = nodes.length;
+  const indexOf = new Map();
+  for (let i = 0; i < n; i++) indexOf.set(nodes[i].id, i);
+  const endIdx = (e) => indexOf.get(typeof e === "object" && e ? e.id : e);
+  const src = new Int32Array(graph.links.length), dst = new Int32Array(graph.links.length);
+  let m = 0;
+  const outStart = new Int32Array(n + 1), inStart = new Int32Array(n + 1);
+  for (const l of graph.links) {
+    const a = endIdx(l.source), b = endIdx(l.target);
+    if (a === undefined || b === undefined || a === b) continue;
+    src[m] = a; dst[m] = b; m++;
+    outStart[a + 1]++; inStart[b + 1]++;
+  }
+  for (let i = 0; i < n; i++) { outStart[i + 1] += outStart[i]; inStart[i + 1] += inStart[i]; }
+  const outAdj = new Int32Array(m), inAdj = new Int32Array(m);
+  const oc = outStart.slice(0, n), ic = inStart.slice(0, n);
+  for (let k = 0; k < m; k++) { outAdj[oc[src[k]]++] = dst[k]; inAdj[ic[dst[k]]++] = src[k]; }
+  const degree = new Int32Array(n);
+  for (let i = 0; i < n; i++) degree[i] = outStart[i + 1] - outStart[i] + inStart[i + 1] - inStart[i];
+  let hasKind = false, hasMtime = false;
+  const mtime = new Float64Array(n).fill(NaN);
+  for (let i = 0; i < n; i++) {
+    if (nodes[i].kind !== undefined && nodes[i].kind !== null) hasKind = true;
+    if (nodes[i].mtime !== undefined && nodes[i].mtime !== null) {
+      const t = typeof nodes[i].mtime === "number" ? nodes[i].mtime : Date.parse(nodes[i].mtime);
+      if (!Number.isNaN(t)) { mtime[i] = t; hasMtime = true; }
+    }
+  }
+  return { n, nodes, indexOf, outStart, outAdj, inStart, inAdj, degree, mtime, hasKind, hasMtime };
+}
+
+const idOf = (idx, i) => idx.nodes[i].id;
+
+/** Docs reachable from `root` within `hops`, over the full graph. dir: "out" | "in" | "both". Root included. Byte mask; null for an unknown root. */
+function walk(idx, root, hops, dir) {
+  const r = idx.indexOf.get(root);
+  if (r === undefined) return null;
+  const seen = new Uint8Array(idx.n);
+  seen[r] = 1;
+  let frontier = [r];
+  for (let h = 0; h < hops && frontier.length; h++) {
+    const next = [];
+    for (const u of frontier) {
+      if (dir !== "in") for (let k = idx.outStart[u]; k < idx.outStart[u + 1]; k++) { const v = idx.outAdj[k]; if (!seen[v]) { seen[v] = 1; next.push(v); } }
+      if (dir !== "out") for (let k = idx.inStart[u]; k < idx.inStart[u + 1]; k++) { const v = idx.inAdj[k]; if (!seen[v]) { seen[v] = 1; next.push(v); } }
+    }
+    frontier = next;
+  }
+  return seen;
+}
+
+/** Shortest undirected path between two doc ids over the full graph: ordered ids, or null when either is unknown or they are not connected. */
+export function shortestPath(idx, from, to) {
+  const a = idx.indexOf.get(from), b = idx.indexOf.get(to);
+  if (a === undefined || b === undefined) return null;
+  if (a === b) return [from];
+  const prev = new Int32Array(idx.n).fill(-2);
+  prev[a] = -1;
+  let frontier = [a];
+  while (frontier.length && prev[b] === -2) {
+    const next = [];
+    for (const u of frontier) {
+      for (let pass = 0; pass < 2; pass++) {
+        const st = pass ? idx.inStart : idx.outStart, ad = pass ? idx.inAdj : idx.outAdj;
+        for (let k = st[u]; k < st[u + 1]; k++) { const v = ad[k]; if (prev[v] === -2) { prev[v] = u; next.push(v); } }
+      }
+    }
+    frontier = next;
+  }
+  if (prev[b] === -2) return null;
+  const path = [];
+  for (let v = b; v !== -1; v = prev[v]) path.push(idOf(idx, v));
+  return path.reverse();
+}
+
+// ---------------------------------------------------------------------------------------------------------------- steps
+
+const DAY = 86400000;
+/** `ctx`: `{ now?: number (ms), matches?: Map<q, Iterable<docId>> }`. `matches` carries the server content-search ids per query. */
+const matchSet = (ctx, q) => { const m = ctx && ctx.matches && ctx.matches.get(q); return m ? new Set(m) : null; };
+
+/** The predicate form of a step: (i) -> boolean over node index, or null when the step is not a predicate. Status is set on `info`. */
+function predicateOf(idx, step, ctx, info) {
+  switch (step.op) {
+    case "in": {
+      const p = step.path;
+      return (i) => { const f = idx.nodes[i].folder || ""; return p === "" || f === p || f.startsWith(p + "/"); };
+    }
+    case "degree": { const lo = step.min ?? -Infinity, hi = step.max ?? Infinity; return (i) => idx.degree[i] >= lo && idx.degree[i] <= hi; }
+    case "orphans": return (i) => idx.degree[i] === 0;
+    case "area": { const s = new Set(step.names); return (i) => s.has(idx.nodes[i].area || NO_AREA); }
+    case "kind": {
+      if (!idx.hasKind) { info.status = "unsupported"; return null; }
+      const s = new Set(step.names);
+      return (i) => { const k = idx.nodes[i].kind; return k !== undefined && k !== null && s.has(k); };
+    }
+    case "modified": {
+      if (!idx.hasMtime) { info.status = "unsupported"; return null; }
+      const now = ctx && ctx.now !== undefined ? ctx.now : Date.now();
+      let lo = step.since ? Date.parse(step.since) : -Infinity;
+      const hi = step.until ? Date.parse(step.until) : Infinity;
+      if (step.within) lo = Math.max(lo, now - parseInt(step.within, 10) * DAY);
+      return (i) => { const t = idx.mtime[i]; return !Number.isNaN(t) && t >= lo && t <= hi; };
+    }
+    case "match": {
+      const ids = matchSet(ctx, step.q);
+      if (!ids) { info.status = "pending"; return null; }
+      return (i) => ids.has(idOf(idx, i));
+    }
+    case "only": { const s = new Set(step.ids); return (i) => s.has(idOf(idx, i)); }
+    default: return null;
+  }
+}
+
+/** One step over a mask: returns `{ mask, status }`. status: "ok" | "unsupported" (no node carries the field: the step passes through) |
+ *  "pending" (a `match` whose server ids have not landed: passes through) | "missing-root" (the walk's root is not in the graph: matches nothing). */
+export function applyStep(idx, maskIn, step, ctx = {}) {
+  const info = { status: "ok" };
+  const out = new Uint8Array(idx.n);
+  const neg = step.not === true;
+  if (step.op === "from" || step.op === "to" || step.op === "near") {
+    const reach = walk(idx, step.id, step.hops, step.op === "from" ? "out" : step.op === "to" ? "in" : "both");
+    if (!reach) info.status = "missing-root";
+    for (let i = 0; i < idx.n; i++) if (maskIn[i] && (reach ? reach[i] === 1 : false) !== neg) out[i] = 1;
+    return { mask: out, status: info.status };
+  }
+  if (step.op === "grow") {
+    // adds the neighbours (either direction, full graph) of the current set. `not grow` keeps only the ring it would add.
+    out.set(maskIn);
+    for (let i = 0; i < idx.n; i++) {
+      if (!maskIn[i]) continue;
+      for (let k = idx.outStart[i]; k < idx.outStart[i + 1]; k++) out[idx.outAdj[k]] = 1;
+      for (let k = idx.inStart[i]; k < idx.inStart[i + 1]; k++) out[idx.inAdj[k]] = 1;
+    }
+    if (neg) for (let i = 0; i < idx.n; i++) if (maskIn[i]) out[i] = 0;
+    return { mask: out, status: "ok" };
+  }
+  const pred = predicateOf(idx, step, ctx, info);
+  if (!pred) { out.set(maskIn); return { mask: out, status: info.status }; }
+  for (let i = 0; i < idx.n; i++) if (maskIn[i] && pred(i) !== neg) out[i] = 1;
+  return { mask: out, status: "ok" };
+}
+
+const count = (mask) => { let c = 0; for (let i = 0; i < mask.length; i++) c += mask[i]; return c; };
+
+const stepKey = (step, ctx) => {
+  let k = JSON.stringify(step);
+  if (step.op === "match") { const m = matchSet(ctx, step.q); k += ":" + (m ? "m" + JSON.stringify([...m].sort()) : "p"); }
+  if (step.op === "modified" && step.within) k += ":" + Math.floor((ctx && ctx.now !== undefined ? ctx.now : Date.now()) / 60000);
+  return k;
+};
+
+/** An explorer over one fetched graph: the index plus a prefix cache, so editing the last chip recomputes one step. */
+export function createExplorer(graph) {
+  const idx = buildIndex(graph);
+  const all = new Uint8Array(idx.n).fill(1);
+  /** @type {{key: string, mask: Uint8Array, status: string, count: number}[]} */
+  let cache = [];
+  return {
+    idx,
+    /** Run a stack. Returns `{ mask, count, total, steps: [{ count, status }] }` (steps[i] = docs left after step i). */
+    run(steps, ctx = {}) {
+      const keys = steps.map((s) => stepKey(s, ctx));
+      let keep = 0;
+      while (keep < cache.length && keep < keys.length && cache[keep].key === keys[keep]) keep++;
+      cache = cache.slice(0, keep);
+      for (let i = keep; i < steps.length; i++) {
+        const { mask, status } = applyStep(idx, i ? cache[i - 1].mask : all, steps[i], ctx);
+        cache.push({ key: keys[i], mask, status, count: count(mask) });
+      }
+      const mask = steps.length ? cache[steps.length - 1].mask : all;
+      return {
+        mask,
+        count: steps.length ? cache[steps.length - 1].count : idx.n,
+        total: idx.n,
+        steps: cache.map((c) => ({ count: c.count, status: c.status })),
+      };
+    },
+  };
+}
+
+/** One-shot convenience: the mask for a state's steps, no cache. */
+export function runStack(graph, state, ctx = {}) { return createExplorer(graph).run(state.steps, ctx); }
+
+/** The `visible` predicate LEVELS takes: docId -> boolean from a mask. */
+export function visiblePredicate(idx, mask) { return (id) => { const i = idx.indexOf.get(id); return i !== undefined && mask[i] === 1; }; }
+
+// ---------------------------------------------------------------------------------------------------------------- lenses
+
+/** Lenses only mark. Returns `{ dim, path }`: `dim` is a Uint8Array (1 = dimmed, i.e. does not match the highlight) or null with no
+ *  highlight lens; `path` is the ordered ids of the shortest path or null. Nothing is ever removed. `ctx.matches` adds server ids. */
+export function applyLenses(idx, lenses, ctx = {}) {
+  let dim = null, path = null;
+  for (const l of lenses) {
+    if (l.lens === "highlight") {
+      const q = l.q.toLowerCase(), ids = matchSet(ctx, l.q);
+      const hit = new Uint8Array(idx.n);
+      for (let i = 0; i < idx.n; i++) {
+        const nd = idx.nodes[i];
+        if (String(nd.title || "").toLowerCase().includes(q) || String(nd.id).toLowerCase().includes(q) || (ids && ids.has(nd.id))) hit[i] = 1;
+      }
+      dim = dim || new Uint8Array(idx.n).fill(1);
+      for (let i = 0; i < idx.n; i++) if (hit[i]) dim[i] = 0;
+    } else if (l.lens === "path") path = shortestPath(idx, l.from, l.to);
+  }
+  return { dim, path };
+}
+
+// ---------------------------------------------------------------------------------------------------------------- URL codec
+
+const enc = (s) => encodeURIComponent(s).replace(/[!~'()*]/g, (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+const dec = (s) => decodeURIComponent(s);
+const encList = (a) => a.map(enc).join(",");
+const decList = (s) => s.split(",").filter(Boolean).map(dec);
+const optNum = (v) => (v === undefined ? "" : String(v));
+
+function encodeStep(s) {
+  const bang = s.not ? "!" : "";
+  switch (s.op) {
+    case "in": return `${bang}in:${enc(s.path)}`;
+    case "from": case "to": case "near": return `${bang}${s.op}:${enc(s.id)}:${s.hops}`;
+    case "degree": return `${bang}degree:${optNum(s.min)}:${optNum(s.max)}`;
+    case "orphans": return `${bang}orphans`;
+    case "area": case "kind": return `${bang}${s.op}:${encList(s.names)}`;
+    case "modified": return `${bang}modified:${enc(s.since || "")}:${enc(s.until || "")}:${s.within || ""}`;
+    case "match": return `${bang}match:${enc(s.q)}`;
+    case "only": return `${bang}only:${encList(s.ids)}`;
+    case "grow": return `${bang}grow:${s.hops}`;
+    default: return "";
+  }
+}
+
+function decodeStep(token) {
+  const not = token.startsWith("!");
+  const parts = (not ? token.slice(1) : token).split(":");
+  const f = parts.slice(1);
+  let raw;
+  switch (parts[0]) {
+    case "in": raw = { op: "in", path: dec(f[0] ?? "") }; break;
+    case "from": case "to": case "near": raw = { op: parts[0], id: dec(f[0] ?? ""), hops: f[1] }; break;
+    case "degree": raw = { op: "degree", min: num(f[0]), max: num(f[1]) }; break;
+    case "orphans": raw = { op: "orphans" }; break;
+    case "area": case "kind": raw = { op: parts[0], names: decList(f[0] ?? "") }; break;
+    case "modified": raw = { op: "modified", since: f[0] ? dec(f[0]) : undefined, until: f[1] ? dec(f[1]) : undefined, within: f[2] || undefined }; break;
+    case "match": raw = { op: "match", q: dec(f[0] ?? "") }; break;
+    case "only": raw = { op: "only", ids: decList(f[0] ?? "") }; break;
+    case "grow": raw = { op: "grow", hops: 1 }; break;
+    default: return null;
+  }
+  if (not) raw.not = true;
+  return normaliseStep(raw);
+}
+
+function decodeLens(token) {
+  const parts = token.slice(1).split(":");
+  if (parts[0] === "highlight") return normaliseLens({ lens: "highlight", q: dec(parts[1] ?? "") });
+  if (parts[0] === "path") return normaliseLens({ lens: "path", from: dec(parts[1] ?? ""), to: dec(parts[2] ?? "") });
+  return null;
+}
+
+export const emptyState = () => ({ v: VERSION, steps: [], lenses: [] });
+
+/** `x` param value for a state ("" when it has no steps and no lenses). Steps that fail validation are skipped. */
+export function encodeX(state) {
+  const steps = (state.steps || []).map(normaliseStep).filter(Boolean).map(encodeStep);
+  const lenses = (state.lenses || []).map(normaliseLens).filter(Boolean).map((l) =>
+    l.lens === "highlight" ? `@highlight:${enc(l.q)}` : `@path:${enc(l.from)}:${enc(l.to)}`);
+  return steps.length || lenses.length ? [String(VERSION), ...steps, ...lenses].join("~") : "";
+}
+
+/** The visible notice for dropped filters (design §6): "1 filter from a newer link was ignored". */
+export const ignoredNotice = (n) => (n <= 0 ? "" : n === 1 ? "1 filter from a newer link was ignored" : `${n} filters from a newer link were ignored`);
+
+/** Decode an `x` value. Never throws: hostile input yields what could be read plus `ignored` (count of tokens dropped) and one
+ *  console warning. A newer version drops everything. Returns `{ state, ignored, notice }`. */
+export function decodeX(value) {
+  const state = emptyState();
+  if (typeof value !== "string" || value === "") return { state, ignored: 0, notice: "" };
+  let ignored = 0;
+  let text = value;
+  if (text.length > MAX_X_LENGTH) { text = text.slice(0, MAX_X_LENGTH); ignored++; }
+  const tokens = text.split("~");
+  const ver = /^\d{1,4}$/.test(tokens[0]) ? Number(tokens[0]) : NaN;
+  if (ver !== VERSION) {
+    ignored += Math.max(1, tokens.length - (Number.isNaN(ver) ? 0 : 1));
+  } else {
+    for (const tok of tokens.slice(1, 1 + MAX_STEPS + 64)) {
+      if (tok === "") continue;
+      let item = null;
+      try { item = tok.startsWith("@") ? decodeLens(tok) : decodeStep(tok); } catch { item = null; }
+      if (!item) ignored++;
+      else if (tok.startsWith("@")) state.lenses.push(item);
+      else if (state.steps.length < MAX_STEPS) state.steps.push(item);
+      else ignored++;
+    }
+    if (tokens.length - 1 > MAX_STEPS + 64) ignored += tokens.length - 1 - (MAX_STEPS + 64);
+  }
+  if (ignored > 0 && typeof console !== "undefined") console.warn(`wiki graph: ignored ${ignored} unreadable or newer filter(s) in the x parameter`);
+  return { state, ignored, notice: ignoredNotice(ignored) };
+}
+
+const hopsOf = (v) => clampHops(v);
+
+/** Read a state from URL params (`URLSearchParams` or a query string). `x` wins; with no `x` the legacy params map over:
+ *  `hide=a,b` -> `not area` (the old `local=1` is ignored: a focus always narrows to its hops). Returns `{ state, focus, ignored, notice }`, where
+ *  `focus` is `root` (it stays the focus, not a filter). */
+export function parseExploreParams(params) {
+  const sp = typeof params === "string" ? new URLSearchParams(params) : params;
+  const focus = sp.get("root") || null;
+  const x = sp.get("x");
+  if (x !== null) return { focus, ...decodeX(x) };
+  const state = emptyState();
+  const hide = (sp.get("hide") || "").split(",").filter(Boolean).map((s) => { try { return dec(s); } catch { return s; } });
+  if (hide.length) state.steps.push({ op: "area", names: hide, not: true });
+  return { focus, state, ignored: 0, notice: "" };
+}
+
+/** A copy of `params` carrying `state` in the `x` form and none of the legacy `hide` / `local` / `hops` (design §6). */
+export function writeExploreParams(params, state) {
+  const sp = new URLSearchParams(typeof params === "string" ? params : params.toString());
+  for (const k of ["hide", "local", "hops", "x"]) sp.delete(k);
+  const x = encodeX(state);
+  if (x) sp.set("x", x);
+  return sp;
+}
+
+/** Whether Share can copy a link for this state (design §6: over 200 `only` ids or ~6 KB of URL it says "save it instead"). */
+export function shareable(state, base = "") {
+  const big = (state.steps || []).some((s) => s.op === "only" && s.ids.length > SHARE_MAX_IDS);
+  return !big && base.length + encodeX(state).length <= SHARE_MAX_URL;
+}
+
+// ---------------------------------------------------------------------------------------------------------------- sentence
+
+const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+const titleOf = (idx, id) => { const i = idx && idx.indexOf.get(id); return i === undefined || i === null ? id : idx.nodes[i].title || id; };
+
+/** The phrase for one step ("linked ≥ 3"), without the `not `. */
+export function phraseOf(step, idx = null) {
+  switch (step.op) {
+    case "in": return step.path === "" ? "in the root" : `in ${step.path}`;
+    case "from": return step.hops === 1 ? `linked from ${titleOf(idx, step.id)}` : `reached from ${titleOf(idx, step.id)} (${plural(step.hops, "hop")})`;
+    case "to": return step.hops === 1 ? `linking to ${titleOf(idx, step.id)}` : `leading to ${titleOf(idx, step.id)} (${plural(step.hops, "hop")})`;
+    case "near": return step.hops === 1 ? `children of ${titleOf(idx, step.id)}` : `within ${plural(step.hops, "hop")} of ${titleOf(idx, step.id)}`;
+    case "degree": {
+      if (step.min !== undefined && step.max !== undefined) return `linked ${step.min}–${step.max}`;
+      return step.min !== undefined ? `linked ≥ ${step.min}` : `linked ≤ ${step.max}`;
+    }
+    case "orphans": return "orphans";
+    case "area": return `area ${step.names.join(", ")}`;
+    case "kind": return `kind ${step.names.join(", ")}`;
+    case "modified": {
+      if (step.within) return `changed within ${step.within}`;
+      if (step.since && step.until) return `changed ${step.since.slice(0, 10)} to ${step.until.slice(0, 10)}`;
+      return step.since ? `changed since ${step.since.slice(0, 10)}` : `changed until ${step.until.slice(0, 10)}`;
+    }
+    case "match": return `matching "${step.q}"`;
+    case "only": return `selection (${step.ids.length})`;
+    case "grow": return "+1 hop";
+    default: return step.op;
+  }
+}
+
+/** The path lens's chip: `path A → B (k links)` (the shortest undirected path over the full graph), or `no path A → B` when the two docs
+ *  are not connected. Without an index it names the ids' titles only. */
+export function pathChipText(lens, idx = null) {
+  const names = `${titleOf(idx, lens.from)} → ${titleOf(idx, lens.to)}`;
+  if (!idx) return `path ${names}`;
+  const path = shortestPath(idx, lens.from, lens.to);
+  if (!path) return `no path ${names}`;
+  const k = path.length - 1;
+  return `path ${names} (${k} ${k === 1 ? "link" : "links"})`;
+}
+
+/** The sentence row's parts: `{ chips: [{ text, not, unsupported }], lenses: [{ text }], countText }`. `run` is a result of
+ *  `explorer.run` (for the count and for `unsupported`); `idx` names docs by title. */
+export function sentenceOf(state, run = null, idx = null) {
+  const chips = state.steps.map((s, i) => ({
+    text: (s.not ? "not " : "") + phraseOf(s, idx),
+    not: s.not === true,
+    unsupported: !!(run && run.steps[i] && run.steps[i].status === "unsupported"),
+  }));
+  const lenses = state.lenses.map((l) => ({ text: l.lens === "highlight" ? `highlight "${l.q}"` : pathChipText(l, idx), ...(l.lens === "path" ? { path: true } : {}) }));
+  let countText = "";
+  if (run) {
+    const f = (v) => v.toLocaleString("en-US");
+    countText = run.count < run.total ? `${f(run.count)} of ${f(run.total)} docs` : `${f(run.count)} docs`;
+  }
+  return { chips, lenses, countText };
+}
+
+/** When the stack leaves nothing: the one chip whose removal brings back the most docs (ties go to the rightmost chip). Returns
+ *  `{ index, gain, text }` (text e.g. `No docs match. Remove "linked ≥ 3" to see 41 docs.`) or null when the stack is not empty or no
+ *  single removal helps. */
+export function emptyHint(explorer, state, ctx = {}) {
+  const { idx } = explorer;
+  if (!state.steps.length || explorer.run(state.steps, ctx).count > 0) return null;
+  let best = null;
+  for (let i = 0; i < state.steps.length; i++) {
+    const rest = state.steps.filter((_, j) => j !== i);
+    const c = runWithout(explorer, rest, ctx);
+    if (c > 0 && (!best || c >= best.gain)) best = { index: i, gain: c };
+  }
+  if (!best) return null;
+  const step = state.steps[best.index];
+  return { ...best, text: `No docs match. Remove "${(step.not ? "not " : "") + phraseOf(step, idx)}" to see ${plural(best.gain, "doc")}.` };
+}
+
+// a separate cache so probing removals does not evict the live stack's prefix cache
+function runWithout(explorer, steps, ctx) {
+  let mask = new Uint8Array(explorer.idx.n).fill(1);
+  for (const s of steps) mask = applyStep(explorer.idx, mask, s, ctx).mask;
+  return count(mask);
+}
+
+// ---------------------------------------------------------------------------------------------------------------- arrow keys
+
+const DIRS = { left: [-1, 0], right: [1, 0], up: [0, -1], down: [0, 1] };
+
+/** The neighbour in a screen direction for the arrow keys. `positions`: `[{ id, x, y, visible }]` (screen px, y down; 3D passes
+ *  projected points). Candidates sit in the 90° cone around the direction; the nearest wins, with sideways offset weighing double
+ *  so "right" prefers the doc straight to the right. Ties go to the smaller id. Returns an id or null. */
+export function neighbourInDirection(positions, fromId, dir) {
+  const d = DIRS[dir];
+  const from = positions.find((p) => p.id === fromId);
+  if (!d || !from) return null;
+  let best = null, bestScore = Infinity;
+  for (const p of positions) {
+    if (p.id === fromId || p.visible === false) continue;
+    const dx = p.x - from.x, dy = p.y - from.y;
+    const along = dx * d[0] + dy * d[1], across = Math.abs(dx * d[1] - dy * d[0]);
+    if (along <= 0 || across > along) continue;
+    const score = along + 2 * across;
+    if (score < bestScore || (score === bestScore && String(p.id) < String(best))) { best = p.id; bestScore = score; }
+  }
+  return best;
+}
+
+/** With nothing focused: the biggest visible doc (`size` or `degree` on each position; ties go to the smaller id). */
+export function biggestVisible(positions) {
+  let best = null, bs = -Infinity;
+  for (const p of positions) {
+    if (p.visible === false) continue;
+    const s = p.size ?? p.degree ?? 0;
+    if (s > bs || (s === bs && String(p.id) < String(best))) { best = p.id; bs = s; }
+  }
+  return best;
+}

package/src/graph/lib/graphFind.js

@@ -0,0 +1,46 @@
+// WIKI-GRAPH-FIND-FILTER-LIVE-1: "Find a doc by title" filters the graph live. Typing (debounced FIND_DEBOUNCE_MS) sets a
+// match set; both canvases light the matches and dim everything else through the selection-focus treatment (graphView
+// `litOf`, the canvases' `relight`), with no layout pass and no node moved. The pure parts live here so the page and both
+// renderers share one rule.
+import { searchNodes } from "./wikiGraph";
+import { folderId } from "./graphLevels";
+
+export const FIND_DEBOUNCE_MS = 100;
+export const FIND_LIST = 8; // the dropdown shows the best few; the count and the lit set cover every match
+
+/** Is there anything to find? An empty or whitespace term is no filter. */
+export const hasTerm = (term) => String(term || "").trim().length > 0;
+
+/** Every doc of `nodes` whose title holds `term` (case-insensitive substring), in searchNodes' order: title prefixes first,
+ *  then shorter titles, then by title. Only the docs `visible(id)` keeps count (the legend's hidden groups, the local
+ *  graph's hops); no `visible` keeps all. [] for an empty term. */
+export function findMatches(nodes, term, visible) {
+  if (!hasTerm(term)) return [];
+  return searchNodes(visible ? nodes.filter((n) => visible(n.id)) : nodes, term, Infinity);
+}
+
+/** The drawn node a doc shows as: the doc itself when it is drawn, else (a level view) the deepest drawn folder holding
+ *  it (the virtual root folder `folderId("")` last, which holds the root docs, `folder: ""`), else null (not drawn at all). `drawnIds`: the
+ *  ids the canvas draws. */
+export function drawnFor(doc, drawnIds) {
+  if (drawnIds.has(doc.id)) return doc.id;
+  const parts = String(doc.folder || "").split("/").filter(Boolean);
+  for (let k = parts.length; k >= 0; k--) {
+    const id = folderId(parts.slice(0, k).join("/"));
+    if (drawnIds.has(id)) return id;
+  }
+  return null;
+}
+
+/** The drawn ids the matches light, in match order, each once: a matching doc, or the folder that holds it in a level view. */
+export function litIds(matches, drawnIds) {
+  const out = new Set();
+  for (const d of matches) {
+    const id = drawnFor(d, drawnIds);
+    if (id !== null) out.add(id);
+  }
+  return [...out];
+}
+
+/** The text next to the box. */
+export const countText = (n) => (n === 0 ? "No doc title matches." : n === 1 ? "1 match" : `${n} matches`);

package/src/graph/lib/graphLasso.js

@@ -0,0 +1,44 @@
+// WIKI-GRAPH-EXPLORE-1c-UI round 1: the 3D lasso's pure parts (3D-UX-1 REPORT rows "lasso" and D2). Shift-drag on the 3D surface draws a
+// polygon in surface px; release selects every doc whose projected centre is inside it, THROUGH the ball (front and back), and the live
+// count says how many of them were behind the pivot. The canvas draws and samples the polygon, the page calls lassoHits on what
+// `screenPositions()` reports (x, y, visible, depth = view depth, `pivotDepth()` = the turn pivot's view depth).
+
+export const LASSO_STEP_PX = 4; // a drag point closer than this to the last one is dropped (keeps the polygon short)
+export const LASSO_MIN_POINTS = 3; // fewer than this is a line, not an area: it catches nothing
+
+/** Ray-casting point-in-polygon for `pts` = [[x, y], ...] (implicitly closed). A point on an edge may go either way. */
+export function pointInPolygon(x, y, pts) {
+  let inside = false;
+  for (let i = 0, j = pts.length - 1; i < pts.length; j = i++) {
+    const [xi, yi] = pts[i], [xj, yj] = pts[j];
+    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) inside = !inside;
+  }
+  return inside;
+}
+
+/** The polygon after the pointer reaches (x, y): the same array when the point is under `step` px from the last one, else a new
+ *  array with it appended. A non-finite point is ignored. */
+export function lassoSample(pts, x, y, step = LASSO_STEP_PX) {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return pts;
+  const last = pts[pts.length - 1];
+  if (last && Math.hypot(x - last[0], y - last[1]) < step) return pts;
+  return [...pts, [x, y]];
+}
+
+/** What a polygon catches. `list` = screenPositions rows {id, x, y, visible, depth}; `pivotDepth` = the pivot's view depth (null: nothing
+ *  counts as behind). A row counts when it is drawn (`visible`, so in front of the camera, on screen and not hidden) and its centre is
+ *  inside the polygon, whatever its depth. `behind` = those farther than the pivot. Returns {ids, inside, behind}. */
+export function lassoHits(pts, list, pivotDepth = null) {
+  if (!pts || pts.length < LASSO_MIN_POINTS) return { ids: [], inside: 0, behind: 0 };
+  const ids = [];
+  let behind = 0;
+  for (const r of list) {
+    if (!r.visible || !pointInPolygon(r.x, r.y, pts)) continue;
+    ids.push(r.id);
+    if (pivotDepth != null && r.depth > pivotDepth) behind++;
+  }
+  return { ids, inside: ids.length, behind };
+}
+
+/** The live count while dragging, and the same words once released. */
+export const lassoText = (inside, behind) => `${inside} inside (${behind} behind)`;