@caddis/cli 0.4.44 → 0.4.46

package/bundles/codex/.codex/skills/frontend/flow-studio/src/engine.ts

@@ -0,0 +1,193 @@
+// flow-studio engine entry. mount() draws a model into a page that has the shell's element ids and returns
+// a small API (also placed on window.FlowStudio for the check harness). The generated demo page calls mount() itself.
+
+import { validateModel, type Model, type NoteDef } from "./model.ts";
+import { autoLayout } from "./autolayout.ts";
+import type { Ctx, Els } from "./ctx.ts";
+import type { View } from "./viewport.ts";
+import type { Geometry } from "./layout.ts";
+import { stateCss } from "./stateCss.ts";
+import { defaultView, initialCollapsed } from "./rules.ts";
+import { install as installInteract } from "./interact.ts";
+import { install as installRender } from "./render.ts";
+import { install as installControls } from "./controls.ts";
+import { install as installInspector } from "./inspector.ts";
+import { install as installChrome } from "./chrome.ts";
+import { install as installNotes } from "./notes.ts";
+import { install as installPlayback, type PlaybackController } from "./playbackui.ts";
+import { diffModels } from "./diff.ts";
+import { notifySelection } from "./selection.ts";
+import type { Issue } from "./model.ts";
+
+export interface FlowStudio {
+  model: Model;
+  geometry(): Geometry;
+  view(): View;
+  setView(v: View, animate?: boolean): void;
+  fit(animate?: boolean): void;
+  select(id: string | null): void;
+  selected(): string | null;
+  mode(): string;
+  setMode(id: string): void;
+  simulate(actionId: string): void;
+  resetSimulation(): void;
+  play(scenarioId?: string): void;
+  pause(): void;
+  step(): void;
+  seek(tMs: number): void;
+  playback(): { scenario: string | null; step: number; playing: boolean; t: number };
+  update(model: Model, opts?: { animate?: boolean }): { ok: boolean; issues: Issue[] };
+  destroy(): void;
+}
+
+declare global {
+  interface Window { FlowStudio?: FlowStudio; flowStudioMount?: typeof mount }
+}
+
+const IDS: Record<keyof Els, string> = {
+  vp: "viewport", world: "world", svg: "edges", layer: "edgeLayer", cols: "cols", tools: "tools", zoom: "zoomLabel",
+  inspector: "inspector", workspace: "workspace", live: "live", strip: "layerstrip", tiles: "kpis", legend: "legend",
+  ledger: "ledger", table: "tbl", q: "q", hops: "hops", matchinfo: "matchinfo", modeSwitch: "modeSwitch", drawer: "drawer",
+  notelist: "notelist", notesBtn: "notesBtn", theme: "theme", specbody: "specbody", spec: "spec", title: "title",
+  readat: "readat", help: "help", footer: "footer", playbar: "playbar", pbScenario: "pbScenario", pbPlay: "pbPlay",
+  pbStep: "pbStep", pbReset: "pbReset", pbSpeed: "pbSpeed", pbScrub: "pbScrub", pbCaption: "pbCaption",
+  pbCounter: "pbCounter", pbChoices: "pbChoices", banner: "banner",
+};
+
+function findEls(root: ParentNode): Els {
+  const out = {} as Record<string, Element>;
+  for (const [key, id] of Object.entries(IDS)) {
+    const e = root.querySelector("#" + id);
+    if (!e) throw new Error(`flow-studio: the page has no element #${id}`);
+    out[key] = e;
+  }
+  return out as unknown as Els;
+}
+
+interface SavedState { view: View; mode: string; selected: string | null; inspectorOpen: boolean; query: string; hops: number; filter: Ctx["filter"]; collapsed: Set<string>; knownGroups: Set<string>; playback: ReturnType<PlaybackController["playback"]> }
+export function mount(root: ParentNode, model: Model, opts: { notes?: NoteDef[]; onSelect?: (id: string | null) => void; restore?: SavedState } = {}): FlowStudio {
+  if (!model || !Array.isArray(model.columns) || !Array.isArray(model.lanes) || !Array.isArray(model.nodes) || !Array.isArray(model.links) || !model.states) {
+    throw new Error("flow-studio: the model needs columns, lanes, states, nodes and links");
+  }
+  if (model.layout === "auto") model = autoLayout(model);
+  const els = findEls(root);
+  const issues = validateModel(model);
+  const errors = issues.filter(i => i.level === "error");
+  for (const i of issues) (i.level === "error" ? console.error : console.warn)(`flow-studio ${i.code} ${i.where}: ${i.message}`);
+  if (errors.length) els.help.textContent = `${errors.length} model error(s). See the console. The page shows what it can.`;
+
+  const rm = matchMedia("(prefers-reduced-motion: reduce)");
+  const ctx: Ctx = {
+    model, root, els, onSelect: opts.onSelect,
+    notes: opts.notes && opts.notes.length ? opts.notes : model.notes ?? [],
+    nodes: new Map(model.nodes.map(n => [n.id, n])),
+    links: model.links,
+    geom: { xs: [], nodes: {}, lanes: {}, loops: {}, bounds: { x: 0, y: 0, w: 1, h: 1 }, world: { w: 1, h: 1 } },
+    view: { x: 0, y: 0, k: 1 },
+    reduced: rm.matches,
+    mode: opts.restore && (model.views?.some(v => v.id === opts.restore!.mode) || (!model.views?.length && opts.restore.mode === "all")) ? opts.restore.mode : defaultView(model),
+    collapsed: opts.restore ? new Set(model.nodes.filter(n => n.kind === "group" && n.contains && (opts.restore!.collapsed.has(n.id) || (!opts.restore!.knownGroups.has(n.id) && n.collapsed !== false))).map(n => n.id)) : initialCollapsed(model),
+    selected: opts.restore?.selected && model.nodes.some(n => n.id === opts.restore!.selected) ? opts.restore.selected : null,
+    hl: null, query: opts.restore?.query ?? "", hops: opts.restore?.hops ?? 0, filter: opts.restore?.filter ?? null, tool: "select",
+    spaceDown: false, userMoved: false, dismissed: false, simActive: false, moved: 0,
+    nodeEls: new Map(), laneEls: new Map(), edgeEls: [], labelEls: [], overlays: [], simTimers: [], disposers: [],
+    fn: {} as Ctx["fn"],
+  };
+  const onRm = (e: MediaQueryListEvent) => { ctx.reduced = e.matches; };
+  rm.addEventListener("change", onRm);
+  ctx.disposers.push(() => rm.removeEventListener("change", onRm));
+
+  let style = document.getElementById("state-css") as HTMLStyleElement | null;
+  if (!style) { style = document.createElement("style"); style.id = "state-css"; document.head.prepend(style); }
+  style.textContent = stateCss(model.states);
+
+  installInteract(ctx);
+  installRender(ctx);
+  installControls(ctx);
+  installInspector(ctx);
+  installChrome(ctx);
+  installNotes(ctx);
+  els.q.value = ctx.query;
+  els.hops.value = String(ctx.hops);
+
+  ctx.fn.buildWorld();
+  ctx.fn.paint(false);
+  const playback = installPlayback(ctx);
+  if (opts.restore) {
+    ctx.userMoved = true;
+    ctx.fn.setView(opts.restore.view, false);
+    playback.restore(opts.restore.playback);
+    if (opts.restore.inspectorOpen) {
+      els.inspector.classList.add("open");
+      els.workspace.classList.add("inspopen");
+      els.inspector.setAttribute("aria-hidden", "false");
+      ctx.fn.renderInspector();
+    } else {
+      els.inspector.classList.remove("open");
+      els.workspace.classList.remove("inspopen");
+      els.inspector.setAttribute("aria-hidden", "true");
+    }
+  } else {
+    // The entrance animation is for the first mount only; a live update restores and must not replay it.
+    document.body.classList.add("intro");
+    const introTimer = window.setTimeout(() => document.body.classList.remove("intro"), 2100);
+    // destroy() clears these timers, so an update inside the window cannot fire the old instance's callbacks.
+    ctx.disposers.push(() => { window.clearTimeout(introTimer); document.body.classList.remove("intro"); });
+    ctx.fn.fitWidth(false);
+    const fitTimer = window.setTimeout(() => { if (!ctx.userMoved) ctx.fn.fitWidth(false); }, 120);
+    ctx.disposers.push(() => window.clearTimeout(fitTimer));
+  }
+
+  const api: FlowStudio = {
+    model,
+    geometry: () => ctx.geom,
+    view: () => ({ ...ctx.view }),
+    setView: (v, animate) => ctx.fn.setView(v, animate),
+    fit: animate => { ctx.userMoved = false; ctx.fn.fit(animate); },
+    select: id => ctx.fn.select(id),
+    selected: () => ctx.selected,
+    mode: () => ctx.mode,
+    setMode: id => ctx.fn.setMode(id),
+    simulate: id => ctx.fn.simulate(id),
+    resetSimulation: () => { ctx.fn.clearSim(); ctx.fn.renderInspector(); },
+    play: id => playback.play(id),
+    pause: () => playback.pause(),
+    step: () => playback.step(),
+    seek: t => playback.seek(t),
+    playback: () => playback.playback(),
+    update: (nextModel, updateOpts) => {
+      const prepared = nextModel.layout === "auto" ? autoLayout(nextModel) : nextModel;
+      const nextIssues = validateModel(prepared);
+      const count = nextIssues.filter(i => i.level === "error").length;
+      if (count) {
+        els.banner.textContent = `Update failed: ${count} errors. Showing the last good graph.`;
+        els.banner.hidden = false;
+        return { ok: false, issues: nextIssues };
+      }
+      const changes = diffModels(ctx.model, prepared);
+      const saved: SavedState = { view: { ...ctx.view }, mode: ctx.mode, selected: ctx.selected, inspectorOpen: els.inspector.classList.contains("open"), query: ctx.query, hops: ctx.hops, filter: ctx.filter, collapsed: new Set(ctx.collapsed), knownGroups: new Set(ctx.model.nodes.filter(n => n.kind === "group").map(n => n.id)), playback: playback.playback() };
+      api.destroy();
+      const replacement = mount(root, prepared, { notes: opts.notes, onSelect: opts.onSelect, restore: saved });
+      notifySelection(saved.selected, replacement.selected(), opts.onSelect);
+      // Refresh this api in place: callers keep their reference and window.FlowStudio stays this
+      // instance, so an update can never overwrite a different mounted engine.
+      Object.assign(api, replacement);
+      window.FlowStudio = api;
+      els.banner.hidden = true; els.banner.textContent = "";
+      if (updateOpts?.animate !== false && !ctx.reduced) {
+        for (const id of changes.changed) root.querySelector<HTMLElement>(`#n_${CSS.escape(id)}`)?.classList.add("updated");
+        for (const id of changes.added) root.querySelector<HTMLElement>(`#n_${CSS.escape(id)}`)?.classList.add("added");
+      }
+      return { ok: true, issues: nextIssues };
+    },
+    destroy: () => {
+      ctx.fn.clearSim();
+      ctx.disposers.forEach(d => d());
+      ctx.disposers = [];
+      style?.remove();
+      if (window.FlowStudio === api || window.FlowStudio?.model === api.model) delete window.FlowStudio;
+    },
+  };
+  window.FlowStudio = api;
+  return api;
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/src/inspector.ts

@@ -0,0 +1,126 @@
+// The slide-in inspector. It uses the markup and class names of the host app's own inspector
+// (.insp, .insp-h, .counts .cbtn, .insp-b, .drill, .pill, .meta), so it looks native when the page lives in an app.
+// It is closed until a click, and it also opens to list search matches when nothing is selected.
+
+import type { Ctx } from "./ctx.ts";
+import { esc } from "./model.ts";
+import type { NodeDef, RelationDef } from "./model.ts";
+import { bucketOf, effectiveLinks, groupFor, isImproved, isNew, nodeStateId, nodeVisible } from "./rules.ts";
+import { matches, relationSet, relationsOf } from "./interact.ts";
+import { sparklinePoints } from "./metrics.ts";
+
+const BUCKET_COLOR = { good: "ok", neutral: "muted", gap: "warn" } as const;
+const PILL = { ok: "ok", warn: "warn", crit: "warn", info: "info", accent: "info", muted: "muted" } as const;
+
+export function install(ctx: Ctx): void {
+  const { els, model } = ctx;
+
+  const matchesFilter = (n: NodeDef, f: RelationDef["filter"]): boolean =>
+    !f || ((f.col === undefined || n.col === f.col) && (f.kind === undefined || n.kind === f.kind));
+
+  function wire(box: HTMLElement): void {
+    box.querySelector("#hideInsp")?.addEventListener("click", () => {
+      if (ctx.selected) ctx.fn.select(null);
+      else { ctx.dismissed = true; ctx.fn.renderInspector(); }
+    });
+    box.querySelectorAll<HTMLElement>("[data-hl]").forEach(b => b.addEventListener("click", () => {
+      ctx.hl = ctx.hl === b.dataset.hl ? null : (b.dataset.hl ?? null);
+      ctx.fn.trace(ctx.selected);
+      ctx.fn.renderInspector();
+    }));
+    box.querySelectorAll<HTMLElement>("[data-g]").forEach(b => b.addEventListener("click", () => { ctx.fn.select(b.dataset.g ?? null); ctx.fn.zoomToPath(); }));
+    box.querySelectorAll<HTMLElement>("[data-act]").forEach(b => b.addEventListener("click", () => ctx.fn.simulate(b.dataset.act ?? "")));
+    box.querySelectorAll<HTMLElement>("[data-toggle-group]").forEach(b => b.addEventListener("click", () => ctx.fn.toggleGroup(b.dataset.toggleGroup ?? "")));
+    box.querySelector("#simReset")?.addEventListener("click", () => { ctx.fn.clearSim(); ctx.fn.renderInspector(); ctx.fn.announce("Simulation reset."); });
+    box.querySelector("#zPath")?.addEventListener("click", () => ctx.fn.zoomToPath());
+    box.querySelector("#zBand")?.addEventListener("click", () => { const n = ctx.selected ? ctx.nodes.get(ctx.selected) : undefined; if (n?.lane) ctx.fn.zoomToBand(n.lane); });
+  }
+
+  function renderInspector(): void {
+    const box = els.inspector, ws = els.workspace;
+    const sel = ctx.selected ? ctx.nodes.get(ctx.selected) : undefined;
+    const head = `<div class="insp-h"><span>Inspector</span><button type="button" id="hideInsp" aria-label="Close the inspector">Close ✕</button></div>`;
+
+    if (!sel) {
+      const found = ctx.query && !ctx.dismissed ? model.nodes.filter(n => nodeVisible(model, ctx.mode, n, ctx.collapsed) && matches(ctx, n)) : [];
+      const open = found.length > 0;
+      box.classList.toggle("open", open);
+      ws.classList.toggle("inspopen", open);
+      box.setAttribute("aria-hidden", String(!open));
+      if (!open) return;
+      const rows = found.map(f => {
+        const b = bucketOf(model, nodeStateId(model, ctx.mode, f));
+        const hits = (f.members ?? []).filter(m => m.toLowerCase().includes(ctx.query)).length;
+        return `<button type="button" class="dr" data-g="${esc(f.id)}"><span class="dbar" style="background:var(--${BUCKET_COLOR[b]})"></span><span class="dtx"><span class="dn">${esc(f.title)}</span><span class="dk">${hits} match · ${esc(model.columns[f.col ?? 0]?.title ?? "")}</span></span></button>`;
+      }).join("");
+      box.innerHTML = head + `<div class="insp-b"><div class="insp-sec"><b>${found.length}</b> group${found.length === 1 ? "" : "s"} match “${esc(ctx.query)}”</div><div class="drill">${rows}</div></div>`;
+      wire(box);
+      return;
+    }
+
+    box.classList.add("open");
+    ws.classList.add("inspopen");
+    box.setAttribute("aria-hidden", "false");
+
+    const sid = nodeStateId(model, ctx.mode, sel);
+    const st = model.states[sid];
+    const bucket = bucketOf(model, sid);
+    const lane = model.lanes.find(l => l.id === sel.lane);
+    const counts = relationsOf(ctx).slice(0, 3).map(r => {
+      const set = relationSet(ctx, r, sel.id);
+      let n = 0;
+      for (const id of set) {
+        const x = ctx.nodes.get(id);
+        if (!x) continue;
+        if (r.filter) { if (matchesFilter(x, r.filter)) n += Math.max(1, x.weight ?? 1); }
+        else if (id !== sel.id) n += 1;
+      }
+      const cls = r.id === "up" ? "cn--up" : r.id === "down" ? "cn--down" : "";
+      return `<button class="cbtn" data-hl="${esc(r.id)}" aria-pressed="${ctx.hl === r.id}"><span class="cn ${cls}">${n}</span><span class="cl">${esc(r.label)}</span></button>`;
+    }).join("");
+
+    const pills = `<span class="pill ${PILL[st?.tone ?? "muted"]}">${esc(st?.word ?? sid)}</span>`
+      + (isImproved(model, ctx.mode, sel) ? '<span class="pill info">gap filled</span>' : "")
+      + (isNew(model, ctx.mode, sel) ? '<span class="pill muted">new in this view</span>' : "");
+    const actions = (model.inspector?.actions ?? []).map(a => `<button type="button" class="danger" data-act="${esc(a.id)}">▶ ${esc(a.label)}</button>`).join("");
+    const members = sel.members ?? [];
+    const owner = groupFor(model, sel.id);
+    const foldAction = sel.kind === "group" && sel.contains?.length && ctx.collapsed.has(sel.id)
+      ? `<button type="button" data-toggle-group="${esc(sel.id)}">Expand group</button>`
+      : owner && !ctx.collapsed.has(owner.id)
+        ? `<button type="button" data-toggle-group="${esc(owner.id)}">Collapse into ${esc(owner.title)}</button>` : "";
+    const exits = sel.kind === "gateway" ? effectiveLinks(model, ctx.mode, ctx.collapsed, ctx.nodes).filter(l => l.from === sel.id).map(l => {
+      const target = ctx.nodes.get(l.to);
+      return `<div class="dr"><span class="dtx"><span class="dn">${esc(l.label ?? "Unlabelled")}</span><span class="dk">${esc(target?.title ?? l.to)}</span></span></div>`;
+    }).join("") : "";
+    const metric = sel.metrics;
+    const series = metric?.series ?? [];
+    const points = sparklinePoints(series, 300, 40);
+    const metricHtml = metric ? `<div class="insp-sec metrics"><b>Metrics</b><table class="meta"><tr><th>label</th><td>${esc(metric.label ?? "Metric")}</td></tr><tr><th>value</th><td>${esc(String(metric.value))} ${esc(metric.unit ?? "")}</td></tr>${metric.max != null ? `<tr><th>max</th><td>${esc(String(metric.max))} ${esc(metric.unit ?? "")}</td></tr>` : ""}</table>${points ? `<svg width="300" height="40" viewBox="0 0 300 40" role="img" aria-label="Metric trend"><polyline points="${points}"/></svg><div class="metric-range"><span>${esc(String(Math.min(...series)))}</span><span>${esc(String(Math.max(...series)))}</span></div>` : ""}</div>` : "";
+
+    box.innerHTML = head + `<div class="counts">${counts}</div>
+      <div class="insp-b"><div class="insp-sec"><p class="nname">${esc(sel.title)}</p><div class="nkind">${esc(model.columns[sel.col ?? 0]?.title ?? "")} · ${esc(lane?.title ?? sel.lane)}</div><div class="pillrow">${pills}</div>${sel.subtitle ? `<p class="note">${esc(sel.subtitle)}</p>` : ""}</div>
+      <div class="insp-sec"><b>Details</b><table class="meta"><tr><th>state</th><td>${esc(st?.word ?? sid)}</td></tr><tr><th>members</th><td>${Math.max(1, sel.weight ?? 1)}</td></tr><tr><th>lane</th><td>${esc(lane?.title ?? sel.lane)}${lane?.badge ? ` (${esc(lane.badge)})` : ""}</td></tr>${sel.upgrade && bucket !== "good" ? `<tr><th>can improve</th><td>${esc(sel.upgrade)}</td></tr>` : ""}</table></div>
+      ${metricHtml}
+      ${sel.kind === "gateway" ? `<div class="insp-sec"><b>Exits</b><div class="drill">${exits}</div></div>` : ""}
+      ${members.length ? `<div class="insp-sec"><b>Members</b> (${Math.max(members.length, sel.weight ?? 0)})<input id="mq" type="search" placeholder="Filter ${members.length} members…" aria-label="Filter members"><div class="drill" id="mlist"></div><p class="drill-hint" id="mcount"></p></div>` : `<div class="insp-sec"><p class="note">No member names are recorded for this group.</p></div>`}
+      ${foldAction ? `<div class="acts">${foldAction}</div>` : ""}
+      <div class="acts"><button type="button" id="zPath">Zoom to path</button><button type="button" id="zBand">Go to lane</button></div>
+      ${actions ? `<div class="acts">${actions}<button type="button" id="simReset"${ctx.simActive ? "" : " hidden"}>Reset</button></div>` : ""}</div>`;
+    wire(box);
+
+    const mq = box.querySelector<HTMLInputElement>("#mq");
+    const draw = () => {
+      const f = (mq?.value ?? "").toLowerCase();
+      const rows = members.filter(m => m.toLowerCase().includes(f));
+      const list = box.querySelector<HTMLElement>("#mlist");
+      if (list) list.innerHTML = rows.slice(0, 14).map(m => `<div class="dr"><span class="dbar" style="background:var(--${BUCKET_COLOR[bucket]})"></span><span class="dtx"><span class="dn mono" style="font-size:12px">${esc(m)}</span></span></div>`).join("");
+      const cnt = box.querySelector<HTMLElement>("#mcount");
+      const weight = sel.weight ?? 0;
+      if (cnt) cnt.textContent = `${Math.min(14, rows.length)} of ${rows.length}${weight > members.length ? ` named (${weight} members in all)` : ""}`;
+    };
+    if (mq) { mq.addEventListener("input", draw); draw(); }
+  }
+
+  ctx.fn.renderInspector = renderInspector;
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/src/interact.ts

@@ -0,0 +1,253 @@
+// Interaction: tracing a path, selecting, the draw-in trail, the what-if action, zooming to a path or lane.
+
+import type { Ctx } from "./ctx.ts";
+import type { NodeDef, RelationDef } from "./model.ts";
+import type { Rect } from "./viewport.ts";
+import { connected, relatives, withinHops, type Edge } from "./trace.ts";
+import { bucketOf, canonOf, effectiveLinks, nodeStateId, nodeVisible, toggleGroupState } from "./rules.ts";
+import { notifySelection } from "./selection.ts";
+
+export function relationsOf(ctx: Ctx): RelationDef[] {
+  const given = ctx.model.inspector?.relations;
+  if (given && given.length) return given;
+  const last = Math.max(0, ctx.model.columns.length - 1);
+  return [
+    { id: "up", label: "Upstream", dir: "up" },
+    { id: "down", label: "Downstream", dir: "down" },
+    { id: "end", label: "At the end", dir: "down", filter: { col: last } },
+  ];
+}
+
+export function visibleEdges(ctx: Ctx): Edge[] {
+  return effectiveLinks(ctx.model, ctx.mode, ctx.collapsed, ctx.nodes).map(l => ({ from: l.from, to: l.to }));
+}
+
+export function relationSet(ctx: Ctx, rel: RelationDef, start: string): Set<string> {
+  const canon = (id: string) => canonOf(ctx.nodes, id);
+  const set = relatives(visibleEdges(ctx), canon, start, rel.dir);
+  if (!rel.filter) return set;
+  const out = new Set<string>([canon(start)]);
+  for (const id of set) {
+    const n = ctx.nodes.get(id);
+    if (!n) continue;
+    if ((rel.filter.col === undefined || n.col === rel.filter.col) && (rel.filter.kind === undefined || n.kind === rel.filter.kind)) out.add(id);
+  }
+  return out;
+}
+
+export function matches(ctx: Ctx, n: NodeDef): boolean {
+  const q = ctx.query;
+  return !!q && (n.title.toLowerCase().includes(q) || (n.members ?? []).some(m => m.toLowerCase().includes(q)));
+}
+
+export function install(ctx: Ctx): void {
+  const { els, model } = ctx;
+  const canon = (id: string) => canonOf(ctx.nodes, id);
+  const visibleNodes = () => model.nodes.filter(n => nodeVisible(model, ctx.mode, n, ctx.collapsed));
+  const inspInset = () => (els.inspector.classList.contains("open") ? 340 : 0);
+
+  function activeSet(id: string | null): Set<string> | null {
+    const edges = visibleEdges(ctx);
+    if (id) {
+      if (id === ctx.selected && ctx.hl) {
+        const rel = relationsOf(ctx).find(r => r.id === ctx.hl);
+        if (rel) return relationSet(ctx, rel, id);
+      }
+      return connected(edges, canon, id);
+    }
+    if (ctx.filter) {
+      return new Set(visibleNodes().filter(n => {
+        const b = bucketOf(model, nodeStateId(model, ctx.mode, n));
+        return ctx.filter === "gap" ? b === "gap" : !!n.upgrade && b !== "good";
+      }).map(n => canon(n.id)));
+    }
+    if (ctx.query) return withinHops(edges, canon, visibleNodes().filter(n => matches(ctx, n)).map(n => n.id), ctx.hops);
+    return null;
+  }
+
+  function trace(id: string | null): void {
+    const set = activeSet(id);
+    const lit = !!id && !!set;
+    for (const n of model.nodes) {
+      const d = ctx.nodeEls.get(n.id);
+      if (!d) continue;
+      d.classList.toggle("dim", !!set && !set.has(canon(n.id)));
+      d.classList.toggle("lit", lit && !!set && set.has(canon(n.id)));
+    }
+    ctx.edgeEls.forEach(p => {
+      if (!p) return;
+      const inSet = !!set && set.has(canon(p.dataset.a ?? "")) && set.has(canon(p.dataset.b ?? ""));
+      p.classList.toggle("dim", !!set && !inSet);
+      p.classList.toggle("hot", lit && inSet);
+    });
+    ctx.labelEls.forEach(l => { if (l) l.classList.toggle("show", lit && !!set && set.has(canon(l.dataset.a ?? "")) && set.has(canon(l.dataset.b ?? ""))); });
+  }
+
+  function select(id: string | null): void {
+    clearSim();
+    const previous = ctx.selected;
+    ctx.selected = id ? canon(id) : null;
+    ctx.hl = null;
+    ctx.dismissed = false;
+    for (const n of model.nodes) ctx.nodeEls.get(n.id)?.classList.toggle("sel", !!ctx.selected && canon(n.id) === ctx.selected);
+    trace(ctx.selected);
+    ctx.fn.renderInspector();
+    drawTrail();
+    if (ctx.selected) revealNode(ctx.selected);
+    notifySelection(previous, ctx.selected, ctx.onSelect);
+  }
+
+  /** An overlay is a copy of one link drawn on top. pathLength=1 makes the draw-in independent of zoom. */
+  function overlay(edge: SVGPathElement, cls: string, delay: number, dur: number): SVGPathElement {
+    const o = edge.cloneNode(false) as SVGPathElement;
+    o.setAttribute("class", cls);
+    o.setAttribute("pathLength", "1");
+    o.removeAttribute("data-i");
+    els.layer.appendChild(o);
+    ctx.overlays.push(o);
+    if (ctx.reduced) return o;
+    o.style.strokeDasharray = "1 1";
+    o.style.strokeDashoffset = "1";
+    o.getBoundingClientRect();
+    o.style.transition = `stroke-dashoffset ${dur}s ${delay}s ease-out`;
+    o.style.strokeDashoffset = "0";
+    return o;
+  }
+  function dropOverlays(cls: string): void {
+    ctx.overlays.filter(o => o.classList.contains(cls)).forEach(o => o.remove());
+    ctx.overlays = ctx.overlays.filter(o => o.isConnected);
+  }
+  function drawTrail(): void {
+    dropOverlays("trail");
+    if (!ctx.selected || ctx.reduced) return;
+    const set = connected(visibleEdges(ctx), canon, ctx.selected);
+    const c0 = ctx.nodes.get(ctx.selected)?.col ?? 0;
+    for (const p of ctx.edgeEls) {
+      if (!p || p.classList.contains("off")) continue;
+      const a = canon(p.dataset.a ?? ""), b = canon(p.dataset.b ?? "");
+      if (!(set.has(a) && set.has(b))) continue;
+      const delay = Math.min(Math.abs((ctx.nodes.get(a)?.col ?? 0) - c0), Math.abs((ctx.nodes.get(b)?.col ?? 0) - c0)) * 0.09;
+      const o = overlay(p, "trail", delay, 0.55);
+      window.setTimeout(() => { o.style.transition = "opacity .6s"; o.style.opacity = "0"; window.setTimeout(() => o.remove(), 650); }, (delay + 0.55) * 1000 + 150);
+    }
+  }
+
+  function simulate(actionId: string): void {
+    clearSim();
+    if (!ctx.selected) return;
+    const action = model.inspector?.actions?.find(a => a.id === actionId);
+    const stale = action?.staleText ?? "potentially stale";
+    ctx.simActive = true;
+    const down = relatives(visibleEdges(ctx), canon, ctx.selected, "down");
+    const c0 = ctx.nodes.get(ctx.selected)?.col ?? 0;
+    for (const p of ctx.edgeEls) {
+      if (!p || p.classList.contains("off")) continue;
+      const a = canon(p.dataset.a ?? ""), b = canon(p.dataset.b ?? "");
+      if (down.has(a) && down.has(b)) overlay(p, "ripple", Math.abs((ctx.nodes.get(a)?.col ?? 0) - c0) * 0.11, 0.5);
+    }
+    down.forEach(id => {
+      if (id === ctx.selected) return;
+      const d = ctx.nodeEls.get(id);
+      if (!d) return;
+      const delay = ctx.reduced ? 0 : Math.abs((ctx.nodes.get(id)?.col ?? 0) - c0) * 110 + 450;
+      ctx.simTimers.push(window.setTimeout(() => {
+        d.classList.add("fail");
+        const sub = d.querySelector(".s");
+        if (sub) { d.dataset.s = sub.innerHTML; sub.textContent = stale; }
+      }, delay));
+    });
+    ctx.fn.announce(`Simulation: ${down.size - 1} groups downstream of ${ctx.nodes.get(ctx.selected)?.title ?? ""} would be ${stale}.`);
+    ctx.fn.renderInspector();
+  }
+  function clearSim(): void {
+    ctx.simTimers.forEach(t => clearTimeout(t));
+    ctx.simTimers = [];
+    dropOverlays("ripple");
+    document.querySelectorAll<HTMLElement>(".node.fail").forEach(d => {
+      d.classList.remove("fail");
+      const sub = d.querySelector(".s");
+      if (sub && d.dataset.s !== undefined) { sub.innerHTML = d.dataset.s; delete d.dataset.s; }
+    });
+    ctx.simActive = false;
+  }
+
+  /** The inspector covers the right 340 px. If the group would sit under it, glide the view left. */
+  function revealNode(id: string): void {
+    const d = ctx.nodeEls.get(id);
+    if (!d) return;
+    const r = d.getBoundingClientRect(), v = els.vp.getBoundingClientRect(), edge = v.right - 340 - 24;
+    if (r.right > edge) {
+      ctx.userMoved = true;
+      ctx.fn.setView({ k: ctx.view.k, x: ctx.view.x + Math.max(edge - r.right, v.left + 60 - r.left), y: ctx.view.y }, true);
+    }
+  }
+
+  function rectOf(ids: string[]): Rect | null {
+    const ps = ids.map(i => ctx.geom.nodes[i]).filter((p): p is NonNullable<typeof p> => !!p && !!ctx.nodes.get(p.id) && nodeVisible(model, ctx.mode, ctx.nodes.get(p.id) as NodeDef, ctx.collapsed));
+    if (!ps.length) return null;
+    const x1 = Math.min(...ps.map(p => p.x)), y1 = Math.min(...ps.map(p => p.y));
+    const x2 = Math.max(...ps.map(p => p.x + p.w)), y2 = Math.max(...ps.map(p => p.y + p.h));
+    return { x: x1 - 20, y: y1 - 20, w: x2 - x1 + 40, h: y2 - y1 + 40 };
+  }
+  function zoomToPath(): void {
+    if (!ctx.selected) return;
+    const ids = [...connected(visibleEdges(ctx), canon, ctx.selected)];
+    ids.push(...model.nodes.filter(n => n.ref && ids.includes(n.ref)).map(n => n.id));
+    const r = rectOf(ids);
+    if (r) { ctx.userMoved = true; ctx.fn.fit(true, r, inspInset()); ctx.fn.announce(`Zoomed to the path of ${ctx.nodes.get(ctx.selected)?.title ?? ""}`); }
+  }
+  function zoomToBand(id: string): void {
+    const r = ctx.geom.lanes[id];
+    if (!r) return;
+    ctx.userMoved = true;
+    ctx.fn.fit(true, { x: r.x - 10, y: r.y - 10, w: r.w + 20, h: r.h + 20 }, inspInset());
+    ctx.fn.announce(`Zoomed to the lane ${model.lanes.find(l => l.id === id)?.title ?? id}`);
+  }
+
+  function escape(): void {
+    clearSim();
+    select(null);
+    ctx.filter = null;
+    ctx.query = "";
+    els.q.value = "";
+    els.matchinfo.textContent = "";
+    ctx.fn.buildChrome();
+    trace(null);
+    ctx.fn.toggleNotes(false);
+  }
+  function setMode(id: string): void {
+    if (ctx.mode === id) return;
+    document.body.classList.remove("intro");
+    clearSim();
+    ctx.mode = id;
+    const sel = ctx.selected && ctx.nodes.get(ctx.selected);
+    if (sel && !nodeVisible(model, id, sel, ctx.collapsed)) select(null);
+    ctx.fn.paint(true);
+    ctx.userMoved = false;
+    ctx.fn.fitWidth(true);
+    const added = model.nodes.filter(n => nodeVisible(model, id, n, ctx.collapsed) && !nodeVisible(model, model.views?.[0]?.id ?? "all", n, ctx.collapsed)).length;
+    ctx.fn.announce(added ? `${model.views?.find(v => v.id === id)?.label ?? id} view: ${added} groups added.` : `${model.views?.find(v => v.id === id)?.label ?? id} view.`);
+  }
+
+  ctx.fn.trace = trace;
+  ctx.fn.select = select;
+  ctx.fn.drawTrail = drawTrail;
+  ctx.fn.simulate = simulate;
+  ctx.fn.clearSim = clearSim;
+  ctx.fn.rectOf = rectOf;
+  ctx.fn.zoomToPath = zoomToPath;
+  ctx.fn.zoomToBand = zoomToBand;
+  ctx.fn.escape = escape;
+  ctx.fn.setMode = setMode;
+  ctx.fn.toggleGroup = (id: string) => {
+    const group = model.nodes.find(n => n.id === id && n.kind === "group" && n.contains?.length);
+    if (!group) return;
+    const change = toggleGroupState(model, ctx.mode, ctx.collapsed, id);
+    if (!change) return;
+    ctx.collapsed = change.collapsed;
+    ctx.fn.paint();
+    ctx.fn.select(change.selected);
+    ctx.fn.announce(change.expanding ? `Expanded ${group.title}.` : `Collapsed into ${group.title}.`);
+  };
+  ctx.fn.announce = (t: string) => { els.live.textContent = t; };
+}