@caddis/cli 0.4.43 → 0.4.45

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

@@ -0,0 +1,107 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { validateModel, esc, type Model } from "./model.ts";
+
+const base = (): Model => ({
+  version: 1,
+  meta: { title: "T", help: "h", asOf: "2026-01-01", source: "s" },
+  layout: "columns-lanes",
+  columns: [{ id: "c0", title: "A", width: 150 }, { id: "c1", title: "B", width: 150 }],
+  lanes: [{ id: "l1", title: "Lane 1" }],
+  states: { ok: { word: "OK", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" } },
+  nodes: [
+    { id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "ok", title: "A" },
+    { id: "b", kind: "card", lane: "l1", col: 1, row: 0, state: "ok", title: "B" },
+  ],
+  links: [{ id: "a-b", from: "a", to: "b", state: "ok" }],
+});
+const codes = (m: unknown) => validateModel(m).filter(i => i.level === "error").map(i => i.code);
+
+test("a valid model has no errors", () => assert.deepEqual(codes(base()), []));
+test("not an object", () => assert.deepEqual(codes(null), ["model-shape"]));
+test("link to a missing node names the link", () => {
+  const m = base(); m.links[0]!.to = "zzz";
+  const issues = validateModel(m);
+  assert.ok(issues.some(i => i.code === "link-endpoint" && i.where === "links[a-b]"));
+});
+test("duplicate node id", () => { const m = base(); m.nodes[1]!.id = "a"; assert.ok(codes(m).includes("node-duplicate")); });
+test("undefined state on a node", () => { const m = base(); m.nodes[0]!.state = "nope"; assert.ok(codes(m).includes("state-undefined")); });
+test("node in an unknown lane", () => { const m = base(); m.nodes[0]!.lane = "zz"; assert.ok(codes(m).includes("lane-undefined")); });
+test("column out of range", () => { const m = base(); m.nodes[0]!.col = 5; assert.ok(codes(m).includes("column-range")); });
+test("colSpan that runs past the last column", () => { const m = base(); m.nodes[1]!.colSpan = 3; assert.ok(codes(m).includes("column-range")); });
+test("two nodes in the same cell overlap", () => {
+  const m = base(); m.nodes[1]!.col = 0; m.links = [];
+  assert.ok(codes(m).includes("cell-overlap"));
+});
+test("rows less than one apart in the same column overlap", () => {
+  const m = base(); m.nodes[1]!.col = 0; m.nodes[1]!.row = 0.5;
+  assert.ok(codes(m).includes("cell-overlap"));
+});
+test("an orphan node is an error unless allowed", () => {
+  const m = base(); m.links = [];
+  assert.equal(codes(m).filter(c => c === "orphan").length, 2);
+  m.nodes[0]!.allowIsolated = true; m.nodes[1]!.allowIsolated = true;
+  assert.deepEqual(codes(m), []);
+});
+test("a chip must point at a real node", () => {
+  const m = base(); m.nodes.push({ id: "c", kind: "chip", lane: "l1", col: 0, row: 1, state: "ok", title: "c", ref: "zzz" });
+  assert.ok(codes(m).includes("chip-ref"));
+});
+test("empty model is reported, not thrown", () => {
+  const m = base(); m.nodes = []; m.links = [];
+  const issues = validateModel(m);
+  assert.ok(issues.some(i => i.code === "model-empty"));
+});
+test("duplicate link id", () => { const m = base(); m.links.push({ ...m.links[0]! }); assert.ok(codes(m).includes("link-duplicate")); });
+test("a state with an unknown tone is rejected", () => {
+  const m = base(); (m.states.ok as any).tone = "purple";
+  assert.ok(codes(m).includes("state-shape"));
+});
+test("only the columns-lanes layout exists in this stage", () => {
+  const m = base(); (m as any).layout = "free";
+  assert.ok(codes(m).includes("layout-unsupported"));
+});
+test("a link that goes backward or sideways is a warning, not silence", () => {
+  const m = base(); m.links[0]!.from = "b"; m.links[0]!.to = "a";
+  const issues = validateModel(m);
+  assert.ok(issues.some(i => i.level === "warn" && i.code === "link-direction" && i.where === "links[a-b]"));
+  assert.deepEqual(codes(m), []);
+});
+test("a forward link has no direction warning", () => {
+  assert.ok(!validateModel(base()).some(i => i.code === "link-direction"));
+});
+test("a model with no meta is an error, not a crash later", () => {
+  const m = base(); delete (m as any).meta;
+  assert.ok(codes(m).includes("meta-missing"));
+});
+test("a node row that is not a finite number is an error (it would draw NaN)", () => {
+  const m = base(); (m.nodes[0] as any).row = "zero"; (m.nodes[1] as any).row = NaN;
+  assert.equal(codes(m).filter(c => c === "row-invalid").length, 2);
+});
+test("a node that is not an object is reported, never thrown (review focus 1)", () => {
+  const m = base(); (m.nodes as any[]).push(null, 7, "x");
+  assert.doesNotThrow(() => validateModel(m));
+  assert.equal(codes(m).filter(c => c === "node-shape").length, 3);
+});
+test("a link that is not an object is reported, never thrown", () => {
+  const m = base(); (m.links as any[]).push(null);
+  assert.doesNotThrow(() => validateModel(m));
+  assert.ok(codes(m).includes("link-shape"));
+});
+test("a node id that is not a string is an error", () => {
+  const m = base(); (m.nodes[0] as any).id = 5;
+  assert.ok(codes(m).includes("node-shape"));
+});
+test("lanes that are not an array do not make the validator throw", () => {
+  const m = base(); (m as any).lanes = "abc";
+  assert.doesNotThrow(() => validateModel(m));
+  assert.ok(codes(m).includes("lanes-missing"));
+});
+test("a state id must be usable as a CSS class", () => {
+  const m = base(); m.states['bad id"'] = m.states.ok!;
+  assert.ok(codes(m).includes("state-id"));
+});
+test("esc turns markup into text", () => {
+  assert.equal(esc(`<img src=x onerror="a()">&'`), "&lt;img src=x onerror=&quot;a()&quot;&gt;&amp;&#39;");
+  assert.equal(esc(undefined), "");
+});

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

@@ -0,0 +1,165 @@
+// The model: what an author writes. Pure types plus validation. No DOM.
+
+export type Kind = "card" | "group" | "chip" | "gateway" | "start" | "end" | "event" | "placeholder" | "note";
+export type Tone = "ok" | "warn" | "crit" | "info" | "muted" | "accent";
+export type Border = "solid" | "dashed" | "dotted";
+export type EdgeStyle = "flow" | "dash" | "dash-short" | "dot";
+export type Motion = "flow" | "flow-slow" | "breathe" | "none";
+export type Bucket = "good" | "neutral" | "gap";
+
+export interface StateDef {
+  word: string;
+  tone: Tone;
+  border: Border;
+  edge: EdgeStyle;
+  motion: Motion;
+  bucket: Bucket;
+}
+export interface ColumnDef { id: string; title: string; short?: string; width: number; phase?: string }
+export interface LaneDef { id: string; title: string; badge?: string; badgeTone?: "ok" | "warn" | "muted"; note?: string; gap?: boolean }
+export interface NodeDef {
+  id: string;
+  kind: Kind;
+  lane: string;
+  col: number;
+  colSpan?: number;
+  row: number;
+  state: string;
+  stateIn?: Record<string, string>;
+  visibleIn?: string[];
+  title: string;
+  subtitle?: string;
+  members?: string[];
+  weight?: number;
+  ref?: string;
+  upgrade?: string;
+  allowIsolated?: boolean;
+}
+export interface LinkDef {
+  id: string;
+  from: string;
+  to: string;
+  state: string;
+  stateIn?: Record<string, string>;
+  visibleIn?: string[];
+  label?: string;
+}
+export interface ViewDef { id: string; label: string; default?: boolean }
+export interface RelationDef { id: string; label: string; dir: "up" | "down"; filter?: { col?: number; kind?: Kind } }
+export interface ActionDef { id: string; label: string; dir: "down"; staleText: string }
+export interface NoteDef { anchor: string; title: string; text: string }
+export interface Model {
+  version: 1;
+  meta: { title: string; help: string; asOf: string; source: string; labels?: Record<string, string> };
+  layout: "columns-lanes";
+  columns: ColumnDef[];
+  lanes: LaneDef[];
+  states: Record<string, StateDef>;
+  nodes: NodeDef[];
+  links: LinkDef[];
+  views?: ViewDef[];
+  inspector?: { relations: RelationDef[]; actions?: ActionDef[] };
+  notes?: NoteDef[];
+}
+export interface Issue { level: "error" | "warn"; code: string; where: string; message: string }
+
+const TONES = ["ok", "warn", "crit", "info", "muted", "accent"];
+const BORDERS = ["solid", "dashed", "dotted"];
+const EDGES = ["flow", "dash", "dash-short", "dot"];
+const MOTIONS = ["flow", "flow-slow", "breathe", "none"];
+const BUCKETS = ["good", "neutral", "gap"];
+
+/** Turns a value into text that is safe inside HTML. Use it for every model string put into markup. */
+export function esc(s: unknown): string {
+  const map: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+  return String(s ?? "").replace(/[&<>"']/g, c => map[c] as string);
+}
+
+/** Checks a model and returns every problem. Never throws. An error blocks the build; a warning does not. */
+export function validateModel(input: unknown): Issue[] {
+  const out: Issue[] = [];
+  const add = (level: Issue["level"], code: string, where: string, message: string) => out.push({ level, code, where, message });
+  if (!input || typeof input !== "object") {
+    add("error", "model-shape", "model", "The model must be a JSON object.");
+    return out;
+  }
+  const m = input as Model;
+  if (m.version !== 1) add("error", "model-version", "version", "version must be 1.");
+  if (m.layout !== "columns-lanes") add("error", "layout-unsupported", "layout", `layout ${String(m.layout)} is not supported yet: use "columns-lanes" ("free" and "auto" arrive in a later stage).`);
+  if (!Array.isArray(m.columns) || m.columns.length === 0) add("error", "columns-missing", "columns", "At least one column is required.");
+  if (!Array.isArray(m.lanes) || m.lanes.length === 0) add("error", "lanes-missing", "lanes", "At least one lane is required.");
+  if (!m.states || typeof m.states !== "object" || Object.keys(m.states).length === 0) add("error", "states-missing", "states", "At least one state is required.");
+  const columns = Array.isArray(m.columns) ? m.columns : [];
+  const lanes = Array.isArray(m.lanes) ? m.lanes : [];
+  const states = m.states && typeof m.states === "object" ? m.states : {};
+  if (!m.meta || typeof m.meta !== "object" || typeof m.meta.title !== "string") add("error", "meta-missing", "meta", "meta with a title is required.");
+  // Entries that are not objects are reported and dropped, so no later loop can throw on them.
+  const nodes: NodeDef[] = [];
+  (Array.isArray(m.nodes) ? m.nodes : []).forEach((n, i) => {
+    if (!n || typeof n !== "object" || typeof (n as NodeDef).id !== "string") add("error", "node-shape", `nodes[${i}]`, "A node must be an object with a string id.");
+    else nodes.push(n);
+  });
+  const links: LinkDef[] = [];
+  (Array.isArray(m.links) ? m.links : []).forEach((l, i) => {
+    if (!l || typeof l !== "object" || typeof (l as LinkDef).id !== "string") add("error", "link-shape", `links[${i}]`, "A link must be an object with a string id.");
+    else links.push(l);
+  });
+  if (nodes.length === 0) add("warn", "model-empty", "nodes", "The model has no nodes.");
+
+  for (const [id, s] of Object.entries(states)) {
+    if (!/^[A-Za-z0-9_-]+$/.test(id)) add("error", "state-id", `states[${id}]`, `State id ${id} may only use letters, digits, "_" and "-" (it becomes a CSS class).`);
+    const ok = s && typeof s.word === "string" && TONES.includes(s.tone) && BORDERS.includes(s.border) && EDGES.includes(s.edge) && MOTIONS.includes(s.motion) && BUCKETS.includes(s.bucket);
+    if (!ok) add("error", "state-shape", `states[${id}]`, `State ${id} needs word, tone, border, edge, motion and bucket with allowed values.`);
+  }
+  const laneIds = new Set(lanes.map(l => l.id));
+  const stateIds = new Set(Object.keys(states));
+  const nodeIds = new Set<string>();
+  const ncols = columns.length;
+  for (const n of nodes) {
+    const w = `nodes[${n.id}]`;
+    if (nodeIds.has(n.id)) add("error", "node-duplicate", w, `Duplicate node id ${n.id}.`);
+    nodeIds.add(n.id);
+    if (!laneIds.has(n.lane)) add("error", "lane-undefined", w, `Lane ${n.lane} is not defined.`);
+    for (const s of [n.state, ...Object.values(n.stateIn ?? {})]) if (!stateIds.has(s)) add("error", "state-undefined", w, `State ${s} is not defined.`);
+    if (typeof n.row !== "number" || !Number.isFinite(n.row)) add("error", "row-invalid", w, `Node ${n.id} needs a finite number for row (it sets the vertical position).`);
+    const span = n.colSpan ?? 1;
+    if (!Number.isInteger(n.col) || n.col < 0 || n.col + span > ncols) add("error", "column-range", w, `Column ${n.col} with span ${span} is outside 0..${ncols - 1}.`);
+  }
+  for (const n of nodes) {
+    if (n.kind === "chip" && (!n.ref || !nodeIds.has(n.ref))) add("error", "chip-ref", `nodes[${n.id}]`, `A chip must point at a real node (ref ${n.ref}).`);
+  }
+  const linkIds = new Set<string>();
+  const linked = new Set<string>();
+  for (const l of links) {
+    const w = `links[${l.id}]`;
+    if (linkIds.has(l.id)) add("error", "link-duplicate", w, `Duplicate link id ${l.id}.`);
+    linkIds.add(l.id);
+    if (!nodeIds.has(l.from) || !nodeIds.has(l.to)) add("error", "link-endpoint", w, `Link ${l.id} has an endpoint that is not a node (${l.from} to ${l.to}).`);
+    else {
+      linked.add(l.from); linked.add(l.to);
+      const a = nodes.find(n => n.id === l.from)!, b = nodes.find(n => n.id === l.to)!;
+      if (b.col <= a.col + (a.colSpan ?? 1) - 1) {
+        add("warn", "link-direction", w, `Link ${l.id} does not run left to right (column ${a.col} to ${b.col}); it will look wrong until loop-back links arrive.`);
+      }
+    }
+    for (const s of [l.state, ...Object.values(l.stateIn ?? {})]) if (!stateIds.has(s)) add("error", "state-undefined", w, `State ${s} is not defined.`);
+  }
+  for (const n of nodes) {
+    if (!linked.has(n.id) && !n.allowIsolated && n.kind !== "note") {
+      add("error", "orphan", `nodes[${n.id}]`, `Node ${n.id} has no links. Add a link, a placeholder neighbour, or set allowIsolated.`);
+    }
+  }
+  // Columns and rows are global to the canvas, so two nodes clash whatever their lane.
+  for (let i = 0; i < nodes.length; i++) {
+    for (let j = i + 1; j < nodes.length; j++) {
+      const a = nodes[i]!, b = nodes[j]!;
+      const ax2 = a.col + (a.colSpan ?? 1), bx2 = b.col + (b.colSpan ?? 1);
+      if (a.col < bx2 && b.col < ax2 && Math.abs(a.row - b.row) < 1) {
+        add("error", "cell-overlap", `nodes[${a.id}]`, `Nodes ${a.id} and ${b.id} overlap (same columns, rows less than 1 apart).`);
+      }
+    }
+  }
+  const used = new Set(nodes.map(n => n.lane));
+  for (const l of lanes) if (!used.has(l.id)) add("warn", "lane-empty", `lanes[${l.id}]`, `Lane ${l.id} has no nodes.`);
+  return out;
+}

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

@@ -0,0 +1,92 @@
+// Implementation notes (a left drawer with numbered markers on the page) and the model reference
+// section with Copy as Markdown and Copy JSON. The notes are for the person or agent who builds the page.
+
+import { el, on, type Ctx } from "./ctx.ts";
+import { esc } from "./model.ts";
+
+export function install(ctx: Ctx): void {
+  const { els, model } = ctx;
+  const notes = ctx.notes.map((n, i) => ({ id: i + 1, ...n }));
+
+  const card = (id: number) => els.notelist.querySelector<HTMLElement>(`[data-n="${id}"]`);
+  const anchorOf = (sel: string): Element | null => { try { return document.querySelector(sel); } catch { return null; } };
+
+  function clearMarkers(): void {
+    document.querySelectorAll(".marker").forEach(m => m.remove());
+    document.querySelectorAll(".anchored").forEach(a => a.classList.remove("anchored"));
+  }
+
+  function placeMarkers(): void {
+    clearMarkers();
+    for (const n of notes) {
+      const a = anchorOf(n.anchor);
+      if (!a) continue;
+      let r = a.getBoundingClientRect();
+      if (!r.width && !r.height) continue;
+      if (a.id === "inspector" && !a.classList.contains("open")) {
+        const vr = els.vp.getBoundingClientRect();
+        r = { left: vr.right - 130, top: vr.top + 56, right: vr.right - 128, bottom: vr.top + 58, width: 2, height: 2, x: 0, y: 0, toJSON: () => ({}) };
+      }
+      const v = els.vp.getBoundingClientRect();
+      if (a.closest("#world") && (r.right < v.left || r.left > v.right || r.bottom < v.top || r.top > v.bottom)) continue;
+      const m = el("button", "marker", String(n.id));
+      m.type = "button"; m.dataset.n = String(n.id); m.title = n.title;
+      m.setAttribute("aria-label", `Note ${n.id}: ${n.title}`);
+      m.style.left = r.left + scrollX - 10 + "px";
+      m.style.top = r.top + scrollY - 10 + "px";
+      m.addEventListener("mouseenter", () => { a.classList.add("anchored"); card(n.id)?.classList.add("on"); });
+      m.addEventListener("mouseleave", () => { a.classList.remove("anchored"); card(n.id)?.classList.remove("on"); });
+      m.addEventListener("click", () => card(n.id)?.scrollIntoView({ block: "center", behavior: ctx.reduced ? "auto" : "smooth" }));
+      document.body.appendChild(m);
+    }
+  }
+
+  function toggleNotes(next?: boolean): void {
+    const on_ = next === undefined ? !document.body.classList.contains("notes") : next;
+    document.body.classList.toggle("notes", on_);
+    els.notesBtn.setAttribute("aria-pressed", String(on_));
+    if (on_) window.setTimeout(placeMarkers, ctx.reduced ? 30 : 340);
+    else clearMarkers();
+  }
+
+  els.notelist.innerHTML = notes.map(n => `<div class="ncard" data-n="${n.id}"><b><span>${n.id}</span>${esc(n.title)}</b>${esc(n.text)}</div>`).join("")
+    || '<p class="note">This page has no implementation notes.</p>';
+  els.notelist.querySelectorAll<HTMLElement>(".ncard").forEach(c => {
+    c.addEventListener("mouseenter", () => { const n = notes.find(x => String(x.id) === c.dataset.n); const a = n && anchorOf(n.anchor); if (a) a.classList.add("anchored"); });
+    c.addEventListener("mouseleave", () => document.querySelectorAll(".anchored").forEach(a => a.classList.remove("anchored")));
+  });
+  on(ctx, els.notesBtn, "click", () => toggleNotes());
+  on(ctx, window, "scroll", () => { if (document.body.classList.contains("notes")) placeMarkers(); }, { passive: true });
+
+  // ---- model reference
+  const markdown = (): string => {
+    const out = [`# ${model.meta.title}`, "", model.meta.help, "", `As of ${model.meta.asOf}. Source: ${model.meta.source}`, "", "## States"];
+    for (const [id, s] of Object.entries(model.states)) out.push(`- **${s.word}** (${id}): tone ${s.tone}, border ${s.border}, link ${s.edge}, motion ${s.motion}, bucket ${s.bucket}`);
+    out.push("", "## Columns", ...model.columns.map((c, i) => `${i + 1}. ${c.title}${c.phase ? ` (${c.phase})` : ""}`));
+    out.push("", "## Lanes", ...model.lanes.map(l => `- ${l.title}${l.badge ? ` [${l.badge}]` : ""}${l.note ? `: ${l.note}` : ""}`));
+    out.push("", `## Size`, `${model.nodes.length} nodes, ${model.links.length} links.`);
+    if (notes.length) out.push("", "## Notes", ...notes.map(n => `${n.id}. **${n.title}**: ${n.text}`));
+    return out.join("\n");
+  };
+  const rows = (items: string[]) => `<ul>${items.map(i => `<li>${i}</li>`).join("")}</ul>`;
+  els.specbody.innerHTML = `<div class="specbtns"><button type="button" id="cpMd">Copy as Markdown</button><button type="button" id="cpJson">Copy model JSON</button><span class="note" id="cpMsg" style="margin:0"></span></div>
+    <h3>States</h3>${rows(Object.entries(model.states).map(([id, s]) => `<b>${esc(s.word)}</b> (<code>${esc(id)}</code>): tone ${esc(s.tone)}, border ${esc(s.border)}, link ${esc(s.edge)}, motion ${esc(s.motion)}, bucket ${esc(s.bucket)}`))}
+    <h3>Columns</h3>${rows(model.columns.map(c => `${esc(c.title)}${c.phase ? ` (${esc(c.phase)})` : ""}`))}
+    <h3>Lanes</h3>${rows(model.lanes.map(l => `${esc(l.title)}${l.badge ? ` [${esc(l.badge)}]` : ""}${l.note ? `: ${esc(l.note)}` : ""}`))}
+    <h3>Size</h3><p>${model.nodes.length} nodes, ${model.links.length} links.</p>`;
+  const msg = (t: string) => { const m = document.getElementById("cpMsg"); if (m) m.textContent = t; };
+  const copy = async (text: string, what: string) => {
+    try { await navigator.clipboard.writeText(text); msg(`${what} copied.`); }
+    catch {
+      const ta = document.createElement("textarea");
+      ta.value = text; document.body.appendChild(ta); ta.select();
+      try { document.execCommand("copy"); msg(`${what} copied.`); } catch { msg("Copy is blocked here: select the text instead."); }
+      ta.remove();
+    }
+  };
+  document.getElementById("cpMd")?.addEventListener("click", () => void copy(markdown(), "Markdown"));
+  document.getElementById("cpJson")?.addEventListener("click", () => void copy(JSON.stringify(model, null, 2), "JSON"));
+
+  ctx.fn.toggleNotes = toggleNotes;
+  ctx.fn.placeMarkers = placeMarkers;
+}

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

@@ -0,0 +1,155 @@
+// Builds the world (lanes, nodes, links) once, and paints it for the current view.
+// Every model string goes through esc(), so a hostile title cannot become markup.
+
+import { el, sv, on, type Ctx } from "./ctx.ts";
+import { esc } from "./model.ts";
+import type { NodeDef } from "./model.ts";
+import { computeGeometry, DEFAULTS } from "./layout.ts";
+import { elbow } from "./routing.ts";
+import { cssId } from "./stateCss.ts";
+import { baselineView, bucketOf, canonOf, isImproved, isNew, linkStateId, linkVisible, nodeStateId, nodeVisible } from "./rules.ts";
+
+function nodeHtml(ctx: Ctx, n: NodeDef): string {
+  const m = ctx.model;
+  const sid = nodeStateId(m, ctx.mode, n);
+  const word = m.states[sid]?.word ?? sid;
+  const bucket = bucketOf(m, sid);
+  const sub = n.subtitle ?? m.columns[n.col]?.title ?? "";
+  const weight = Math.max(1, n.weight ?? 1);
+  const showWord = n.kind !== "placeholder" && n.kind !== "note";
+  const bar = weight > 1 && n.kind !== "chip"
+    ? `<div class="bar"><i class="${["good", "neutral", "gap"].includes(bucket) ? bucket : "gap"}" style="width:100%"></i></div>`
+    : "";
+  const improved = isImproved(m, ctx.mode, n) ? '<span class="cor up" title="Gap filled in this view">▲</span>' : "";
+  const upgrade = n.upgrade && bucket !== "good" ? `<span class="cor meas" title="${esc("Can improve: " + n.upgrade)}">↗</span>` : "";
+  const arrow = n.kind === "chip" ? '<span aria-hidden="true">↑ </span>' : "";
+  const lead = showWord ? `<b class="ev st-${cssId(sid)}">${esc(word)}</b> · ` : "";
+  return `<div class="t"><span class="newdot" title="Added in this view"></span><span class="name">${arrow}${esc(n.title)}</span></div>`
+    + `<div class="s" title="${esc(sub)}">${lead}${esc(sub)}</div>${bar}${improved}${upgrade}`;
+}
+
+function build(ctx: Ctx): void {
+  const { model, els } = ctx;
+  ctx.geom = computeGeometry(model);
+  els.world.style.width = ctx.geom.world.w + "px";
+  els.world.style.height = ctx.geom.world.h + "px";
+  els.svg.setAttribute("width", String(ctx.geom.world.w));
+  els.svg.setAttribute("height", String(ctx.geom.world.h));
+  els.world.querySelectorAll(".node, .band, .elabel").forEach(n => n.remove());
+  els.layer.innerHTML = "";
+  ctx.nodeEls.clear(); ctx.laneEls.clear(); ctx.edgeEls = []; ctx.labelEls = [];
+
+  for (const l of model.lanes) {
+    const d = el("div", "band" + (l.gap ? " gap" : ""));
+    d.id = "lane_" + l.id;
+    const badge = l.badge ? `<span class="bd t-${["ok", "warn", "muted"].includes(l.badgeTone ?? "") ? l.badgeTone : "muted"}">${esc(l.badge)}</span>` : "";
+    const note = l.note ? `<span class="bn">${esc(l.note)}</span>` : "";
+    d.innerHTML = `<div class="bandlabel" role="button" tabindex="0" aria-label="${esc("Zoom to the lane " + l.title)}"><b>${esc(l.title)}</b>${badge}${note}</div>`;
+    const label = d.firstElementChild as HTMLElement;
+    on(ctx, label, "click", (e: Event) => { e.stopPropagation(); ctx.fn.zoomToBand(l.id); });
+    on(ctx, label, "keydown", (e: KeyboardEvent) => { if (e.key === "Enter") ctx.fn.zoomToBand(l.id); });
+    els.world.insertBefore(d, els.svg.parentElement === els.world ? els.svg : null);
+    ctx.laneEls.set(l.id, d);
+  }
+
+  for (const n of model.nodes) {
+    const p = ctx.geom.nodes[n.id];
+    if (!p) continue;
+    const d = el("div", "node" + (n.kind === "chip" ? " ref" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : ""));
+    d.id = "n_" + n.id;
+    d.tabIndex = 0;
+    d.setAttribute("role", "button");
+    d.style.setProperty("--c", String(n.col));
+    d.style.left = p.x + "px"; d.style.top = p.y + "px"; d.style.width = p.w + "px"; d.style.height = p.h + "px";
+    on(ctx, d, "click", () => { if (ctx.moved > 4) return; ctx.fn.select(canonOf(ctx.nodes, n.id)); });
+    on(ctx, d, "dblclick", (e: Event) => { e.stopPropagation(); ctx.fn.select(canonOf(ctx.nodes, n.id)); ctx.fn.zoomToPath(); });
+    on(ctx, d, "keydown", (e: KeyboardEvent) => { if (e.key === "Enter" || e.key === " ") { e.preventDefault(); ctx.fn.select(canonOf(ctx.nodes, n.id)); } });
+    on(ctx, d, "mouseenter", () => ctx.fn.trace(n.id));
+    on(ctx, d, "mouseleave", () => ctx.fn.trace(ctx.selected));
+    on(ctx, d, "focus", () => ctx.fn.trace(n.id));
+    on(ctx, d, "blur", () => ctx.fn.trace(ctx.selected));
+    els.world.appendChild(d);
+    ctx.nodeEls.set(n.id, d);
+  }
+
+  const gap = DEFAULTS.gap;
+  ctx.links.forEach((l, i) => {
+    const A = ctx.geom.nodes[l.from], B = ctx.geom.nodes[l.to];
+    if (!A || !B) { console.warn(`flow-studio: link ${l.id} skipped (an end is missing)`); return; }
+    const x1 = A.x + A.w, y1 = A.y + A.h / 2, x2 = B.x, y2 = B.y + B.h / 2, tx = x1 + gap / 2;
+    const path = sv("path", { d: elbow(x1, y1, x2 - 1, y2, tx), class: "edge", "data-i": String(i), "data-a": l.from, "data-b": l.to, "marker-end": "url(#arr)" }) as SVGPathElement;
+    els.layer.appendChild(path);
+    ctx.edgeEls[i] = path;
+    if (l.label) {
+      const lab = el("div", "elabel", esc(l.label));
+      lab.dataset.i = String(i); lab.dataset.a = l.from; lab.dataset.b = l.to;
+      lab.style.left = (Math.abs(y2 - y1) < 1 ? (x1 + x2) / 2 : tx) + "px";
+      lab.style.top = (y1 + y2) / 2 + "px";
+      els.world.appendChild(lab);
+      ctx.labelEls[i] = lab;
+    }
+  });
+}
+
+function paint(ctx: Ctx, fromSwitch = false): void {
+  const { model } = ctx;
+  const mode = ctx.mode;
+  ctx.geom = computeGeometry(model, { visible: id => { const n = ctx.nodes.get(id); return !!n && nodeVisible(model, mode, n); } });
+  document.body.classList.toggle("alt", !!model.views && mode !== baselineView(model));
+
+  for (const n of model.nodes) {
+    const d = ctx.nodeEls.get(n.id);
+    if (!d) continue;
+    const sid = nodeStateId(model, mode, n);
+    const show = nodeVisible(model, mode, n);
+    const bucket = bucketOf(model, sid);
+    const cors = (isImproved(model, mode, n) ? 1 : 0) + (n.upgrade && bucket !== "good" ? 1 : 0);
+    const fresh = isNew(model, mode, n);
+    d.className = "node st-" + cssId(sid)
+      + (n.kind === "chip" ? " ref" : "") + ((n.colSpan ?? 1) > 1 ? " wide" : "") + (n.kind === "placeholder" ? " placeholder" : "")
+      + (show ? "" : " off") + (fresh ? " isnew" : "") + (cors ? (cors > 1 ? " hascor2" : " hascor") : "")
+      + (ctx.selected && canonOf(ctx.nodes, n.id) === ctx.selected ? " sel" : "");
+    d.innerHTML = nodeHtml(ctx, n);
+    d.setAttribute("aria-hidden", show ? "false" : "true");
+    d.tabIndex = show ? 0 : -1;
+    const word = model.states[sid]?.word ?? sid;
+    const lane = model.lanes.find(l => l.id === n.lane)?.title ?? n.lane;
+    d.setAttribute("aria-label", n.kind === "chip"
+      ? `${n.title}: a reference to the node in the ${lane} lane. Press Enter to select it.`
+      : `${n.title}. ${n.subtitle ?? model.columns[n.col]?.title ?? ""}, ${word}. Press Enter to inspect.`);
+    if (fromSwitch && fresh && !ctx.reduced) {
+      d.style.transitionDelay = n.col * 60 + "ms";
+      d.classList.add("pulse");
+      window.setTimeout(() => { d.style.transitionDelay = ""; d.classList.remove("pulse"); }, 2200);
+    } else {
+      d.style.transitionDelay = "";
+    }
+  }
+
+  ctx.links.forEach((l, i) => {
+    const p = ctx.edgeEls[i];
+    if (!p) return;
+    const vis = linkVisible(model, mode, l, ctx.nodes);
+    p.setAttribute("class", "edge st-" + cssId(linkStateId(model, mode, l)) + (vis ? "" : " off"));
+    ctx.labelEls[i]?.classList.toggle("off", !vis);
+  });
+
+  for (const l of model.lanes) {
+    const d = ctx.laneEls.get(l.id);
+    const r = ctx.geom.lanes[l.id];
+    if (!d) continue;
+    d.classList.toggle("off", !r);
+    if (r) { d.style.left = r.x + "px"; d.style.top = r.y + "px"; d.style.width = r.w + "px"; d.style.height = r.h + "px"; }
+  }
+
+  ctx.fn.buildChrome();
+  ctx.fn.trace(ctx.selected);
+  ctx.fn.renderInspector();
+  ctx.fn.stickLabels();
+  ctx.fn.placeHeaders();
+}
+
+export function install(ctx: Ctx): void {
+  ctx.fn.buildWorld = () => build(ctx);
+  ctx.fn.paint = (fromSwitch?: boolean) => paint(ctx, fromSwitch);
+}

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

@@ -0,0 +1,13 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { elbow } from "./routing.ts";
+
+test("same height is a straight line", () => assert.equal(elbow(0, 50, 100, 50, 50), "M0,50 H100"));
+test("a small vertical step is a gentle S curve", () => assert.equal(elbow(0, 50, 100, 60, 50), "M0,50 C50,50 50,60 100,60"));
+test("a large step is an elbow with a trunk at tx and rounded corners", () => {
+  assert.equal(elbow(0, 50, 100, 150, 40), "M0,50 H32 Q40,50 40,58 V142 Q40,150 48,150 H100");
+});
+test("going up mirrors the corners", () => {
+  assert.equal(elbow(0, 150, 100, 50, 40), "M0,150 H32 Q40,150 40,142 V58 Q40,50 48,50 H100");
+});
+test("every number in a path is finite", () => assert.ok(!/NaN|Infinity/.test(elbow(0, 0, 10, 300, 5))));

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

@@ -0,0 +1,11 @@
+// Link routing. A link leaves the right side of a node, runs to a vertical trunk at tx (half way
+// across the column gap), and enters the left side of the next node. It is horizontal where it
+// touches a node, so every arrowhead points right and the links of one node share one trunk.
+
+export function elbow(x1: number, y1: number, x2: number, y2: number, tx: number): string {
+  const r = 8;
+  if (Math.abs(y2 - y1) < 1) return `M${x1},${y1} H${x2}`;
+  if (Math.abs(y2 - y1) < 2 * r + 2) return `M${x1},${y1} C${tx},${y1} ${tx},${y2} ${x2},${y2}`;
+  const dir = y2 > y1 ? 1 : -1;
+  return `M${x1},${y1} H${tx - r} Q${tx},${y1} ${tx},${y1 + dir * r} V${y2 - dir * r} Q${tx},${y2} ${tx + r},${y2} H${x2}`;
+}

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

@@ -0,0 +1,88 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import type { Model } from "./model.ts";
+import { baselineView, defaultView, nodeVisible, nodeStateId, linkVisible, linkStateId, isNew, isImproved, bucketOf, canonOf } from "./rules.ts";
+
+const m = (): Model => ({
+  version: 1,
+  meta: { title: "t", help: "", asOf: "", source: "" },
+  layout: "columns-lanes",
+  columns: [{ id: "c0", title: "A", width: 150 }, { id: "c1", title: "B", width: 150 }],
+  lanes: [{ id: "l1", title: "L" }],
+  states: {
+    good: { word: "GOOD", tone: "ok", border: "solid", edge: "flow", motion: "flow", bucket: "good" },
+    gap: { word: "GAP", tone: "warn", border: "dotted", edge: "dot", motion: "breathe", bucket: "gap" },
+  },
+  views: [{ id: "today", label: "Today" }, { id: "full", label: "Full", default: true }],
+  nodes: [
+    { id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "good", title: "A" },
+    { id: "b", kind: "card", lane: "l1", col: 1, row: 0, state: "good", stateIn: { today: "gap" }, title: "B" },
+    { id: "c", kind: "card", lane: "l1", col: 1, row: 1.8, state: "good", visibleIn: ["full"], title: "C" },
+    { id: "k", kind: "chip", lane: "l1", col: 0, row: 3.6, state: "good", ref: "a", title: "k" },
+  ],
+  links: [
+    { id: "a-b", from: "a", to: "b", state: "good" },
+    { id: "a-c", from: "a", to: "c", state: "good", stateIn: { today: "gap" } },
+    { id: "only-today", from: "a", to: "b", state: "gap", visibleIn: ["today"] },
+  ],
+});
+const byId = (mm: Model) => new Map(mm.nodes.map(n => [n.id, n]));
+
+test("the baseline is the first view and the default is the marked one", () => {
+  assert.equal(baselineView(m()), "today");
+  assert.equal(defaultView(m()), "full");
+});
+test("a model with no views has one implicit view", () => {
+  const mm = m(); delete mm.views;
+  assert.equal(baselineView(mm), "all");
+  assert.equal(defaultView(mm), "all");
+  assert.equal(nodeVisible(mm, "all", mm.nodes[0]!), true);
+});
+test("visibleIn hides a node in other views", () => {
+  const mm = m();
+  assert.equal(nodeVisible(mm, "today", mm.nodes[2]!), false);
+  assert.equal(nodeVisible(mm, "full", mm.nodes[2]!), true);
+});
+test("stateIn overrides the state in that view only", () => {
+  const mm = m();
+  assert.equal(nodeStateId(mm, "today", mm.nodes[1]!), "gap");
+  assert.equal(nodeStateId(mm, "full", mm.nodes[1]!), "good");
+});
+test("a link is hidden when an end is hidden", () => {
+  const mm = m(), nodes = byId(mm);
+  assert.equal(linkVisible(mm, "today", mm.links[1]!, nodes), false);
+  assert.equal(linkVisible(mm, "full", mm.links[1]!, nodes), true);
+});
+test("visibleIn on a link restricts it to those views", () => {
+  const mm = m(), nodes = byId(mm);
+  assert.equal(linkVisible(mm, "today", mm.links[2]!, nodes), true);
+  assert.equal(linkVisible(mm, "full", mm.links[2]!, nodes), false);
+});
+test("a link state can differ per view", () => {
+  const mm = m();
+  assert.equal(linkStateId(mm, "today", mm.links[1]!), "gap");
+  assert.equal(linkStateId(mm, "full", mm.links[1]!), "good");
+});
+test("isNew: visible now, not in the baseline view", () => {
+  const mm = m();
+  assert.equal(isNew(mm, "full", mm.nodes[2]!), true);
+  assert.equal(isNew(mm, "today", mm.nodes[2]!), false);
+  assert.equal(isNew(mm, "full", mm.nodes[0]!), false);
+});
+test("isImproved: a gap in the baseline that is not a gap now", () => {
+  const mm = m();
+  assert.equal(isImproved(mm, "full", mm.nodes[1]!), true);
+  assert.equal(isImproved(mm, "today", mm.nodes[1]!), false);
+  assert.equal(isImproved(mm, "full", mm.nodes[0]!), false);
+});
+test("bucketOf reads the bucket of a state, and an unknown state is a gap (never a good)", () => {
+  const mm = m();
+  assert.equal(bucketOf(mm, "good"), "good");
+  assert.equal(bucketOf(mm, "nope"), "gap");
+});
+test("canonOf maps a chip to its real node and leaves others alone", () => {
+  const mm = m(), nodes = byId(mm);
+  assert.equal(canonOf(nodes, "k"), "a");
+  assert.equal(canonOf(nodes, "b"), "b");
+  assert.equal(canonOf(nodes, "missing"), "missing");
+});