@caddis/cli 0.4.45 → 0.4.46

package/bundles/codex/.codex/skills/frontend/flow-studio/react/native/native.css

@@ -0,0 +1,18 @@
+.flow-native { position: relative; min-height: 460px; overflow: hidden; }
+.flow-native-tools { display: flex; gap: .5rem; align-items: center; padding: .5rem; }
+.flow-native-cols { position: relative; height: 2.5rem; overflow: hidden; }
+.flow-native-cols span { position: absolute; overflow: hidden; white-space: nowrap; }
+.flow-native-viewport { position: relative; height: 440px; overflow: hidden; touch-action: none; outline-offset: -2px; }
+.flow-native-world { position: absolute; transform-origin: 0 0; }
+.flow-native-lane, .flow-native-node, .flow-native-edges { position: absolute; }
+.flow-native-lane { border: 1px solid currentColor; opacity: .45; pointer-events: none; }
+.flow-native-lane strong { display: block; padding: .3rem; }
+.flow-native-node { display: flex; text-align: left; background: inherit; color: inherit; border: 1px solid currentColor; }
+.flow-native-node-main { flex: 1; min-width: 0; padding: .4rem; background: transparent; color: inherit; border: 0; text-align: left; }
+.flow-native-node-main[aria-pressed="true"] { outline: 2px solid currentColor; }
+.flow-native-toggle { align-self: start; padding: 0 .35rem; cursor: pointer; }
+.flow-native .insp { position: absolute; top: 0; right: 0; bottom: 0; width: min(320px, 90%); background: Canvas; color: CanvasText; border-left: 1px solid; overflow: auto; }
+.flow-native .insp-h { display: flex; justify-content: space-between; padding: 1rem; }
+.flow-native .insp-b { padding: 1rem; }
+.flow-native .counts, .flow-native .drill { display: flex; gap: .5rem; flex-wrap: wrap; }
+.flow-native-live { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }

package/bundles/codex/.codex/skills/frontend/flow-studio/react/native/native.test.tsx

@@ -0,0 +1,161 @@
+if (typeof window !== "undefined" && typeof window.PointerEvent === "undefined") {
+  class PointerEvent extends MouseEvent {
+    pointerId: number;
+    pointerType: string;
+    constructor(type: string, params: PointerEventInit = {}) {
+      super(type, params);
+      this.pointerId = params.pointerId ?? 0;
+      this.pointerType = params.pointerType ?? "mouse";
+    }
+  }
+  window.PointerEvent = PointerEvent as unknown as typeof window.PointerEvent;
+}
+import React from "react";
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import type { Model } from "../../src/model.ts";
+import { useViewport } from "./useViewport.ts";
+import { useFlowGeometry } from "./useFlowGeometry.ts";
+import { FlowCanvas } from "./FlowCanvas.tsx";
+
+const model: Model = {
+  version: 1, meta: { title: "Sample", help: "", asOf: "", source: "" }, layout: "columns-lanes",
+  columns: [{ id: "one", title: "One", width: 180 }, { id: "two", title: "Two", width: 180 }],
+  lanes: [{ id: "lane", title: "Lane" }],
+  states: { good: { word: "Ready", tone: "ok", border: "solid", edge: "flow", motion: "none", bucket: "good" } },
+  nodes: [
+    { id: "a", kind: "card", lane: "lane", col: 0, row: 0, state: "good", title: "Alpha" },
+    { id: "b", kind: "card", lane: "lane", col: 1, row: 0, state: "good", title: "Beta" },
+  ], links: [{ id: "ab", from: "a", to: "b", state: "good" }],
+};
+
+function ViewProbe() {
+  const { view, bind, fit, zoomBy, zoomAboutCenter } = useViewport({ x: 0, y: 0, w: 1000, h: 500 });
+  return <>
+    <div data-testid="pad" {...bind} />
+    <output data-testid="view">{JSON.stringify(view)}</output>
+    <button onClick={() => zoomBy(2, 100, 80)}>Zoom at point</button>
+    <button onClick={() => zoomAboutCenter(2)}>Zoom about center</button>
+    <button onClick={() => fit()}>Fit measured</button>
+    <button onClick={() => fit({ w: 500, h: 300 })}>Fit explicit</button>
+  </>;
+}
+
+const view = () => JSON.parse(screen.getByTestId("view").textContent!) as { x: number; y: number; k: number };
+/** jsdom reports 0 for every box; the hook must read the sizes from the attached element. */
+const measure = (element: Element, w: number, h: number) => {
+  Object.defineProperty(element, "clientWidth", { value: w, configurable: true });
+  Object.defineProperty(element, "clientHeight", { value: h, configurable: true });
+};
+
+afterEach(cleanup);
+
+describe("native flow viewport", () => {
+  it("keeps the point below the cursor during zoom and fits given bounds", () => {
+    render(<ViewProbe />);
+    fireEvent.click(screen.getByText("Zoom at point"));
+    expect(view()).toEqual({ x: -100, y: -80, k: 2 });
+    fireEvent.click(screen.getByText("Fit explicit"));
+    expect(view().k).toBeLessThan(1);
+  });
+
+  it("measures the attached element when fit() gets no size", () => {
+    render(<ViewProbe />);
+    measure(screen.getByTestId("pad"), 800, 400);
+    fireEvent.click(screen.getByText("Fit measured"));
+    expect(view().k).toBeCloseTo(0.616, 5);
+    expect(view().x).toBeCloseTo(92, 5);
+    expect(view().y).toBeCloseTo(68, 5);
+  });
+
+  it("zooms from a native non-passive wheel listener that can block page scroll", () => {
+    render(<ViewProbe />);
+    const pad = screen.getByTestId("pad");
+    const wheel = new WheelEvent("wheel", { deltaY: -120, clientX: 60, clientY: 40, cancelable: true, bubbles: true });
+    fireEvent(pad, wheel);
+    expect(wheel.defaultPrevented).toBe(true);
+    expect(view().k).toBeGreaterThan(1);
+  });
+
+  it("pans with a pointer drag and stops tracking after pointer up", () => {
+    render(<ViewProbe />);
+    const pad = screen.getByTestId("pad");
+    // jsdom has no real pointer capture; the pan maths must not depend on it.
+    if (typeof pad.setPointerCapture === "function") pad.setPointerCapture = () => {};
+    if (typeof pad.releasePointerCapture === "function") pad.releasePointerCapture = () => {};
+    measure(pad, 800, 400);
+    fireEvent.pointerDown(pad, { button: 0, pointerId: 1, clientX: 100, clientY: 100 });
+    fireEvent.pointerMove(pad, { pointerId: 1, clientX: 150, clientY: 120 });
+    expect(view()).toEqual({ x: 50, y: 20, k: 1 });
+    fireEvent.pointerUp(pad, { pointerId: 1 });
+    fireEvent.pointerMove(pad, { pointerId: 1, clientX: 400, clientY: 300 });
+    expect(view()).toEqual({ x: 50, y: 20, k: 1 });
+  });
+
+  it("zooms with the keyboard about the measured center and fits with 0", () => {
+    render(<ViewProbe />);
+    const pad = screen.getByTestId("pad");
+    measure(pad, 800, 400);
+    fireEvent.keyDown(pad, { key: "+" });
+    expect(view()).toEqual({ x: -80, y: -40, k: 1.2 });
+    fireEvent.keyDown(pad, { key: "-" });
+    expect(view().k).toBeCloseTo(1, 10);
+    fireEvent.keyDown(pad, { key: "0" });
+    expect(view().k).toBeCloseTo(0.616, 5);
+  });
+
+  it("zoomAboutCenter keeps the middle of the viewport fixed", () => {
+    render(<ViewProbe />);
+    measure(screen.getByTestId("pad"), 800, 400);
+    fireEvent.click(screen.getByText("Zoom about center"));
+    expect(view()).toEqual({ x: -400, y: -200, k: 2 });
+  });
+
+  it("reuses the geometry across renders when the collapsed default is omitted", () => {
+    const seen: unknown[] = [];
+    function GeometryProbe() {
+      const { geometry } = useFlowGeometry(model, { x: 0, y: 0, k: 1 });
+      seen.push(geometry);
+      return null;
+    }
+    const rendered = render(<GeometryProbe />);
+    rendered.rerender(<GeometryProbe />);
+    rendered.rerender(<GeometryProbe />);
+    expect(seen[1]).toBe(seen[0]);
+    expect(seen[2]).toBe(seen[0]);
+  });
+});
+
+describe("native flow canvas", () => {
+  it("selects a node, traces its link, and closes the inspector with Escape", () => {
+    render(<FlowCanvas model={model} renderNode={node => <span>{node.title}</span>} />);
+    fireEvent.click(screen.getByRole("button", { name: "Alpha" }));
+    expect(screen.getByRole("dialog").textContent).toContain("Alpha");
+    expect(document.querySelector("#n_b button")?.getAttribute("data-connected")).toBe("true");
+    expect(screen.getByRole("button", { name: "0 upstream nodes" })).toBeTruthy();
+    expect(screen.getByRole("button", { name: "1 downstream nodes" })).toBeTruthy();
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("hides contained nodes while their group is collapsed", () => {
+    const grouped: Model = { ...model, nodes: [
+      { id: "g", kind: "group", lane: "lane", col: 0, row: 0, state: "good", title: "Group", contains: ["a"] },
+      { ...model.nodes[0]!, row: 1 }, model.nodes[1]!,
+    ] };
+    render(<FlowCanvas model={grouped} renderNode={node => <span>{node.title}</span>} />);
+    expect(screen.queryByRole("button", { name: "Alpha" })).toBeNull();
+    fireEvent.click(screen.getByRole("button", { name: "Expand Group" }));
+    expect(screen.getByRole("button", { name: "Alpha" })).toBeTruthy();
+  });
+
+  it("zooms the tool buttons about the viewport center, not a fixed point", () => {
+    render(<FlowCanvas model={model} renderNode={node => <span>{node.title}</span>} />);
+    measure(document.getElementById("viewport")!, 800, 400);
+    fireEvent.click(screen.getByRole("button", { name: "Zoom in" }));
+    expect(document.getElementById("world")!.style.transform).toMatch(/translate\(-80px, -40px\) scale\(1\.2\)/);
+    expect(screen.getByText("120%")).toBeTruthy();
+    fireEvent.click(screen.getByRole("button", { name: "Zoom out" }));
+    expect(screen.getByText("100%")).toBeTruthy();
+  });
+});

package/bundles/codex/.codex/skills/frontend/flow-studio/react/native/useFlowGeometry.ts

@@ -0,0 +1,22 @@
+import { useMemo } from "react";
+import { autoLayout } from "../../src/autolayout.ts";
+import { computeGeometry } from "../../src/layout.ts";
+import type { Model } from "../../src/model.ts";
+import { defaultView, nodeVisible } from "../../src/rules.ts";
+import type { View } from "../../src/viewport.ts";
+
+// Shared default. A fresh Set() per render would change the memo identity below and recompute
+// the geometry on every render. Never mutate it.
+const EMPTY_COLLAPSED = new Set<string>();
+
+/** Layout is world-space; the returned view is applied as a transform by the canvas. */
+export function useFlowGeometry(model: Model, view: View, collapsed: Set<string> = EMPTY_COLLAPSED, mode = defaultView(model)) {
+  const laidOut = useMemo(() => model.layout === "auto" ? autoLayout(model) : model, [model]);
+  const geometry = useMemo(() => computeGeometry(laidOut, {
+    visible: id => {
+      const node = laidOut.nodes.find(item => item.id === id);
+      return !!node && nodeVisible(laidOut, mode, node, collapsed);
+    },
+  }), [laidOut, collapsed, mode]);
+  return { model: laidOut, geometry, view };
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/react/native/useTrace.ts

@@ -0,0 +1,29 @@
+import { useEffect, useMemo, useState } from "react";
+import type { Model } from "../../src/model.ts";
+import { canonOf, defaultView, effectiveLinks, initialCollapsed, nodeVisible, toggleGroupState } from "../../src/rules.ts";
+import { connected, relatives } from "../../src/trace.ts";
+
+export function useTrace(model: Model, mode = defaultView(model)) {
+  const [selected, setSelected] = useState<string | null>(null);
+  const [hover, setHover] = useState<string | null>(null);
+  const [collapsed, setCollapsed] = useState<Set<string>>(() => initialCollapsed(model));
+  const nodes = useMemo(() => new Map(model.nodes.map(node => [node.id, node])), [model]);
+  const links = useMemo(() => effectiveLinks(model, mode, collapsed, nodes), [model, mode, collapsed, nodes]);
+  const visible = useMemo(() => new Set(model.nodes.filter(node => nodeVisible(model, mode, node, collapsed)).map(node => node.id)), [model, mode, collapsed]);
+  const focus = selected ?? hover;
+  const canonical = (id: string) => canonOf(nodes, id);
+  const upstream = useMemo(() => focus ? relatives(links, canonical, focus, "up") : new Set<string>(), [links, focus, nodes]);
+  const downstream = useMemo(() => focus ? relatives(links, canonical, focus, "down") : new Set<string>(), [links, focus, nodes]);
+  const connectedNodes = useMemo(() => focus ? connected(links, canonical, focus) : new Set<string>(), [links, focus, nodes]);
+  const toggleGroup = (id: string) => {
+    const next = toggleGroupState(model, mode, collapsed, id);
+    if (next) { setCollapsed(next.collapsed); setSelected(next.selected); }
+  };
+  useEffect(() => {
+    const onKey = (event: KeyboardEvent) => { if (event.key === "Escape") setSelected(null); };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, []);
+  useEffect(() => { if (selected && !visible.has(selected)) setSelected(null); }, [visible, selected]);
+  return { selected, setSelected, hover, setHover, collapsed, toggleGroup, links, visible, connected: connectedNodes, upstream, downstream };
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/react/native/useViewport.ts

@@ -0,0 +1,75 @@
+import { useCallback, useRef, useState, type KeyboardEventHandler, type PointerEventHandler } from "react";
+import { clampPan, fitRect, zoomAt, type Rect, type Size, type View } from "../../src/viewport.ts";
+
+export interface ViewportBind {
+  /** Spread onto the viewport element. The hook owns this ref: it measures the element and listens here. */
+  ref: (element: HTMLElement | null) => void;
+  onPointerDown: PointerEventHandler<HTMLElement>;
+  onPointerMove: PointerEventHandler<HTMLElement>;
+  onPointerUp: PointerEventHandler<HTMLElement>;
+  onPointerCancel: PointerEventHandler<HTMLElement>;
+  onKeyDown: KeyboardEventHandler<HTMLElement>;
+  tabIndex: number;
+}
+
+/** Canvas state and DOM bindings. Coordinates passed to zoomBy are local to the viewport. */
+export function useViewport(bounds: Rect, initial: View = { x: 0, y: 0, k: 1 }) {
+  const [view, setView] = useState<View>(initial);
+  const viewport = useRef<HTMLElement | null>(null);
+  const drag = useRef<{ x: number; y: number; view: View } | null>(null);
+  const zoomBy = useCallback((factor: number, x: number, y: number) => {
+    setView(previous => zoomAt(previous, factor, x, y));
+  }, []);
+  /** Zoom by a factor about the center of the attached viewport element. */
+  const zoomAboutCenter = useCallback((factor: number) => {
+    const element = viewport.current;
+    zoomBy(factor, (element?.clientWidth ?? 0) / 2, (element?.clientHeight ?? 0) / 2);
+  }, [zoomBy]);
+  const fit = useCallback((size?: Size) => {
+    const measured = size ?? { w: viewport.current?.clientWidth ?? 0, h: viewport.current?.clientHeight ?? 0 };
+    setView(fitRect(bounds, measured, 24, 44));
+  }, [bounds]);
+  // React's synthetic onWheel listener is passive, so its preventDefault cannot stop the page
+  // scrolling. Wheel zoom must be a native listener with { passive: false } on the viewport element.
+  const onWheelZoom = useCallback((event: WheelEvent) => {
+    event.preventDefault();
+    const element = event.currentTarget as HTMLElement | null;
+    if (!element) return;
+    const rect = element.getBoundingClientRect();
+    zoomBy(Math.exp(-event.deltaY * 0.001), event.clientX - rect.left, event.clientY - rect.top);
+  }, [zoomBy]);
+  // The element ref is also what makes fit() work before the first pointer or wheel interaction.
+  const setViewportElement = useCallback((element: HTMLElement | null) => {
+    if (viewport.current === element) return;
+    viewport.current?.removeEventListener("wheel", onWheelZoom);
+    viewport.current = element;
+    element?.addEventListener("wheel", onWheelZoom, { passive: false });
+  }, [onWheelZoom]);
+  const stop: PointerEventHandler<HTMLElement> = event => {
+    if (drag.current) event.currentTarget.releasePointerCapture?.(event.pointerId);
+    drag.current = null;
+  };
+  const bind: ViewportBind = {
+    tabIndex: 0,
+    ref: setViewportElement,
+    onPointerDown: event => {
+      if (event.button !== 0 || (event.target as Element).closest("button,a,input")) return;
+      drag.current = { x: event.clientX, y: event.clientY, view };
+      event.currentTarget.setPointerCapture?.(event.pointerId);
+    },
+    onPointerMove: event => {
+      if (!drag.current) return;
+      const { x, y, view: start } = drag.current;
+      const size = { w: event.currentTarget.clientWidth, h: event.currentTarget.clientHeight };
+      setView(clampPan({ ...start, x: start.x + event.clientX - x, y: start.y + event.clientY - y }, bounds, size));
+    },
+    onPointerUp: stop,
+    onPointerCancel: stop,
+    onKeyDown: event => {
+      if (event.key === "+" || event.key === "=") { event.preventDefault(); zoomAboutCenter(1.2); }
+      if (event.key === "-") { event.preventDefault(); zoomAboutCenter(1 / 1.2); }
+      if (event.key === "0") { event.preventDefault(); fit(); }
+    },
+  };
+  return { view, bind, fit, zoomBy, zoomAboutCenter, setView };
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/react/states.tsx

@@ -0,0 +1,13 @@
+import type { Model } from "../src/model.ts";
+
+export function FlowLoading() {
+  return <p role="status">Loading flow…</p>;
+}
+
+export function FlowEmpty({ model }: { model: Model }) {
+  return model.nodes.length === 0 ? <p role="status">No flow items to show.</p> : null;
+}
+
+export function FlowError({ message, onRetry }: { message: string; onRetry?: () => void }) {
+  return <div role="alert"><p>{message}</p>{onRetry && <button type="button" onClick={onRetry}>Retry</button>}</div>;
+}

package/bundles/codex/.codex/skills/frontend/flow-studio/references/design-language.md

@@ -0,0 +1,169 @@
+# Design language
+
+Grounded in `src/styles.css`. This document defines the visual design system, CSS custom properties, typography, spatial scales, state encodings, motion catalogue, and dark theme strategy for flow-studio.
+
+## 1. Design tokens
+
+Tokens are defined on `:root` and adapted for dark mode via `@media (prefers-color-scheme: dark)` and `:root[data-theme="dark"]`.
+
+| Token | Light value | Dark value | Description / Purpose |
+|---|---|---|---|
+| `--bg` | `#f6f8fa` | `#0d1117` | Canvas and page background |
+| `--panel` | `#ffffff` | `#161b22` | Cards, drawer, top header, surfaces |
+| `--panel2` | `#f6f8fa` | `#0d1117` | Secondary surface, subtle contrast, table header |
+| `--fg` | `#1f2328` | `#e6edf3` | Primary text and foreground elements |
+| `--muted` | `#59636e` | `#9198a1` | Secondary text, captions, inactive icons |
+| `--edge` | `#d0d7de` | `#30363d` | Element borders, tool dividers, card outlines |
+| `--rule` | `#d8dee4` | `#2b323a` | Dividers, grid separators, table borders |
+| `--accent` | `#0969da` | `#4493f8` | Primary brand accent, selected state, hot trails |
+| `--accent-solid` | `#0969da` | `#1f6feb` | Solid button background, active tab pill |
+| `--ok` | `#1a7f37` | `#3fb950` | Healthy, passed, on-time indicators |
+| `--warn` | `#9a6700` | `#d29922` | Warning, degraded, late indicators |
+| `--crit` | `#cf222e` | `#f85149` | Critical failure, breach, error indicators |
+| `--up` | `#0a7ea4` | `#6fcbe6` | Upstream relation count and badge color |
+| `--down` | `#8250df` | `#d0a0ee` | Downstream relation count and notes marker |
+| `--glow` | `rgba(9,105,218,.22)` | `rgba(68,147,248,.35)` | Accent halo for selection, hover, and canvas focus |
+| `--shadow` | `0 1px 0 rgba(31,35,40,.04), 0 6px 18px rgba(31,35,40,.08)` | `0 1px 0 rgba(0,0,0,.4), 0 8px 24px rgba(0,0,0,.45)` | Elevated card and modal elevation shadow |
+| `--grid` | `rgba(31,35,40,.035)` | `rgba(255,255,255,.04)` | Viewport grid pattern dots and lines |
+| `--ok-bg` | `rgba(26,127,55,.10)` | `rgba(63,185,80,.12)` | Subtle tinted background for healthy states |
+| `--warn-bg` | `rgba(154,103,0,.10)` | `rgba(210,153,34,.14)` | Subtle tinted background for warning states |
+| `--crit-bg` | `rgba(207,34,46,.08)` | `rgba(248,81,73,.12)` | Subtle tinted background for critical states |
+| `--info-bg` | `rgba(9,105,218,.10)` | `rgba(68,147,248,.14)` | Subtle tinted background for informational badges |
+| `--mono` | `"IBM Plex Mono", ui-monospace, ...` | Same | Monospace font family for metrics, counters, and code |
+
+---
+
+## 2. Typography scale
+
+Flow-studio uses system sans-serif (`Inter, "Segoe UI", system-ui, -apple-system, sans-serif`) for readable text and `--mono` for tabular numerals and technical metadata.
+
+| Role | Size | Weight | Line height | Letter spacing | Font family |
+|---|---|---|---|---|---|
+| Page title (`h1`) | 20px | 700 | 1.2 | normal | Sans-serif |
+| KPI / Tile numbers (`.tn`, `.cn`) | 20px | 600 | 1.1 | tabular-nums | Sans-serif |
+| Inspector node title (`.nname`) | 15px | 600 | 1.25 | normal | Sans-serif |
+| Drawer heading (`#drawer h2`) | 15px | 700 | 1.3 | normal | Sans-serif |
+| Body / Default | 14px | 400 | 1.45 | normal | Sans-serif |
+| Card title (`.node .t`) | 13px | 600 | 1.25 | normal | Sans-serif |
+| Lane label (`.bandlabel b`) | 13px | 700 | 1.2 | normal | Sans-serif |
+| Card subtitle / state (`.node .s`) | 12px | 400 | 1.3 | normal | Sans-serif |
+| Help text / Footer | 12px | 400 | 1.4 | normal | Sans-serif |
+| Column header (`#cols .hd`) | 10.5px | 700 | 1.2 | 0.08em (caps) | Sans-serif |
+| Phase pill (`#cols .ph`) | 10px | 700 | 1.2 | 0.14em (caps) | Sans-serif |
+| Evidence / Badges (`.ev`, `.pill`) | 9.5px to 10.5px | 700 | 1.2 | 0.03em (caps) | Sans-serif |
+| Metric badges & code (`.mono`, `code`) | 11px to 11.5px | 500 | 1.2 | normal | Monospace |
+
+---
+
+## 3. Spacing scale
+
+Layout elements follow a strict 4px grid rhythm:
+
+| Scale | Value | Typical usage |
+|---|---|---|
+| 2xs | 2px to 4px | Inline icon gaps, badge vertical padding, bottom border highlights |
+| xs | 4px to 7px | Button vertical padding (`4px 11px`), card vertical padding (`5px 10px 7px`), playbar gaps (`7px`) |
+| sm | 8px to 10px | Card horizontal padding (`10px`), toolbar item gaps, summary grid gaps |
+| md | 12px to 16px | Page padding (`12px 14px 20px`), header gaps, inspector body padding |
+| lg | 20px to 28px | Section margins, top header padding, grid line pitch (28px canvas grid) |
+| xl | 32px to 44px | Column header heights (44px), tool button dimensions (34px x 32px) |
+
+---
+
+## 4. Border radius and shadow tiers
+
+### Border radius
+- **Sharp (0px):** Segmented buttons inside groups, summary tiles inside strips, tools.
+- **Small (6px):** Buttons, search inputs, dropdowns, segmented group wrappers.
+- **Medium (8px):** Node cards (`.node`).
+- **Pill (9px to 10px):** Edge labels (`.elabel`), lane bands (`.band` radius 10px).
+- **Large (12px):** Workspace container (`.workspace`).
+- **Circular (50%):** Markers, status dots, tokens, and avatar chips.
+
+### Shadow tiers
+- **Subtle border shadow (`var(--shadow)`):** `0 1px 0 rgba(31,35,40,.04), 0 6px 18px rgba(31,35,40,.08)` (Light) / `0 1px 0 rgba(0,0,0,.4), 0 8px 24px rgba(0,0,0,.45)` (Dark).
+- **Interactive hover:** `box-shadow: 0 0 0 3px var(--glow), var(--shadow)`.
+- **Slide-in drawer elevation:** `box-shadow: -14px 0 34px rgba(0,0,0,.16), -1px 0 0 var(--glow)`.
+- **Marker pulse halo:** `box-shadow: 0 0 0 3px rgba(130,80,223,.3)`.
+
+---
+
+## 5. Glow tiers
+
+Glows communicate focus, connection, and selection:
+1. **Normal:** `box-shadow: 0 0 14px -4px color-mix(in srgb, <tone> 55%, transparent)` on healthy or highlighted cards.
+2. **Hover:** `box-shadow: 0 0 0 3px var(--glow)` with border color change to `--accent`.
+3. **Selected / Lit:** `box-shadow: 0 0 0 2px var(--glow), 0 0 18px var(--glow)` plus animated ripple or trail.
+
+---
+
+## 6. State encoding table
+
+The engine generates CSS from 12 canonical domain states defined in `src/stateCss.ts`:
+
+| State ID | Tone | Border Style | Edge Style | Motion | Bucket | Semantic Meaning |
+|---|---|---|---|---|---|---|
+| `ok` | `ok` | `solid` | `flow` | `flow` | `good` | Fully healthy, active, operational |
+| `healthy` | `ok` | `solid` | `flow` | `flow` | `good` | System running within normal operating SLAs |
+| `planned` | `muted` | `dashed` | `dash` | `flow-slow` | `neutral` | Future work or planned integration |
+| `in-progress` | `accent` | `solid` | `flow` | `flow` | `neutral` | Actively processing or undergoing update |
+| `waiting` | `warn` | `dashed` | `dash-short` | `breathe` | `neutral` | Blocked on upstream dependency or approval |
+| `late` | `warn` | `solid` | `flow` | `flow` | `neutral` | Running behind schedule but executing |
+| `degraded` | `warn` | `dashed` | `dash` | `breathe` | `neutral` | Performance or capacity reduced |
+| `failed` | `crit` | `solid` | `flow` | `flow` | `gap` | Execution halted due to fatal defect |
+| `breached` | `crit` | `solid` | `flow` | `flow` | `gap` | SLA threshold crossed |
+| `blocked` | `crit` | `dashed` | `dot` | `none` | `gap` | Cannot proceed due to hard impediment |
+| `unknown` | `warn` | `dotted` | `dot` | `breathe` | `gap` | No telemetry or unverified source |
+| `skipped` | `muted` | `dotted` | `dot` | `none` | `neutral` | Deliberately omitted execution step |
+
+---
+
+## 7. Motion catalogue
+
+`src/styles.css` defines 12 `@keyframes`; the count treats the three flow dash variants (`flow`, `flowd`, `flowc`) separately. Motion is never decorative; every animation carries status information.
+
+| Animation name | Duration | Easing | Meaning / State Carried |
+|---|---|---|---|
+| `beat` | 2.6s | ease (default), infinite | Live indicator pulse on the header brand dot. Indicates the engine session is active. |
+| `fadein` | 0.6s / 1s (0.5s delay) | ease (default) | Lane bands and the edge layer fade in during initial canvas load. |
+| `rise` | 0.5s / 0.55s / 1.2s | ease (default) / ease-out | Cards, tiles and summary cells enter with subtle upward movement (`translateY(8px)` to `none`); `1.2s` marks a node added by a live update. |
+| `flow` | 3s or 7s | linear infinite | Dash-offset marching on links whose state has `edge: "flow"` (`3s` with `motion: "flow"`, `7s` with `motion: "flow-slow"`). Indicates active data transit. |
+| `flowd` | 3s or 7s | linear infinite | Same marching for `edge: "dash"` links. |
+| `flowc` | 3s or 7s | linear infinite | Same marching for `edge: "dash-short"` links. |
+| `flowhot` | 0.9s | linear infinite | Faster marching on highlighted (hot) edges: search trails, relations, playback. |
+| `selpulse` | 2.4s / 1.8s | ease-out infinite | Expanding glowing ring around a selected card (`2.4s`) or the active playback node (`1.8s`). |
+| `breathe` | 3.2s | ease-in-out infinite | Soft pulsing box-shadow on warning or waiting nodes (`color-mix` with `--warn` or the state tone). |
+| `failflash` | 0.9s | ease-out 1 | Red box-shadow burst indicating SLA breach or what-if blast-radius failure. |
+| `newring` | 1.2s / 1.8s | ease-out 1 | Accent ring on a node changed by a live update (`1.2s`) or newly appeared in a view (`1.8s`). |
+| `ring` | - | - | Defined but referenced by no rule today; reserved. |
+
+---
+
+## 8. Reduced motion fallback rules
+
+Accessibility rules respect user OS preferences:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation: none !important;
+    transition: none !important;
+  }
+  path.edge.hot {
+    stroke-dasharray: none;
+  }
+}
+```
+
+- When reduced motion is active, token animations are immediate without transitions.
+- Selection rings remain solid outlines without pulsating box-shadows.
+- Links show solid or static dashed strokes without moving dashes.
+
+---
+
+## 9. Dark theme strategy
+
+1. The page listens to system preference: `@media (prefers-color-scheme: dark)` applies dark tokens to `:root:not([data-theme="light"])`.
+2. Manual override is supported via the `data-theme="dark"` attribute set on `<html>` or `:root`.
+3. The theme toggle button switches between light and dark without page reload.
+4. Colors do not invert naively; backgrounds use `#0d1117`, card panels use `#161b22`, borders use `#30363d`, and semantic colors (ok, warn, crit) use high-contrast luminance tuned for dark backgrounds.