@smartmemory/wiki-components 0.5.0 → 0.6.0

package/src/graph/lib/graphPress.js

@@ -0,0 +1,27 @@
+// WIKI-GRAPH-3D-PAN-MODIFIER-1: what a mouse press on the 3D surface does, decided ONCE from the pointerdown event's own flags and
+// held for the whole drag (OrbitControls fixes its state at pointerdown and never re-reads a modifier on move). Pure: no three import.
+// Plain left turns; Cmd, Ctrl, Option/Alt, Option+Cmd or Shift (the lasso takes Shift+left first) pan; middle pans; right does nothing
+// (it stays the node menu). OrbitControls swaps ROTATE<->PAN whenever ctrl/meta/shift is down, so we pick the button action that
+// comes out as the wanted one after that swap, instead of depending on it.
+
+// three's MOUSE enum values (ROTATE 0, DOLLY 1, PAN 2), kept as numbers so this file stays pure: a test pins them to three.
+export const ROTATE = 0;
+export const PAN = 2;
+
+/** Whether OrbitControls (three r17x) applies its own modifier swap to this press (ctrl, meta or shift down). */
+export const swapActive = (e) => !!(e.ctrlKey || e.metaKey || e.shiftKey);
+
+/** "pan" | "turn" for a mouse press `{button, shiftKey, altKey, ctrlKey, metaKey}` (touch is not decided here). Any modifier pans. */
+export const pressMode = (e) => {
+  if ((e.button ?? 0) === 1) return "pan";
+  return e.shiftKey || e.altKey || e.ctrlKey || e.metaKey ? "pan" : "turn";
+};
+
+/** The OrbitControls action to put on a button for this press so that, after its own swap, the drag does `want` ("pan" | "turn"). */
+export const actionFor = (e, want) => ((want === "pan") === swapActive(e) ? ROTATE : PAN);
+
+/** `{LEFT, MIDDLE}` OrbitControls actions for this press. Middle is always a pan, whatever modifiers are down. */
+export const buttonActions = (e) => ({ LEFT: actionFor(e, pressMode({ button: 0, shiftKey: e.shiftKey, altKey: e.altKey, ctrlKey: e.ctrlKey, metaKey: e.metaKey })), MIDDLE: actionFor(e, "pan") });
+
+/** The mouse mapping in plain words (gizmo tooltip). */
+export const MOUSE_HELP = "drag turns, Cmd/Option+drag pans, Shift+drag selects";

package/src/graph/lib/graphShell.js

@@ -0,0 +1,296 @@
+// WIKI-GRAPH-EXPLORE-1b-SHELL (part A): the pure half of the Graph page's omnibox and filter chips (no DOM, no React, no canvas).
+// The omnibox reads a verb ("in", "links to", "orphans", ...) or a title, and offers docs to fly to, folders, filter verbs and the
+// recent docs; picking a filter appends a step to the explore state (graphExplore.js, 1a), which the page encodes in the `x` URL
+// param and runs to get the visible docs. Ported from the EXPLORE-1b branch's graphShell.js (a44298e, omnibox grammar, chip
+// edits, small stores) and narrowed to part A: the search lens is not offered (nothing creates one), the path lens is (round 3 of 1c-UI:
+// the `path A to B` verb, graphPath.js), part B adds
+// the doc card, the View drawer and Back as undo. Design: smart-memory-docs docs/features/WIKI-GRAPH-EXPLORE-1/design.md §3, §5, §6.
+import { emptyState, encodeX, normaliseStep, parseExploreParams, pathChipText, phraseOf } from "./graphExplore";
+import { findMatches } from "./graphFind";
+import { splitPathArgs } from "./graphPath";
+
+// ------------------------------------------------------------------------------------------------------------- chip edits
+
+const sameStep = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+/** Append a step (validated). An identical last step is not added twice. Returns the same state when nothing changes. */
+export function addStep(state, raw) {
+  const step = normaliseStep(raw);
+  if (!step) return state;
+  const last = state.steps[state.steps.length - 1];
+  if (last && sameStep(last, step)) return state;
+  return { ...state, steps: [...state.steps, step] };
+}
+/** Remove chip `i` (out of range: the same state). */
+export const removeStep = (state, i) => (i < 0 || i >= state.steps.length ? state : { ...state, steps: state.steps.filter((_, j) => j !== i) });
+/** Every chip and lens gone. */
+export const clearAll = (state) => (state.steps.length || state.lenses.length ? { ...state, steps: [], lenses: [] } : state);
+
+/** The explore state the URL holds. Only `x` is read: the legacy `hide` / `local` / `hops` params stay owned by today's legend,
+ *  Local graph box and hops stepper (parseExploreParams would turn `hide` into a `not area` chip, which is wrong while the legend
+ *  colours by folder or by scope, where `hide` holds folder or scope names). `x`: the param's value, or null when absent.
+ *  Returns `{ state, ignored, notice }`. */
+export function readExplore(x) {
+  if (typeof x !== "string") return { state: emptyState(), ignored: 0, notice: "" };
+  const { state, ignored, notice } = parseExploreParams(new URLSearchParams({ x }));
+  return { state, ignored, notice };
+}
+
+/** A copy of `params` with `x` set to `state` (removed when the state is empty); every other param, the legacy ones included, is
+ *  kept (graphExplore writeExploreParams drops `hide` / `local` / `hops`, which today's legend and hops stepper still own). */
+export function withExplore(params, state) {
+  const sp = new URLSearchParams(typeof params === "string" ? params : params.toString());
+  const x = encodeX(state);
+  if (x) sp.set("x", x); else sp.delete("x");
+  return sp;
+}
+
+/** True when writing `state` would leave the URL's `x` as it is: such an edit must not push a history entry, or Back would "undo" nothing. */
+export function exploreUnchanged(params, state) {
+  const sp = typeof params === "string" ? new URLSearchParams(params) : params;
+  return withExplore(sp, state).toString() === sp.toString();
+}
+
+// ------------------------------------------------------------------------------------------------------------ the omnibox
+
+/** The omnibox's verbs (design §3). `arg`: what it asks for next ("folder", "doc", "folder-or-doc", "number", "area", "docs" (two docs, the path lens), "none").
+ *  `make(arg, extra)` gives the step for the chosen argument. A leading "not " is read by `parseVerb` and sets `not`. Owner
+ *  decision 2: "children of" a doc is linked either way (`near`, 1 hop). */
+export const OMNI_VERBS = [
+  { key: "children", label: "children of …", hint: "a folder's contents, or the docs linked to a doc either way", arg: "folder-or-doc", words: ["children of", "children"],
+    make: (a) => (a.kind === "folder" ? { op: "in", path: a.path } : { op: "near", id: a.id, hops: 1 }) },
+  { key: "in", label: "in …", hint: "docs inside a folder", arg: "folder", words: ["in", "inside", "folder"], make: (a) => ({ op: "in", path: a.path }) },
+  { key: "from", label: "links from …", hint: "docs a doc links to", arg: "doc", words: ["links from", "linked from", "from"], make: (a) => ({ op: "from", id: a.id, hops: 1 }) },
+  { key: "to", label: "links to …", hint: "docs that link to a doc (backlinks)", arg: "doc", words: ["backlinks of", "backlinks", "links to", "linking to", "to"],
+    make: (a) => ({ op: "to", id: a.id, hops: 1 }) },
+  { key: "near", label: "near … [n]", hint: "within n links of a doc, either way", arg: "doc", words: ["near", "within", "nearby"], make: (a, n) => ({ op: "near", id: a.id, hops: n || 2 }) },
+  { key: "min", label: "linked ≥ n", hint: "docs with at least n links", arg: "number", words: ["linked >=", "linked ≥", "linked at least", "min links"], make: (n) => ({ op: "degree", min: n }) },
+  { key: "max", label: "linked ≤ n", hint: "docs with at most n links", arg: "number", words: ["linked <=", "linked ≤", "linked at most", "max links"], make: (n) => ({ op: "degree", max: n }) },
+  { key: "hubs", label: "hubs", hint: "the top 1% by links", arg: "none", words: ["hubs", "hub"], make: (_a, t) => ({ op: "degree", min: t }) },
+  { key: "orphans", label: "orphans", hint: "docs with no links", arg: "none", words: ["orphans", "orphan"], make: () => ({ op: "orphans" }) },
+  { key: "path", label: "path … to …", hint: "the shortest chain of links between two docs, lit on the graph", arg: "docs", lens: true, words: ["path", "path from", "path between"] },
+  { key: "area", label: "area …", hint: "docs in an area", arg: "area", words: ["area"], make: (a) => ({ op: "area", names: [a] }) },
+];
+
+/** Read what the reader typed: `{ not, verb, rest }` when the text starts with a verb word (longest word first, then a space or the
+ *  end; a word ending in ≥ ≤ = may run straight into the number), else `{ not: false, verb: null, rest: text }`. */
+export function parseVerb(text) {
+  let t = String(text || "").replace(/^\s+/, "");
+  let not = false;
+  if (/^not\s+/i.test(t)) { not = true; t = t.replace(/^not\s+/i, ""); }
+  const lower = t.toLowerCase();
+  let best = null;
+  for (const v of OMNI_VERBS) {
+    for (const w of v.words) {
+      if ((lower === w || lower.startsWith(w + " ") || (/[≥≤=]$/.test(w) && lower.startsWith(w))) && (!best || w.length > best.w.length)) best = { v, w };
+    }
+  }
+  if (!best) return { not: false, verb: null, rest: String(text || "").trim() };
+  return { not, verb: best.v, rest: t.slice(best.w.length).trim() };
+}
+
+/** The verbs whose label or words start with (or contain) the typed text, best first; empty text lists none. */
+export function verbsMatching(text, limit = 5) {
+  const q = String(text || "").trim().toLowerCase().replace(/^not\s+/, "");
+  if (!q) return [];
+  const score = (v) => {
+    let s = Infinity;
+    for (const w of [v.label.toLowerCase(), ...v.words]) {
+      const at = w.indexOf(q);
+      if (at === 0) s = Math.min(s, 0);
+      else if (at > 0) s = Math.min(s, 1);
+    }
+    return s;
+  };
+  return OMNI_VERBS.map((v) => [score(v), v]).filter(([s]) => s < Infinity).sort((a, b) => a[0] - b[0]).slice(0, limit).map(([, v]) => v);
+}
+
+/** Docs per folder path, counting every ancestor (a doc in a/b counts for a and a/b). */
+export function folderCounts(nodes) {
+  const out = new Map();
+  for (const n of nodes) {
+    const segs = String(n.folder || "").split("/").filter(Boolean);
+    for (let i = 1; i <= segs.length; i++) { const p = segs.slice(0, i).join("/"); out.set(p, (out.get(p) || 0) + 1); }
+  }
+  return out;
+}
+
+/** Folders whose path holds `q` (case-insensitive): path prefixes first, then a match at a segment start, then shallower, then
+ *  bigger, then by path. Empty `q` lists the biggest top-level folders. `counts` maps path -> docs. Returns `[{ path, count }]`. */
+export function searchFolders(counts, q, limit = 6) {
+  const needle = String(q || "").trim().toLowerCase().replace(/^\/+|\/+$/g, "");
+  const hits = [];
+  for (const [path, n] of counts) {
+    if (!path) continue;
+    const depth = path.split("/").length;
+    if (!needle) { if (depth === 1) hits.push([0, depth, -n, path]); continue; }
+    const p = path.toLowerCase();
+    const at = p.indexOf(needle);
+    if (at < 0) continue;
+    hits.push([at === 0 ? 0 : p[at - 1] === "/" ? 1 : 2, depth, -n, path]);
+  }
+  hits.sort((a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2] || a[3].localeCompare(b[3]));
+  return hits.slice(0, limit).map((h) => ({ path: h[3], count: -h[2] }));
+}
+
+/** The trailing hop count of a `near` argument ("Plan v2 3" gives 3), 1..4, else null. */
+export function trailingHops(rest) {
+  const m = /\s([1-4])$/.exec(String(rest || ""));
+  return m ? Number(m[1]) : null;
+}
+
+/** The degree a doc needs to be a hub: the top 1% by links (at least 1 link). `idx`: graphExplore buildIndex. */
+export function hubThreshold(idx) {
+  if (!idx.n) return 1;
+  const d = Array.from(idx.degree).sort((a, b) => b - a);
+  return Math.max(1, d[Math.max(0, Math.ceil(idx.n * 0.01) - 1)]);
+}
+
+/** The chip text a step adds (with `not `), for the omnibox preview and the chip row. */
+export const chipText = (step, idx) => (step.not ? "not " : "") + phraseOf(step, idx);
+
+/** The area names of the docs, sorted. */
+export const areaNames = (nodes) => [...new Set(nodes.map((n) => n.area).filter(Boolean))].sort((a, b) => a.localeCompare(b));
+
+export const OMNI_DOCS = 8; // docs offered per query (the old find list's FIND_LIST)
+export const OMNI_FOLDERS = 4; // folders offered beside the docs when no verb is typed
+export const OMNI_PREVIEW = 6; // filter rows that show how many docs they would leave (one explorer run each)
+
+/** The omnibox's rows for what the reader typed. Every row is `{ kind, key, label, detail, action }`; `action` is
+ *  `{ type: "fly", id }` (go to a doc), `{ type: "step", step }` (add that filter chip), `{ type: "lens", lens }` (set the path lens), `{ type: "view", name }` (apply that saved view), `{ type: "verb", fill }` (put the verb in
+ *  the box and ask for its argument), `{ type: "clear" }` (remove every filter), or null for a row that only says why nothing is
+ *  offered. Kinds: recent | view | doc | folder | verb | filter | clear | empty.
+ *  - empty text: the recent docs still in view, then the saved views, then "Clear all filters" when there are chips;
+ *  - no verb: docs by title (the visible ones, searchNodes' order), then folders (an `in` chip), then the verbs that match;
+ *  - a verb: its argument's candidates as filter rows (`not ` kept), or one `empty` row saying what it needs.
+ *  `opts`: `{ text, nodes, visible, idx, counts, recent, steps, explorer, byId }`. With `explorer`, the first OMNI_PREVIEW filter
+ *  rows carry `detail` = how many docs the stack would leave with that chip added. */
+export function omniRows({ text = "", nodes = [], visible, idx = null, counts = new Map(), recent = [], views = [], steps = [], explorer = null, byId = null }) {
+  const rows = [];
+  const t = String(text || "");
+  const docRows = (q, make) => findMatches(nodes, q, visible).slice(0, OMNI_DOCS).map(make);
+  if (!t.trim()) {
+    for (const id of Array.isArray(recent) ? recent : []) {
+      if (typeof id !== "string") continue;
+      const n = byId ? byId.get(id) : nodes.find((m) => m.id === id);
+      if (n && (!visible || visible(n.id))) rows.push({ kind: "recent", key: `recent:${id}`, label: n.title, detail: n.folder || "(root)", action: { type: "fly", id } });
+    }
+    for (const v of Array.isArray(views) ? views : []) {
+      if (v && typeof v.name === "string") rows.push({ kind: "view", key: `view:${v.name}`, label: v.name, detail: "saved view", action: { type: "view", name: v.name } });
+    }
+    if (steps.length) rows.push({ kind: "clear", key: "clear", label: "Clear all filters", detail: "", action: { type: "clear" } });
+    return rows;
+  }
+  const { not, verb, rest } = parseVerb(t);
+  if (!verb) {
+    rows.push(...docRows(t, (n) => ({ kind: "doc", key: `doc:${n.id}`, label: n.title, detail: n.folder || "(root)", action: { type: "fly", id: n.id } })));
+    for (const f of searchFolders(counts, t, OMNI_FOLDERS)) rows.push(filterRow({ op: "in", path: f.path }, `folder:${f.path}`, "folder"));
+    for (const v of verbsMatching(t)) {
+      rows.push(v.arg === "none"
+        ? filterRow(v.make(null, idx ? hubThreshold(idx) : 1), `verb:${v.key}`, "verb", v.hint)
+        : { kind: "verb", key: `verb:${v.key}`, label: v.label, detail: v.hint, action: { type: "verb", fill: `${v.words[0]} ` } });
+    }
+  } else {
+    const mark = (s) => (not ? { ...s, not: true } : s);
+    const add = (raw, key) => { const r = filterRow(mark(raw), key, "filter"); if (r) rows.push(r); };
+    if (verb.arg === "folder" || verb.arg === "folder-or-doc") {
+      for (const f of searchFolders(counts, rest)) add(verb.make({ kind: "folder", path: f.path }), `in:${f.path}`);
+    }
+    if (verb.arg === "doc" || verb.arg === "folder-or-doc") {
+      const hops = verb.key === "near" ? trailingHops(rest) : null;
+      const q = hops ? rest.replace(/\s[1-4]$/, "") : rest;
+      if (q.trim()) for (const r of docRows(q, (n) => n)) add(verb.make({ kind: "doc", id: r.id }, hops), `${verb.key}:${r.id}`);
+    }
+    if (verb.arg === "number") {
+      const n = /^\d{1,6}$/.test(rest) ? Number(rest) : NaN;
+      if (Number.isFinite(n)) add(verb.make(n), `${verb.key}:${n}`);
+    }
+    if (verb.arg === "none") add(verb.make(null, idx ? hubThreshold(idx) : 1), verb.key);
+    if (verb.arg === "docs") rows.push(...pathRows(rest));
+    if (verb.arg === "area") {
+      const q = rest.toLowerCase();
+      for (const a of areaNames(nodes).filter((a) => a.toLowerCase().includes(q))) add(verb.make(a), `area:${a}`);
+    }
+    if (!rows.length) rows.push({ kind: "empty", key: "empty", label: emptyText(verb, rest), detail: verb.hint, action: null });
+  }
+  if (explorer) {
+    let shown = 0;
+    for (const r of rows) {
+      if (r.action?.type !== "step" || shown >= OMNI_PREVIEW) continue;
+      shown++;
+      const n = explorer.run([...steps, r.action.step]).count;
+      r.detail = `${n.toLocaleString("en-US")} ${n === 1 ? "doc" : "docs"}`;
+    }
+    explorer.run(steps); // leave the prefix cache on the live stack
+  }
+  return rows;
+
+  /** `path A to B`: while the first doc is being typed, its docs as verb rows that fill `path <title> to `; once there is a ` to `,
+   *  one lens row per second-doc match, labelled with the chip it makes. */
+  function pathRows(rest) {
+    const { from, left, right, hasTo } = splitPathArgs(rest, nodes, visible);
+    if (!left) return [];
+    if (!hasTo) return findMatches(nodes, left, visible).slice(0, OMNI_DOCS).map((n) => ({ kind: "verb", key: `path-from:${n.id}`, label: n.title, detail: "then type to …", action: { type: "verb", fill: `path ${n.title} to ` } }));
+    if (!from) return [];
+    if (!right) return [{ kind: "empty", key: "path-to", label: `Path from ${from.title}: type the second doc`, detail: "", action: null }];
+    return findMatches(nodes, right, visible).slice(0, OMNI_DOCS).map((n) => {
+      const lens = { lens: "path", from: from.id, to: n.id };
+      return { kind: "filter", key: `path:${from.id}:${n.id}`, label: pathChipText(lens, idx), detail: "", action: { type: "lens", lens } };
+    });
+  }
+
+  function filterRow(raw, key, kind, detail = "") {
+    const step = normaliseStep(raw);
+    return step ? { kind, key, label: chipText(step, idx), detail, action: { type: "step", step } } : null;
+  }
+}
+
+function emptyText(verb, rest) {
+  if (verb.arg === "number") return rest ? `"${rest}" is not a number` : "Type a number";
+  if (verb.arg === "area") return rest ? `No area matches "${rest}"` : "No areas in this workspace";
+  if (verb.arg === "folder") return rest ? `No folder matches "${rest}"` : "No folders in this workspace";
+  if (verb.arg === "docs") return rest ? `No doc title matches "${rest}"` : "Type the first doc, then to, then the second";
+  return rest ? `No doc title matches "${rest}"` : "Type a doc title";
+}
+
+/** Which row a key moves to: `cursor` is the active row (-1 none), `rows` the omnibox rows (rows with no action are skipped). */
+export function moveCursor(rows, cursor, d) {
+  const live = rows.map((r, i) => (r.action ? i : -1)).filter((i) => i >= 0);
+  if (!live.length) return -1;
+  const at = live.indexOf(cursor);
+  if (at < 0) return d > 0 ? live[0] : live[live.length - 1];
+  return live[(at + d + live.length) % live.length];
+}
+
+// ------------------------------------------------------------------------------------------------------------ small stores
+
+/** Read / write a small JSON value in localStorage; every access in try/catch (a browser that refuses storage still works). */
+export function readStore(key, fallback) {
+  try { const v = globalThis.localStorage?.getItem(key); return v === null || v === undefined ? fallback : JSON.parse(v); } catch { return fallback; }
+}
+export function writeStore(key, value) {
+  try { globalThis.localStorage?.setItem(key, JSON.stringify(value)); return true; } catch { return false; }
+}
+export const RECENT_MAX = 6;
+/** A recent list read back from storage (untrusted): a non-array is `[]`, an entry that is not a non-empty string is dropped, repeats go,
+ *  at most RECENT_MAX stay. Never throws. */
+export const cleanRecent = (raw) => (Array.isArray(raw) ? [...new Set(raw.filter((x) => typeof x === "string" && x))].slice(0, RECENT_MAX) : []);
+/** The recent-docs list: `id` moved to the front, at most `max`. */
+export const pushRecent = (list, id, max = RECENT_MAX) => [id, ...(Array.isArray(list) ? list : []).filter((x) => x !== id)].slice(0, max);
+/** The recent-docs store key, one list per workspace. */
+export const recentKey = (workspace) => `wiki.graph.recent.${workspace}`;
+/** Fixed warning text, per feature: never the workspace, the stored payload, a name, a url or an id. */
+export const RECENT_DISCARDED = "Graph: recent docs saved in this browser were malformed and were dropped.";
+/** A stored list (WIKI-GRAPH-STORAGE-WARNING-FU-1): `[]` when the key is missing or storage is refused (both normal and silent); when a value
+ *  is there but is not JSON, not an array, or holds an entry `whole` rejects, ONE console.warn with `text` and the cleaned list. */
+export function readStoredList(key, text, whole, clean) {
+  let raw;
+  try { raw = globalThis.localStorage?.getItem(key); } catch { return []; }
+  if (raw === null || raw === undefined) return [];
+  let v;
+  try { v = JSON.parse(raw); } catch { console.warn(text); return []; }
+  if (!Array.isArray(v) || !v.every(whole)) console.warn(text);
+  return clean(v);
+}
+/** The stored recent list, shape-checked (WIKI-GRAPH-RECENT-SHAPE-FU-1): valid JSON of any other shape reads as empty, with the fixed warning. */
+export const readRecent = (workspace) => readStoredList(recentKey(workspace), RECENT_DISCARDED, (x) => typeof x === "string" && x, cleanRecent);

package/src/graph/lib/graphTheme.js

@@ -0,0 +1,50 @@
+// UI-LIGHT-MODE-LM8-1: the graph's non-data colours by colour mode, one place for the 2D (canvas / pixi) and 3D (three) bases and the
+// overlay above them. DARK is exactly what these files hard-coded before this unit (so dark does not change). Node hues (wikiGraph
+// PALETTE, OTHER, OUTSIDE, UNMAPPED_COLOR) stay the data identity (dark hex, what graphLevels and the legend compare on); WIKI-GRAPH-LIGHT-HUES-1
+// translates them to the light set at the four places that draw them (`hueFor`: both canvases, the legend, the linked-docs dot).
+// The mode is module state set by the page (`setGraphMode(resolved)`, from useColorMode) before the canvases render; the canvases are
+// keyed by the mode, so a switch rebuilds the bases, and every draw reads `graphTheme()` fresh, never a copy taken at import.
+export const GRAPH_DARK = {
+  field: "#0a0f1a", // www `ground`
+  label: "#cbd5e1", labelOutline: "#0f172a",
+  hot: "#2bb1ff", focusRing: "#ffffff", selectRing: "#facc15",
+  contain: "#94a3b8", linkRgb: "148,163,184", edgeHex: 0x94a3b8,
+  halo: "#ffffff", haloHex: 0xffffff,
+  bubbleLabel: "rgba(226,232,240,0.75)",
+  gizmoDot: "rgba(255,255,255,0.85)", lassoFill: "rgba(255,255,255,0.08)",
+};
+export const GRAPH_LIGHT = {
+  field: "#f6f8fb", // LANDING light ground
+  label: "#334155", labelOutline: "#f6f8fb",
+  hot: "#0369a1", focusRing: "#0b1526", selectRing: "#b45309",
+  contain: "#64748b", linkRgb: "100,116,139", edgeHex: 0x64748b,
+  halo: "#0b1526", haloHex: 0x0b1526,
+  bubbleLabel: "rgba(51,65,85,0.85)",
+  gizmoDot: "rgba(11,21,38,0.55)", lassoFill: "rgba(3,105,161,0.10)",
+};
+let current = GRAPH_DARK;
+/** The colours in force now. */
+export const graphTheme = () => current;
+/** `light` selects the light set, anything else (dark, a bad value) the dark one. */
+export function setGraphMode(mode) { current = mode === "light" ? GRAPH_LIGHT : GRAPH_DARK; return current; }
+
+// WIKI-GRAPH-LIGHT-HUES-1: the light hue per node hue, same hue family, deeper and slightly less chroma (HSL saturation x0.9, lightness lowered
+// until the fill reaches >= 3.2:1 against the light field `#f6f8fb`, the WCAG 1.4.11 non-text 3:1 plus margin). The design-system kit has no
+// categorical or chart tokens (grep of tokens.cjs / tokens.css / colors_and_type.css, 2026-10-25), so these are derived, not tokens.
+// Rows: [name, dark (the data hex in wikiGraph / graphLevels), light]. OUTSIDE is "dim" by intent: its light value is a pale slate (about the
+// same 1.6-2:1 dimness against its field as the dark one has), so it is exempt from the 3:1 target.
+export const NODE_HUES = [
+  ["amber", "#E69F00", "#b6810a"],
+  ["sky", "#56B4E9", "#2692cf"],
+  ["green", "#009E73", "#08966f"],
+  ["yellow", "#F0E442", "#958c14"],
+  ["blue", "#0072B2", "#0970a9"],
+  ["vermilion", "#D55E00", "#ca5f0b"],
+  ["pink", "#CC79A7", "#c26f9d"],
+  ["other", "#7f8ea5", "#6f7e94"],
+  ["unmapped", "#B9A7FF", "#9176f8"],
+  ["outside", "#3b4556", "#c4cddb"],
+];
+const LIGHT_OF = new Map(NODE_HUES.map(([, dark, light]) => [dark.toLowerCase(), light]));
+/** `hex` (a data hue, `#rrggbb`) as drawn in the mode in force: itself in dark, its light variant in light. A hex that is not a node hue is returned as is. */
+export const hueFor = (hex) => (current === GRAPH_LIGHT && typeof hex === "string" ? LIGHT_OF.get(hex.toLowerCase()) ?? hex : hex);