@caddis/cli 0.4.44 → 0.4.46

package/bundles/antigravity-plugin/skills/flow-studio/src/model.ts

@@ -0,0 +1,250 @@
+// 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 const NODE_HEIGHT: Record<Kind, number> = { card: 54, group: 54, gateway: 64, placeholder: 54, chip: 40, start: 40, end: 40, event: 40, note: 40 };
+
+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;
+  x?: number;
+  y?: number;
+  w?: number;
+  h?: number;
+  state: string;
+  stateIn?: Record<string, string>;
+  visibleIn?: string[];
+  title: string;
+  subtitle?: string;
+  members?: string[];
+  weight?: number;
+  ref?: string;
+  upgrade?: string;
+  allowIsolated?: boolean;
+  contains?: string[];
+  collapsed?: boolean;
+  sla?: number;
+  metrics?: NodeMetric;
+}
+export interface NodeMetric {
+  value: number;
+  /** null means "no maximum" — the same as omitting it. Renderers treat both the same way. */
+  max?: number | null;
+  unit?: string;
+  label?: string;
+  series?: number[];
+}
+export interface LinkDef {
+  id: string;
+  from: string;
+  to: string;
+  state: string;
+  stateIn?: Record<string, string>;
+  visibleIn?: string[];
+  label?: string;
+  kind?: "forward" | "loop-back";
+}
+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 StepDef { link: string; at?: number; dur?: number; caption?: string }
+export interface ScenarioDef { id: string; label: string; steps: StepDef[] }
+export interface Model {
+  version: 1;
+  meta: { title: string; help: string; asOf: string; source: string; labels?: Record<string, string> };
+  layout: "columns-lanes" | "free" | "auto";
+  columns: ColumnDef[];
+  lanes: LaneDef[];
+  states: Record<string, StateDef>;
+  nodes: NodeDef[];
+  links: LinkDef[];
+  views?: ViewDef[];
+  inspector?: { relations: RelationDef[]; actions?: ActionDef[] };
+  notes?: NoteDef[];
+  scenarios?: ScenarioDef[];
+}
+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 (!["columns-lanes", "free", "auto"].includes(m.layout)) add("error", "layout-unsupported", "layout", `layout ${String(m.layout)} is not supported: use "columns-lanes", "free", or "auto".`);
+  if (!Array.isArray(m.columns) || (m.layout === "columns-lanes" && m.columns.length === 0)) add("error", "columns-missing", "columns", "Columns are required for columns-lanes layout.");
+  if (!Array.isArray(m.lanes) || (m.layout !== "auto" && 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 ((m.layout !== "auto" || n.lane !== undefined) && !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 (m.layout === "columns-lanes" && (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 (m.layout === "columns-lanes" && (!Number.isInteger(n.col) || (n.col ?? -1) < 0 || (n.col ?? 0) + span > ncols)) add("error", "column-range", w, `Column ${n.col} with span ${span} is outside 0..${ncols - 1}.`);
+    if (m.layout === "free") {
+      if (!Number.isFinite(n.x) || !Number.isFinite(n.y)) add("error", "position-invalid", w, `Node ${n.id} needs finite x and y.`);
+      if ((n.w !== undefined && (!Number.isFinite(n.w) || n.w <= 0)) || (n.h !== undefined && (!Number.isFinite(n.h) || n.h <= 0))) add("error", "size-invalid", w, `Node ${n.id} needs positive finite width and height.`);
+    }
+    const metric = n.metrics;
+    const invalidSeries = metric?.series !== undefined && (!Array.isArray(metric.series) || metric.series.length > 60 || metric.series.some(v => !Number.isFinite(v)));
+    if (metric !== undefined && (!metric || !Number.isFinite(metric.value) || (metric.max != null && !Number.isFinite(metric.max)) || invalidSeries)) add("error", "metric-invalid", w, "Metrics need finite values and at most 60 finite series points.");
+    if (n.sla !== undefined && (!Number.isFinite(n.sla) || n.sla <= 0)) add("error", "sla-invalid", w, "SLA must be a positive finite number of seconds.");
+  }
+  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 owner = new Map<string, string>();
+  for (const group of nodes.filter(n => n.contains !== undefined)) {
+    if (group.kind !== "group" || !Array.isArray(group.contains)) {
+      add("error", "contains-shape", `nodes[${group.id}]`, "Only a group may contain a list of node ids.");
+      continue;
+    }
+    for (const id of group.contains) {
+      if (id === group.id) add("error", "contains-self", `nodes[${group.id}]`, `Group ${group.id} cannot contain itself.`);
+      else if (!nodeIds.has(id)) add("error", "contains-undefined", `nodes[${group.id}]`, `Contained node ${id} does not exist.`);
+      else if (owner.has(id)) add("error", "contains-duplicate", `nodes[${group.id}]`, `Node ${id} is already contained by ${owner.get(id)}.`);
+      else owner.set(id, group.id);
+    }
+  }
+  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 (m.layout !== "free" && a.col !== undefined && b.col !== undefined) {
+        const forward = b.col > a.col + (a.colSpan ?? 1) - 1;
+        if (!forward && l.kind !== "loop-back") add("warn", "link-direction", w, `Link ${l.id} does not run left to right (column ${a.col} to ${b.col}); mark it loop-back if it returns to an earlier stage.`);
+        if (forward && l.kind === "loop-back") add("warn", "loop-back-forward", w, `Link ${l.id} is marked loop-back but runs forward.`);
+      }
+    }
+    for (const s of [l.state, ...Object.values(l.stateIn ?? {})]) if (!stateIds.has(s)) add("error", "state-undefined", w, `State ${s} is not defined.`);
+  }
+  const scenarioIds = new Set<string>();
+  for (const [i, scenario] of (Array.isArray(m.scenarios) ? m.scenarios : []).entries()) {
+    const w = `scenarios[${i}]`;
+    if (!scenario || typeof scenario.id !== "string" || typeof scenario.label !== "string" || !Array.isArray(scenario.steps)) { add("error", "scenario-shape", w, "A scenario needs an id, label and steps."); continue; }
+    if (scenarioIds.has(scenario.id)) add("error", "scenario-duplicate", w, `Duplicate scenario id ${scenario.id}.`);
+    scenarioIds.add(scenario.id);
+    if (!scenario.steps.length) add("error", "scenario-empty", w, "A scenario needs at least one step.");
+    const timed = scenario.steps.filter(s => s && s.at !== undefined).length;
+    if (timed && timed !== scenario.steps.length) add("error", "scenario-at-partial", w, "Give every step an at time or none.");
+    let prev: LinkDef | undefined, previousAt = -Infinity;
+    for (const [j, step] of scenario.steps.entries()) {
+      const sw = `${w}.steps[${j}]`;
+      const link = links.find(l => l.id === step?.link);
+      if (!link) add("error", "scenario-link", sw, `Unknown link ${step?.link}.`);
+      if (step?.at !== undefined) {
+        if (!Number.isFinite(step.at) || step.at < 0 || step.at < previousAt) add("error", "scenario-at-order", sw, "Step times must be finite, nonnegative and nondecreasing.");
+        if (Number.isFinite(step.at) && step.at >= 0 && step.at >= previousAt) previousAt = step.at;
+      }
+      if (step?.dur !== undefined && (!Number.isFinite(step.dur) || step.dur <= 0)) add("error", "scenario-duration", sw, "Duration must be positive and finite.");
+      if (prev && link) {
+        const previousTo = prev.to;
+        if ((nodes.find(n => n.id === previousTo)?.ref ?? previousTo) !== (nodes.find(n => n.id === link.from)?.ref ?? link.from)) add("warn", "scenario-gap", sw, "This step does not start at the previous step's target.");
+      }
+      if (link) prev = link;
+    }
+  }
+  for (const n of nodes) {
+    if (n.kind !== "gateway") continue;
+    const exits = links.filter(l => l.from === n.id);
+    if (exits.length === 0) add("warn", "gateway-no-exit", `nodes[${n.id}]`, `Gateway ${n.id} has no exit.`);
+    else if (exits.length > 1 && exits.some(l => !l.label?.trim())) add("warn", "gateway-exit-label", `nodes[${n.id}]`, `Every exit from gateway ${n.id} needs a label.`);
+  }
+  for (const n of nodes) {
+    if (!linked.has(n.id) && !n.allowIsolated && n.kind !== "note" && !(n.kind === "group" && n.contains?.length)) {
+      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]!;
+      if (a.contains?.includes(b.id) || b.contains?.includes(a.id)) continue;
+      if (m.layout === "free") {
+        const aw = a.w ?? 190, ah = a.h ?? NODE_HEIGHT[a.kind] ?? 54, bw = b.w ?? 190, bh = b.h ?? NODE_HEIGHT[b.kind] ?? 54;
+        if ([a.x, a.y, b.x, b.y, aw, ah, bw, bh].every(v => typeof v === "number" && Number.isFinite(v))
+          && a.x! < b.x! + bw && b.x! < a.x! + aw && a.y! < b.y! + bh && b.y! < a.y! + ah) {
+          add("error", "rect-overlap", `nodes[${a.id}]`, `Nodes ${a.id} and ${b.id} overlap.`);
+        }
+      } else if (a.col !== undefined && b.col !== undefined && a.row !== undefined && b.row !== undefined) {
+        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/antigravity-plugin/skills/flow-studio/src/notes.ts

@@ -0,0 +1,100 @@
+// 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) {
+        // A closed <details> hides the anchor, so the marker sits on the outermost closed details.
+        // An open details hides nothing: an anchor that is still zero-size inside one is hidden for
+        // another reason and gets no marker.
+        let d = a.closest<HTMLDetailsElement>("details");
+        while (d && d.open) d = d.parentElement?.closest<HTMLDetailsElement>("details") ?? null;
+        if (d) r = d.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/antigravity-plugin/skills/flow-studio/src/page.ts

@@ -0,0 +1,21 @@
+import { mount } from "./engine.ts";
+import type { Model, NoteDef } from "./model.ts";
+
+function auto(): void {
+  const m = document.getElementById("flow-model");
+  if (!m) return;
+  try {
+    const model = JSON.parse(m.textContent ?? "{}") as Model;
+    const n = document.getElementById("flow-notes");
+    const notes = n ? (JSON.parse(n.textContent ?? "[]") as NoteDef[]) : undefined;
+    mount(document, model, { notes });
+  } catch (e) {
+    console.error(e);
+    const h = document.getElementById("help");
+    if (h) h.textContent = "This page could not be drawn: " + (e instanceof Error ? e.message : String(e));
+  }
+}
+
+window.flowStudioMount = mount;
+if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", auto);
+else auto();

package/bundles/antigravity-plugin/skills/flow-studio/src/playback.test.ts

@@ -0,0 +1,104 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { planScenario, positionAt, slaState, formatElapsed, exitsOf, suggestedExit, buildManualRoute, extendScenarioWithRoute } from "./playback.ts";
+import { validateModel, type Model, type ScenarioDef, type StepDef } from "./model.ts";
+
+const model = JSON.parse(readFileSync(new URL("../examples/order-desk.json", import.meta.url), "utf8")) as Model;
+const steps = [{ link: "l-intake-verify" }, { link: "l-verify-route", dur: 400 }];
+test("untimed playback is sequential and clamped", () => {
+  const p = planScenario(model, { id: "a", label: "A", steps });
+  assert.equal(p.mode, "none"); assert.equal(p.totalMs, 1300);
+  assert.deepEqual(p.steps.map(s => s.at), [0, 900]);
+  assert.deepEqual(positionAt(p, -10), { stepIndex: 0, progress: 0, done: false });
+  assert.deepEqual(positionAt(p, 900), { stepIndex: 1, progress: 0, done: false });
+  assert.deepEqual(positionAt(p, Infinity), { stepIndex: 1, progress: 1, done: true });
+});
+test("elapsed playback scales the shortest gap and handles empty plans", () => {
+  const p = planScenario(model, { id: "a", label: "A", steps: [{ link: "l-intake-verify", at: 2 }, { link: "l-verify-route", at: 2.2 }] });
+  assert.equal(p.mode, "elapsed"); assert.equal(p.steps[1]?.at, 900);
+  assert.equal(p.steps[0]?.caption, "New request to Verify details");
+  const empty = planScenario(model, { id: "x", label: "X", steps: [] });
+  assert.deepEqual(positionAt(empty, 0), { stepIndex: -1, progress: 0, done: true });
+  const one = planScenario(model, { id: "one", label: "One", steps: [{ link: "l-intake-verify", at: 0 }] });
+  assert.equal(one.totalMs, 900);
+  assert.deepEqual(positionAt(one, NaN), { stepIndex: 0, progress: 0, done: false });
+  assert.deepEqual(positionAt(one, 900), { stepIndex: 0, progress: 1, done: true });
+});
+test("time and branches have stable boundaries", () => {
+  assert.equal(slaState(79.9, 100), "ok"); assert.equal(slaState(80, 100), "warn"); assert.equal(slaState(100, 100), "breach");
+  assert.equal(formatElapsed(59.6), "1:00"); assert.equal(formatElapsed(3600), "1:00:00");
+  assert.deepEqual(exitsOf(model, "route").map(l => l.id), ["l-route-hold", "l-route-quote"]);
+  assert.equal(suggestedExit(exitsOf(model, "route"), "l-route-quote")?.id, "l-route-quote");
+});
+test("validator reports scenario and metric errors", () => {
+  const m = structuredClone(model);
+  m.scenarios = [{ id: "a", label: "A", steps: [{ link: "missing", at: 2 }, { link: "l-intake-verify" }] }, { id: "a", label: "B", steps: [] }];
+  m.nodes[0]!.metrics = { value: NaN, series: Array(61).fill(0) };
+  const codes = validateModel(m).map(i => i.code);
+  for (const c of ["scenario-duplicate", "scenario-empty", "scenario-link", "scenario-at-partial", "metric-invalid"]) assert.ok(codes.includes(c), c);
+});
+test("validator warns for disconnected steps and rejects decreasing time", () => {
+  const m = structuredClone(model);
+  m.scenarios = [{ id: "gap", label: "Gap", steps: [{ link: "l-intake-verify", at: 10 }, { link: "l-route-quote", at: 9 }] }];
+  const codes = validateModel(m).map(i => i.code);
+  assert.ok(codes.includes("scenario-at-order"));
+  assert.ok(codes.includes("scenario-gap"));
+});
+test("validator catches decreasing time even when intermediate step has NaN at", () => {
+  const m = structuredClone(model);
+  m.scenarios = [{
+    id: "nan-order", label: "NaN Order",
+    steps: [
+      { link: "l-intake-verify", at: 10 },
+      { link: "l-verify-route", at: NaN },
+      { link: "l-route-quote", at: 5 },
+    ],
+  }];
+  const issues = validateModel(m).filter(i => i.code === "scenario-at-order");
+  assert.equal(issues.length, 2, "Both step with NaN and step with decreasing time should report scenario-at-order");
+});
+test("buildManualRoute and extendScenarioWithRoute preserve manual branches and elapsed timing", () => {
+  const choiceLink = model.links.find(l => l.id === "l-route-hold")!;
+  const route = buildManualRoute(model, choiceLink);
+  assert.deepEqual(route.map(l => l.id), ["l-route-hold", "l-hold-verify", "l-verify-route"]);
+
+  const initialScenario = model.scenarios?.[0]!;
+  const plan1 = planScenario(model, initialScenario);
+  // User at step 1 (gateway 'route') chooses 'l-route-hold'
+  const manual1 = extendScenarioWithRoute(initialScenario, plan1, 1, route);
+  assert.equal(manual1.steps.length, 5);
+  assert.equal(manual1.steps[2].link, "l-route-hold");
+  assert.equal(manual1.steps[3].link, "l-hold-verify");
+  assert.equal(manual1.steps[4].link, "l-verify-route");
+  assert.ok(manual1.steps[2].at! > manual1.steps[1].at!);
+  assert.ok(manual1.steps[3].at! > manual1.steps[2].at!);
+  assert.ok(manual1.steps[4].at! > manual1.steps[3].at!);
+
+  const plan2 = planScenario(model, manual1);
+  assert.equal(plan2.mode, "elapsed");
+
+  // Subsequent manual choice from the new branch must NOT drop earlier manual steps
+  const route2 = [model.links.find(l => l.id === "l-route-quote")!];
+  const manual2 = extendScenarioWithRoute(manual1, plan2, 4, route2);
+  assert.equal(manual2.steps.length, 6);
+  assert.deepEqual(manual2.steps.map(s => s.link), [
+    initialScenario.steps[0].link,
+    initialScenario.steps[1].link,
+    "l-route-hold",
+    "l-hold-verify",
+    "l-verify-route",
+    "l-route-quote",
+  ]);
+  assert.ok(manual2.steps[5].at! > manual2.steps[4].at!);
+});
+test("a scenario with malformed steps plans without throwing and keeps indices aligned", () => {
+  // The validator reports a null step (scenario-link) but the page still renders, so playback must not throw on it.
+  const sc = { id: "n", label: "N", steps: [{ link: "l-intake-verify", at: 0 }, null as unknown as StepDef, { link: "l-verify-route", at: 5 }] } as unknown as ScenarioDef;
+  const plan = planScenario(model, sc);
+  assert.deepEqual(plan.steps.map(s => [s.link, s.index]), [["l-intake-verify", 0], ["l-verify-route", 2]]);
+  // The counter reads a scenario step's at through the plan step's index, so the index must stay the original one.
+  assert.equal(sc.steps[2]!.at, 5);
+  const ext = extendScenarioWithRoute(sc, plan, 1, [model.links.find(l => l.id === "l-route-hold")!]);
+  assert.doesNotThrow(() => planScenario(model, ext));
+});

package/bundles/antigravity-plugin/skills/flow-studio/src/playback.ts

@@ -0,0 +1,106 @@
+import type { LinkDef, Model, ScenarioDef, StepDef } from "./model.ts";
+
+export interface PlannedStep { link: string; from: string; to: string; at: number; dur: number; caption: string; index: number }
+export interface Plan { steps: PlannedStep[]; mode: "elapsed" | "none"; totalMs: number }
+
+export function planScenario(model: Model, scenario: ScenarioDef): Plan {
+  const source = scenario.steps ?? [];
+  const mode = source.some(s => s?.at !== undefined) ? "elapsed" : "none";
+  const start = source[0]?.at ?? 0;
+  // One global scale keeps the relative spacing. Zero gaps cannot be scaled, so they follow the prior duration.
+  const scale = mode === "elapsed" ? Math.max(1, ...source.slice(1).map((s, i) => {
+    const gap = ((s?.at ?? 0) - (source[i]?.at ?? 0)) * 1000;
+    return gap > 0 ? (source[i]?.dur ?? 900) / gap : 1;
+  })) : 1;
+  const steps: PlannedStep[] = [];
+  for (let i = 0; i < source.length; i++) {
+    const s = source[i];
+    // A step that is not an object is a validator error (scenario-link), but the page still renders:
+    // skip it and keep the original index, because the counter reads a step's at back through it.
+    if (!s || typeof s !== "object") continue;
+    const link = model.links.find(l => l.id === s.link);
+    if (!link) continue;
+    const from = model.nodes.find(n => n.id === link.from);
+    const to = model.nodes.find(n => n.id === link.to);
+    const dur = Number.isFinite(s.dur) && (s.dur ?? 0) > 0 ? s.dur! : 900;
+    const proposed = mode === "elapsed" ? Math.max(0, ((s.at ?? 0) - start) * 1000 * scale) : 0;
+    const at = steps.length === 0 ? 0 : Math.max(proposed, steps.at(-1)!.at + steps.at(-1)!.dur);
+    steps.push({ link: s.link, from: from?.ref ?? link.from, to: to?.ref ?? link.to, at, dur, caption: s.caption ?? `${from?.title ?? link.from} to ${to?.title ?? link.to}`, index: i });
+  }
+  return { steps, mode, totalMs: steps.length ? steps.at(-1)!.at + steps.at(-1)!.dur : 0 };
+}
+
+export function positionAt(plan: Plan, tMs: number): { stepIndex: number; progress: number; done: boolean } {
+  if (!plan.steps.length) return { stepIndex: -1, progress: 0, done: true };
+  const t = Number.isNaN(tMs) ? 0 : Math.max(0, tMs);
+  if (t >= plan.totalMs) return { stepIndex: plan.steps.length - 1, progress: 1, done: true };
+  let i = plan.steps.length - 1;
+  while (i > 0 && t < plan.steps[i]!.at) i--;
+  const s = plan.steps[i]!;
+  return { stepIndex: i, progress: Math.max(0, Math.min(1, (t - s.at) / s.dur)), done: false };
+}
+
+export function slaState(elapsedSec: number, sla: number): "ok" | "warn" | "breach" {
+  if (elapsedSec >= sla) return "breach";
+  return elapsedSec >= sla * .8 ? "warn" : "ok";
+}
+
+export function formatElapsed(sec: number): string {
+  const n = Math.max(0, Math.round(Number.isFinite(sec) ? sec : 0));
+  const m = Math.floor(n / 60), s = String(n % 60).padStart(2, "0");
+  return n < 3600 ? `${m}:${s}` : `${Math.floor(n / 3600)}:${String(m % 60).padStart(2, "0")}:${s}`;
+}
+
+export function exitsOf(model: Model, nodeId: string): LinkDef[] {
+  const canon = (id: string) => model.nodes.find(n => n.id === id)?.ref ?? id;
+  return model.links.filter(l => canon(l.from) === canon(nodeId));
+}
+
+export function suggestedExit(exits: LinkDef[], nextLink: string | undefined): LinkDef | undefined {
+  return exits.find(l => l.id === nextLink);
+}
+
+export function buildManualRoute(model: Model, choiceLink: LinkDef): LinkDef[] {
+  const route = [choiceLink];
+  const seen = new Set([choiceLink.id]);
+  let at = choiceLink.to;
+  while (exitsOf(model, at).length === 1) {
+    const next = exitsOf(model, at)[0]!;
+    if (seen.has(next.id)) break;
+    route.push(next);
+    seen.add(next.id);
+    at = next.to;
+  }
+  return route;
+}
+
+export function extendScenarioWithRoute(
+  scenario: ScenarioDef,
+  plan: Plan,
+  stepIndex: number,
+  route: LinkDef[]
+): ScenarioDef {
+  const isElapsed = plan.mode === "elapsed" || scenario.steps.some(s => s?.at !== undefined);
+  const prefix: StepDef[] = scenario.steps.slice(0, stepIndex + 1).map(s => ({ ...s }));
+  for (let i = prefix.length; i <= stepIndex && i < plan.steps.length; i++) {
+    const ps = plan.steps[i]!;
+    prefix.push({ link: ps.link, dur: ps.dur, caption: ps.caption });
+  }
+  let lastAt = 0;
+  if (isElapsed) {
+    const lastWithAt = [...prefix].reverse().find(s => s?.at !== undefined);
+    lastAt = lastWithAt?.at ?? 0;
+  }
+  const newSteps: StepDef[] = route.map(l => {
+    const step: StepDef = { link: l.id };
+    if (isElapsed) {
+      lastAt += 1;
+      step.at = lastAt;
+    }
+    return step;
+  });
+  return {
+    ...scenario,
+    steps: [...prefix, ...newSteps],
+  };
+}