@smartmemory/wiki-components 0.4.0 → 0.6.0

package/src/graph/host.jsx

@@ -0,0 +1,56 @@
+import React, { createContext, useContext, useEffect } from "react";
+import { useClientCall, useDataClient } from "../data-client";
+
+// COMPOSE-WIKI-GRAPH-1a: what the moved Graph files took from the wiki app, its router, its query layer and the design
+// system, under the same names and call shapes. The host (the wiki app's route wrapper, or Compose) gives the values once,
+// through <GraphHost value={...}>; the files import these names from here instead of from the app.
+//   value: { workspace, useSearchParams, Link, useColorMode, requestTreeSync, aspectHint }
+const Ctx = createContext(null);
+let treeSync = null; // the mounted host's requestTreeSync: a plain function called from event handlers, outside React
+
+export function GraphHost({ value, children }) {
+  useEffect(() => {
+    treeSync = value.requestTreeSync || null;
+    return () => { if (treeSync === (value.requestTreeSync || null)) treeSync = null; };
+  }, [value.requestTreeSync]);
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+function useHost() {
+  const host = useContext(Ctx);
+  if (!host) throw new Error("the wiki graph needs a <GraphHost value={...}> above it");
+  return host;
+}
+
+export const useWiki = () => ({ workspace: useHost().workspace });
+export const useSearchParams = () => useHost().useSearchParams();
+export const useColorMode = () => useHost().useColorMode();
+export const useAspectHint = () => useHost().aspectHint;
+export function Link(props) {
+  const HostLink = useHost().Link;
+  return <HostLink {...props} />;
+}
+/** Ask the host's folder tree to show a doc; nothing happens when the host has no tree. */
+export const requestTreeSync = (req) => { if (treeSync) treeSync(req); };
+
+/** react-query's `useQuery` for the one shape the graph uses: `{data, error, isLoading}`. `staleTime` is the host client's. */
+export function useQuery({ queryKey, queryFn }) {
+  return useClientCall(queryKey, queryFn);
+}
+
+/** One note with its text, through the DataClient. */
+export function useNote(workspace, id, { enabled = true } = {}) {
+  const client = useDataClient();
+  return useClientCall(["note", workspace, id], () => client.note({ workspace, id }), { enabled: enabled && !!id && !!workspace });
+}
+
+// Copied unchanged from ui/src/lib/treeSync.js (the app keeps its own copy for FolderTree).
+const segmentsOf = (path) => String(path || "").split("/").filter(Boolean);
+
+/** A doc of the graph that sits in `folder` or under it (the first by order), or null: a folder node has no source of its own,
+ *  so the tree asks about one of its docs and reads the source from that note. `nodes` are the flat graph's `{id, folder, kind?}`. */
+export function docUnder(nodes, folder) {
+  const f = segmentsOf(folder).join("/");
+  const hit = nodes.find((n) => n.kind !== "folder" && (f === "" ? true : n.folder === f || String(n.folder || "").startsWith(`${f}/`)));
+  return hit ? hit.id : null;
+}

package/src/graph/index.d.ts

@@ -0,0 +1,26 @@
+// Types for @smartmemory/wiki-components/graph. The DataClient calls the Graph makes: graphAll, graphPage, note (../data-client.d.ts).
+import type { ComponentType, ReactElement, ReactNode } from "react";
+import type { DataClient, GraphResult, Workspace } from "../data-client";
+
+/** What the Graph takes from its host, given once through <GraphHost value={...}>. */
+export interface GraphHostValue {
+  workspace: Workspace;
+  /** react-router's `useSearchParams` (or any hook returning `[URLSearchParams, setter]`): the graph keeps its whole view state in the URL. */
+  useSearchParams: () => [URLSearchParams, (next: URLSearchParams | ((prev: URLSearchParams) => URLSearchParams), opts?: { replace?: boolean }) => void];
+  /** A link component taking `to` (the host's own route). */
+  Link: ComponentType<{ to: string; className?: string; children?: ReactNode }>;
+  /** The design system's `useColorMode`: `{ resolved: "light" | "dark" }`. */
+  useColorMode: () => { resolved: string };
+  /** Ask the host's folder tree to show a doc (or a folder of the doc's source). Optional. */
+  requestTreeSync?: (req: { id: string; folder?: string | null }) => void;
+  /** The words for the greyed "aspect" options. */
+  aspectHint: string;
+}
+
+export function GraphHost(props: { value: GraphHostValue; children?: ReactNode }): ReactElement;
+/** The Graph screen. Needs a <WikiDataProvider> and a <GraphHost> above it. */
+export const GraphPage: () => ReactElement;
+export const GRAPH_ASPECTS: string[];
+export function resetWebGL2Probe(): void;
+export function wholeGraph(workspace: Workspace, client: DataClient): Promise<{ items: Record<string, unknown>[]; edges: Record<string, unknown>[]; total: number; layout: unknown }>;
+export type { GraphResult };

package/src/graph/index.js

@@ -0,0 +1,4 @@
+// @smartmemory/wiki-components/graph (COMPOSE-WIKI-GRAPH-1a): the wiki Graph screen, moved as it was. Its own entry so a host
+// that never draws it does not load it (d3-force, d3-quadtree, react-markdown; pixi.js and three load lazily from inside).
+export { default as GraphPage, GRAPH_ASPECTS, resetWebGL2Probe, wholeGraph } from "./pages/GraphPage";
+export { GraphHost } from "./host";

package/src/graph/lib/areaFamilies.js

@@ -0,0 +1,32 @@
+// WIKI-GRAPH-AREA-FAMILIES-1: "Colour by: area" rolls the ~240 areas (feature-id prefixes, classifier_rules `_areas`) up into a few
+// FAMILIES, one palette colour each, so the legend and the graph stay readable. Adding a prefix is one word in one list below.
+// Order matters: a family's position is its PALETTE index, so a family keeps its colour in every graph. At most PALETTE.length families.
+// An area in no list is UNMAPPED (its own legend row and swatch, never the grey): folder-derived containers that exist in several repos
+// (root, docs, architecture, features, evidence, smartmemory) say nothing about a family and stay there on purpose.
+export const UNMAPPED = "unmapped"; // the family name an area in no list gets
+
+export const AREA_FAMILIES = {
+  // memory engine: store, graph, retrieval, ingestion, consolidation, the 2.0 alignment and local runtime
+  "core engine": ["core", "onto", "vec", "search", "memory", "graph", "falkor", "ingest", "pipe", "recall", "sleep", "self", "recon", "decision", "full", "sm2", "fwd", "code", "local", "mem", "decisions", "implicit", "zettel", "meta", "lite"],
+  // service and platform: API, accounts, tenancy, auth, billing, secrets, MCP, connectors, governance, observability
+  "service & platform": ["svc", "plat", "ws", "session", "api", "common", "auth", "clerk", "tenant", "bill", "secret", "mcp", "tier", "byoc", "conn", "gov", "obs", "admin", "scope", "sec", "secrets", "adm", "byok", "idp", "cross", "workspace"],
+  // apps and UI: web, studio, Maya, hub, insights, SDKs and clients, demos, video
+  "apps & UI": ["web", "studio", "maya", "client", "sdk", "ui", "hub", "insights", "vis", "demo", "video", "app", "cli", "ask", "wrapper", "render", "ds", "tour", "catalog"],
+  // the wiki itself, its sync and captures
+  wiki: ["wiki", "sync", "capture"],
+  // ops and process: units, batches, ledgers, status, tooling, deploys, landing, tests, follow-ups, tech debt, plus the bug, plan and archive
+  // folders (those exist per repo and hold work records, so they roll up here)
+  "ops & process": ["units", "batch", "ops", "fu", "status", "coordination", "claude", "deps", "infra", "deploy", "land", "e2e", "tick", "cc", "refactor", "tech", "test", "max", "compose", "stamps", "report", "coord", "crash", "port", "testsem", "us1", "rel", "stamp", "gate", "job", "seat", "kill", "load", "night", "nightly", "reboot", "sigkill", "statusline", "wake", "dry", "tab", "medium", "ultra", "techdebt", "prepush", "queue", "queues", "seat2", "detach", "jobwatch", "wait", "landed", "daemon", "quota", "retro", "estimate", "tools", "auto", "chain", "pre", "codex", "forward", "time", "fable", "gap", "error", "overlap", "briefs", "roadmap", "arch", "bugs", "plans", "archive"],
+  // bench and research: benchmarks, spikes, metrics, model A/B
+  "bench & research": ["bench", "spike", "metrics", "comp", "locomo"],
+  // go-to-market and product: distribution, launch, onboarding, support, pricing, grants, strategy
+  "go-to-market": ["gtm", "marketing", "product", "launch", "dist", "support", "onboarding", "upgrade", "strat", "grant", "dev", "cofounder", "beta", "interview", "enterprise", "soc2", "raindrop", "content", "prospect", "competitor", "yc", "onboard"],
+};
+
+/** area name -> family name, built once from the table; the first list that names an area wins (a completeness test forbids a second). */
+const FAMILY_OF = new Map(Object.entries(AREA_FAMILIES).flatMap(([family, areas]) => areas.map((a) => [a, family])));
+
+/** The family an area belongs to, or UNMAPPED. */
+export function familyOf(area) {
+  return FAMILY_OF.get(area) ?? UNMAPPED;
+}

package/src/graph/lib/camFollow.js

@@ -0,0 +1,30 @@
+// WIKI-GRAPH-DRIFT-LONG-EDGES-1: when a layout may move the camera, one rule for both canvases (GraphCanvas 2D, GraphCanvas3D).
+// Before it, both refit the camera on EVERY worker tick (and 3D every 150 ms of a glide) until the reader moved it, so the view
+// zoomed and slid for the whole settle and again after any reheat: the owner's "zoom drift".
+//
+// Now a view (a node set, and in 3D its cluster/focus/hops state) gets a follow budget: while its first layout runs the camera
+// refits at most FOLLOW_MAX times, FOLLOW_MS apart (a cold layout grows out of its seed frame, and without a few early refits the
+// graph sits half off screen for the whole settle), and once when that layout settles (or its glide lands). After that ticks never
+// move the camera: a reheat, a slider, a pin or unpin, new weights all leave it where it is. Explicit refits (the fit button,
+// fitTo, a focus, a level or view change, a resize, a click on empty space) call placeView directly and are not counted here.
+export const FOLLOW_MAX = 3;
+export const FOLLOW_MS = 1000;
+
+/** The follow state for view `key`: `prev` when it is the same view (a reheat keeps a spent budget spent), else a fresh budget. */
+export function followFor(prev, key) {
+  return prev && prev.key === key ? prev : { key, fits: 0, at: -Infinity, done: false };
+}
+
+/** A spent follow state for view `key`: a view that is already final (no layout ran, or no worker) never follows. */
+export const followDone = (key) => ({ key, fits: FOLLOW_MAX, at: -Infinity, done: true });
+
+/** Whether a layout `event` ("tick": a frame, "settled": the layout or its glide came to rest) refits the camera now, at `now` ms.
+ *  Never after a user move or once the view's first layout has settled. Updates `f`. */
+export function follows(f, event, now, userMoved) {
+  if (!f || f.done) return false;
+  if (event === "settled") { f.done = true; return !userMoved; }
+  if (userMoved || f.fits >= FOLLOW_MAX || now - f.at < FOLLOW_MS) return false;
+  f.fits++;
+  f.at = now;
+  return true;
+}

package/src/graph/lib/canvasPort.js

@@ -0,0 +1,93 @@
+// WIKI-GRAPH-3D-PORT-1: the pure parts of the canvas port (EXPLORE-1b REPORT handoff item 4, 3D-UX-1 REPORT §2 change table),
+// kept out of the canvas so the 2D canvas can call the same helpers when it gets the port: the Alt-click depth cycle, the flash
+// ring, the hover-card placement, the pivot (orbit about a point that is not the controls' target), the zoom step and the
+// screen-position list the page reads (`screenPositions`). Nothing here touches the DOM or three.
+
+export const FLASH_MS = 900; // `flash(id)`: an expanding ring for ~900 ms (1b handoff item 4)
+export const FLASH_GROW_PX = 28;
+export const CARD_GAP = 12; // the hover card sits 12 px below-right of the dot (3D-UX-1 §2 "hover card")
+
+const ease = (t) => 1 - (1 - t) ** 3;
+
+/** Alt-click depth cycle (3D-UX-1 §2 "occlusion": "Alt-click cycles one deeper per click"). `stack`: the node indices under the
+ *  pointer, front to back (graph3d pickStack). `prev`: the state this returned last time, or null. The first Alt-click at a spot
+ *  takes the hit one behind the front (a plain click already gives the front), each further Alt-click within `tol` px on the same
+ *  stack goes one deeper and wraps to the front after the last. Returns {pick, state}; pick -1 and state null on an empty stack. */
+export function depthCycle(prev, stack, x, y, tol = 3) {
+  if (!stack || !stack.length) return { pick: -1, state: null };
+  const same = !!prev && Math.hypot(x - prev.x, y - prev.y) <= tol && prev.stack.length === stack.length && prev.stack.every((v, i) => v === stack[i]);
+  const k = same ? (prev.k + 1) % stack.length : stack.length > 1 ? 1 : 0;
+  return { pick: stack[k], state: { x: same ? prev.x : x, y: same ? prev.y : y, stack: [...stack], k } };
+}
+
+/** The flash ring `t` ms after `flash(id)` round a dot of drawn radius `r` px: {radius, alpha}, or null once it is over.
+ *  `still` (reduced motion): the same life and fade, but a constant radius (a static ring). */
+export function flashRing(t, r, still = false) {
+  if (!(t >= 0) || t >= FLASH_MS) return null;
+  const u = t / FLASH_MS;
+  return { radius: r + 4 + (still ? 0 : FLASH_GROW_PX * ease(u)), alpha: 1 - u };
+}
+
+/** Where a `cw` x `ch` px hover card goes for a dot at (ax, ay) with drawn radius `ar` on a `w` x `h` surface: below-right with a
+ *  CARD_GAP gap; flipped left when it would cross the right edge and up when it would cross the bottom (3D-UX-1 §2 "hover card"). */
+export function placeCard(ax, ay, ar, cw, ch, w, h, gap = CARD_GAP) {
+  let left = ax + ar + gap, top = ay + ar + gap, flipX = false, flipY = false;
+  if (left + cw > w) { left = ax - ar - gap - cw; flipX = true; }
+  if (top + ch > h) { top = ay - ar - gap - ch; flipY = true; }
+  return { left, top, flipX, flipY };
+}
+
+const sub = (a, b) => [a[0] - b[0], a[1] - b[1], a[2] - b[2]];
+const add = (a, b) => [a[0] + b[0], a[1] + b[1], a[2] + b[2]];
+const len = (a) => Math.hypot(a[0], a[1], a[2]);
+const cross = (a, b) => [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]];
+const dot = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+/** `w` turned by `angle` about the unit axis `k` (Rodrigues). */
+const turn = (w, k, angle) => {
+  const c = Math.cos(angle), s = Math.sin(angle), kw = cross(k, w), d = dot(k, w) * (1 - c);
+  return [w[0] * c + kw[0] * s + k[0] * d, w[1] * c + kw[1] * s + k[1] * d, w[2] * c + kw[2] * s + k[2] * d];
+};
+/** three's Spherical angles of `v` about +Y: theta = atan2(x, z), phi = the angle from +Y. */
+const angles = (v) => { const r = len(v); return [Math.atan2(v[0], v[2]), Math.acos(Math.max(-1, Math.min(1, v[1] / r)))]; };
+
+/** The pivot (3D-UX-1 §2: "the focused doc, else the centre of the visible set"). OrbitControls always turns the camera round its
+ *  target. Given the camera and target before (`prevC`, `prevT`) and after (`C`, `T`) one of its updates, when that update was a
+ *  pure turn (target unmoved, distance unchanged) this returns the camera and target for the same turn made round `P` instead:
+ *  the turn is OrbitControls' own (theta about +Y, then phi about the camera's horizontal right axis), applied to the target's
+ *  offset from P, so the look direction is OrbitControls' and P keeps its place on screen. Null when the update was not a pure
+ *  turn (a zoom or a pan), or the turn is nil. Arrays [x, y, z] in, {c, t} out. */
+export function orbitAbout(P, prevC, prevT, C, T, eps = 1e-6) {
+  const u = sub(prevC, prevT), v = sub(C, T), ru = len(u), rv = len(v);
+  if (ru < 1e-9 || len(sub(T, prevT)) > eps * Math.max(1, ru) || Math.abs(rv - ru) > eps * Math.max(1, ru)) return null;
+  const [tu, pu] = angles(u), [tv, pv] = angles(v);
+  const dTheta = tv - tu, dPhi = pv - pu;
+  if (Math.abs(dTheta) < 1e-12 && Math.abs(dPhi) < 1e-12) return null;
+  const right = cross([0, 1, 0], u), rl = len(right);
+  if (rl < 1e-9) return null; // straight above or below: OrbitControls never gets here (it clamps phi off the poles)
+  const k = [right[0] / rl, right[1] / rl, right[2] / rl];
+  const R = (w) => turn(turn(w, k, dPhi), [0, 1, 0], dTheta);
+  const t = add(P, R(sub(T, P)));
+  return { c: add(t, v), t };
+}
+
+/** The camera position after zooming by `f` toward the target `t` (f > 1 closer), the distance kept in [minD, maxD]. */
+export function dollyBy(c, t, f, minD = 0, maxD = Infinity) {
+  const off = sub(c, t), d = len(off);
+  if (!(f > 0) || d < 1e-12) return [...c];
+  const nd = Math.min(maxD, Math.max(minD, d / f));
+  return add(t, [(off[0] * nd) / d, (off[1] * nd) / d, (off[2] * nd) / d]);
+}
+
+/** `screenPositions(ids?)` (1b handoff item 4): [{id, x, y, visible, degree, depth}] for the ids asked (every drawn node when `ids` is
+ *  null), in the order asked; an id the canvas does not hold is skipped. `scr` holds x, y and depth (cw) per index (graph3d project;
+ *  cw <= 0 is behind the camera, where x and y are NaN; `depth` is that cw, the view depth, so the lasso can tell behind the pivot); `visible` = drawn (`mask`), in front of the camera and on the w x h surface. */
+export function screenList(ids, index, scr, mask, degree, w, h) {
+  const out = [];
+  const one = (id, i) => {
+    const front = scr[3 * i + 2] > 1e-6, x = front ? scr[3 * i] : NaN, y = front ? scr[3 * i + 1] : NaN;
+    out.push({ id, x, y, visible: !!mask?.[i] && front && x >= 0 && x <= w && y >= 0 && y <= h, degree: degree ? degree[i] : 0, depth: scr[3 * i + 2] });
+  };
+  if (ids == null) { for (const [id, i] of index) if (!mask || mask[i]) one(id, i); return out; }
+  for (const id of ids) { const i = index.get(id); if (i !== undefined) one(id, i); }
+  return out;
+}

package/src/graph/lib/cardVisibility.js

@@ -0,0 +1,58 @@
+// The focused doc's card shows for a few seconds, then hides itself; Esc and an info button show/hide it (WIKI-GRAPH-CARD-AUTOHIDE-1).
+// Pure rules only: the page owns the timer and the DOM.
+import { useCallback, useEffect, useState } from "react";
+
+export const CARD_AUTOHIDE_MS = 3000; // how long a freshly focused doc's card stays before it fades out
+export const CARD_KEYS_HELP = "Esc show/hide doc info"; // the line in the 3D keys help (the gizmo title)
+export const CARD_HINT = "Esc: show/hide info · click empty space: clear focus";
+
+/** Card state for one focus: `shown`, `pinned` (shown by Esc: stays until Esc again or the focus changes), `pointerIn` (pointer over it), `focusIn` (keyboard focus inside),
+ *  `held` (either one: the two are tracked apart so one leaving does not release the other). */
+export const freshCard = (id) => ({ id, shown: true, pinned: false, held: false, pointerIn: false, focusIn: false });
+const withIn = (st, o) => { const n = { ...st, ...o }; return { ...n, held: n.pointerIn || n.focusIn }; };
+
+/** One event applied to a card state. Events: "hold" / "release" (pointer enters / leaves the card), "focusIn" / "focusOut" (keyboard focus enters / leaves it), "esc" (the toggle),
+ *  "expire" (the auto-hide timer fired). A new focus is a new `freshCard`, not an event. */
+export function cardReduce(st, ev) {
+  switch (ev) {
+    case "hold": return st.pointerIn ? st : withIn(st, { pointerIn: true });
+    case "release": return st.pointerIn ? withIn(st, { pointerIn: false }) : st;
+    case "focusIn": return st.focusIn ? st : withIn(st, { focusIn: true });
+    case "focusOut": return st.focusIn ? withIn(st, { focusIn: false }) : st;
+    case "esc": return st.shown ? { ...st, shown: false, pinned: false } : { ...st, shown: true, pinned: true };
+    case "expire": return st.held || st.pinned || !st.shown ? st : { ...st, shown: false };
+    default: return st;
+  }
+}
+
+/** True while the auto-hide timer should run: the card is up, nothing holds it, Esc has not pinned it. */
+export const cardTimerArmed = (st, autoHide) => !!autoHide && st.shown && !st.held && !st.pinned;
+
+/** What Esc does, one step per press, in order: a lasso selection clears, then an open pane closes, then (with a focused doc) the card toggles,
+ *  then a level or drill steps up, then the path lens clears. Clearing the focus is not a step: it is a click on empty space or the clear control.
+ *  `s`: { lasso, docOpen, focus, up (a level or drill step exists), pathLens } booleans. Returns the action name or null. */
+export function escAction(s) {
+  if (s.lasso) return "clearLasso";
+  if (s.docOpen) return "closeDoc";
+  if (s.focus) return "toggleCard";
+  if (s.up) return "up";
+  if (s.pathLens) return "clearPath";
+  return null;
+}
+
+/** Card visibility for the focused doc `focusId`. `autoHide` false (2D: the side panel is not over the nodes) keeps it shown until Esc.
+ *  Returns { shown, esc, hold, release, focusIn, focusOut }. Every change of focus starts a fresh 3 s, including a return to a doc focused before. */
+export function useCardVisibility(focusId, autoHide) {
+  const [raw, setRaw] = useState(() => freshCard(focusId));
+  if (raw.id !== focusId) setRaw(freshCard(focusId)); // reset on the focus change itself, so a return to an earlier doc does not reuse its old hidden state
+  const st = raw.id === focusId ? raw : freshCard(focusId);
+  const send = useCallback((ev) => setRaw((r) => cardReduce(r.id === focusId ? r : freshCard(focusId), ev)), [focusId]);
+  const armed = !!focusId && cardTimerArmed(st, autoHide);
+  useEffect(() => {
+    if (!armed) return undefined;
+    const t = setTimeout(() => send("expire"), CARD_AUTOHIDE_MS);
+    return () => clearTimeout(t);
+  }, [armed, send, st.shown, st.held, st.pinned, focusId]);
+  return { shown: st.shown, esc: useCallback(() => send("esc"), [send]), hold: useCallback(() => send("hold"), [send]), release: useCallback(() => send("release"), [send]),
+    focusIn: useCallback(() => send("focusIn"), [send]), focusOut: useCallback(() => send("focusOut"), [send]) };
+}

package/src/graph/lib/docCard.js

@@ -0,0 +1,28 @@
+// The doc card at the focused node (WIKI-GRAPH-EXPLORE-1b-SHELL B1). Pure positioning: the page feeds it one `screenPositions` entry per
+// frame and a card size, it says where the card goes or that it hides. Nothing here touches the DOM.
+import { placeCard } from "./canvasPort.js";
+import { drawnFor } from "./graphFind.js";
+
+export const CARD_NODE_RADIUS = 6; // px the card stays clear of the dot (the dot's drawn radius is not in screenPositions)
+export const CARD_EDGE = 8; // px the card keeps from the surface edge
+
+/** True when `p` ({x, y, visible}) is a node on the surface: drawn, in front of the camera, finite coordinates. */
+export function onScreen(p) {
+  return !!p && p.visible === true && Number.isFinite(p.x) && Number.isFinite(p.y);
+}
+
+/** Where a `cw` x `ch` card goes for the node `p` on a `w` x `h` surface: below-right of the dot, flipped at the right and bottom edges
+ *  (canvasPort placeCard), then clamped inside the surface with CARD_EDGE. null = hide (no node, off-screen, behind the camera, or no surface). */
+export function docCardAt(p, cw, ch, w, h) {
+  if (!onScreen(p) || !(w > 0) || !(h > 0)) return null;
+  const { left, top } = placeCard(p.x, p.y, CARD_NODE_RADIUS, cw, ch, w, h);
+  const clamp = (v, size, span) => Math.max(CARD_EDGE, Math.min(v, span - size - CARD_EDGE));
+  return { left: clamp(left, cw, w), top: clamp(top, ch, h) };
+}
+
+/** The drawn id the card hangs from: the focused doc itself when the canvas draws it, else the folder that stands for it (a level view collapses
+ *  docs into folders: graphFind drawnFor, the helper the camera and the lit set use), else null (nothing draws it: the card stays hidden).
+ *  `drawnIds`: the ids the canvas draws (null while the graph is not built). */
+export function cardAnchor(focus, drawnIds) {
+  return focus && drawnIds ? drawnFor(focus, drawnIds) : null;
+}

package/src/graph/lib/forceWorker.js

@@ -0,0 +1,123 @@
+// WIKI-GRAPH-OBSIDIAN-1: the graph's d3-force layout, in a Web Worker so the main thread never runs a tick and panning
+// stays smooth while the graph settles. Index-based: positions are a Float32Array [x0, y0, x1, y1, ...], links a
+// Uint32Array of node index pairs, targets the per-node group centre the x/y forces pull towards (the clustering).
+//
+// Main -> worker: `init` {xy, links, targets, params, progressMs, maxTicks, alpha, big, radii?, pinned?, weights?}; `params` {params} (live, reheats
+// to at least 0.3); `weights` {weights} (live, no reheat); `contain` {pairs, lead} (live, no reheat: the containment springs after the first `lead` links become `pairs`); `pause`; `resume`; `reheat`; `stop`. Worker -> main: `tick` {xy (transferred), alpha, ticks} every
+// `progressMs` and once more when it settles; `state` {state: running|paused|settled, ticks, ms}.
+// Ticks run in slices of `sliceMs`, then yield, so a message always gets through within one slice (or one tick, when a
+// single tick is longer: ~600 ms at 50k docs).
+// WIKI-GRAPH-P0-LEVEL0-ZOOM-1: `radii` (a level view with folders, graphView layoutRadii) makes link distance surface to
+// surface and adds a collide force (up to COLLIDE_N nodes), so no two drawn circles overlap.
+// WIKI-GRAPH-CLUSTER-REGROUP-1: `pinned` (optional Uint8Array, 1 per pinned node) fixes those nodes at their start position
+// (d3 fx/fy), so a scoped re-layout (the focus's lit set) moves only the unpinned nodes and the dimmed rest never moves.
+import { forceCollide, forceLink, forceManyBody, forceSimulation, forceX, forceY } from "d3-force";
+import { COLLIDE_N, collideRadiusFn, linkDistanceFn } from "./graphView";
+import { linkStrength } from "./linkWeight";
+
+export const ALPHA_MIN = 0.001, PARAMS_ALPHA = 0.3, REHEAT_ALPHA = 0.5;
+import { ORPHAN_PULL, markFree } from "./orphanPull";
+export { ORPHAN_PULL, markFree }; // r3 tests import them from here
+
+const strengthOf = (l) => linkStrength(l.w); // WIKI-GRAPH-LEVEL-WEIGHTS-FU-1: 0.15 for a flat link, up to 0.45 for a heavy folder link
+
+/** The message handler, with its clock and scheduler injected so the tests can drive it without a Worker. */
+export function makeHandler({ post, now = () => performance.now(), defer = (f) => setTimeout(f, 0), sliceMs = 30 }) {
+  let sim = null, nodes = null, radii = null, linkList = null, state = "idle", ticks = 0, t0 = 0, lastPost = 0, progressMs = 100, gen = 0, pending = false;
+
+  const postState = (s) => { state = s; post({ type: "state", state: s, ticks, ms: now() - t0 }); };
+  const postTick = () => {
+    const xy = new Float32Array(2 * nodes.length);
+    for (let i = 0; i < nodes.length; i++) { xy[2 * i] = nodes[i].x; xy[2 * i + 1] = nodes[i].y; }
+    post({ type: "tick", xy, alpha: sim.alpha(), ticks }, [xy.buffer]);
+  };
+  const loop = (g) => {
+    if (g !== gen) return; // a newer `init` or a `stop` came in meanwhile
+    pending = false;
+    if (state !== "running") return;
+    const end = now() + sliceMs;
+    do { sim.tick(); ticks++; } while (now() < end && sim.alpha() >= ALPHA_MIN);
+    if (sim.alpha() < ALPHA_MIN) { postTick(); postState("settled"); return; }
+    if (now() - lastPost >= progressMs) { lastPost = now(); postTick(); }
+    schedule();
+  };
+  const schedule = () => {
+    if (pending) return;
+    pending = true;
+    const g = gen;
+    defer(() => loop(g));
+  };
+  let cur = null; // the params last applied: the centre pull is re-read when the springs change which nodes are free
+  const apply = (p) => {
+    cur = p;
+    sim.force("charge").strength(p.charge);
+    sim.force("link").distance(linkDistanceFn(p.linkDistance, radii));
+    const pull = (d) => (d.free ? p.centre * ORPHAN_PULL : p.centre);
+    sim.force("x").strength(pull);
+    sim.force("y").strength(pull);
+  };
+  const run = () => { if (state !== "running") postState("running"); schedule(); };
+
+  return (e) => {
+    const m = e.data || {};
+    if (m.type === "init") {
+      gen++; pending = false;
+      const { xy, links, targets, params, maxTicks = 300, alpha = 1, big = false } = m;
+      radii = m.radii || null; // a level view with folders: keep the spheres apart (graphView layoutRadii)
+      progressMs = m.progressMs ?? 100;
+      const n = xy.length / 2;
+      nodes = new Array(n);
+      const pinned = m.pinned || null;
+      for (let i = 0; i < n; i++) {
+        nodes[i] = { x: xy[2 * i], y: xy[2 * i + 1], tx: targets[2 * i], ty: targets[2 * i + 1] };
+        if (pinned && pinned[i]) { nodes[i].fx = nodes[i].x; nodes[i].fy = nodes[i].y; }
+      }
+      const ls = new Array(links.length / 2);
+      for (let i = 0; i < ls.length; i++) ls[i] = { source: links[2 * i], target: links[2 * i + 1], w: m.weights?.[i] ?? 1 }; // weights: one per leading link, the rest (containment springs) 1
+      linkList = ls;
+      markFree(nodes, ls);
+      sim = forceSimulation(nodes).stop()
+        .alpha(alpha).alphaMin(ALPHA_MIN).alphaDecay(1 - Math.pow(ALPHA_MIN, 1 / maxTicks))
+        .force("charge", forceManyBody().theta(0.9).distanceMax(big ? 220 : 400))
+        .force("link", forceLink(ls).strength(strengthOf))
+        .force("x", forceX((d) => d.tx))
+        .force("y", forceY((d) => d.ty));
+      if (radii && n <= COLLIDE_N) sim.force("collide", forceCollide(collideRadiusFn(radii)).iterations(2));
+      apply(params);
+      ticks = 0; t0 = now(); lastPost = t0; state = "idle";
+      if (n === 0) { postState("settled"); return; }
+      run();
+      return;
+    }
+    if (!sim) return;
+    if (m.type === "params") {
+      apply(m.params);
+      sim.alpha(Math.max(sim.alpha(), PARAMS_ALPHA));
+      if (state === "settled") run(); // a paused layout stays paused and moves with the new forces on resume
+    } else if (m.type === "weights") { // a same-topology refresh changed the weights: new strengths, no reheat (nothing moves until it next runs)
+      for (let i = 0; i < linkList.length; i++) linkList[i].w = m.weights?.[i] ?? 1;
+      sim.force("link").strength(strengthOf);
+    } else if (m.type === "contain") { // a same-topology refresh changed the containment pairs: swap the springs after the `lead` real links, no reheat
+      const ls = linkList.slice(0, m.lead), at = m.pairs;
+      for (let i = 0; i < at.length / 2; i++) ls.push({ source: at[2 * i], target: at[2 * i + 1], w: 1 });
+      linkList = ls;
+      sim.force("link").links(ls);
+      markFree(nodes, ls);
+      apply(cur);
+    } else if (m.type === "pause") {
+      if (state === "running") postState("paused");
+    } else if (m.type === "resume") {
+      if (state === "paused") run();
+    } else if (m.type === "reheat") {
+      sim.alpha(Math.max(sim.alpha(), REHEAT_ALPHA));
+      run();
+    } else if (m.type === "stop") {
+      gen++; pending = false; sim = null; nodes = null; radii = null; linkList = null; state = "idle";
+    }
+  };
+}
+
+/* global WorkerGlobalScope */
+if (typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope) {
+  self.onmessage = makeHandler({ post: (msg, transfer) => self.postMessage(msg, transfer || []) });
+}

package/src/graph/lib/forceWorker3d.js

@@ -0,0 +1,136 @@
+// WIKI-GRAPH-3D-1: the 3D twin of forceWorker.js. d3-force-3d in a Web Worker, so orbiting stays smooth while the graph
+// settles. Same protocol and the same injected handler (tests drive it without a Worker); only the shapes differ: positions
+// are [x0, y0, z0, x1, ...] and targets carry a z.
+//
+// Main -> worker: `init` {xyz, links, targets, params, progressMs, maxTicks, alpha, big, radii?, pinned?, weights?} (radii, pinned, weights: forceWorker.js); `params` {params} (live, reheats to
+// at least 0.3); `pause`; `resume`; `reheat`; `pin` {i, x, y, z} / `unpin` {idx?} (hold a doc at a point, release some or all: fx/fy/fz); `stop`. Worker -> main: `tick` {xyz (transferred), alpha, ticks} every
+// `progressMs` and once more when it settles; `state` {state: running|paused|settled, ticks, ms}.
+//
+// A 3D many-body tick (octree) costs ~2.5x a 2D one at the same settings (spike, units/WIKI-GRAPH-3D-1/spike-report.md), so
+// the Barnes-Hut approximation is looser: theta 1.2 (3D real-sized graph settles in ~13 s instead of 24 s), and past
+// HUGE_N docs theta 1.5 with a 120 cut-off (50k settles in ~54 s, not in 3 minutes). Every other force value is the 2D one.
+import { forceCollide, forceLink, forceManyBody, forceSimulation, forceX, forceY, forceZ } from "d3-force-3d";
+import { COLLIDE_N, collideRadiusFn, linkDistanceFn } from "./graphView";
+import { linkStrength } from "./linkWeight";
+import { ORPHAN_PULL, markFree } from "./orphanPull";
+
+export const ALPHA_MIN = 0.001, PARAMS_ALPHA = 0.3, REHEAT_ALPHA = 0.5;
+export const HUGE_N = 15000;
+
+/** The many-body settings for `n` docs: {theta, distanceMax}. `big` is the 2D view's big-graph flag (LOD_N). */
+export function chargeFor(n, big) {
+  if (n > HUGE_N) return { theta: 1.5, distanceMax: 120 };
+  return { theta: 1.2, distanceMax: big ? 220 : 400 };
+}
+
+const strengthOf = (l) => linkStrength(l.w); // WIKI-GRAPH-LEVEL-WEIGHTS-FU-1: 0.15 for a flat link, up to 0.45 for a heavy folder link
+
+/** The message handler, with its clock and scheduler injected so the tests can drive it without a Worker. */
+export function makeHandler({ post, now = () => performance.now(), defer = (f) => setTimeout(f, 0), sliceMs = 30 }) {
+  let sim = null, nodes = null, radii = null, linkList = null, state = "idle", ticks = 0, t0 = 0, lastPost = 0, progressMs = 100, gen = 0, pending = false;
+
+  const postState = (s) => { state = s; post({ type: "state", state: s, ticks, ms: now() - t0 }); };
+  const postTick = () => {
+    const xyz = new Float32Array(3 * nodes.length);
+    for (let i = 0; i < nodes.length; i++) { const p = nodes[i]; xyz[3 * i] = p.x; xyz[3 * i + 1] = p.y; xyz[3 * i + 2] = p.z; }
+    post({ type: "tick", xyz, alpha: sim.alpha(), ticks }, [xyz.buffer]);
+  };
+  const loop = (g) => {
+    if (g !== gen) return; // a newer `init` or a `stop` came in meanwhile
+    pending = false;
+    if (state !== "running") return;
+    const end = now() + sliceMs;
+    do { sim.tick(); ticks++; } while (now() < end && sim.alpha() >= ALPHA_MIN);
+    if (sim.alpha() < ALPHA_MIN) { postTick(); postState("settled"); return; }
+    if (now() - lastPost >= progressMs) { lastPost = now(); postTick(); }
+    schedule();
+  };
+  const schedule = () => {
+    if (pending) return;
+    pending = true;
+    const g = gen;
+    defer(() => loop(g));
+  };
+  let cur = null; // the params last applied: the centre pull is re-read when the springs change which nodes are free
+  const apply = (p) => {
+    cur = p;
+    sim.force("charge").strength(p.charge);
+    sim.force("link").distance(linkDistanceFn(p.linkDistance, radii));
+    // WIKI-GRAPH-FIT-HIDDEN-1 r4: an unlinked doc is pulled ORPHAN_PULL x harder to its target (0 when unclustered, its group centre when clustered)
+    const pull = (d) => (d.free ? p.centre * ORPHAN_PULL : p.centre);
+    for (const f of ["x", "y", "z"]) sim.force(f).strength(pull);
+  };
+  const run = () => { if (state !== "running") postState("running"); schedule(); };
+
+  return (e) => {
+    const m = e.data || {};
+    if (m.type === "init") {
+      gen++; pending = false;
+      const { xyz, links, targets, params, maxTicks = 300, alpha = 1, big = false } = m;
+      radii = m.radii || null; // a level view with folders: keep the spheres apart (graphView layoutRadii)
+      progressMs = m.progressMs ?? 100;
+      const n = xyz.length / 3, pinned = m.pinned || null; // pinned: fixed at the start position (forceWorker.js)
+      nodes = new Array(n);
+      for (let i = 0; i < n; i++) {
+        nodes[i] = { x: xyz[3 * i], y: xyz[3 * i + 1], z: xyz[3 * i + 2], tx: targets[3 * i], ty: targets[3 * i + 1], tz: targets[3 * i + 2] };
+        if (pinned && pinned[i]) { nodes[i].fx = nodes[i].x; nodes[i].fy = nodes[i].y; nodes[i].fz = nodes[i].z; }
+      }
+      const ls = new Array(links.length / 2);
+      for (let i = 0; i < ls.length; i++) ls[i] = { source: links[2 * i], target: links[2 * i + 1], w: m.weights?.[i] ?? 1 }; // weights: one per leading link, the rest (containment springs) 1
+      linkList = ls;
+      markFree(nodes, ls);
+      const c = chargeFor(n, big);
+      sim = forceSimulation(nodes, 3).stop()
+        .alpha(alpha).alphaMin(ALPHA_MIN).alphaDecay(1 - Math.pow(ALPHA_MIN, 1 / maxTicks))
+        .force("charge", forceManyBody().theta(c.theta).distanceMax(c.distanceMax))
+        .force("link", forceLink(ls).strength(strengthOf))
+        .force("x", forceX((d) => d.tx))
+        .force("y", forceY((d) => d.ty))
+        .force("z", forceZ((d) => d.tz));
+      if (radii && n <= COLLIDE_N) sim.force("collide", forceCollide(collideRadiusFn(radii)).iterations(2));
+      apply(params);
+      ticks = 0; t0 = now(); lastPost = t0; state = "idle";
+      if (n === 0) { postState("settled"); return; }
+      run();
+      return;
+    }
+    if (!sim) return;
+    if (m.type === "params") {
+      apply(m.params);
+      sim.alpha(Math.max(sim.alpha(), PARAMS_ALPHA));
+      if (state === "settled") run(); // a paused layout stays paused and moves with the new forces on resume
+    } else if (m.type === "weights") { // a same-topology refresh changed the weights: new strengths, no reheat (nothing moves until it next runs)
+      for (let i = 0; i < linkList.length; i++) linkList[i].w = m.weights?.[i] ?? 1;
+      sim.force("link").strength(strengthOf);
+    } else if (m.type === "contain") { // a same-topology refresh changed the containment pairs: swap the springs after the `lead` real links, no reheat
+      const ls = linkList.slice(0, m.lead), at = m.pairs;
+      for (let i = 0; i < at.length / 2; i++) ls.push({ source: at[2 * i], target: at[2 * i + 1], w: 1 });
+      linkList = ls;
+      sim.force("link").links(ls);
+      markFree(nodes, ls);
+      apply(cur);
+    } else if (m.type === "pause") {
+      if (state === "running") postState("paused");
+    } else if (m.type === "resume") {
+      if (state === "paused") run();
+    } else if (m.type === "pin" || m.type === "unpin") { // drag-to-pin (EXPLORE-1c-UI r2): hold a doc at fx/fy/fz, or let it go; a paused layout stays paused
+      if (m.type === "pin") {
+        const d = nodes[m.i];
+        if (d) { d.x = d.fx = m.x; d.y = d.fy = m.y; d.z = d.fz = m.z; }
+      } else {
+        for (const i of m.idx || nodes.keys()) { const d = nodes[i]; if (d) { d.fx = d.fy = d.fz = null; } }
+      }
+      if (state !== "paused") { sim.alpha(Math.max(sim.alpha(), REHEAT_ALPHA)); run(); }
+    } else if (m.type === "reheat") {
+      sim.alpha(Math.max(sim.alpha(), REHEAT_ALPHA));
+      run();
+    } else if (m.type === "stop") {
+      gen++; pending = false; sim = null; nodes = null; radii = null; linkList = null; state = "idle";
+    }
+  };
+}
+
+/* global WorkerGlobalScope */
+if (typeof WorkerGlobalScope !== "undefined" && self instanceof WorkerGlobalScope) {
+  self.onmessage = makeHandler({ post: (msg, transfer) => self.postMessage(msg, transfer || []) });
+}