@caddis/cli 0.4.43 → 0.4.45

package/bundles/codex/.codex/skills/frontend/flow-studio/scripts/validate.mjs

@@ -0,0 +1,38 @@
+// Validate a flow-studio model.
+//   node --experimental-strip-types scripts/validate.mjs <model.json>
+// Exit 0: no errors (warnings are printed). Exit 1: at least one error. Exit 2: cannot read the file.
+
+import { readFileSync } from "node:fs";
+import { validateModel } from "../src/model.ts";
+
+export function loadModel(path) {
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    console.error(`cannot read ${path}: ${e.message}`);
+    process.exit(2);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    console.error(`${path} is not valid JSON: ${e.message}`);
+    process.exit(2);
+  }
+}
+
+export function report(issues) {
+  for (const i of issues) console.log(`${i.level.toUpperCase().padEnd(5)} ${i.code.padEnd(16)} ${i.where}: ${i.message}`);
+  return issues.filter(i => i.level === "error").length;
+}
+
+if (process.argv[1]?.endsWith("validate.mjs")) {
+  const path = process.argv[2];
+  if (!path) {
+    console.error("usage: node --experimental-strip-types scripts/validate.mjs <model.json>");
+    process.exit(2);
+  }
+  const errors = report(validateModel(loadModel(path)));
+  console.log(errors ? `${errors} error(s)` : "OK");
+  process.exit(errors ? 1 : 0);
+}

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

@@ -0,0 +1,171 @@
+// The page around the canvas: completeness strip, summary tiles, legend, ledger, table view, title,
+// view switch, search box and theme toggle. Text comes from the model; every string goes through esc() or textContent.
+
+import { el, on, type Ctx } from "./ctx.ts";
+import { esc } from "./model.ts";
+import { DASH, toneVar, cssId } from "./stateCss.ts";
+import { bucketOf, linkStateId, linkVisible, nodeStateId, nodeVisible } from "./rules.ts";
+import { matches } from "./interact.ts";
+
+const DEFAULT_LABELS: Record<string, string> = {
+  tileGood: "links in a good state",
+  tileNeutral: "links in a neutral state",
+  tileGap: "groups with a gap: click to show",
+  tileUpgrade: "groups you can improve: click to show",
+  ledgerTitle: "What this view could not establish",
+  tableTitle: "Table view",
+};
+
+export function install(ctx: Ctx): void {
+  const { els, model } = ctx;
+  const label = (k: string): string => model.meta.labels?.[k] ?? DEFAULT_LABELS[k] ?? k;
+  const visible = (id: string): boolean => { const n = ctx.nodes.get(id); return !!n && nodeVisible(model, ctx.mode, n); };
+
+  function countUp(node: HTMLElement, to: number, ms = 700): void {
+    if (ctx.reduced) { node.textContent = String(to); return; }
+    const t0 = performance.now();
+    const step = (t: number) => {
+      const k = Math.min(1, (t - t0) / ms), e = 1 - Math.pow(1 - k, 3);
+      node.textContent = String(Math.round(to * e));
+      if (k < 1) requestAnimationFrame(step);
+    };
+    requestAnimationFrame(step);
+  }
+
+  function buildStrip(): void {
+    const box = els.strip;
+    box.style.gridTemplateColumns = `repeat(${Math.max(1, model.columns.length)}, minmax(0, 1fr))`;
+    if (!box.firstChild) {
+      box.innerHTML = model.columns.map(c => `<div class="lcell"><div class="ln">${esc(c.title)}</div><div class="lb"><i class="good"></i><i class="neutral"></i><i class="gap"></i></div><div class="lv"></div></div>`).join("");
+    }
+    box.querySelectorAll<HTMLElement>(".lcell").forEach((cell, i) => {
+      cell.style.setProperty("--i", String(i));
+      let tot = 0, good = 0, neutral = 0, gap = 0;
+      for (const n of model.nodes) {
+        if (n.col !== i || n.kind === "chip") continue;
+        const w = Math.max(1, n.weight ?? 1);
+        tot += w;
+        if (!visible(n.id)) continue;
+        const b = bucketOf(model, nodeStateId(model, ctx.mode, n));
+        if (b === "good") good += w; else if (b === "neutral") neutral += w; else gap += w;
+      }
+      const t = tot || 1, bars = cell.querySelectorAll<HTMLElement>("i");
+      requestAnimationFrame(() => {
+        if (bars[0]) bars[0].style.width = good / t * 100 + "%";
+        if (bars[1]) bars[1].style.width = neutral / t * 100 + "%";
+        if (bars[2]) bars[2].style.width = gap / t * 100 + "%";
+      });
+      const lv = cell.querySelector<HTMLElement>(".lv");
+      if (lv) lv.textContent = `${good + neutral} / ${tot}`;
+      cell.title = `${model.columns[i]?.title ?? ""}: ${good} good, ${neutral} neutral, ${gap} gap`;
+    });
+  }
+
+  function buildTiles(): void {
+    const k = els.tiles;
+    let good = 0, neutral = 0;
+    for (const l of ctx.links) {
+      if (!linkVisible(model, ctx.mode, l, ctx.nodes)) continue;
+      const b = bucketOf(model, linkStateId(model, ctx.mode, l));
+      if (b === "good") good++; else if (b === "neutral") neutral++;
+    }
+    let gaps = 0, upgrades = 0;
+    for (const n of model.nodes) {
+      if (!visible(n.id) || n.kind === "chip") continue;
+      const b = bucketOf(model, nodeStateId(model, ctx.mode, n));
+      if (b === "gap") gaps += 1;
+      if (n.upgrade && b !== "good") upgrades++;
+    }
+    k.innerHTML = "";
+    const tile = (cls: string, n: number, text: string, filter?: "gap" | "upgrade") => {
+      const b = el(filter ? "button" : "div", "tile " + cls, `<span class="tn">0</span><span class="tl">${esc(text)}</span>`);
+      b.style.setProperty("--i", String(k.children.length + 9));
+      if (filter) {
+        (b as HTMLButtonElement).type = "button";
+        b.setAttribute("aria-pressed", String(ctx.filter === filter));
+        b.addEventListener("click", () => {
+          ctx.filter = ctx.filter === filter ? null : filter;
+          ctx.fn.select(null);
+          buildTiles();
+          ctx.fn.trace(null);
+          ctx.fn.announce(ctx.filter ? "Filter on" : "Filter off");
+        });
+      }
+      k.appendChild(b);
+      countUp(b.querySelector<HTMLElement>(".tn") as HTMLElement, n);
+    };
+    tile("ok", good, label("tileGood"));
+    tile("", neutral, label("tileNeutral"));
+    tile("warn", gaps, label("tileGap"), "gap");
+    tile("", upgrades, label("tileUpgrade"), "upgrade");
+  }
+
+  function buildLegend(): void {
+    const parts = Object.entries(model.states).map(([id, s]) => {
+      const cap = s.edge === "dot" ? ' stroke-linecap="round"' : "";
+      return `<span><svg width="40" height="10" aria-hidden="true"><path d="M0 5 H40" stroke="${toneVar(s.tone)}" stroke-width="2" stroke-dasharray="${DASH[s.edge]}"${cap}/></svg><b class="ev st-${cssId(id)}">${esc(s.word)}</b></span>`;
+    });
+    parts.push('<span id="hintline">scroll = zoom · drag = pan · double-click = fit</span>');
+    els.legend.innerHTML = parts.join("");
+  }
+
+  function buildLedger(): void {
+    let gaps = 0, total = 0;
+    for (const n of model.nodes) { if (n.kind === "chip" || !visible(n.id)) continue; total++; if (bucketOf(model, nodeStateId(model, ctx.mode, n)) === "gap") gaps++; }
+    const noLane = model.lanes.filter(l => l.gap).length;
+    els.ledger.innerHTML = `<h4>${esc(label("ledgerTitle"))}</h4><p><b>${gaps}</b> of <b>${total}</b> groups in this view have a gap: they are drawn dotted and are never guessed. ${noLane ? `<b>${noLane}</b> lane${noLane === 1 ? " has" : "s have"} no source document yet.` : ""}</p><p>${esc(model.meta.source)}</p>`;
+  }
+
+  function buildTable(): void {
+    const rows = model.nodes.filter(n => visible(n.id) && n.kind !== "chip").map(n => {
+      const sid = nodeStateId(model, ctx.mode, n);
+      const lane = model.lanes.find(l => l.id === n.lane)?.title ?? n.lane;
+      return `<tr><th scope="row">${esc(model.columns[n.col]?.title ?? "")}</th><td>${esc(lane)}</td><td>${esc(n.title)}</td><td>${esc(model.states[sid]?.word ?? sid)}</td><td>${Math.max(1, n.weight ?? 1)}</td><td>${esc(n.subtitle ?? "")}</td><td>${esc(n.upgrade ?? "")}</td></tr>`;
+    }).join("");
+    els.table.innerHTML = `<thead><tr><th scope="col">Column</th><th scope="col">Lane</th><th scope="col">Group</th><th scope="col">State</th><th scope="col">Members</th><th scope="col">Detail</th><th scope="col">Can improve</th></tr></thead><tbody>${rows}</tbody>`;
+  }
+
+  ctx.fn.buildChrome = () => { buildStrip(); buildTiles(); buildTable(); buildLedger(); };
+
+  // ---- page text and controls, set up once
+  document.title = model.meta.title;
+  els.title.textContent = model.meta.title;
+  els.help.textContent = model.meta.help;
+  els.readat.textContent = model.meta.asOf ? `as of ${model.meta.asOf}` : "";
+  els.footer.textContent = model.meta.source;
+  buildLegend();
+
+  const views = model.views ?? [];
+  els.modeSwitch.hidden = views.length < 2;
+  els.modeSwitch.innerHTML = "";
+  for (const v of views) {
+    const b = el("button", "seg");
+    b.type = "button"; b.setAttribute("role", "tab"); b.dataset.mode = v.id;
+    b.setAttribute("aria-selected", String(v.id === ctx.mode));
+    b.textContent = v.label;
+    on(ctx, b, "click", () => {
+      els.modeSwitch.querySelectorAll("button").forEach(x => x.setAttribute("aria-selected", String(x === b)));
+      ctx.fn.setMode(v.id);
+    });
+    els.modeSwitch.appendChild(b);
+  }
+
+  on(ctx, els.q, "input", (e: Event) => {
+    ctx.query = (e.target as HTMLInputElement).value.trim().toLowerCase();
+    ctx.dismissed = false;
+    const n = model.nodes.filter(x => visible(x.id) && matches(ctx, x)).length;
+    els.matchinfo.textContent = ctx.query ? `${n} group${n === 1 ? "" : "s"} match` : "";
+    if (!ctx.selected) { ctx.fn.trace(null); ctx.fn.renderInspector(); }
+  });
+  on(ctx, els.q, "keydown", (e: KeyboardEvent) => {
+    if (e.key !== "Enter" || !ctx.query) return;
+    const ids = model.nodes.filter(x => visible(x.id) && matches(ctx, x)).map(x => x.id);
+    const r = ctx.fn.rectOf(ids);
+    if (r) { ctx.userMoved = true; ctx.fn.fit(true, r, els.inspector.classList.contains("open") ? 340 : 0); ctx.fn.announce(`Zoomed to ${ids.length} matching groups`); }
+  });
+  on(ctx, els.theme, "click", () => {
+    const r = document.documentElement;
+    const dark = r.dataset.theme ? r.dataset.theme === "dark" : matchMedia("(prefers-color-scheme: dark)").matches;
+    r.dataset.theme = dark ? "light" : "dark";
+  });
+}

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

@@ -0,0 +1,231 @@
+// The canvas controls: view (pan and zoom), pinned headers, pointer, wheel, pinch, keys and the tool strip.
+// The maths lives in viewport.ts; this file only reads and writes the DOM.
+
+import { on, el, type Ctx } from "./ctx.ts";
+import { clampPan, fitRect, fitWidth, zoomAt, type Rect, type View } from "./viewport.ts";
+
+const HEAD = 44; // height of the pinned header overlay
+
+const ICON: Record<string, string> = {
+  select: '<path d="M5 3l12 6.5-5.2 1.6L9.5 17z"/>',
+  hand: '<path d="M8 11V5.5a1.5 1.5 0 013 0V10m0-5a1.5 1.5 0 013 0v5m0-3.5a1.5 1.5 0 013 0V13c0 4-2.5 7-6.5 7S5 17 5 14l-1.6-3.2a1.4 1.4 0 012.4-1.4L8 12"/>',
+  plus: '<path d="M12 5v14M5 12h14"/>',
+  minus: '<path d="M5 12h14"/>',
+  fit: '<path d="M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5"/>',
+  one: '<path d="M9 8l3-2v12"/><path d="M5 20h14"/>',
+  sel: '<circle cx="12" cy="12" r="3.2"/><path d="M12 3v3M12 18v3M3 12h3M18 12h3"/>',
+  full: '<path d="M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5"/>',
+};
+
+export function install(ctx: Ctx): void {
+  const { els, model } = ctx;
+  const vp = els.vp;
+  // The size is cached: reading clientWidth on every wheel event would force a layout of the whole page each time.
+  let cached = { w: vp.clientWidth, h: vp.clientHeight };
+  const size = () => cached;
+  // Same for the viewport rectangle: it is refreshed on resize, scroll and when the pointer enters.
+  let vpRect = vp.getBoundingClientRect();
+  const refreshRect = () => { vpRect = vp.getBoundingClientRect(); };
+  let animTimer = 0;
+  let raf = 0;
+
+  function applyView(): void {
+    const v = ctx.view;
+    els.world.style.transform = `translate(${v.x}px,${v.y}px) scale(${v.k})`;
+    vp.style.setProperty("--inv", Math.max(1, 0.9 / v.k).toFixed(3));
+    vp.style.setProperty("--k", v.k.toFixed(4));
+    vp.classList.toggle("lod1", v.k < 0.62);
+    vp.classList.toggle("lod2", v.k < 0.4);
+    els.zoom.textContent = Math.round(v.k * 100) + "%";
+    ctx.fn.stickLabels();
+    ctx.fn.placeHeaders();
+    if (!raf) raf = requestAnimationFrame(() => { raf = 0; if (document.body.classList.contains("notes")) ctx.fn.placeMarkers(); });
+  }
+
+  function setView(v: View, animate = false): void {
+    const c = clampPan(v, ctx.geom.bounds, size());
+    ctx.view = [c.x, c.y, c.k].every(Number.isFinite) ? c : { x: 0, y: 0, k: 1 };
+    const glide = animate && !ctx.reduced;
+    vp.classList.toggle("anim", glide);
+    if (glide) { clearTimeout(animTimer); animTimer = window.setTimeout(() => vp.classList.remove("anim"), 330); }
+    applyView();
+  }
+
+  function fit(animate = false, rect?: Rect, inset = 0): void {
+    const r = rect ?? ctx.geom.bounds;
+    if (!(r.w > 0)) return;
+    const s = size();
+    setView(fitRect(r, { w: s.w - inset, h: s.h }, 28, HEAD + 8), animate);
+  }
+  function fitW(animate = false): void {
+    setView(fitWidth(ctx.geom.bounds, size(), 28, HEAD + 8), animate);
+  }
+  function zoomBy(f: number): void {
+    const s = size();
+    ctx.userMoved = true;
+    setView(zoomAt(ctx.view, f, s.w / 2, s.h / 2), true);
+    ctx.fn.announce("Zoom " + Math.round(ctx.view.k * 100) + " percent");
+  }
+
+  function placeHeaders(): void {
+    const cols = els.cols;
+    if (!cols.firstChild) {
+      model.columns.forEach((c, i) => { const h = el("div", "hd"); h.textContent = (c.short ?? c.title).toUpperCase(); h.title = c.title; h.dataset.i = String(i); cols.appendChild(h); });
+      let i = 0;
+      while (i < model.columns.length) {
+        const name = model.columns[i]?.phase;
+        let j = i;
+        while (j + 1 < model.columns.length && model.columns[j + 1]?.phase === name) j++;
+        if (name) { const p = el("div", "ph"); p.innerHTML = "<span></span><i></i>"; (p.firstElementChild as HTMLElement).textContent = name; p.dataset.a = String(i); p.dataset.b = String(j); cols.appendChild(p); }
+        i = j + 1;
+      }
+    }
+    const v = ctx.view, xs = ctx.geom.xs;
+    cols.querySelectorAll<HTMLElement>(".hd").forEach(h => { const i = +(h.dataset.i ?? 0); h.style.left = v.x + (xs[i] ?? 0) * v.k + "px"; h.style.width = Math.max(0, (model.columns[i]?.width ?? 0) * v.k - 6) + "px"; });
+    cols.querySelectorAll<HTMLElement>(".ph").forEach(p => {
+      const a = +(p.dataset.a ?? 0), b = +(p.dataset.b ?? 0);
+      p.style.left = v.x + (xs[a] ?? 0) * v.k + "px";
+      p.style.width = Math.max(40, ((xs[b] ?? 0) + (model.columns[b]?.width ?? 0) - (xs[a] ?? 0)) * v.k) + "px";
+    });
+  }
+
+  function stickLabels(): void {
+    const wl = (52 - ctx.view.x) / ctx.view.k;
+    for (const l of model.lanes) {
+      const r = ctx.geom.lanes[l.id], d = ctx.laneEls.get(l.id);
+      if (!r || !d?.firstElementChild) continue;
+      (d.firstElementChild as HTMLElement).style.left = Math.min(Math.max(12, wl - r.x), Math.max(12, r.w - 300)) + "px";
+    }
+  }
+
+  // ---- pointer: drag the background (or any spot with the hand tool, Space, or the middle button) to pan; pinch to zoom
+  const pointers = new Map<number, { x: number; y: number }>();
+  let drag: { x: number; y: number; vx: number; vy: number } | null = null;
+  let pinch: { d: number; view: View } | null = null;
+
+  on(ctx, vp, "pointerdown", (e: PointerEvent) => {
+    if ((e.target as HTMLElement).closest("#tools, .bandlabel")) return;
+    pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+    ctx.moved = 0;
+    if (pointers.size === 2) {
+      const [a, b] = [...pointers.values()] as [{ x: number; y: number }, { x: number; y: number }];
+      pinch = { d: Math.hypot(a.x - b.x, a.y - b.y), view: { ...ctx.view } };
+      drag = null;
+      return;
+    }
+    const onNode = !!(e.target as HTMLElement).closest(".node");
+    if (e.button === 1 || ctx.tool === "hand" || ctx.spaceDown || !onNode) {
+      drag = { x: e.clientX, y: e.clientY, vx: ctx.view.x, vy: ctx.view.y };
+      try { vp.setPointerCapture(e.pointerId); } catch { /* a synthetic pointer cannot be captured */ }
+      vp.classList.add("panning");
+      if (e.button === 1) e.preventDefault();
+    }
+  });
+  on(ctx, vp, "pointermove", (e: PointerEvent) => {
+    if (pointers.has(e.pointerId)) pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+    if (pinch && pointers.size === 2) {
+      const [a, b] = [...pointers.values()] as [{ x: number; y: number }, { x: number; y: number }];
+      const d = Math.hypot(a.x - b.x, a.y - b.y), r = vpRect;
+      ctx.userMoved = true;
+      setView(zoomAt(pinch.view, d / pinch.d, (a.x + b.x) / 2 - r.left, (a.y + b.y) / 2 - r.top), false);
+      return;
+    }
+    if (!drag) return;
+    const dx = e.clientX - drag.x, dy = e.clientY - drag.y;
+    ctx.moved = Math.max(ctx.moved, Math.hypot(dx, dy));
+    if (ctx.moved > 4) { ctx.userMoved = true; setView({ k: ctx.view.k, x: drag.vx + dx, y: drag.vy + dy }, false); }
+  });
+  const endDrag = (e: PointerEvent) => {
+    pointers.delete(e.pointerId);
+    if (pointers.size < 2) pinch = null;
+    if (drag) {
+      drag = null;
+      vp.classList.remove("panning");
+      try { vp.releasePointerCapture(e.pointerId); } catch { /* not captured */ }
+      window.setTimeout(() => { ctx.moved = 0; }, 0);
+    }
+  };
+  on(ctx, vp, "pointerup", endDrag);
+  on(ctx, vp, "pointercancel", endDrag);
+  on(ctx, vp, "wheel", (e: WheelEvent) => {
+    e.preventDefault();
+    const r = vpRect, unit = e.deltaMode === 1 ? 16 : 1;
+    ctx.userMoved = true;
+    setView(zoomAt(ctx.view, Math.exp(-e.deltaY * unit * (e.ctrlKey ? 0.01 : 0.0012)), e.clientX - r.left, e.clientY - r.top), false);
+  }, { passive: false });
+  on(ctx, vp, "dblclick", (e: MouseEvent) => { if (!(e.target as HTMLElement).closest(".node, .bandlabel, #tools")) { ctx.userMoved = false; fit(true); } });
+  on(ctx, vp, "click", (e: MouseEvent) => { if (!(e.target as HTMLElement).closest(".node, .bandlabel, #tools") && ctx.moved <= 4) ctx.fn.select(null); });
+
+  const ro = new ResizeObserver(() => { cached = { w: vp.clientWidth, h: vp.clientHeight }; refreshRect(); if (!ctx.userMoved) fitW(false); else setView(ctx.view, false); });
+  ro.observe(vp);
+  on(ctx, vp, "pointerenter", refreshRect);
+  on(ctx, window, "scroll", refreshRect, { passive: true });
+  ctx.disposers.push(() => ro.disconnect());
+
+  // ---- tools
+  function setTool(id: "select" | "hand"): void {
+    ctx.tool = id;
+    vp.classList.toggle("hand", id === "hand");
+    els.tools.querySelectorAll<HTMLElement>("[data-id='select'], [data-id='hand']").forEach(b => b.setAttribute("aria-pressed", String(b.dataset.id === id)));
+    ctx.fn.announce(id === "hand" ? "Hand tool: drag to pan" : "Select tool");
+  }
+  function toggleFull(): void {
+    const ws = els.workspace;
+    if (document.fullscreenElement) void document.exitFullscreen();
+    else if (ws.requestFullscreen) ws.requestFullscreen().catch(() => ws.classList.toggle("fs"));
+    else ws.classList.toggle("fs");
+  }
+  type Tool = [string, string, "tool" | "full" | (() => void)] | ["-"];
+  const TOOLS: Tool[] = [
+    ["select", "Select (V)", "tool"], ["hand", "Hand: drag to pan (H)", "tool"], ["-"],
+    ["plus", "Zoom in (+)", () => zoomBy(1.25)], ["minus", "Zoom out (-)", () => zoomBy(1 / 1.25)],
+    ["fit", "Fit to screen (0)", () => { ctx.userMoved = false; fit(true); ctx.fn.announce("Fit to screen"); }],
+    ["one", "Actual size (1)", () => { const s = size(); ctx.userMoved = true; setView(zoomAt(ctx.view, 1 / ctx.view.k, s.w / 2, s.h / 2), true); }],
+    ["sel", "Zoom to selection (F)", () => ctx.fn.zoomToPath()], ["-"],
+    ["full", "Fullscreen", "full"],
+  ];
+  els.tools.innerHTML = "";
+  for (const t of TOOLS) {
+    if (t[0] === "-") { els.tools.appendChild(el("div", "sep")); continue; }
+    const [id, label, act] = t as [string, string, "tool" | "full" | (() => void)];
+    const b = el("button", "tb", `<svg viewBox="0 0 24 24" aria-hidden="true">${ICON[id] ?? ""}</svg>`);
+    b.type = "button"; b.title = label; b.setAttribute("aria-label", label); b.dataset.id = id;
+    if (act === "tool") { b.setAttribute("aria-pressed", String(ctx.tool === id)); on(ctx, b, "click", () => setTool(id as "select" | "hand")); }
+    else if (act === "full") on(ctx, b, "click", toggleFull);
+    else on(ctx, b, "click", act);
+    els.tools.appendChild(b);
+  }
+  requestAnimationFrame(() => { const r = els.tools.getBoundingClientRect(), v = vp.getBoundingClientRect(); els.zoom.style.top = r.bottom - v.top + 6 + "px"; });
+  on(ctx, document, "fullscreenchange", () => window.setTimeout(() => { if (!ctx.userMoved) fitW(false); }, 60));
+
+  // ---- keys
+  on(ctx, document, "keydown", (e: KeyboardEvent) => {
+    const typing = !!e.target && /INPUT|TEXTAREA/.test((e.target as HTMLElement).tagName);
+    if (typing) { if (e.key === "Escape") (e.target as HTMLElement).blur(); return; }
+    if (e.ctrlKey || e.metaKey || e.altKey) return; // never hijack Ctrl+F, Ctrl+N, Ctrl+plus and the like
+    if (e.key === " " && document.activeElement === vp) { ctx.spaceDown = true; e.preventDefault(); vp.classList.add("hand"); return; }
+    const k = e.key, step = e.shiftKey ? 240 : 60;
+    if (k === "/") { e.preventDefault(); els.q.focus(); }
+    else if (k === "n" || k === "N") ctx.fn.toggleNotes();
+    else if (k === "v" || k === "V") setTool("select");
+    else if (k === "h" || k === "H") setTool("hand");
+    else if (k === "+" || k === "=") zoomBy(1.25);
+    else if (k === "-" || k === "_") zoomBy(1 / 1.25);
+    else if (k === "0") { ctx.userMoved = false; fit(true); }
+    else if (k === "1") { const s = size(); ctx.userMoved = true; setView(zoomAt(ctx.view, 1 / ctx.view.k, s.w / 2, s.h / 2), true); }
+    else if (k === "f" || k === "F") ctx.fn.zoomToPath();
+    else if (k.startsWith("Arrow") && (document.activeElement === vp || document.activeElement === document.body)) {
+      e.preventDefault();
+      ctx.userMoved = true;
+      setView({ k: ctx.view.k, x: ctx.view.x + (k === "ArrowLeft" ? step : k === "ArrowRight" ? -step : 0), y: ctx.view.y + (k === "ArrowUp" ? step : k === "ArrowDown" ? -step : 0) }, false);
+    } else if (k === "Escape") ctx.fn.escape();
+  });
+  on(ctx, document, "keyup", (e: KeyboardEvent) => { if (e.key === " ") { ctx.spaceDown = false; if (ctx.tool !== "hand") vp.classList.remove("hand"); } });
+
+  ctx.fn.setView = setView;
+  ctx.fn.fit = fit;
+  ctx.fn.fitWidth = fitW;
+  ctx.fn.zoomBy = zoomBy;
+  ctx.fn.stickLabels = stickLabels;
+  ctx.fn.placeHeaders = placeHeaders;
+}

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

@@ -0,0 +1,118 @@
+// The engine's shared state. Each DOM module receives one Ctx, reads and writes it, and registers
+// its functions on ctx.fn, so modules call each other without importing each other.
+
+import type { Model, NodeDef, LinkDef, NoteDef } from "./model.ts";
+import type { View, Rect } from "./viewport.ts";
+import type { Geometry } from "./layout.ts";
+
+export interface Els {
+  vp: HTMLElement;
+  world: HTMLElement;
+  svg: SVGSVGElement;
+  layer: SVGGElement;
+  cols: HTMLElement;
+  tools: HTMLElement;
+  zoom: HTMLElement;
+  inspector: HTMLElement;
+  workspace: HTMLElement;
+  live: HTMLElement;
+  strip: HTMLElement;
+  tiles: HTMLElement;
+  legend: HTMLElement;
+  ledger: HTMLElement;
+  table: HTMLElement;
+  q: HTMLInputElement;
+  matchinfo: HTMLElement;
+  modeSwitch: HTMLElement;
+  drawer: HTMLElement;
+  notelist: HTMLElement;
+  notesBtn: HTMLElement;
+  theme: HTMLElement;
+  specbody: HTMLElement;
+  spec: HTMLElement;
+  title: HTMLElement;
+  readat: HTMLElement;
+  help: HTMLElement;
+  footer: HTMLElement;
+}
+
+export type Filter = "gap" | "upgrade" | null;
+
+export interface Fns {
+  paint(fromSwitch?: boolean): void;
+  buildWorld(): void;
+  trace(id: string | null): void;
+  select(id: string | null): void;
+  renderInspector(): void;
+  setView(v: View, animate?: boolean): void;
+  fit(animate?: boolean, rect?: Rect, inset?: number): void;
+  fitWidth(animate?: boolean): void;
+  zoomBy(factor: number): void;
+  zoomToPath(): void;
+  zoomToBand(id: string): void;
+  rectOf(ids: string[]): Rect | null;
+  drawTrail(): void;
+  simulate(actionId: string): void;
+  clearSim(): void;
+  announce(text: string): void;
+  stickLabels(): void;
+  placeHeaders(): void;
+  buildChrome(): void;
+  toggleNotes(on?: boolean): void;
+  placeMarkers(): void;
+  escape(): void;
+  setMode(id: string): void;
+}
+
+export interface Ctx {
+  model: Model;
+  root: ParentNode;
+  els: Els;
+  notes: NoteDef[];
+  nodes: Map<string, NodeDef>;
+  links: LinkDef[];
+  geom: Geometry;
+  view: View;
+  reduced: boolean;
+  mode: string;
+  selected: string | null;
+  hl: string | null;
+  query: string;
+  filter: Filter;
+  tool: "select" | "hand";
+  spaceDown: boolean;
+  userMoved: boolean;
+  dismissed: boolean;
+  simActive: boolean;
+  moved: number;
+  nodeEls: Map<string, HTMLElement>;
+  laneEls: Map<string, HTMLElement>;
+  edgeEls: SVGPathElement[];
+  labelEls: HTMLElement[];
+  overlays: SVGPathElement[];
+  simTimers: number[];
+  disposers: Array<() => void>;
+  fn: Fns;
+}
+
+export const SVG_NS = "http://www.w3.org/2000/svg";
+
+/** Make an element with a class and (trusted, already escaped) inner HTML. */
+export function el<K extends keyof HTMLElementTagNameMap>(tag: K, cls?: string, html?: string): HTMLElementTagNameMap[K] {
+  const e = document.createElement(tag);
+  if (cls) e.className = cls;
+  if (html !== undefined) e.innerHTML = html;
+  return e;
+}
+
+export function sv(tag: string, attrs: Record<string, string>): SVGElement {
+  const e = document.createElementNS(SVG_NS, tag);
+  for (const k of Object.keys(attrs)) e.setAttribute(k, attrs[k] as string);
+  return e;
+}
+
+/** Listen on a target and remember how to stop, so destroy() removes every listener. */
+export function on<T extends EventTarget>(ctx: Ctx, target: T, type: string, fn: (e: any) => void, opts?: AddEventListenerOptions): void {
+  target.addEventListener(type, fn, opts);
+  ctx.disposers.push(() => target.removeEventListener(type, fn, opts));
+}