@caddis/cli 0.4.45 → 0.4.46

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

@@ -0,0 +1,29 @@
+import type { NodeMetric } from "./model.ts";
+import { esc } from "./model.ts";
+
+export function sparklinePoints(series: number[], width: number, height: number): string {
+  if (!Array.isArray(series) || series.length < 2 || series.some(v => !Number.isFinite(v))) return "";
+  const min = Math.min(...series), max = Math.max(...series), span = max - min;
+  return series.map((v, i) => `${Math.round(i / (series.length - 1) * width * 100) / 100},${Math.round((span ? 1 - (v - min) / span : .5) * height * 100) / 100}`).join(" ");
+}
+
+export function metricBadge(metric: NodeMetric | undefined): string {
+  if (!metric) return "";
+  const label = metric.label ?? "Metric";
+  const valStr = esc(String(metric.value));
+  const unitStr = metric.unit ? " " + esc(metric.unit) : "";
+  const title = `${esc(label)}: ${valStr}${unitStr}`;
+  const hasMax = metric.max != null && Number.isFinite(metric.max) && metric.max > 0;
+  const pct = hasMax && Number.isFinite(metric.value)
+    ? Math.max(0, Math.min(100, (metric.value / metric.max!) * 100))
+    : 0;
+  const bar = hasMax ? `<i style="width:${pct}%"></i>` : "";
+  return `<span class="metric-badge" title="${title}">${valStr}${unitStr}${bar}</span>`;
+}
+
+export function sparkline(metric: NodeMetric | undefined, width = 56, height = 12): string {
+  if (!metric?.series || metric.series.length < 2) return "";
+  const points = sparklinePoints(metric.series, width, height);
+  if (!points) return "";
+  return `<svg class="spark" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" aria-hidden="true"><polyline points="${points}"/></svg>`;
+}

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

@@ -57,9 +57,30 @@ 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";
+test("free layout needs finite position and positive size but no columns", () => {
+  const m = base(); m.layout = "free"; m.columns = [];
+  m.nodes[0] = { id: "a", kind: "card", lane: "l1", x: 0, y: 0, w: 100, h: 40, state: "ok", title: "A" };
+  m.nodes[1] = { id: "b", kind: "card", lane: "l1", x: 200, y: 0, state: "ok", title: "B" };
+  assert.deepEqual(codes(m), []);
+  delete m.nodes[0]!.x;
+  assert.ok(codes(m).includes("position-invalid"));
+  m.nodes[0]!.x = 0; m.nodes[0]!.w = -1;
+  assert.ok(codes(m).includes("size-invalid"));
+});
+test("free layout detects rectangle intersections", () => {
+  const m = base(); m.layout = "free"; m.columns = [];
+  m.nodes[0] = { id: "a", kind: "card", lane: "l1", x: 0, y: 0, w: 100, h: 50, state: "ok", title: "A" };
+  m.nodes[1] = { id: "b", kind: "card", lane: "l1", x: 90, y: 49, w: 100, h: 50, state: "ok", title: "B" };
+  assert.ok(codes(m).includes("rect-overlap"));
+  m.nodes[1]!.x = 100;
+  assert.ok(!codes(m).includes("rect-overlap"));
+});
+test("unsupported layout is an error; auto permits missing positions before layout", () => {
+  const m = base(); (m as any).layout = "timeline";
   assert.ok(codes(m).includes("layout-unsupported"));
+  m.layout = "auto"; m.columns = []; m.lanes = [];
+  m.nodes.forEach(n => { delete n.col; delete n.row; delete n.lane; });
+  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";
@@ -70,6 +91,26 @@ test("a link that goes backward or sideways is a warning, not silence", () => {
 test("a forward link has no direction warning", () => {
   assert.ok(!validateModel(base()).some(i => i.code === "link-direction"));
 });
+test("a branching gateway requires a label on every exit", () => {
+  const m = base(); m.nodes[0]!.kind = "gateway";
+  m.nodes.push({ id: "c", kind: "card", lane: "l1", col: 1, row: 1, state: "ok", title: "C" });
+  m.links.push({ id: "a-c", from: "a", to: "c", state: "ok", label: "No" });
+  assert.ok(validateModel(m).some(i => i.level === "warn" && i.code === "gateway-exit-label" && i.where === "nodes[a]"));
+  m.links[0]!.label = "Yes";
+  assert.ok(!validateModel(m).some(i => i.code === "gateway-exit-label"));
+});
+test("a gateway with no exit warns", () => {
+  const m = base(); m.nodes[1]!.kind = "gateway";
+  assert.ok(validateModel(m).some(i => i.level === "warn" && i.code === "gateway-no-exit" && i.where === "nodes[b]"));
+});
+test("an explicit loop-back suppresses backward direction warning", () => {
+  const m = base(); m.links[0]!.from = "b"; m.links[0]!.to = "a"; m.links[0]!.kind = "loop-back";
+  assert.ok(!validateModel(m).some(i => i.code === "link-direction" || i.code === "loop-back-forward"));
+});
+test("a loop-back that runs forward warns", () => {
+  const m = base(); m.links[0]!.kind = "loop-back";
+  assert.ok(validateModel(m).some(i => i.level === "warn" && i.code === "loop-back-forward"));
+});
 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"));
@@ -101,7 +142,26 @@ 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("a metric max of null means no maximum; a non-numeric max is still an error", () => {
+  const m = base();
+  m.nodes[0]!.metrics = { value: 5, max: null };
+  assert.ok(!codes(m).includes("metric-invalid"), "null max is the author's way to say there is no maximum");
+  m.nodes[0]!.metrics = { value: 5, max: "10" as unknown as number };
+  assert.ok(codes(m).includes("metric-invalid"));
+});
 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), "");
 });
+test("group containment validates ids, ownership, self-reference, and skips group-member overlap", () => {
+  const m = base();
+  const group = { id: "g", kind: "group" as const, lane: "l1", col: 0, row: 0, state: "ok", title: "G", contains: ["a"] };
+  m.nodes.push(group);
+  assert.ok(!codes(m).includes("cell-overlap"));
+  group.contains = ["a", "g", "missing"];
+  m.nodes.push({ ...group, id: "g2", contains: ["a"], row: 2 });
+  const found = codes(m);
+  assert.ok(found.includes("contains-self"));
+  assert.ok(found.includes("contains-undefined"));
+  assert.ok(found.includes("contains-duplicate"));
+});

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

@@ -6,6 +6,7 @@ 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;
@@ -20,10 +21,14 @@ export interface LaneDef { id: string; title: string; badge?: string; badgeTone?
 export interface NodeDef {
   id: string;
   kind: Kind;
-  lane: string;
-  col: number;
+  lane?: string;
+  col?: number;
   colSpan?: number;
-  row: number;
+  row?: number;
+  x?: number;
+  y?: number;
+  w?: number;
+  h?: number;
   state: string;
   stateIn?: Record<string, string>;
   visibleIn?: string[];
@@ -34,6 +39,18 @@ export interface NodeDef {
   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;
@@ -43,15 +60,18 @@ export interface LinkDef {
   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";
+  layout: "columns-lanes" | "free" | "auto";
   columns: ColumnDef[];
   lanes: LaneDef[];
   states: Record<string, StateDef>;
@@ -60,6 +80,7 @@ export interface Model {
   views?: ViewDef[];
   inspector?: { relations: RelationDef[]; actions?: ActionDef[] };
   notes?: NoteDef[];
+  scenarios?: ScenarioDef[];
 }
 export interface Issue { level: "error" | "warn"; code: string; where: string; message: string }
 
@@ -85,9 +106,9 @@ export function validateModel(input: unknown): Issue[] {
   }
   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 (!["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 : [];
@@ -119,15 +140,36 @@ export function validateModel(input: unknown): Issue[] {
     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.`);
+    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 (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).`);
+    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 (!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}.`);
+    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) {
@@ -138,14 +180,48 @@ export function validateModel(input: unknown): Issue[] {
     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.`);
+      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") {
+    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.`);
     }
   }
@@ -153,9 +229,18 @@ export function validateModel(input: unknown): Issue[] {
   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).`);
+      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).`);
+        }
       }
     }
   }

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

@@ -22,6 +22,14 @@ export function install(ctx: Ctx): void {
       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();

package/bundles/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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/codex/.codex/skills/frontend/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],
+  };
+}