@caddis/cli 0.4.44 → 0.4.46

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

@@ -0,0 +1,144 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { computeGeometry } from "./layout.ts";
+import type { Model } from "./model.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: 200 }],
+  lanes: [{ id: "l1", title: "One" }, { id: "l2", title: "Two" }],
+  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" },
+    { id: "c", kind: "card", lane: "l2", col: 0, row: 1.8, state: "ok", title: "C" },
+    { id: "w", kind: "placeholder", lane: "l2", col: 0, colSpan: 2, row: 2.8, state: "ok", title: "W" },
+  ],
+  links: [{ id: "a-b", from: "a", to: "b", state: "ok" }],
+});
+
+test("columns are laid out left to right with the gap", () => {
+  const g = computeGeometry(m());
+  assert.equal(g.xs[0], 24);
+  assert.equal(g.xs[1], 24 + 150 + 34);
+});
+test("a node sits at its column and its row", () => {
+  const g = computeGeometry(m());
+  assert.equal(g.nodes.a!.x, 24);
+  assert.equal(g.nodes.a!.w, 150);
+  assert.ok(g.nodes.c!.y > g.nodes.a!.y);
+});
+test("a wide node spans its columns", () => {
+  const g = computeGeometry(m());
+  assert.equal(g.nodes.w!.w, 150 + 34 + 200);
+});
+test("a chip is shorter than a card", () => {
+  const mm = m();
+  mm.nodes.push({ id: "k", kind: "chip", lane: "l1", col: 0, row: 3.8, state: "ok", title: "k", ref: "a" });
+  const g = computeGeometry(mm);
+  assert.ok(g.nodes.k!.h < g.nodes.a!.h);
+});
+test("lane rectangles are computed from their nodes and do not overlap", () => {
+  const g = computeGeometry(m());
+  const a = g.lanes.l1!, b = g.lanes.l2!;
+  assert.ok(a.y + a.h <= b.y, `${a.y + a.h} <= ${b.y}`);
+});
+test("a lane without visible nodes has no rectangle", () => {
+  const g = computeGeometry(m(), { visible: id => id !== "c" && id !== "w" });
+  assert.equal(g.lanes.l2, undefined);
+});
+test("bounds cover every lane and the world is finite", () => {
+  const g = computeGeometry(m());
+  assert.ok(Object.values(g.lanes).every(l => l.y >= g.bounds.y && l.y + l.h <= g.bounds.y + g.bounds.h + 1e-6));
+  assert.ok(Number.isFinite(g.world.w) && Number.isFinite(g.world.h));
+});
+test("an empty model has a finite, empty geometry (review focus 2)", () => {
+  const mm = m();
+  mm.nodes = [];
+  mm.links = [];
+  const g = computeGeometry(mm);
+  assert.ok(Number.isFinite(g.bounds.w) && Number.isFinite(g.bounds.h) && Number.isFinite(g.world.h));
+});
+test("a node whose column is out of range does not produce NaN", () => {
+  const mm = m();
+  mm.nodes[0]!.col = 9;
+  const g = computeGeometry(mm);
+  assert.ok(Object.values(g.nodes).every(n => [n.x, n.y, n.w, n.h].every(Number.isFinite)));
+});
+test("a gateway has a 64 px diamond box", () => {
+  const mm = m(); mm.nodes[0]!.kind = "gateway";
+  assert.equal(computeGeometry(mm).nodes.a!.h, 64);
+});
+test("loop-back channels stay below nodes, inside their lane, and separate from the next lane", () => {
+  const mm = m();
+  mm.links.push({ id: "return", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  mm.links.push({ id: "again", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  const g = computeGeometry(mm);
+  const y = g.loops.return!.channelY;
+  assert.ok(y >= g.nodes.a!.y + g.nodes.a!.h + 10);
+  assert.ok(y >= g.nodes.b!.y + g.nodes.b!.h + 10);
+  assert.equal(g.loops.again!.channelY, y + 8);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h > g.loops.again!.channelY);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h <= g.lanes.l2!.y);
+});
+
+test("a loop clears a lower node within its horizontal span", () => {
+  const mm = m();
+  mm.columns.push({ id: "c2", title: "C", width: 150 });
+  mm.nodes.find(n => n.id === "b")!.col = 2;
+  mm.nodes.push({ id: "middle", kind: "card", lane: "l1", col: 1, row: 1, state: "ok", title: "Middle" });
+  mm.links.push({ id: "return", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  const g = computeGeometry(mm);
+  assert.equal(g.loops.return!.channelY, g.nodes.middle!.y + g.nodes.middle!.h + 10);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h <= g.lanes.l2!.y);
+});
+
+test("a lower node outside the loop span does not lower its channel", () => {
+  const mm = m();
+  mm.columns.push({ id: "c2", title: "C", width: 150 });
+  mm.nodes.push({ id: "outside", kind: "card", lane: "l1", col: 2, row: 1, state: "ok", title: "Outside" });
+  mm.links.push({ id: "return", from: "b", to: "a", state: "ok", kind: "loop-back" });
+  const g = computeGeometry(mm);
+  assert.equal(g.loops.return!.channelY, g.nodes.a!.y + g.nodes.a!.h + 10);
+});
+
+test("interleaved lanes calculate channels after all endpoint shifts", () => {
+  const mm = m();
+  mm.nodes = [
+    { id: "a", kind: "card", lane: "l1", col: 0, row: 0, state: "ok", title: "A" },
+    { id: "deep", kind: "card", lane: "l1", col: 1, row: 5, state: "ok", title: "Deep" },
+    { id: "b", kind: "card", lane: "l2", col: 0, row: 1, state: "ok", title: "B" },
+  ];
+  mm.links = [{ id: "return", from: "deep", to: "b", state: "ok", kind: "loop-back" }];
+  const g = computeGeometry(mm);
+  assert.ok(g.loops.return!.channelY >= g.nodes.b!.y + g.nodes.b!.h + 10);
+  assert.ok(g.lanes.l1!.y + g.lanes.l1!.h <= g.lanes.l2!.y);
+  assert.ok(Object.values(g.nodes).every(n => [n.x, n.y, n.w, n.h].every(Number.isFinite)));
+  assert.ok(Object.values(g.loops).every(l => Number.isFinite(l.channelY)));
+});
+
+test("free layout uses explicit world rectangles and works without columns", () => {
+  const mm = m();
+  mm.layout = "free"; mm.columns = [];
+  mm.nodes = [
+    { id: "a", kind: "card", lane: "l1", x: 18, y: 70, w: 121, h: 47, state: "ok", title: "A" },
+    { id: "b", kind: "card", lane: "l2", x: 250, y: 300, state: "ok", title: "B" },
+  ];
+  const g = computeGeometry(mm);
+  assert.deepEqual(g.xs, []);
+  assert.deepEqual(g.nodes.a, { id: "a", x: 18, y: 70, w: 121, h: 47 });
+  assert.equal(g.nodes.b?.w, 190);
+  assert.ok(g.world.w >= 440);
+  assert.ok(g.lanes.l1 && g.lanes.l2);
+});
+
+test("free layout preserves finite negative node coordinates", () => {
+  const mm = m(); mm.layout = "free"; mm.columns = [];
+  mm.nodes = [{ id: "a", kind: "card", lane: "l1", x: -80, y: -40, w: 60, h: 30, state: "ok", title: "A" }];
+  const g = computeGeometry(mm);
+  assert.equal(g.nodes.a!.x, -80);
+  assert.equal(g.nodes.a!.y, -40);
+  assert.ok([g.bounds.x, g.bounds.y, g.bounds.w, g.bounds.h, g.world.w, g.world.h].every(Number.isFinite));
+});

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

@@ -0,0 +1,95 @@
+// Geometry from a model: where every node, lane and column sits in world units. Pure, no DOM.
+// Node sizes are fixed per kind, so layout never depends on fonts or text measurement.
+
+import { NODE_HEIGHT, type Model } from "./model.ts";
+import type { Rect, Size } from "./viewport.ts";
+
+export interface Placed extends Rect { id: string }
+export interface Geometry {
+  xs: number[];
+  nodes: Record<string, Placed>;
+  lanes: Record<string, Rect>;
+  loops: Record<string, { channelY: number }>;
+  bounds: Rect;
+  world: Size;
+}
+export interface LayoutOptions { pitch: number; top: number; gap: number; padX: number; visible: (id: string) => boolean }
+
+export const DEFAULTS: LayoutOptions = { pitch: 62, top: 64, gap: 34, padX: 24, visible: () => true };
+
+const LANE_PAD_TOP = 38; // room for the lane title
+const LANE_PAD_BOTTOM = 14;
+
+export function computeGeometry(m: Model, opt: Partial<LayoutOptions> = {}): Geometry {
+  const o: LayoutOptions = { ...DEFAULTS, ...opt };
+  const xs: number[] = [];
+  let x = o.padX;
+  for (const c of m.columns) { xs.push(x); x += c.width + o.gap; }
+  const world: Size = { w: Math.max(1, x - o.gap + o.padX), h: 1 };
+
+  const nodes: Record<string, Placed> = {};
+  for (const n of m.nodes) {
+    const h = NODE_HEIGHT[n.kind] ?? 54;
+    if (m.layout === "free") {
+      nodes[n.id] = { id: n.id, x: n.x ?? 0, y: n.y ?? 0, w: n.w ?? 190, h: n.h ?? h };
+      continue;
+    }
+    const first = Math.min(Math.max(0, n.col ?? 0), m.columns.length - 1);
+    const last = Math.min(m.columns.length - 1, first + (n.colSpan ?? 1) - 1);
+    const x0 = xs[first] ?? o.padX;
+    const x1 = (xs[last] ?? x0) + (m.columns[last]?.width ?? 0);
+    nodes[n.id] = { id: n.id, x: x0, y: o.top + 40 + (n.row ?? 0) * o.pitch - h / 2, w: Math.max(1, x1 - x0), h };
+  }
+  if (m.layout === "free") world.w = Math.max(world.w, ...Object.values(nodes).map(p => p.x + p.w + o.padX), 1);
+
+  const loops: Geometry["loops"] = {};
+  const lanes: Record<string, Rect> = {};
+  const visibleMembers = (id: string) => m.nodes.filter(n => n.lane === id && o.visible(n.id)).map(n => nodes[n.id]!);
+  const ordered = m.lanes.map(l => ({ l, mem: visibleMembers(l.id) })).filter(x => x.mem.length)
+    .sort((a, b) => Math.min(...a.mem.map(p => p.y)) - Math.min(...b.mem.map(p => p.y)));
+  let previousBottom = -Infinity;
+  for (const { l, mem } of ordered) {
+    const top = Math.min(...mem.map(p => p.y)) - LANE_PAD_TOP;
+    const shift = m.layout === "free" ? 0 : Math.max(0, previousBottom + 8 - top);
+    if (shift) for (const p of mem) p.y += shift;
+    const y1 = top + shift;
+    const laneNodeIds = new Set(mem.map(p => p.id));
+    // Reserve channel space before shifting the following lane. The exact channel
+    // positions are calculated only after every lane has reached its final y.
+    const possibleLoops = m.links.filter(link => link.kind === "loop-back" && o.visible(link.from) && o.visible(link.to)
+      && (laneNodeIds.has(link.from) || laneNodeIds.has(link.to))).length;
+    const bottom = Math.max(...mem.map(p => p.y + p.h));
+    const y2 = bottom + (possibleLoops ? 10 + 8 * (possibleLoops - 1) : 0) + LANE_PAD_BOTTOM;
+    lanes[l.id] = { x: 8, y: y1, w: world.w - 16, h: y2 - y1 };
+    previousBottom = y2;
+  }
+
+  const channelCounts = new Map<string, number>();
+  for (const link of m.links) {
+    if (link.kind !== "loop-back" || !o.visible(link.from) || !o.visible(link.to)) continue;
+    const a = nodes[link.from], b = nodes[link.to];
+    if (!a || !b) continue;
+    const lower = a.y + a.h >= b.y + b.h ? a : b;
+    const laneId = m.nodes.find(n => n.id === lower.id)?.lane;
+    if (!laneId || !lanes[laneId]) continue;
+    const left = Math.min(a.x + a.w / 2, b.x + b.w / 2);
+    const right = Math.max(a.x + a.w / 2, b.x + b.w / 2);
+    const laneMembers = visibleMembers(laneId);
+    const crossed = laneMembers.filter(p => p.x < right && p.x + p.w > left);
+    const lowestBottom = Math.max(a.y + a.h, b.y + b.h, ...crossed.map(p => p.y + p.h));
+    const index = channelCounts.get(laneId) ?? 0;
+    loops[link.id] = { channelY: lowestBottom + 10 + 8 * index };
+    channelCounts.set(laneId, index + 1);
+    const lane = lanes[laneId];
+    lane.h = Math.max(lane.h, loops[link.id]!.channelY + LANE_PAD_BOTTOM - lane.y);
+  }
+
+  const all = Object.values(lanes);
+  let bounds: Rect = { x: 0, y: 0, w: world.w, h: 1 };
+  if (all.length) {
+    const top = Math.min(...all.map(r => r.y));
+    bounds = { x: 8, y: top, w: world.w - 16, h: Math.max(...all.map(r => r.y + r.h)) - top };
+  }
+  world.h = Math.max(1, bounds.y + bounds.h + 70);
+  return { xs, nodes, lanes, loops, bounds, world };
+}

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

@@ -0,0 +1,20 @@
+/** Replaced with the shared template at library build time. */
+export const SHELL_BODY_HTML = "/*__SHELL_BODY__*/";
+export { mount, type FlowStudio } from "./engine.ts";
+export * from "./model.ts";
+export { autoLayout } from "./autolayout.ts";
+export { computeGeometry } from "./layout.ts";
+export type { Geometry, LayoutOptions, Placed } from "./layout.ts";
+export * from "./viewport.ts";
+export * from "./routing.ts";
+export * from "./trace.ts";
+export * from "./rules.ts";
+export * from "./playback.ts";
+export * from "./diff.ts";
+export * as viewport from "./viewport.ts";
+export * as routing from "./routing.ts";
+export * as trace from "./trace.ts";
+export * as rules from "./rules.ts";
+export * as playback from "./playback.ts";
+export * as diff from "./diff.ts";
+export { stateCss } from "./stateCss.ts";

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

@@ -0,0 +1,57 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { sparklinePoints, metricBadge, sparkline } from "./metrics.ts";
+
+test("sparkline handles flat, missing and varied series", () => {
+  assert.equal(sparklinePoints([], 56, 12), "");
+  assert.equal(sparklinePoints([4, 4], 56, 12), "0,6 56,6");
+  assert.equal(sparklinePoints([0, 10], 56, 12), "0,12 56,0");
+});
+
+test("metricBadge renders value, unit, and consistent title", () => {
+  assert.equal(metricBadge(undefined), "");
+  const badge1 = metricBadge({ value: 92, unit: "ms", label: "Hit rate" });
+  assert.ok(badge1.includes('title="Hit rate: 92 ms"'), "Title includes label, value and unit");
+  assert.ok(badge1.includes(">92 ms"), "Badge body includes value and unit");
+  assert.ok(!badge1.includes("<i"), "No fill bar when max is omitted");
+});
+
+test("metricBadge renders clamped fill bar when max is valid, ignores invalid max", () => {
+  const withMax = metricBadge({ value: 50, max: 100, label: "CPU" });
+  assert.ok(withMax.includes('<i style="width:50%"></i>'));
+
+  const clamped = metricBadge({ value: 150, max: 100 });
+  assert.ok(clamped.includes('<i style="width:100%"></i>'));
+
+  const negativeVal = metricBadge({ value: -10, max: 100 });
+  assert.ok(negativeVal.includes('<i style="width:0%"></i>'));
+
+  const nullMax = metricBadge({ value: 50, max: null as any });
+  assert.ok(!nullMax.includes("<i"), "null max produces no bar");
+
+  const zeroMax = metricBadge({ value: 50, max: 0 });
+  assert.ok(!zeroMax.includes("<i"), "zero max produces no bar");
+});
+
+test("metricBadge escapes special HTML characters", () => {
+  const hostile = metricBadge({ value: 1, unit: '<script>"&', label: '<tag>&"' });
+  assert.ok(!hostile.includes("<script>"));
+  assert.ok(!hostile.includes("<tag>"));
+  assert.ok(hostile.includes("&lt;script&gt;"));
+  assert.ok(hostile.includes("&lt;tag&gt;"));
+});
+test("metricBadge escapes quotes so nothing can break out of the title attribute", () => {
+  // label and unit land inside title="…": a raw quote there would open attacker-controlled attributes.
+  const hostile = metricBadge({ value: 1, unit: '">&x', label: 'y" onmouseover="z' });
+  assert.ok(hostile.includes('title="y&quot; onmouseover=&quot;z: 1 &quot;&gt;&amp;x"'));
+});
+
+test("sparkline renders accessible SVG with aria-hidden", () => {
+  assert.equal(sparkline(undefined), "");
+  assert.equal(sparkline({ value: 10 }), "");
+  assert.equal(sparkline({ value: 10, series: [1] }), "");
+
+  const svg = sparkline({ value: 10, series: [2, 8] }, 56, 12);
+  assert.ok(svg.startsWith('<svg class="spark" width="56" height="12" viewBox="0 0 56 12" aria-hidden="true">'));
+  assert.ok(svg.includes('<polyline points="0,12 56,0"/>'));
+});

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

@@ -0,0 +1,167 @@
+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("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";
+  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 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"));
+});
+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("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"));
+});