pi-weave 0.1.7 → 0.1.9

package/src/web/client/graph/Graph.tsx

@@ -0,0 +1,209 @@
+/**
+ * The graph column (weave-workspace §1.2, §7, P3).
+ *
+ * Props in, JSX out, and one `ref` handed to a renderer. Every string, every
+ * branch and every set comes from `column.model.ts`, `graph.model.ts` or
+ * `positions.ts`; what is left here is a `useState`, three effects and four
+ * handlers. §10's rule, and the reason the 95 % gate survives a phase whose
+ * whole deliverable is a WebGL canvas.
+ *
+ * The three effects, all one-liners over injected units:
+ *
+ *  1. **mount** — build a renderer, attach it to the `<div>`, subscribe to
+ *     selection. The returned `destroy` is the cleanup, so a hot reload cannot
+ *     leak a WebGL context.
+ *  2. **graph** — push the drawn model whenever the reduction or the layout
+ *     changes. Keyed on `model.key`, which is the *shape* digest, so an SSE
+ *     tick that changed a note's body does not re-upload the graph (§7.3:
+ *     re-run on drag or expand/collapse, not every frame).
+ *  3. **highlight** — push the neighbourhood whenever the selection moves.
+ *     This is the §1.3 bus arriving from the tree, a wikilink or the context
+ *     rail; the graph does not care which, and that is the whole mechanism
+ *     behind "selecting anywhere highlights everywhere".
+ *
+ * ## The `live` ref
+ *
+ * The renderer's `onSelect` is registered once at mount and outlives every
+ * render, so a handler that closed over `view` and `model` directly would keep
+ * answering with the state as it was at mount. The same `live.current` pattern
+ * `Shell.tsx` uses for its drag handlers, for the same reason.
+ */
+
+import { useEffect, useMemo, useRef, useState, useCallback } from "preact/hooks";
+import type { GraphPayload } from "../../shared/wire";
+import type { GraphViewState } from "./column.model";
+import {
+  FIT_HINT,
+  FIT_LABEL,
+  LEGEND,
+  allExpanded,
+  effectiveView,
+  expandHint,
+  expandLabel,
+  graphClick,
+  graphColumnModel,
+  graphCountLabel,
+  toggleExpandAll,
+} from "./column.model";
+import type { PositionStorage } from "./positions";
+import type { GraphRenderer, RendererFactory } from "./renderer";
+import { schemeOf } from "./scheme";
+import type { SchemeHost } from "./scheme";
+import { createGraphSimulation } from "./dynamics";
+import type { GraphSimulation } from "./dynamics";
+
+export interface GraphProps {
+  graph: GraphPayload | null;
+  selectedId: string | null;
+  onSelect: (id: string | null) => void;
+  /** Injected: `createSigmaRenderer` in the browser, a fake in a test. */
+  renderer: RendererFactory;
+  /** Injected: `localStorage`. See `positions.ts` for why it is a port. */
+  storage: PositionStorage;
+  /** Injected: `window`. Read once, for `prefers-color-scheme`. */
+  host: SchemeHost;
+  /**
+   * A slot the column writes its `fit` into, so the global `g` key can reach
+   * it (§11 P4).
+   *
+   * A ref rather than lifting the renderer into the shell: the renderer is
+   * created, owned and destroyed by the mount effect below, and hoisting it
+   * would move a WebGL lifecycle out of the one component that can see the
+   * `<div>` it attaches to. A slot the column fills and clears on unmount
+   * keeps the ownership where it is and costs one line at each end.
+   */
+  fit: { current: (() => void) | null };
+}
+
+export function Graph(props: GraphProps) {
+  const canvas = useRef<HTMLDivElement | null>(null);
+  const renderer = useRef<GraphRenderer | null>(null);
+  const dynamics = useRef<GraphSimulation | null>(null);
+  const clock = useRef<number | null>(null);
+  /**
+   * Arm the simulation clock — idempotent.
+   *
+   * The layout is always live; the clock still sleeps whenever the engine's
+   * alpha reaches its floor (a graph that is holding still costs zero frames)
+   * and re-arms when a drag pins a node or a re-layout hands over a new
+   * engine.
+   */
+  const armClock = useCallback(() => {
+    if (clock.current !== null) return;
+    const step = () => {
+      clock.current = null;
+      const engine = dynamics.current;
+      if (engine === null) return;
+      engine.tick();
+      // Asleep: let the clock die. The next pin re-arms it.
+      if (!engine.awake()) return;
+      renderer.current?.setPositions(engine.positions());
+      clock.current = requestAnimationFrame(step);
+    };
+    clock.current = requestAnimationFrame(step);
+  }, []);
+  // `null` means "the user has not touched the expansion" — not "nothing is
+  // expanded". `effectiveView` resolves the difference; see its doc comment.
+  const [state, setState] = useState<GraphViewState | null>(null);
+
+  const scheme = useMemo(() => schemeOf(props.host), [props.host]);
+  const view = effectiveView(props.graph, state);
+  const model = graphColumnModel(props.graph, props.selectedId, view, props.storage, scheme);
+  const everything = allExpanded(view, model.clusters);
+
+  // Read by the mount-time `onSelect`, which outlives this render.
+  const live = useRef({ view, model, onSelect: props.onSelect });
+  live.current = { view, model, onSelect: props.onSelect };
+
+  useEffect(() => {
+    const instance = props.renderer(scheme);
+    instance.onSelect((id) => {
+      const next = graphClick(live.current.view, live.current.model.clusters, id);
+      setState(next.state);
+      live.current.onSelect(next.selectedId);
+    });
+    instance.onDragStart((id) => {
+      const at = renderer.current?.positions().get(id);
+      if (at) {
+        dynamics.current?.pin(id, at);
+        // The pin re-heats the engine; if the clock was asleep, wake it.
+        armClock();
+      }
+    });
+    instance.onDragMove((id, at) => {
+      dynamics.current?.pin(id, at);
+    });
+    instance.onDragEnd((id) => {
+      dynamics.current?.release(id);
+    });
+    instance.mount(canvas.current ?? { clientWidth: 0, clientHeight: 0 });
+    renderer.current = instance;
+    props.fit.current = () => instance.fit();
+    return () => {
+      instance.destroy();
+      renderer.current = null;
+      // Cleared, not left dangling: `g` after a breakpoint has unmounted the
+      // graph column would otherwise call `fit` on a destroyed WebGL context.
+      props.fit.current = null;
+    };
+  }, [props.renderer, scheme]);
+
+  useEffect(() => {
+    renderer.current?.setGraph(model.graph);
+  }, [model.key]);
+
+  // Live layout, in two effects so pause/resume and re-layout are independent.
+  //
+  // Effect 1 (keyed on `model.key`) owns the *simulation*: it is created once
+  // per graph shape, warm-started from the renderer's current positions so a
+  // drag or an expand does not make the graph jump, and disposed when the shape
+  // changes. A fresh engine starts at settle alpha — the "alive" answer to an
+  // expand — so the clock must arm here if it had gone to sleep.
+  useEffect(() => {
+    const engine = createGraphSimulation(model.graph, renderer.current?.positions());
+    dynamics.current = engine;
+    if (engine !== null) armClock();
+    return () => {
+      dynamics.current = null;
+    };
+  }, [model.key, armClock]);
+
+  // Effect 2 owns the clock's unmount cleanup: the engine's own lifecycle is
+  // effect 1's, and the step self-terminates whenever the engine settles, so
+  // the only teardown left here is a frame that could outlive the component.
+  useEffect(
+    () => () => {
+      if (clock.current !== null) {
+        cancelAnimationFrame(clock.current);
+        clock.current = null;
+      }
+    },
+    [],
+  );
+
+  useEffect(() => {
+    renderer.current?.setHighlight(model.highlight);
+  }, [model.highlight]);
+
+  return (
+    <div class="weave-graph">
+      {/* Same shape as `ContextRail`'s: the *decision* is `graphEmptyMessage`,
+          and what is left here is whether to render the paragraph it returned. */}
+      {model.empty === null ? null : <p class="weave-graph-empty">{model.empty}</p>}
+      <div class="weave-graph-canvas" ref={canvas} role="img" aria-label="Knowledge graph" />
+      <div class="weave-graph-controls">
+        <button type="button" class="weave-chip" title={FIT_HINT} onClick={() => renderer.current?.fit()}>
+          {FIT_LABEL}
+        </button>
+        <button type="button" class="weave-chip" title={expandHint(everything)} onClick={() => setState(toggleExpandAll(view, model.clusters))}>
+          {expandLabel(everything)}
+        </button>
+        <span class="weave-graph-legend">
+          <span class="weave-legend-on">◉ {LEGEND.selected}</span>
+          <span class="weave-legend-near">● {LEGEND.neighborhood}</span>
+        </span>
+      </div>
+      <p class="weave-graph-count">{graphCountLabel(model.visible, model.total)}</p>
+    </div>
+  );
+}

package/src/web/client/graph/column.model.ts

@@ -0,0 +1,372 @@
+/**
+ * The graph column's own state: what is expanded, what is highlighted, and
+ * what the control strip says (weave-workspace §1.2, §1.3, §7.4, §10, P3).
+ *
+ * `graph.model.ts` decides how a *node* is drawn. This module decides what the
+ * *column* is currently showing — which is a different question with a
+ * different lifetime, and keeping them apart is what stops either becoming a
+ * grab-bag:
+ *
+ * ```text
+ * payload + selection + view state   ← this module
+ *          │
+ *          ▼  clusterAggregate (core)        which nodes exist right now
+ *          ▼  positions.ts                   where they are
+ *          ▼  graph.model.ts                 how each one looks
+ *          ▼  project.ts → renderer.ts       drawn
+ * ```
+ *
+ * Every branch lives here for §10's reason: sigma needs a canvas, so a
+ * conditional inside the renderer is a conditional no test can reach.
+ * `Graph.tsx` is left with a `useState`, three effects and four handlers.
+ *
+ * ## The §1.3 context bus, from the graph's side
+ *
+ * There is one signal, `selectedId`, and the graph both writes and reads it.
+ * Clicking a node writes it — which drives the note column and the context
+ * rail with no further wiring. Selecting *anywhere* (tree row, wikilink,
+ * context rail) is read back here as {@link highlightFor}, so "selecting in
+ * the tree highlights in the graph" needs no code beyond deriving the
+ * neighbourhood from the same signal. That is §1.3's whole claim, and the
+ * assertion that proves it is a test showing tree-driven and graph-driven
+ * selection produce the identical highlight set.
+ *
+ * ## Tier rules (§2)
+ *
+ * `src/web/client/**`. Core view-models via `../../shared/view` — the one
+ * sanctioned door (§2.1.1), through which P3 brings `clusterAggregate`,
+ * `focusNeighborhood` and `degreeOf`. No DOM type is named and no npm package
+ * is imported, so the root `tsconfig.json` project compiles the tests.
+ */
+
+import type { Point } from "../../shared/layout";
+import type { ClusterAggregate, ClusterInfo, ViewGraphModel } from "../../shared/view";
+import { clusterAggregate, degreeOf, focusNeighborhood } from "../../shared/view";
+import type { GraphPayload, WireGraphEdge, WireGraphNode } from "../../shared/wire";
+import { viewModel } from "../tree/tree.model";
+import type { ColorScheme, RenderGraph } from "./graph.model";
+import { EMPTY_RENDER_GRAPH, renderGraph } from "./graph.model";
+import type { PositionStorage } from "./positions";
+import { resolveLayout } from "./positions";
+
+// --- the view state ------------------------------------------------------------------
+
+/** The graph column's state. Owned by the column; never on the context bus. */
+export interface GraphViewState {
+  /**
+   * Cluster ids the user has expanded (§7.4).
+   *
+   * Passed straight to `clusterAggregate`, whose contract is that a node is
+   * visible when every containment ancestor between it and a root is
+   * expanded. An empty set is therefore the maximally collapsed view — the
+   * roots alone — which is the right first frame for a repository with
+   * thousands of files and the wrong one for a vault with nine notes. See
+   * {@link initialGraphView}.
+   */
+  readonly expanded: ReadonlySet<string>;
+}
+
+/**
+ * How many nodes a graph may have before it opens collapsed.
+ *
+ * Not a preference — a legibility bound. Above roughly this many, a
+ * force-directed layout of a containment tree is a disc of overlapping labels
+ * whichever way you draw it, and the honest first frame is the five clusters
+ * with their counts. Below it, collapsing hides a graph the user could simply
+ * have read.
+ *
+ * 120 is the point at which this repository's own fixture (89 nodes) still
+ * opens whole while a real `src/` scan (hundreds of files) does not.
+ */
+export const AUTO_COLLAPSE_ABOVE = 120;
+
+/**
+ * The state a freshly loaded graph opens in.
+ *
+ * Everything expanded for a small graph, nothing for a large one. `expanded`
+ * has to name the clusters explicitly rather than carry an "all" flag, because
+ * `clusterAggregate` takes a set and the first thing a user does is collapse
+ * one — which has to leave the others open.
+ */
+export function initialGraphView(model: ViewGraphModel): GraphViewState {
+  const expanded =
+    model.nodes.length > AUTO_COLLAPSE_ABOVE ? new Set<string>() : new Set(clusterAggregate(model, new Set()).clusters.keys());
+  return { expanded };
+}
+
+/**
+ * The state to render with: the user's, or the default for this payload.
+ *
+ * The column holds `GraphViewState | null` and `null` means "the user has not
+ * touched the expansion yet" — which is not the same as "nothing is expanded",
+ * because {@link initialGraphView} opens a small graph whole. Resolving that
+ * here rather than in the component keeps a real branch out of a `.tsx` (§10)
+ * and, more importantly, makes the rule testable: a refetch must **not** reset
+ * an expansion the user has chosen, and the watcher fires on every file save.
+ */
+export function effectiveView(payload: GraphPayload | null, state: GraphViewState | null): GraphViewState {
+  if (state !== null) return state;
+  if (payload === null) return { expanded: new Set() };
+  return initialGraphView(viewModel(payload));
+}
+
+/** Open or close one cluster. Returns a new state; see {@link expandAll}. */
+export function toggleCluster(state: GraphViewState, id: string): GraphViewState {
+  const expanded = new Set(state.expanded);
+  if (!expanded.delete(id)) expanded.add(id);
+  return { ...state, expanded };
+}
+
+/**
+ * Open every cluster. The `[expand]` control from the §1.2 mock.
+ *
+ * `clusters` is `ClusterAggregate.clusters`, which holds **every** node with a
+ * containment child whether or not it is currently visible — so one press
+ * opens the whole tree rather than one level of it. That is deliberate: the
+ * per-level walk is what the tree column is for, and a graph control that
+ * needed six presses to show the graph would be a worse version of it.
+ */
+export function expandAll(state: GraphViewState, clusters: ReadonlyMap<string, ClusterInfo>): GraphViewState {
+  return { ...state, expanded: new Set(clusters.keys()) };
+}
+
+/** Close every cluster, back to the roots. The other half of `[expand]`. */
+export function collapseAll(state: GraphViewState): GraphViewState {
+  return { ...state, expanded: new Set() };
+}
+
+// --- the highlight (§1.3, §7.4) ---------------------------------------------------------
+
+/**
+ * The set of ids that stay lit when `selectedId` is selected.
+ *
+ * `focusNeighborhood` **verbatim** — core's function, the same one the
+ * context rail's "Related" is built from, reached through the §2.1.1 door
+ * rather than reimplemented. (The `[depth 1 ▾]` control once let the user
+ * widen this to two and three hops; it read as decoration next to the rail's
+ * fixed-depth "Related" and is gone — one definition of "related", one
+ * behaviour everywhere.)
+ *
+ * `null` in, `null` out: nothing selected means no highlight at all, which the
+ * reducers treat as "render everything normally" — deliberately not the same
+ * as an empty set (see `graph.model.ts`).
+ *
+ * Computed over the **currently visible** edges, not the full model. A
+ * neighbour inside a collapsed cluster is not on screen, and `clusterAggregate`
+ * has already retargeted the edge onto the cluster standing in for it — so
+ * highlighting the hidden id would light nothing while leaving the cluster
+ * that actually represents it dimmed.
+ */
+export function highlightFor(edges: readonly WireGraphEdge[], selectedId: string | null): Set<string> | null {
+  if (selectedId === null) return null;
+  return focusNeighborhood(selectedId, edges);
+}
+
+// --- the control strip (§1.2) ---------------------------------------------------------------
+
+/** The `[expand]` control's label, which is really a toggle. */
+export function expandLabel(allExpanded: boolean): string {
+  return allExpanded ? "collapse" : "expand";
+}
+
+/** Its tooltip. */
+export function expandHint(allExpanded: boolean): string {
+  return allExpanded ? "collapse every cluster back to the roots" : "expand every cluster";
+}
+
+/** Whether every cluster in the graph is currently open. */
+export function allExpanded(state: GraphViewState, clusters: ReadonlyMap<string, ClusterInfo>): boolean {
+  if (clusters.size === 0) return false;
+  for (const id of clusters.keys()) if (!state.expanded.has(id)) return false;
+  return true;
+}
+
+/**
+ * What the `[expand]` control does when pressed.
+ *
+ * One function rather than a ternary in the component, for §10's reason: the
+ * choice between expanding and collapsing is a branch, and a branch in a
+ * `.tsx` is a branch no test can reach. It is also the *only* place the
+ * toggle's two halves are paired, so its label and its effect cannot disagree
+ * — {@link expandLabel} reads the same predicate.
+ */
+export function toggleExpandAll(state: GraphViewState, clusters: ReadonlyMap<string, ClusterInfo>): GraphViewState {
+  return allExpanded(state, clusters) ? collapseAll(state) : expandAll(state, clusters);
+}
+
+/** The `[fit]` control. Constant, but named here so the component holds no copy. */
+export const FIT_LABEL = "fit";
+export const FIT_HINT = "frame the whole graph";
+
+/**
+ * The legend under the canvas, from the §1.2 mock:
+ * `◉ selected  ● neighborhood`.
+ */
+export const LEGEND = { selected: "selected", neighborhood: "neighborhood", dimmed: "not related" } as const;
+
+/**
+ * The count line: what is on screen out of what exists.
+ *
+ * Both numbers, always. "89 nodes" next to a canvas showing 5 is the reading
+ * that makes a collapsed graph look broken; "5 of 89 nodes" makes it obvious
+ * that there is more behind the clusters.
+ */
+export function graphCountLabel(visible: number, total: number): string {
+  const noun = total === 1 ? "node" : "nodes";
+  return visible === total ? `${total} ${noun}` : `${visible} of ${total} ${noun}`;
+}
+
+/** What the column says instead of a canvas. `null` means "there is a graph". */
+export function graphEmptyMessage(payload: GraphPayload | null, visible: number): string | null {
+  if (payload === null) return "Loading…";
+  if (payload.model.nodes.length === 0) return "Nothing indexed yet — add a note or run /weave-scan.";
+  // A payload with nodes but nothing visible cannot happen through the UI
+  // (`clusterAggregate` always keeps the roots), but a truncated response
+  // could produce it, and a blank canvas with no explanation reads as a crash.
+  return visible === 0 ? "Nothing to draw at this expansion." : null;
+}
+
+// --- the whole column state -----------------------------------------------------------------
+
+/** Everything the column needs to render one frame. */
+export interface GraphColumnModel {
+  /** What sigma draws. */
+  readonly graph: RenderGraph;
+  /** What the reducers dim outside of. `null` when nothing is selected. */
+  readonly highlight: Set<string> | null;
+  /** The layout's cache key, so the caller can tell one shape from another. */
+  readonly key: string;
+  /** True when the layout came from `localStorage` rather than the simulation. */
+  readonly cached: boolean;
+  /** Every cluster in the *unreduced* model — what `[expand]` operates on. */
+  readonly clusters: ReadonlyMap<string, ClusterInfo>;
+  /** Visible / total, for the count line. */
+  readonly visible: number;
+  readonly total: number;
+  /** Non-null when there is nothing to draw. */
+  readonly empty: string | null;
+}
+
+/** The column with nothing in it. What the first render produces. */
+export const EMPTY_COLUMN: GraphColumnModel = {
+  graph: EMPTY_RENDER_GRAPH,
+  highlight: null,
+  key: "",
+  cached: false,
+  clusters: new Map(),
+  visible: 0,
+  total: 0,
+  empty: "Loading…",
+};
+
+/**
+ * Reduce, lay out, resolve and highlight — one frame of the graph column.
+ *
+ * The order is the design, and each step depends on the one before it:
+ *
+ * 1. **Reduce** (`clusterAggregate`, core). Collapsed subtrees become their
+ *    parent and boundary-crossing edges are retargeted onto it. The renderer
+ *    is never handed a node it is expected to hide (§7.4).
+ * 2. **Lay out** the *reduced* graph. Laying out the full model and then
+ *    hiding nodes would leave the visible ones spread across the holes the
+ *    hidden ones left — the collapsed view would have the geometry of the
+ *    expanded one, which is the opposite of the point.
+ * 3. **Resolve** to a `RenderGraph`.
+ * 4. **Highlight** over the reduced edges, so a neighbour inside a collapsed
+ *    cluster lights the cluster rather than nothing.
+ *
+ * Step 2 is also why the layout cache is keyed by shape: every expand and
+ * collapse produces a genuinely different graph, gets its own key, and is
+ * remembered independently — so collapsing and re-expanding returns the
+ * arrangement the user had, rather than a fresh one.
+ */
+export function graphColumnModel(
+  payload: GraphPayload | null,
+  selectedId: string | null,
+  state: GraphViewState,
+  storage: PositionStorage,
+  scheme: ColorScheme,
+): GraphColumnModel {
+  if (payload === null) return EMPTY_COLUMN;
+
+  const model = viewModel(payload);
+  const reduced: ClusterAggregate = clusterAggregate(model, state.expanded);
+  const layout = resolveLayout(storage, reduced.nodes, reduced.edges);
+
+  return {
+    graph: renderGraph(reduced.nodes, reduced.edges, layout.positions, scheme),
+    highlight: highlightFor(reduced.edges, selectedId),
+    key: layout.key,
+    cached: layout.cached,
+    clusters: reduced.clusters,
+    visible: reduced.nodes.length,
+    total: model.nodes.length,
+    empty: graphEmptyMessage(payload, reduced.nodes.length),
+  };
+}
+
+// --- clicking a node -------------------------------------------------------------------------
+
+/** What a click on the canvas produced. */
+export interface GraphClick {
+  /** The next view state — changed only when a collapsed cluster was opened. */
+  readonly state: GraphViewState;
+  /** What to write to `selectedId`. Always set, even when a cluster expanded. */
+  readonly selectedId: string | null;
+}
+
+/**
+ * Apply a click on a node (or on empty stage, with `null`).
+ *
+ * A click does **two** things when it lands on a collapsed cluster: it selects
+ * it *and* it expands it (§7.4, "expand on click"). Both, deliberately — the
+ * selection is what drives the note column and the context rail, and dropping
+ * it in favour of the expansion would make clicking a module the one gesture
+ * in the workspace that does not update the other columns.
+ *
+ * A click on an already-expanded cluster selects without collapsing. Collapse
+ * is the `[expand]` control and the tree; making a second click close a
+ * cluster would make it impossible to select one and read it.
+ */
+export function graphClick(state: GraphViewState, clusters: ReadonlyMap<string, ClusterInfo>, id: string | null): GraphClick {
+  if (id === null) return { state, selectedId: null };
+  const cluster = clusters.get(id);
+  if (cluster === undefined || state.expanded.has(id)) return { state, selectedId: id };
+  return { state: toggleCluster(state, id), selectedId: id };
+}
+
+// --- tooltips ---------------------------------------------------------------------------------
+
+/**
+ * What a node says when it stands in for a collapsed subtree.
+ *
+ * `ClusterInfo.members` is exactly the hidden descendants this cluster is
+ * currently representing — not `descendants`, which overlaps freely between a
+ * cluster and its ancestors and would report the same file under both
+ * `src/core` and `repository`. `members` partitions the hidden set across the
+ * visible clusters, so the counts add up to the number of nodes that are not
+ * on screen.
+ */
+export function clusterBadge(cluster: ClusterInfo | undefined): string | null {
+  if (cluster === undefined || cluster.members.length === 0) return null;
+  return cluster.members.length === 1 ? "1 hidden" : `${cluster.members.length} hidden`;
+}
+
+/**
+ * A node's hover text: its label, its degree, and what it is standing in for.
+ *
+ * `degreeOf` is core's, reached through the §2.1.1 door. The bulk `degrees`
+ * pass in `graph.model.ts` is a different algorithm for a different question
+ * (every node at once, O(edges)); this is one node, which is what a tooltip
+ * asks.
+ */
+export function nodeTooltip(node: WireGraphNode, edges: readonly WireGraphEdge[], cluster: ClusterInfo | undefined): string {
+  const degree = degreeOf(node.id, edges);
+  const parts = [node.label, degree === 1 ? "1 link" : `${degree} links`];
+  const badge = clusterBadge(cluster);
+  if (badge !== null) parts.push(badge);
+  return parts.join(" · ");
+}
+
+/** Positions keyed by id, for a caller warm-starting a re-run. */
+export type LayoutSnapshot = ReadonlyMap<string, Point>;