@cardenelabs/cdl 0.5.0

package/src/builder.ts

@@ -0,0 +1,3740 @@
+import { parseFormula } from "./formula";
+import type {
+  CdlDiagram,
+  CdlEdge,
+  CdlEventBinding,
+  CdlEventTarget,
+  CdlFormula,
+  CdlInput,
+  CdlLane,
+  CdlNode,
+  CdlPhase,
+  CdlReadout,
+  CdlScrollTrigger,
+  CdlState,
+  EdgeStyle,
+  NodeKind,
+  Side,
+  Tone,
+} from "./types";
+
+/**
+ * repeatNodes template で `{i}` / `{i+1}` / `{i-1}` を index に置換する (CAR: repeat primitive)。
+ * template 経由で source: 'gas{i+1}' のように書けば、 iteration 毎に gas1 / gas2 / gas3 が生成される。
+ */
+function substituteI(input: string, i: number): string {
+  return input.replace(/\{i([+-]\d+)?\}/g, (_, offset) => {
+    if (!offset) return String(i);
+    return String(i + Number(offset));
+  });
+}
+
+/**
+ * template で `{r}` / `{c}` / `{r+1}` 等の変数を置換する generic helper (grid用)。
+ */
+function substituteVars(input: string, vars: Record<string, string>): string {
+  return input.replace(/\{([a-z])([+-]\d+)?\}/g, (m, k, offset) => {
+    if (!(k in vars)) return m;
+    const base = Number(vars[k]);
+    if (Number.isNaN(base)) return vars[k] ?? m;
+    if (!offset) return String(base);
+    return String(base + Number(offset));
+  });
+}
+
+function deepSubstituteVars<T>(obj: T, vars: Record<string, string>): T {
+  if (typeof obj === "string") return substituteVars(obj, vars) as unknown as T;
+  if (Array.isArray(obj)) return obj.map((el) => deepSubstituteVars(el, vars)) as unknown as T;
+  if (obj !== null && typeof obj === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(obj as Record<string, unknown>)) {
+      out[key] = deepSubstituteVars((obj as Record<string, unknown>)[key], vars);
+    }
+    return out as T;
+  }
+  return obj;
+}
+
+/**
+ * recursive に object / array 内の string field の `{i}` を substituteI で置換する。
+ * 非 string field はそのまま。 primitive (number / boolean / undefined) もそのまま。
+ */
+function deepSubstituteI<T>(obj: T, i: number): T {
+  if (typeof obj === "string") return substituteI(obj, i) as unknown as T;
+  if (Array.isArray(obj)) return obj.map((el) => deepSubstituteI(el, i)) as unknown as T;
+  if (obj !== null && typeof obj === "object") {
+    const out: Record<string, unknown> = {};
+    for (const key of Object.keys(obj as Record<string, unknown>)) {
+      out[key] = deepSubstituteI((obj as Record<string, unknown>)[key], i);
+    }
+    return out as T;
+  }
+  return obj;
+}
+
+/**
+ * built diagram の interactive spec 部分だけを deep clone + recursive freeze する SSOT (CAR #260)。
+ *
+ * 対象は `inputs` / `formulas` / `scrollTriggers` / `eventBindings` の 4 array のみ。
+ * これらは interactive integration の schemaKey memoize (`useMemo(fn, [diagram])`) が
+ * identity dep で in-place mutation を検知できない regression の根本原因。 4 array だけを
+ * freeze することで:
+ *   - `d.inputs[0].defaultValue = 999` 等の mutation は throw で検知
+ *   - schemaKey が 4 array を JSON.stringify する経路と対応
+ *
+ * `lanes` / `nodes` / `edges` / `states` / `phases` は freeze しない。 dragon compile.ts 等の
+ * upstream compiler が build() 後に inline extension (`node.subtitle = ...` 等) を merge する
+ * 既存 API を破らないため。 これらは interactive integration の schemaKey に影響しないため
+ * mutation されても schemaKey stale regression は起きない (compile → layout → LaidNode に
+ * 変換される時点で内容が copy される、 render 時は LaidNode を参照する)。
+ *
+ * 2 step の設計:
+ *   1. 対象 array を `structuredClone` で完全独立 copy を作る (builder accumulator + 外部 leak 遮断)
+ *   2. `recursiveFreeze(clone)` で 2 段目 nested (formulas[0].expression 等) まで freeze
+ */
+function recursiveFreeze<T>(obj: T, seen: WeakSet<object>): T {
+  if (obj === null || typeof obj !== "object") return obj;
+  const asObj = obj as unknown as object;
+  if (seen.has(asObj)) return obj;
+  seen.add(asObj);
+  Object.freeze(obj);
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      recursiveFreeze(item, seen);
+    }
+  } else {
+    for (const key of Object.keys(obj as Record<string, unknown>)) {
+      const v = (obj as Record<string, unknown>)[key];
+      if (v !== null && typeof v === "object") recursiveFreeze(v, seen);
+    }
+  }
+  return obj;
+}
+
+function freezeInteractiveSpec<T>(arr: readonly T[] | undefined): readonly T[] | undefined {
+  if (!arr) return arr;
+  const cloned =
+    typeof structuredClone === "function"
+      ? (structuredClone(arr) as T[])
+      : (JSON.parse(JSON.stringify(arr)) as T[]);
+  return recursiveFreeze(cloned, new WeakSet<object>()) as readonly T[];
+}
+
+/**
+ * 有限値 (Number.isFinite) を要求する fail-fast helper (CAR #263)。 NaN / Infinity /
+ * -Infinity は input / scroll spec の source として無効、 受け入れると:
+ *   - JSON.stringify(NaN) / (Infinity) が同じ "null" に潰れ、 schemaKey 衝突
+ *   - range check (`x < 0 || x > 1`) が NaN で silent pass する
+ * ため builder 層で throw する。
+ */
+function assertFiniteNumber(value: number, context: string): void {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(
+      `[cdl] ${context} は有限数値である必要があります (got: ${String(value)})`,
+    );
+  }
+}
+
+function deepFreezeDiagram(diagram: CdlDiagram): CdlDiagram {
+  return {
+    ...diagram,
+    ...(diagram.inputs ? { inputs: freezeInteractiveSpec(diagram.inputs) as CdlInput[] } : {}),
+    ...(diagram.formulas
+      ? { formulas: freezeInteractiveSpec(diagram.formulas) as CdlFormula[] }
+      : {}),
+    ...(diagram.scrollTriggers
+      ? { scrollTriggers: freezeInteractiveSpec(diagram.scrollTriggers) as CdlScrollTrigger[] }
+      : {}),
+    ...(diagram.eventBindings
+      ? { eventBindings: freezeInteractiveSpec(diagram.eventBindings) as CdlEventBinding[] }
+      : {}),
+  };
+}
+
+// ─── Animation chain (scroll-driven trigger + 将来的な animation primitive、 CAR #245) ───
+
+/**
+ * `.animation.scroll(id, opts)` を提供する chain-facing helper。 将来 `.animation.time(...)` 等の
+ * time-based primitive を追加する余地を残すため animation namespace として分離。
+ */
+export type AnimationChain = {
+  scroll: (
+    id: string,
+    opts?: { start?: number; end?: number; scrub?: number; label?: string },
+  ) => DiagramBuilder;
+};
+
+// ─── Event handler chain (`.on.click(target, handlerId)`、 CAR #246) ───
+
+/**
+ * `.on.click(target, handlerId)` / `.on.hover(target, handlerId)` を提供する chain helper。
+ * target は node / edge / lane / diagram の 4 種、 handlerId は string で consumer が attach 時に
+ * 対応関数 map を渡す (JSON DSL 互換のため関数は diagram data model に含めない)。
+ */
+export type EventChain = {
+  click: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  hover: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  doubleClick: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  longPress: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  drag: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  drop: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  keydown: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  focus: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+  blur: (target: CdlEventTarget, handlerId: string) => DiagramBuilder;
+};
+
+// ─── Input widget builder (interactive primitive、 CAR #243) ───
+
+/**
+ * `.input.slider()` / `.number()` / `.dropdown()` / `.toggle()` を提供する chain-facing helper。
+ * 各 method は widget spec を `CdlInput` として累積し、 DiagramBuilder を返して chain 継続を許す。
+ */
+/**
+ * ReadoutChain = visual readout widget を diagram に追加する chain (CAR: widget 拡充)。
+ * 各 method は CdlReadout として累積する。
+ */
+export type ReadoutChain = {
+  bar: (
+    id: string,
+    opts: { source: string; min: number; max: number; color?: string; label?: string },
+  ) => DiagramBuilder;
+  gauge: (
+    id: string,
+    opts: { source: string; min: number; max: number; color?: string; label?: string },
+  ) => DiagramBuilder;
+  stat: (
+    id: string,
+    opts: { source: string; caption?: string; unit?: string; label?: string },
+  ) => DiagramBuilder;
+  sparkline: (
+    id: string,
+    opts: { source: string; history?: number; color?: string; label?: string },
+  ) => DiagramBuilder;
+  countup: (
+    id: string,
+    opts: { source: string; durationMs?: number; decimals?: number; unit?: string; label?: string },
+  ) => DiagramBuilder;
+  typewriter: (
+    id: string,
+    opts: { source: string; charMs?: number; label?: string },
+  ) => DiagramBuilder;
+  delta: (
+    id: string,
+    opts: { source: string; decimals?: number; unit?: string; label?: string },
+  ) => DiagramBuilder;
+  percentRing: (
+    id: string,
+    opts: { source: string; max: number; color?: string; label?: string },
+  ) => DiagramBuilder;
+  heatCell: (
+    id: string,
+    opts: { source: string; min: number; max: number; colors?: readonly string[]; label?: string },
+  ) => DiagramBuilder;
+  badge: (
+    id: string,
+    opts: { source: string; colorSource?: string; map?: readonly { value: string; color: string }[]; label?: string },
+  ) => DiagramBuilder;
+  statusDot: (
+    id: string,
+    opts: { source: string; map: readonly { value: string; color: string; label?: string }[]; label?: string },
+  ) => DiagramBuilder;
+  /** SVG path を signal の 0-100 進行率で stroke-dashoffset animation */
+  pathProgress: (
+    id: string,
+    opts: {
+      source: string;
+      pathD: string;
+      viewW?: number;
+      viewH?: number;
+      strokeWidth?: number;
+      color?: string;
+      max?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** array signal を bullet list 表示 (各 element を row 化) */
+  arrayList: (
+    id: string,
+    opts: { source: string; itemTemplate?: string; max?: number; label?: string },
+  ) => DiagramBuilder;
+  /** array signal の各 element を bar 高さで並列表示 (histogram 的) */
+  arrayBar: (
+    id: string,
+    opts: { source: string; min: number; max: number; color?: string; label?: string },
+  ) => DiagramBuilder;
+  /** array signal を line chart (折れ線 + optional area fill) */
+  lineChart: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      fill?: boolean;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 2 array signal を並列 bar で比較 (A/B histogram) */
+  stackedBar: (
+    id: string,
+    opts: {
+      sourceA: string;
+      sourceB: string;
+      min: number;
+      max: number;
+      colorA?: string;
+      colorB?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** array signal を左から累積、 element 差分を bar 表示 (財務 waterfall chart 用) */
+  waterfall: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      colorPos?: string;
+      colorNeg?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 2D array signal を色 gradient cell で表示 (confusion matrix / heatmap) */
+  matrix: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      cellSize?: number;
+      colors?: readonly string[];
+      showValue?: boolean;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** array signal を progress bar list として表示 (task list progress) */
+  progressGroup: (
+    id: string,
+    opts: {
+      source: string;
+      max: number;
+      labelSource?: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** array signal を横 timeline event marker で表示 (login → auth → response 系 flow) */
+  sequenceTimeline: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** N 次元 array を polygon spider chart で表示 */
+  radar: (
+    id: string,
+    opts: {
+      source: string;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      labelSource?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 3D data (x, y, r) を bubbles で表示 */
+  bubbleChart: (
+    id: string,
+    opts: {
+      source: string;
+      xMin: number;
+      xMax: number;
+      yMin: number;
+      yMax: number;
+      rMin: number;
+      rMax: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** array を multi-segment donut chart で表示 (percent-ring の N 分割版) */
+  donut: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      colors?: readonly string[];
+      innerRatio?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 1 年分の日次 count を GitHub-style contribution heatmap で表示 (53 週 × 7 日) */
+  calendarHeatmap: (
+    id: string,
+    opts: {
+      source: string;
+      max: number;
+      cellSize?: number;
+      cellGap?: number;
+      colors?: readonly string[];
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 大 canvas 上の viewport rect を縮小表示 (overview 用) */
+  miniMap: (
+    id: string,
+    opts: {
+      source: string;
+      canvasW: number;
+      canvasH: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 現在値 + 直前値との delta + mini sparkline を 1 tile に composite (dashboard KPI 単体) */
+  kpiCard: (
+    id: string,
+    opts: {
+      source: string;
+      historySource: string;
+      comparisonSource: string;
+      unit?: string;
+      colorPos?: string;
+      colorNeg?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** OHLC array を蝋燭足 (candlestick chart) で表示 (finance 用) */
+  candlestick: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      colorUp?: string;
+      colorDown?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 2-set Venn diagram (`[|A|, |B|, |A∩B|]`) */
+  venn: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      colorA?: string;
+      colorB?: string;
+      labelA?: string;
+      labelB?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** before/after slope chart (`[[before, after, name], ...]`) */
+  slope: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      colorUp?: string;
+      colorDown?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** conversion funnel chart (`[[stage, count], ...]`) */
+  funnel: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      colorTop?: string;
+      colorBottom?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** gantt task timeline (`[[name, start, duration], ...]`) */
+  gantt: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** treemap hierarchical rectangles (`[[name, size], ...]`) */
+  treemap: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      colors?: readonly string[];
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 2 column sankey flow diagram (`[[fromName, toName, flow], ...]`) */
+  sankey: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      colors?: readonly string[];
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** nightingale rose polar area chart */
+  polarArea: (
+    id: string,
+    opts: {
+      source: string;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      colors?: readonly string[];
+      labelSource?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** wizard step indicator (current index + step names) */
+  stepIndicator: (
+    id: string,
+    opts: {
+      source: string;
+      stepsSource: string;
+      viewW?: number;
+      viewH?: number;
+      colorActive?: string;
+      colorPending?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** bullet-chart (KPI actual vs target + 3 range) */
+  bulletChart: (
+    id: string,
+    opts: {
+      source: string;
+      targetSource: string;
+      max: number;
+      rangeBad?: number;
+      rangeAvg?: number;
+      viewW?: number;
+      viewH?: number;
+      colorActual?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 大 numeric display (scoreboard style) */
+  numberBoard: (
+    id: string,
+    opts: {
+      source: string;
+      prefix?: string;
+      suffix?: string;
+      size?: number;
+      color?: string;
+      caption?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** ranked list (top-N with medal decoration) */
+  leaderboard: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 3-color status indicator (traffic light) */
+  trafficLight: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** weighted tag cloud (`[[tag, weight], ...]`) */
+  tagCloud: (
+    id: string,
+    opts: {
+      source: string;
+      minSize?: number;
+      maxSize?: number;
+      colors?: readonly string[];
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** activity feed (`[[actor, action, time], ...]`) */
+  activityFeed: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** N star rating display (half-star 対応) */
+  rating: (
+    id: string,
+    opts: {
+      source: string;
+      count?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** alert card (info/warn/error/success 4 kind + title + body) */
+  notification: (
+    id: string,
+    opts: {
+      kindSource: string;
+      titleSource: string;
+      bodySource?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** git commit style +N / -N counter */
+  diffCounter: (
+    id: string,
+    opts: {
+      additionsSource: string;
+      deletionsSource: string;
+      colorAdd?: string;
+      colorDel?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** conversation thread (`[[author, text, isSelf], ...]`) */
+  chatBubble: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      colorSelf?: string;
+      colorOther?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** user avatar circle (initials + color) */
+  avatar: (
+    id: string,
+    opts: {
+      source: string;
+      size?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** checklist (`[[label, checked], ...]`) with progress % */
+  checklist: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 270° dial gauge (speedometer / tachometer) */
+  circularGauge: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      unit?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** e-commerce price tag (old/new/discount%) */
+  priceTag: (
+    id: string,
+    opts: {
+      oldSource: string;
+      newSource: string;
+      currency?: string;
+      colorNew?: string;
+      colorOld?: string;
+      colorDiscount?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** loading spinner (running/done/error) + text */
+  spinner: (
+    id: string,
+    opts: {
+      source: string;
+      textSource: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** letter grade (A/B/C/D/F) with color band */
+  grade: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** MM:SS.ms timer display */
+  stopwatch: (
+    id: string,
+    opts: {
+      source: string;
+      runningSource?: string;
+      size?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** confidence meter (0-100% + 3 color band) */
+  confidenceMeter: (
+    id: string,
+    opts: {
+      source: string;
+      lowThreshold?: number;
+      highThreshold?: number;
+      viewW?: number;
+      viewH?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** emoji reaction bar (`[[emoji, count], ...]`) */
+  reactionBar: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** small pill badges list (string array or `[[label, color], ...]`) */
+  pillGroup: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** segmented battery/fuel bar (0-100% + 3 color band) */
+  fuelBar: (
+    id: string,
+    opts: {
+      source: string;
+      segments?: number;
+      lowThreshold?: number;
+      highThreshold?: number;
+      viewW?: number;
+      viewH?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 2x2 stat grid (`[[name, value, unit?], ...]`) */
+  metricsGrid: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** vertical thermometer (min-max normalized) */
+  thermometer: (
+    id: string,
+    opts: {
+      source: string;
+      min: number;
+      max: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      unit?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** icon + label + value tiles (`[[icon, label, value], ...]`) */
+  iconTile: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** crypto/asset token list (`[[icon, name, amount, deltaPct], ...]`) */
+  tokenList: (
+    id: string,
+    opts: {
+      source: string;
+      colorUp?: string;
+      colorDown?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 2D map pins (`[[name, x, y], ...]`) */
+  mapPin: (
+    id: string,
+    opts: {
+      source: string;
+      xMin: number;
+      xMax: number;
+      yMin: number;
+      yMax: number;
+      viewW?: number;
+      viewH?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** priority badge (high/med/low + optional label text) */
+  priorityBadge: (
+    id: string,
+    opts: {
+      source: string;
+      textSource?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 1st/2nd/3rd podium (competition winners) */
+  podium: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** poll option bar (`[[option, count], ...]` + winner highlight) */
+  pollBar: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      colorWinner?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** stacked circular avatars (name array) */
+  userStack: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      size?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** git commit history (`[[sha, msg, author], ...]`) */
+  commitList: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** audio/video mini player (play/pause + progress + time) */
+  mediaPlayer: (
+    id: string,
+    opts: {
+      source: string;
+      durationSource: string;
+      playingSource: string;
+      color?: string;
+      viewW?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** event stream log (`[[timestamp, severity, msg], ...]`) */
+  eventLog: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** search result hits (`[[title, snippet, url], ...]`) */
+  searchResult: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** quarterly roadmap Q1-Q4 (`[[quarter, [items]], ...]`) */
+  roadmap: (
+    id: string,
+    opts: {
+      source: string;
+      viewW?: number;
+      viewH?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 5-day weather forecast (`[[day, icon, high, low], ...]`) */
+  weatherForecast: (
+    id: string,
+    opts: {
+      source: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** video card list (`[[emoji, title, duration, viewCount], ...]`) */
+  videoCard: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** order tracking steps (current step index + step names) */
+  orderStatus: (
+    id: string,
+    opts: {
+      source: string;
+      stepsSource: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** attendance grid (rows=days, cols=members) */
+  attendanceGrid: (
+    id: string,
+    opts: {
+      source: string;
+      membersSource: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** multi-timezone clock (`[[city, offsetHours, HH:MM], ...]`) */
+  timezoneClock: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** form field summary (`[[fieldName, value], ...]`) */
+  formSummary: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** song playlist queue with current index highlight */
+  songQueue: (
+    id: string,
+    opts: {
+      source: string;
+      currentSource?: string;
+      max?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 1 month calendar view (day cells + event dots + today border) */
+  calendarMonth: (
+    id: string,
+    opts: {
+      source: string;
+      monthName?: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** CLI terminal output (`[[prompt, cmd, output], ...]`) */
+  terminal: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 8×8 chess board with piece placement */
+  chessBoard: (
+    id: string,
+    opts: {
+      source: string;
+      cellSize?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 3 column kanban board (Todo / In Progress / Done) */
+  kanbanBoard: (
+    id: string,
+    opts: {
+      source: string;
+      columnWidth?: number;
+      max?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** navigation breadcrumb (Home > Docs > API pattern) */
+  breadcrumb: (
+    id: string,
+    opts: {
+      source: string;
+      currentSource?: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 縦 timeline (dot + line + event text) */
+  timelineVertical: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      max?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 時系列 status 遷移 strip (Active/Idle/Error 等) */
+  statusTimeline: (
+    id: string,
+    opts: {
+      source: string;
+      colorMap?: Array<{ status: string; color: string }>;
+      max?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 7-day mini calendar (week view) */
+  calendarWeek: (
+    id: string,
+    opts: {
+      source: string;
+      cellSize?: number;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 2 KPI horizontal comparison bar (A vs B) */
+  kpiComparison: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      colorA?: string;
+      colorB?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** numbered step + progress line (wizard progress) */
+  stepProgress: (
+    id: string,
+    opts: {
+      source: string;
+      stepsSource: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** user list + online/away/offline presence dot */
+  userPresence: (
+    id: string,
+    opts: {
+      source: string;
+      max?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** thumbs up/down rating (2 count + up %) */
+  ratingThumb: (
+    id: string,
+    opts: {
+      source: string;
+      colorUp?: string;
+      colorDown?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** organization hierarchy 3 level (root/mid/leaf) */
+  orgChartMini: (
+    id: string,
+    opts: {
+      source: string;
+      color?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** KPI current + delta + sparkline を 1 tile */
+  kpiTrendTile: (
+    id: string,
+    opts: {
+      source: string;
+      prevSource: string;
+      historySource: string;
+      unit?: string;
+      colorPos?: string;
+      colorNeg?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 3-4 emoji poll (👍/❤️/🎉 等) */
+  quickPollEmoji: (
+    id: string,
+    opts: {
+      source: string;
+      colorWinner?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** voice message playback UI (waveform bars + play + duration) */
+  voiceMessage: (
+    id: string,
+    opts: {
+      source: string;
+      progressSource?: string;
+      duration?: number;
+      colorPlay?: string;
+      colorBar?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** thread summary card (unread + participants + last author + time ago) */
+  threadSummary: (
+    id: string,
+    opts: {
+      source: string;
+      colorUnread?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** message read receipt (single / double check) */
+  readReceipt: (
+    id: string,
+    opts: {
+      source: string;
+      colorRead?: string;
+      colorPending?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** password strength 4-level meter */
+  passwordStrength: (
+    id: string,
+    opts: {
+      source: string;
+      colorStrong?: string;
+      colorWeak?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** 6-digit OTP input box grid */
+  otpInput: (
+    id: string,
+    opts: {
+      source: string;
+      colorFocus?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** file drag-and-drop upload zone */
+  fileDropzone: (
+    id: string,
+    opts: {
+      source: string;
+      colorActive?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** real-time log tail (5 rows, level color) */
+  logStream: (
+    id: string,
+    opts: {
+      source: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** severity alert banner (info / success / warn / error) */
+  alertBanner: (
+    id: string,
+    opts: {
+      source: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** service health matrix (down / degraded / up) */
+  serviceHealth: (
+    id: string,
+    opts: {
+      source: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** shopping cart summary (items / subtotal / shipping / total) */
+  cartSummary: (
+    id: string,
+    opts: {
+      source: string;
+      currency?: string;
+      colorTotal?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** pricing tier card (name + price + 3 features + CTA) */
+  pricingTier: (
+    id: string,
+    opts: {
+      source: string;
+      colorAccent?: string;
+      currency?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** coupon code entry + apply badge */
+  couponCode: (
+    id: string,
+    opts: {
+      source: string;
+      colorApplied?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** blog article preview card (title / excerpt / author / timeAgo) */
+  articlePreview: (
+    id: string,
+    opts: {
+      source: string;
+      colorAccent?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** table of contents nav with active section highlight */
+  tocNav: (
+    id: string,
+    opts: {
+      source: string;
+      colorActive?: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** social share button row */
+  shareButtons: (
+    id: string,
+    opts: {
+      source: string;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+};
+
+export type InputChain = {
+  slider: (
+    id: string,
+    opts: { min: number; max: number; step?: number; defaultValue: number; label?: string },
+  ) => DiagramBuilder;
+  number: (
+    id: string,
+    opts: { min?: number; max?: number; defaultValue: number; label?: string },
+  ) => DiagramBuilder;
+  dropdown: (
+    id: string,
+    opts: { options: readonly string[]; defaultValue: string; label?: string },
+  ) => DiagramBuilder;
+  toggle: (
+    id: string,
+    opts: { defaultValue: boolean; label?: string },
+  ) => DiagramBuilder;
+  /** 2 軸 slider = XY pad、 単一 id で pointer position を保持 (x/y は同 signal に格納) */
+  xypad: (
+    id: string,
+    opts: {
+      xMin: number;
+      xMax: number;
+      yMin: number;
+      yMax: number;
+      defaultX: number;
+      defaultY: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  /** +/- ボタンで integer 増減、 slider より狭い変化範囲 (数値の細かい調整) */
+  stepper: (
+    id: string,
+    opts: { min?: number; max?: number; step?: number; defaultValue: number; label?: string },
+  ) => DiagramBuilder;
+  /** 排他選択、 dropdown と同じ semantics だが視覚は横並び button */
+  radio: (
+    id: string,
+    opts: { options: readonly string[]; defaultValue: string; label?: string },
+  ) => DiagramBuilder;
+  /** hex color (#RRGGBB) picker、 SVG stroke / fill に signal 経由で bind */
+  color: (
+    id: string,
+    opts: { defaultValue: string; label?: string },
+  ) => DiagramBuilder;
+  /**
+   * timeline = 時間軸を signal 化、 0..1 progress + play/pause/seek/speed 制御 UI。
+   * SVG animation を signal に紐付けて手動制御可能に。
+   */
+  timeline: (
+    id: string,
+    opts: {
+      duration: number;
+      autoplay?: boolean;
+      loop?: boolean;
+      speeds?: readonly number[];
+      defaultSpeedIdx?: number;
+      label?: string;
+    },
+  ) => DiagramBuilder;
+  range: (
+    id: string,
+    opts: { min: number; max: number; step?: number; defaultLo: number; defaultHi: number; label?: string },
+  ) => DiagramBuilder;
+  multiSelect: (
+    id: string,
+    opts: { options: readonly string[]; defaultValues: readonly string[]; label?: string },
+  ) => DiagramBuilder;
+  tabs: (
+    id: string,
+    opts: { options: readonly string[]; defaultValue: string; label?: string },
+  ) => DiagramBuilder;
+  datetime: (
+    id: string,
+    opts: { defaultValue: string; label?: string },
+  ) => DiagramBuilder;
+  text: (
+    id: string,
+    opts: { defaultValue: string; placeholder?: string; maxLength?: number; label?: string },
+  ) => DiagramBuilder;
+};
+
+// ─── Phase builder (inner fluent for activate/tween/badge) ───
+
+export type PhaseBuilder = {
+  activate: (...ids: string[]) => PhaseBuilder;
+  /** 数値 state の線形補間 (write phase で 100→90 等) */
+  tween: (stateId: string, from: number, to: number) => PhaseBuilder;
+  /** 任意型 state を即時切替 (この phase 到達で value 上書き、 lerp なし) */
+  set: (stateId: string, value: string | number) => PhaseBuilder;
+  badge: (text: string) => PhaseBuilder;
+};
+
+type PhaseAcc = {
+  activate: string[];
+  tweens: Array<{ stateId: string; from: number; to: number }>;
+  sets: Array<{ stateId: string; value: string | number }>;
+  badge?: string;
+};
+
+function makePhaseBuilder(acc: PhaseAcc): PhaseBuilder {
+  const api: PhaseBuilder = {
+    activate(...ids) {
+      acc.activate.push(...ids);
+      return api;
+    },
+    tween(stateId, from, to) {
+      acc.tweens.push({ stateId, from, to });
+      return api;
+    },
+    set(stateId, value) {
+      acc.sets.push({ stateId, value });
+      return api;
+    },
+    badge(text) {
+      acc.badge = text;
+      return api;
+    },
+  };
+  return api;
+}
+
+// ─── Diagram builder (fluent) ────────────────────────────────
+
+export type DiagramBuilder = {
+  lane: (id: string, opts: Omit<CdlLane, "id">) => DiagramBuilder;
+  node: (id: string, opts: Omit<CdlNode, "id">) => DiagramBuilder;
+  edge: (
+    from: string,
+    to: string,
+    opts: {
+      /** edge id (省略時は `${from}-${to}` ベースで auto 生成、 重複時は連番付与) */
+      id?: string;
+      label: string;
+      sub?: string;
+      /** tone (default "accent") */
+      tone?: Tone;
+      side?: Side;
+      style?: EdgeStyle;
+      /** FSM guard 条件、 text-dsl v0.5 inline option (`guard: "..."`) を CdlEdge.guard へ透過 */
+      guard?: string;
+      /** ER 関係 cardinality、 text-dsl v0.5 inline option (`cardinality: "1:N"`) を CdlEdge.cardinality へ透過 */
+      cardinality?: string;
+      labelOffsetX?: number;
+      labelOffsetY?: number;
+      routing?: "default" | "back-detour";
+      /** CAR-549 SSOT ... true で label を edge path 上に重ねる (flowchart condition label 用) */
+      overlay?: boolean;
+      /** signal binding: stroke-width template (CAR edge-signal-binding) */
+      widthBind?: string;
+      /** signal binding: stroke color template */
+      strokeBind?: string;
+      /** signal binding: stroke-dashoffset template */
+      dashOffsetBind?: string;
+    },
+  ) => DiagramBuilder;
+  /**
+   * 複数 node を 1 行で宣言する batch helper。
+   * @example .nodes([{ id: "a", lane: "l", stack: 0, kind: "actor", title: "Client" }, ...])
+   */
+  nodes: (defs: Array<{ id: string } & Omit<CdlNode, "id">>) => DiagramBuilder;
+  /**
+   * repeat = N 個の同形 node を宣言的に生成 (CAR: repeat primitive)。
+   * templateFn は index (0..count-1) を受け取って node spec を返す関数、 or template で
+   * `{i}` を書けば index に置換される。 array に対する map より typed で、 index-based signal
+   * 参照 (source: 'gas_{i}') が組める。
+   *
+   * 例: EIP1559 の gas rect 3 個並び (base の 1.0x / 1.2x / 1.5x)
+   *   .repeatNodes(3, (i) => ({
+   *     id: `rect-${i}`,
+   *     lane: `l${i+1}`,
+   *     stack: 0,
+   *     kind: 'dyn-rect',
+   *     title: `Block ${i+1}`,
+   *     shape: { kind: 'rect', source: `{gas${i+1}}`, fillMax: 100, orient: 'up' }
+   *   }))
+   */
+  repeatNodes: (
+    count: number,
+    templateFn: (i: number) => { id: string } & Omit<CdlNode, "id">,
+  ) => DiagramBuilder;
+  /**
+   * gridNodes = 2D grid で node を配置、 rows × cols で iteration index (r, c) を渡す。
+   * template で `{r}` / `{c}` / `{i}` (r*cols + c) を置換可能。 grid の見出し diagram (chess board / matrix / mesh) を宣言的に。
+   */
+  gridNodes: (
+    rows: number,
+    cols: number,
+    templateFn: (r: number, c: number, i: number) => { id: string } & Omit<CdlNode, "id">,
+  ) => DiagramBuilder;
+  /**
+   * radialNodes = 中心点周りの円周上に count 個の node を宣言的に配置 (hub-and-spoke)。
+   * templateFn は (i, angle_deg, x_offset, y_offset) を受け取り、 spec に stack 値と
+   * `{i}` / `{deg}` template 経由で id / title を組める。 SVG 座標系 (y 下向き) 前提で
+   * angle=0 が右、 90 が下、 180 が左、 270 が上。 layout 上は 1 lane に stack=i として
+   * 並べつつ、 render 側 relative offset で円形配置する想定 (consumer 側で offset を適用可)。
+   */
+  radialNodes: (
+    count: number,
+    radius: number,
+    templateFn: (
+      i: number,
+      angleDeg: number,
+      offsetX: number,
+      offsetY: number,
+    ) => { id: string } & Omit<CdlNode, "id">,
+  ) => DiagramBuilder;
+  /**
+   * treeNodes = 深さ (depth) × 分岐数 (branching) の完全 tree layout。
+   * 各 node の (level, posInLevel, i, offsetX, offsetY) を templateFn に渡す。
+   * offsetX/Y は renderOffsetX/Y として直接使える相対 pixel。 root = level 0、 leaves = level depth-1。
+   */
+  treeNodes: (
+    depth: number,
+    branching: number,
+    /** horizontal spacing (px) per leaf */
+    hSpacing: number,
+    /** vertical spacing (px) per level */
+    vSpacing: number,
+    templateFn: (
+      level: number,
+      posInLevel: number,
+      i: number,
+      offsetX: number,
+      offsetY: number,
+    ) => { id: string } & Omit<CdlNode, "id">,
+  ) => DiagramBuilder;
+  /**
+   * 複数 edge を 1 行で宣言する batch helper。
+   * @example .edges([{ from: "a", to: "b", label: "call" }, ...])
+   */
+  edges: (
+    defs: Array<{
+      from: string;
+      to: string;
+      id?: string;
+      label: string;
+      sub?: string;
+      tone?: Tone;
+      side?: Side;
+      style?: EdgeStyle;
+      guard?: string;
+      cardinality?: string;
+      labelOffsetX?: number;
+      labelOffsetY?: number;
+      routing?: "default" | "back-detour";
+      /** CAR-549 SSOT ... true で label を edge path 上に重ねる (flowchart condition label 用) */
+      overlay?: boolean;
+    }>,
+  ) => DiagramBuilder;
+  state: (id: string, opts: Omit<CdlState, "id">) => DiagramBuilder;
+  /**
+   * arraySignal = 配列を保持する signal の shortcut (SSOT)。
+   * 内部は state と同じ格納 (initial は JSON stringify)、 template では
+   *   `{sig[0]}` / `{sig.length}` / `{sig.sum}` / `{sig.max}` / `{sig.min}` / `{sig.avg}`
+   * で access する (`render/utils.ts:interpolate` の拡張規則)。
+   * event handler で update する場合は `JSON.stringify(newArray)` を setSignal に渡す。
+   */
+  arraySignal: (id: string, initial: (string | number)[]) => DiagramBuilder;
+  /**
+   * interactive input widget entry (CAR #243)。
+   * `.input.slider(id, { min, max, ... })` の様に chain して widget spec を追加する。
+   * consumer app 側の React / plain HTML が対応 signal に bind して SVG と反応させる。
+   */
+  input: InputChain;
+  /**
+   * formula primitive (CAR #244)。 safe subset の algebraic expression を diagram に追加、
+   * consumer が createFormulaComputeds() で computed 化して signal と reactive bind する。
+   * expression syntax error は本 method 内で throw (fail-fast)。
+   * 例 `.formula("gasFee", "gasBase * (1 + delta/8)")`
+   */
+  formula: (id: string, expression: string) => DiagramBuilder;
+  /**
+   * derive chain = 「連鎖形 formula」 を N 個宣言的に生成 (CAR: derive chain)。
+   * 各 iteration で `{i}` 置換と、 直前 iteration の id (`prev`) を参照可能。
+   *
+   * 例: gas1 = base、 gas2 = gas1 * 1.2、 gas3 = gas2 * 1.2 のような chain
+   *   .deriveChain('gas', 3, (i) => i === 0 ? 'base' : 'prev * 1.2')
+   *
+   * baseId は「gas1 / gas2 / gas3」 のように `gas${i+1}` として使われる、
+   * expr fn は index (0..count-1) と prev id (前 iteration の完全 id) を受け取る。
+   */
+  deriveChain: (
+    baseId: string,
+    count: number,
+    exprFn: (i: number, prev: string | null) => string,
+  ) => DiagramBuilder;
+  /**
+   * animation primitive (CAR #245)。 `.animation.scroll(id, opts)` で scroll-driven trigger を追加。
+   * 将来的に `.animation.time(...)` 等の time-based primitive を追加する余地を残す namespace。
+   */
+  animation: AnimationChain;
+  /**
+   * event handler primitive (CAR #246)。 `.on.click(target, handlerId)` / `.on.hover(...)` で
+   * DOM event handler を bind、 consumer app 側で attachEventHandlers(root, diagram, handlers) 経由で
+   * signal update 等を実行する。
+   */
+  on: EventChain;
+  /**
+   * readout primitive (visual widget for displaying signal / state values)。
+   * `.readout.bar / .gauge / .stat / .sparkline` で spec 追加、 interactive panel に描画される。
+   */
+  readout: ReadoutChain;
+  phase: (
+    id: string,
+    opts: { duration?: number; title: string; body: string },
+    build: (p: PhaseBuilder) => PhaseBuilder,
+  ) => DiagramBuilder;
+  build: () => CdlDiagram;
+};
+
+export function diagram(
+  id: string,
+  options: {
+    topic: string;
+    /**
+     * structured-data (schema.org) 抽出の対象とみなすか (既定 = `"extract"`)。
+     * figure 1 つを見せる見本など、 文章として取り出す中身を持たせるつもりが無い図に
+     * `"exclude"` を付ける。 詳細は `CdlDiagram.structuredData` の doc 参照。
+     */
+    structuredData?: "extract" | "exclude";
+  },
+): DiagramBuilder {
+  const lanes: CdlLane[] = [];
+  const nodes: CdlNode[] = [];
+  const edges: CdlEdge[] = [];
+  const states: CdlState[] = [];
+  const phases: CdlPhase[] = [];
+  const inputs: CdlInput[] = [];
+  const formulas: CdlFormula[] = [];
+  const scrollTriggers: CdlScrollTrigger[] = [];
+  const eventBindings: CdlEventBinding[] = [];
+  const readouts: CdlReadout[] = [];
+  const assertUniqueReadoutId = (rid: string) => {
+    if (readouts.some((r) => r.id === rid)) {
+      throw new Error(`readout '${rid}' 重複、 diagram 内で同 id は不可`);
+    }
+  };
+  let eventBindingCounter = 0;
+
+  const validateEventTarget = (target: CdlEventTarget, event: string) => {
+    // target の kind と id を validate (存在 check は runtime attach 側で行う、 builder では shape check のみ)
+    switch (target.kind) {
+      case "node":
+      case "edge":
+      case "lane":
+        if (!target.id) {
+          throw new Error(`event handler '${event}': target.kind '${target.kind}' には id が必須です`);
+        }
+        break;
+      case "diagram":
+        break;
+      default: {
+        // exhaustiveness check for future kind additions
+        const _exhaustive: never = target;
+        throw new Error(
+          `event handler '${event}': unsupported target kind (got ${JSON.stringify(_exhaustive)})`,
+        );
+      }
+    }
+  };
+
+  // input / formula / scrollTrigger の id は共通 name space。 collision があると createFormulaComputeds が
+  // signals → formulas の順で resolve するため、 formula 側 declaration が silent に無視されて
+  // 誤った値を返す危険 (codex Round 2 finding、 例 .input.number("x").formula("x", "x+1").formula("y", "x*2") で
+  // y が formula "x" ではなく input signal "x" を参照)。 chain の add 時点で cross-category collision を throw する。
+  const assertUniqueInputId = (inputId: string) => {
+    if (inputs.some((existing) => existing.id === inputId)) {
+      throw new Error(`input id '${inputId}' が重複しています (既存 input: ${inputs.map((i) => i.id).join(", ")})`);
+    }
+    if (formulas.some((existing) => existing.id === inputId)) {
+      throw new Error(
+        `input id '${inputId}' が formula id と衝突しています (input と formula は共通 name space、 既存 formula: ${formulas.map((f) => f.id).join(", ")})`,
+      );
+    }
+    if (scrollTriggers.some((existing) => existing.id === inputId)) {
+      throw new Error(
+        `input id '${inputId}' が scroll trigger id と衝突しています (共通 name space、 既存 scroll trigger: ${scrollTriggers.map((s) => s.id).join(", ")})`,
+      );
+    }
+  };
+
+  const assertUniqueFormulaId = (formulaId: string) => {
+    if (formulas.some((existing) => existing.id === formulaId)) {
+      throw new Error(`formula id '${formulaId}' が重複しています (既存 formula: ${formulas.map((f) => f.id).join(", ")})`);
+    }
+    if (inputs.some((existing) => existing.id === formulaId)) {
+      throw new Error(
+        `formula id '${formulaId}' が input id と衝突しています (input と formula は共通 name space、 既存 input: ${inputs.map((i) => i.id).join(", ")})`,
+      );
+    }
+    if (scrollTriggers.some((existing) => existing.id === formulaId)) {
+      throw new Error(
+        `formula id '${formulaId}' が scroll trigger id と衝突しています (共通 name space、 既存 scroll trigger: ${scrollTriggers.map((s) => s.id).join(", ")})`,
+      );
+    }
+  };
+
+  const assertUniqueScrollTriggerId = (triggerId: string) => {
+    if (scrollTriggers.some((existing) => existing.id === triggerId)) {
+      throw new Error(`scroll trigger id '${triggerId}' が重複しています (既存 scroll trigger: ${scrollTriggers.map((s) => s.id).join(", ")})`);
+    }
+    if (inputs.some((existing) => existing.id === triggerId)) {
+      throw new Error(
+        `scroll trigger id '${triggerId}' が input id と衝突しています (共通 name space、 既存 input: ${inputs.map((i) => i.id).join(", ")})`,
+      );
+    }
+    if (formulas.some((existing) => existing.id === triggerId)) {
+      throw new Error(
+        `scroll trigger id '${triggerId}' が formula id と衝突しています (共通 name space、 既存 formula: ${formulas.map((f) => f.id).join(", ")})`,
+      );
+    }
+  };
+
+  // 重複しない edge id を生成する helper (auto id 用)。
+  // 同じ from-to ペアが複数あれば連番 suffix を付ける。
+  const generateEdgeId = (from: string, to: string): string => {
+    const base = `${from}-${to}`;
+    if (!edges.some((e) => e.id === base)) return base;
+    let i = 2;
+    while (edges.some((e) => e.id === `${base}-${i}`)) i++;
+    return `${base}-${i}`;
+  };
+
+  const api: DiagramBuilder = {
+    lane(laneId, opts) {
+      lanes.push({ id: laneId, ...opts });
+      return api;
+    },
+    node(nodeId, opts) {
+      nodes.push({ id: nodeId, ...opts });
+      return api;
+    },
+    edge(from, to, opts) {
+      edges.push({
+        id: opts.id ?? generateEdgeId(from, to),
+        from,
+        to,
+        label: opts.label,
+        sub: opts.sub,
+        tone: opts.tone ?? "accent",
+        side: opts.side,
+        style: opts.style,
+        guard: opts.guard,
+        cardinality: opts.cardinality,
+        labelOffsetX: opts.labelOffsetX,
+        labelOffsetY: opts.labelOffsetY,
+        routing: opts.routing,
+        overlay: opts.overlay,
+        widthBind: opts.widthBind,
+        strokeBind: opts.strokeBind,
+        dashOffsetBind: opts.dashOffsetBind,
+      });
+      return api;
+    },
+    nodes(defs) {
+      for (const d of defs) {
+        const { id, ...rest } = d;
+        nodes.push({ id, ...rest });
+      }
+      return api;
+    },
+    treeNodes(depth, branching, hSpacing, vSpacing, templateFn) {
+      if (!Number.isInteger(depth) || depth < 1 || depth > 8) {
+        throw new Error(`treeNodes: depth (${depth}) は 1..8 の整数`);
+      }
+      if (!Number.isInteger(branching) || branching < 1 || branching > 8) {
+        throw new Error(`treeNodes: branching (${branching}) は 1..8 の整数`);
+      }
+      if (!Number.isFinite(hSpacing) || hSpacing <= 0 || !Number.isFinite(vSpacing) || vSpacing <= 0) {
+        throw new Error(`treeNodes: hSpacing/vSpacing は正の数値`);
+      }
+      // 完全 tree: level ごとの node 数 = branching^level、 総 node 数 = (b^depth - 1) / (b - 1)
+      // 各 leaf の x offset は等間隔、 各 level の親 node は子の中心に配置。
+      const leavesPerLevel: number[] = [];
+      for (let l = 0; l < depth; l++) leavesPerLevel[l] = Math.pow(branching, depth - 1 - l);
+      const totalLeaves = Math.pow(branching, depth - 1);
+      const layoutWidth = (totalLeaves - 1) * hSpacing;
+      let idx = 0;
+      for (let level = 0; level < depth; level++) {
+        const countAtLevel = Math.pow(branching, level);
+        for (let pos = 0; pos < countAtLevel; pos++) {
+          // level 内 node の x = (pos + 0.5) * (totalLeaves / countAtLevel) * hSpacing - layoutWidth/2
+          const step = (totalLeaves * hSpacing) / countAtLevel;
+          const offsetX = Math.round((pos + 0.5) * step - layoutWidth / 2 - hSpacing / 2);
+          const offsetY = Math.round(level * vSpacing);
+          const spec = templateFn(level, pos, idx, offsetX, offsetY);
+          const { id, ...rest } = spec;
+          const withI = deepSubstituteI(rest, idx);
+          const withVars = deepSubstituteVars(withI, {
+            r: String(level),
+            c: String(pos),
+          });
+          nodes.push({
+            id: substituteVars(substituteI(id, idx), { r: String(level), c: String(pos) }),
+            ...withVars,
+          } as { id: string } & Omit<CdlNode, "id">);
+          idx++;
+        }
+      }
+      return api;
+    },
+    radialNodes(count, radius, templateFn) {
+      if (!Number.isInteger(count) || count < 1 || count > 60) {
+        throw new Error(`radialNodes: count (${count}) は 1..60 の整数`);
+      }
+      if (!Number.isFinite(radius) || radius <= 0) {
+        throw new Error(`radialNodes: radius (${radius}) は正の数値`);
+      }
+      for (let i = 0; i < count; i++) {
+        const angleDeg = (360 * i) / count;
+        const rad = (angleDeg * Math.PI) / 180;
+        const offsetX = Math.round(radius * Math.cos(rad));
+        const offsetY = Math.round(radius * Math.sin(rad));
+        const spec = templateFn(i, angleDeg, offsetX, offsetY);
+        const { id, ...rest } = spec;
+        const withI = deepSubstituteI(rest, i);
+        const withDeg = deepSubstituteVars(withI, { r: String(Math.round(angleDeg)) });
+        nodes.push({
+          id: substituteVars(substituteI(id, i), { r: String(Math.round(angleDeg)) }),
+          ...withDeg,
+        } as { id: string } & Omit<CdlNode, "id">);
+      }
+      return api;
+    },
+    gridNodes(rows, cols, templateFn) {
+      if (!Number.isInteger(rows) || rows < 1 || rows > 30) {
+        throw new Error(`gridNodes: rows (${rows}) は 1..30 の整数`);
+      }
+      if (!Number.isInteger(cols) || cols < 1 || cols > 30) {
+        throw new Error(`gridNodes: cols (${cols}) は 1..30 の整数`);
+      }
+      for (let r = 0; r < rows; r++) {
+        for (let c = 0; c < cols; c++) {
+          const i = r * cols + c;
+          const spec = templateFn(r, c, i);
+          const { id, ...rest } = spec;
+          const withI = deepSubstituteI(rest, i);
+          const withR = deepSubstituteVars(withI, { r: String(r), c: String(c) });
+          nodes.push({
+            id: substituteVars(substituteI(id, i), { r: String(r), c: String(c) }),
+            ...withR,
+          } as { id: string } & Omit<CdlNode, "id">);
+        }
+      }
+      return api;
+    },
+    repeatNodes(count, templateFn) {
+      if (!Number.isInteger(count) || count < 1 || count > 100) {
+        throw new Error(`repeatNodes: count (${count}) は 1..100 の整数である必要があります`);
+      }
+      for (let i = 0; i < count; i++) {
+        const spec = templateFn(i);
+        const { id, ...rest } = spec;
+        // id と string 系 field で `{i}` / `{i+1}` を index 置換する (template 経由の書き方対応)
+        const substituted = { id: substituteI(id, i), ...deepSubstituteI(rest, i) } as {
+          id: string;
+        } & Omit<CdlNode, "id">;
+        nodes.push(substituted);
+      }
+      return api;
+    },
+    edges(defs) {
+      for (const d of defs) {
+        edges.push({
+          id: d.id ?? generateEdgeId(d.from, d.to),
+          from: d.from,
+          to: d.to,
+          label: d.label,
+          sub: d.sub,
+          tone: d.tone ?? "accent",
+          side: d.side,
+          style: d.style,
+          guard: d.guard,
+          cardinality: d.cardinality,
+          labelOffsetX: d.labelOffsetX,
+          labelOffsetY: d.labelOffsetY,
+          routing: d.routing,
+          overlay: d.overlay,
+        });
+      }
+      return api;
+    },
+    arraySignal(id, initial) {
+      if (!Array.isArray(initial)) {
+        throw new Error(`arraySignal(${id}): initial は array`);
+      }
+      states.push({ id, initial: JSON.stringify(initial) });
+      return api;
+    },
+    state(stateId, opts) {
+      states.push({ id: stateId, ...opts });
+      return api;
+    },
+    input: {
+      slider(inputId, opts) {
+        assertUniqueInputId(inputId);
+        // 非有限値 (NaN / Infinity / -Infinity) は cache key の JSON encode で "null" に
+        // 潰れて別 schema が衝突する (CAR #263)、 range check (`< 0 || > 1` 等) も NaN で
+        // silent pass する。 finiteness を先に validate して fail-fast する。
+        assertFiniteNumber(opts.min, `input.slider '${inputId}' min`);
+        assertFiniteNumber(opts.max, `input.slider '${inputId}' max`);
+        if (opts.step !== undefined) assertFiniteNumber(opts.step, `input.slider '${inputId}' step`);
+        assertFiniteNumber(opts.defaultValue, `input.slider '${inputId}' defaultValue`);
+        // slider の defaultValue は [min, max] 範囲内であるべき、 範囲外は明示 error
+        if (opts.defaultValue < opts.min || opts.defaultValue > opts.max) {
+          throw new Error(
+            `input.slider '${inputId}' の defaultValue (${opts.defaultValue}) が [${opts.min}, ${opts.max}] 範囲外です`,
+          );
+        }
+        inputs.push({
+          id: inputId,
+          kind: "slider",
+          min: opts.min,
+          max: opts.max,
+          step: opts.step,
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      number(inputId, opts) {
+        assertUniqueInputId(inputId);
+        if (opts.min !== undefined) assertFiniteNumber(opts.min, `input.number '${inputId}' min`);
+        if (opts.max !== undefined) assertFiniteNumber(opts.max, `input.number '${inputId}' max`);
+        assertFiniteNumber(opts.defaultValue, `input.number '${inputId}' defaultValue`);
+        if (opts.min !== undefined && opts.defaultValue < opts.min) {
+          throw new Error(
+            `input.number '${inputId}' の defaultValue (${opts.defaultValue}) が min (${opts.min}) 未満です`,
+          );
+        }
+        if (opts.max !== undefined && opts.defaultValue > opts.max) {
+          throw new Error(
+            `input.number '${inputId}' の defaultValue (${opts.defaultValue}) が max (${opts.max}) 超過です`,
+          );
+        }
+        inputs.push({
+          id: inputId,
+          kind: "number",
+          min: opts.min,
+          max: opts.max,
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      dropdown(inputId, opts) {
+        assertUniqueInputId(inputId);
+        if (opts.options.length === 0) {
+          throw new Error(`input.dropdown '${inputId}' の options が空です (最低 1 件必要)`);
+        }
+        if (!opts.options.includes(opts.defaultValue)) {
+          throw new Error(
+            `input.dropdown '${inputId}' の defaultValue '${opts.defaultValue}' が options に含まれません (options: ${opts.options.join(", ")})`,
+          );
+        }
+        inputs.push({
+          id: inputId,
+          kind: "dropdown",
+          options: opts.options,
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      toggle(inputId, opts) {
+        assertUniqueInputId(inputId);
+        inputs.push({
+          id: inputId,
+          kind: "toggle",
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      xypad(inputId, opts) {
+        assertUniqueInputId(inputId);
+        assertFiniteNumber(opts.xMin, `input.xypad '${inputId}' xMin`);
+        assertFiniteNumber(opts.xMax, `input.xypad '${inputId}' xMax`);
+        assertFiniteNumber(opts.yMin, `input.xypad '${inputId}' yMin`);
+        assertFiniteNumber(opts.yMax, `input.xypad '${inputId}' yMax`);
+        assertFiniteNumber(opts.defaultX, `input.xypad '${inputId}' defaultX`);
+        assertFiniteNumber(opts.defaultY, `input.xypad '${inputId}' defaultY`);
+        if (opts.defaultX < opts.xMin || opts.defaultX > opts.xMax) {
+          throw new Error(
+            `input.xypad '${inputId}' の defaultX (${opts.defaultX}) が [${opts.xMin}, ${opts.xMax}] 範囲外です`,
+          );
+        }
+        if (opts.defaultY < opts.yMin || opts.defaultY > opts.yMax) {
+          throw new Error(
+            `input.xypad '${inputId}' の defaultY (${opts.defaultY}) が [${opts.yMin}, ${opts.yMax}] 範囲外です`,
+          );
+        }
+        inputs.push({
+          id: inputId,
+          kind: "xypad",
+          xMin: opts.xMin,
+          xMax: opts.xMax,
+          yMin: opts.yMin,
+          yMax: opts.yMax,
+          defaultX: opts.defaultX,
+          defaultY: opts.defaultY,
+          label: opts.label,
+        });
+        return api;
+      },
+      stepper(inputId, opts) {
+        assertUniqueInputId(inputId);
+        if (opts.min !== undefined) assertFiniteNumber(opts.min, `input.stepper '${inputId}' min`);
+        if (opts.max !== undefined) assertFiniteNumber(opts.max, `input.stepper '${inputId}' max`);
+        if (opts.step !== undefined) assertFiniteNumber(opts.step, `input.stepper '${inputId}' step`);
+        assertFiniteNumber(opts.defaultValue, `input.stepper '${inputId}' defaultValue`);
+        if (opts.min !== undefined && opts.defaultValue < opts.min) {
+          throw new Error(
+            `input.stepper '${inputId}' の defaultValue (${opts.defaultValue}) が min (${opts.min}) 未満です`,
+          );
+        }
+        if (opts.max !== undefined && opts.defaultValue > opts.max) {
+          throw new Error(
+            `input.stepper '${inputId}' の defaultValue (${opts.defaultValue}) が max (${opts.max}) 超過です`,
+          );
+        }
+        inputs.push({
+          id: inputId,
+          kind: "stepper",
+          min: opts.min,
+          max: opts.max,
+          step: opts.step,
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      radio(inputId, opts) {
+        assertUniqueInputId(inputId);
+        if (opts.options.length === 0) {
+          throw new Error(`input.radio '${inputId}' の options が空です`);
+        }
+        if (!opts.options.includes(opts.defaultValue)) {
+          throw new Error(
+            `input.radio '${inputId}' の defaultValue '${opts.defaultValue}' が options に含まれません`,
+          );
+        }
+        inputs.push({
+          id: inputId,
+          kind: "radio",
+          options: opts.options,
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      color(inputId, opts) {
+        assertUniqueInputId(inputId);
+        // #RRGGBB / #RGB を許容
+        if (!/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(opts.defaultValue)) {
+          throw new Error(
+            `input.color '${inputId}' の defaultValue '${opts.defaultValue}' が hex color 形式 (#RGB / #RRGGBB) ではありません`,
+          );
+        }
+        inputs.push({
+          id: inputId,
+          kind: "color",
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      timeline(inputId, opts) {
+        assertUniqueInputId(inputId);
+        assertFiniteNumber(opts.duration, `input.timeline '${inputId}' duration`);
+        if (opts.duration < 100) {
+          throw new Error(`input.timeline '${inputId}' の duration は 100ms 以上必要`);
+        }
+        if (opts.speeds !== undefined && opts.speeds.length === 0) {
+          throw new Error(`input.timeline '${inputId}' の speeds が空配列です`);
+        }
+        inputs.push({
+          id: inputId,
+          kind: "timeline",
+          duration: opts.duration,
+          autoplay: opts.autoplay,
+          loop: opts.loop,
+          speeds: opts.speeds,
+          defaultSpeedIdx: opts.defaultSpeedIdx,
+          label: opts.label,
+        });
+        return api;
+      },
+      range(inputId, opts) {
+        assertUniqueInputId(inputId);
+        assertFiniteNumber(opts.min, `input.range '${inputId}' min`);
+        assertFiniteNumber(opts.max, `input.range '${inputId}' max`);
+        assertFiniteNumber(opts.defaultLo, `input.range '${inputId}' defaultLo`);
+        assertFiniteNumber(opts.defaultHi, `input.range '${inputId}' defaultHi`);
+        inputs.push({
+          id: inputId,
+          kind: "range",
+          min: opts.min,
+          max: opts.max,
+          step: opts.step,
+          defaultLo: opts.defaultLo,
+          defaultHi: opts.defaultHi,
+          label: opts.label,
+        });
+        return api;
+      },
+      multiSelect(inputId, opts) {
+        assertUniqueInputId(inputId);
+        if (opts.options.length === 0) {
+          throw new Error(`input.multiSelect '${inputId}' の options が空です`);
+        }
+        inputs.push({
+          id: inputId,
+          kind: "multi-select",
+          options: opts.options,
+          defaultValues: opts.defaultValues,
+          label: opts.label,
+        });
+        return api;
+      },
+      tabs(inputId, opts) {
+        assertUniqueInputId(inputId);
+        if (opts.options.length === 0) {
+          throw new Error(`input.tabs '${inputId}' の options が空です`);
+        }
+        if (!opts.options.includes(opts.defaultValue)) {
+          throw new Error(`input.tabs '${inputId}' の defaultValue が options に含まれません`);
+        }
+        inputs.push({
+          id: inputId,
+          kind: "tabs",
+          options: opts.options,
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      datetime(inputId, opts) {
+        assertUniqueInputId(inputId);
+        inputs.push({
+          id: inputId,
+          kind: "datetime",
+          defaultValue: opts.defaultValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      text(inputId, opts) {
+        assertUniqueInputId(inputId);
+        inputs.push({
+          id: inputId,
+          kind: "text",
+          defaultValue: opts.defaultValue,
+          placeholder: opts.placeholder,
+          maxLength: opts.maxLength,
+          label: opts.label,
+        });
+        return api;
+      },
+    },
+    formula(formulaId, expression) {
+      assertUniqueFormulaId(formulaId);
+      // 入口で parse を試み、 syntax error は formula id 付きで throw (fail-fast)
+      try {
+        parseFormula(expression);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new Error(`formula '${formulaId}' の expression syntax error: ${msg}`);
+      }
+      formulas.push({ id: formulaId, expression });
+      return api;
+    },
+    deriveChain(baseId, count, exprFn) {
+      if (!Number.isInteger(count) || count < 1 || count > 100) {
+        throw new Error(`deriveChain: count (${count}) は 1..100 の整数である必要があります`);
+      }
+      let prev: string | null = null;
+      for (let i = 0; i < count; i++) {
+        const id = `${baseId}${i + 1}`;
+        const rawExpr = exprFn(i, prev);
+        // `prev` を実 id に置換
+        const expr = prev === null ? rawExpr : rawExpr.replace(/\bprev\b/g, prev);
+        assertUniqueFormulaId(id);
+        try {
+          parseFormula(expr);
+        } catch (e) {
+          const msg = e instanceof Error ? e.message : String(e);
+          throw new Error(`deriveChain '${id}' の expression syntax error: ${msg}`);
+        }
+        formulas.push({ id, expression: expr });
+        prev = id;
+      }
+      return api;
+    },
+    on: {
+      click(target, handlerId) {
+        validateEventTarget(target, "click");
+        if (!handlerId) {
+          throw new Error(`event handler '.on.click': handlerId が空文字です`);
+        }
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "click",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      hover(target, handlerId) {
+        validateEventTarget(target, "hover");
+        if (!handlerId) {
+          throw new Error(`event handler '.on.hover': handlerId が空文字です`);
+        }
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "hover",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      doubleClick(target, handlerId) {
+        validateEventTarget(target, "double-click");
+        if (!handlerId) throw new Error(`event handler '.on.doubleClick': handlerId 空`);
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "double-click",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      longPress(target, handlerId) {
+        validateEventTarget(target, "long-press");
+        if (!handlerId) throw new Error(`event handler '.on.longPress': handlerId 空`);
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "long-press",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      drag(target, handlerId) {
+        validateEventTarget(target, "drag");
+        if (!handlerId) throw new Error(`event handler '.on.drag': handlerId 空`);
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "drag",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      drop(target, handlerId) {
+        validateEventTarget(target, "drop");
+        if (!handlerId) throw new Error(`event handler '.on.drop': handlerId 空`);
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "drop",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      keydown(target, handlerId) {
+        validateEventTarget(target, "keydown");
+        if (!handlerId) throw new Error(`event handler '.on.keydown': handlerId 空`);
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "keydown",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      focus(target, handlerId) {
+        validateEventTarget(target, "focus");
+        if (!handlerId) throw new Error(`event handler '.on.focus': handlerId 空`);
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "focus",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+      blur(target, handlerId) {
+        validateEventTarget(target, "blur");
+        if (!handlerId) throw new Error(`event handler '.on.blur': handlerId 空`);
+        eventBindings.push({
+          id: `evt-${++eventBindingCounter}`,
+          event: "blur",
+          target,
+          handlerId,
+        });
+        return api;
+      },
+    },
+    readout: {
+      bar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        assertFiniteNumber(opts.min, `readout.bar '${readoutId}' min`);
+        assertFiniteNumber(opts.max, `readout.bar '${readoutId}' max`);
+        readouts.push({
+          id: readoutId,
+          kind: "bar",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      gauge(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        assertFiniteNumber(opts.min, `readout.gauge '${readoutId}' min`);
+        assertFiniteNumber(opts.max, `readout.gauge '${readoutId}' max`);
+        readouts.push({
+          id: readoutId,
+          kind: "gauge",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      stat(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "stat",
+          source: opts.source,
+          caption: opts.caption,
+          unit: opts.unit,
+          label: opts.label,
+        });
+        return api;
+      },
+      sparkline(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        if (opts.history !== undefined && (opts.history < 2 || opts.history > 200)) {
+          throw new Error(
+            `readout.sparkline '${readoutId}' の history (${opts.history}) は 2..200 の範囲である必要があります`,
+          );
+        }
+        readouts.push({
+          id: readoutId,
+          kind: "sparkline",
+          source: opts.source,
+          history: opts.history,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      countup(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        if (opts.durationMs !== undefined && opts.durationMs < 50) {
+          throw new Error(`readout.countup '${readoutId}' の durationMs は 50 以上必要`);
+        }
+        readouts.push({
+          id: readoutId,
+          kind: "countup",
+          source: opts.source,
+          durationMs: opts.durationMs,
+          decimals: opts.decimals,
+          unit: opts.unit,
+          label: opts.label,
+        });
+        return api;
+      },
+      typewriter(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "typewriter",
+          source: opts.source,
+          charMs: opts.charMs,
+          label: opts.label,
+        });
+        return api;
+      },
+      delta(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "delta",
+          source: opts.source,
+          decimals: opts.decimals,
+          unit: opts.unit,
+          label: opts.label,
+        });
+        return api;
+      },
+      percentRing(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        assertFiniteNumber(opts.max, `readout.percentRing '${readoutId}' max`);
+        readouts.push({
+          id: readoutId,
+          kind: "percent-ring",
+          source: opts.source,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      heatCell(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        assertFiniteNumber(opts.min, `readout.heatCell '${readoutId}' min`);
+        assertFiniteNumber(opts.max, `readout.heatCell '${readoutId}' max`);
+        readouts.push({
+          id: readoutId,
+          kind: "heat-cell",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          colors: opts.colors,
+          label: opts.label,
+        });
+        return api;
+      },
+      badge(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "badge",
+          source: opts.source,
+          colorSource: opts.colorSource,
+          map: opts.map,
+          label: opts.label,
+        });
+        return api;
+      },
+      statusDot(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        if (opts.map.length === 0) {
+          throw new Error(`readout.statusDot '${readoutId}' の map が空です`);
+        }
+        readouts.push({
+          id: readoutId,
+          kind: "status-dot",
+          source: opts.source,
+          map: opts.map,
+          label: opts.label,
+        });
+        return api;
+      },
+      pathProgress(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "path-progress",
+          source: opts.source,
+          pathD: opts.pathD,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          strokeWidth: opts.strokeWidth,
+          color: opts.color,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      arrayList(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "array-list",
+          source: opts.source,
+          itemTemplate: opts.itemTemplate,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      arrayBar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "array-bar",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      lineChart(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "line-chart",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          fill: opts.fill,
+          label: opts.label,
+        });
+        return api;
+      },
+      stackedBar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "stacked-bar",
+          sourceA: opts.sourceA,
+          sourceB: opts.sourceB,
+          min: opts.min,
+          max: opts.max,
+          colorA: opts.colorA,
+          colorB: opts.colorB,
+          label: opts.label,
+        });
+        return api;
+      },
+      waterfall(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "waterfall",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colorPos: opts.colorPos,
+          colorNeg: opts.colorNeg,
+          label: opts.label,
+        });
+        return api;
+      },
+      matrix(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "matrix",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          cellSize: opts.cellSize,
+          colors: opts.colors,
+          showValue: opts.showValue,
+          label: opts.label,
+        });
+        return api;
+      },
+      progressGroup(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "progress-group",
+          source: opts.source,
+          max: opts.max,
+          labelSource: opts.labelSource,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      sequenceTimeline(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "sequence-timeline",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      radar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "radar",
+          source: opts.source,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          labelSource: opts.labelSource,
+          label: opts.label,
+        });
+        return api;
+      },
+      bubbleChart(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "bubble-chart",
+          source: opts.source,
+          xMin: opts.xMin,
+          xMax: opts.xMax,
+          yMin: opts.yMin,
+          yMax: opts.yMax,
+          rMin: opts.rMin,
+          rMax: opts.rMax,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      donut(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "donut",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colors: opts.colors,
+          innerRatio: opts.innerRatio,
+          label: opts.label,
+        });
+        return api;
+      },
+      calendarHeatmap(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "calendar-heatmap",
+          source: opts.source,
+          max: opts.max,
+          cellSize: opts.cellSize,
+          cellGap: opts.cellGap,
+          colors: opts.colors,
+          label: opts.label,
+        });
+        return api;
+      },
+      miniMap(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "mini-map",
+          source: opts.source,
+          canvasW: opts.canvasW,
+          canvasH: opts.canvasH,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      kpiCard(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "kpi-card",
+          source: opts.source,
+          historySource: opts.historySource,
+          comparisonSource: opts.comparisonSource,
+          unit: opts.unit,
+          colorPos: opts.colorPos,
+          colorNeg: opts.colorNeg,
+          label: opts.label,
+        });
+        return api;
+      },
+      candlestick(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "candlestick",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colorUp: opts.colorUp,
+          colorDown: opts.colorDown,
+          label: opts.label,
+        });
+        return api;
+      },
+      venn(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "venn",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colorA: opts.colorA,
+          colorB: opts.colorB,
+          labelA: opts.labelA,
+          labelB: opts.labelB,
+          label: opts.label,
+        });
+        return api;
+      },
+      slope(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "slope",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colorUp: opts.colorUp,
+          colorDown: opts.colorDown,
+          label: opts.label,
+        });
+        return api;
+      },
+      funnel(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "funnel",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colorTop: opts.colorTop,
+          colorBottom: opts.colorBottom,
+          label: opts.label,
+        });
+        return api;
+      },
+      gantt(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "gantt",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      treemap(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "treemap",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colors: opts.colors,
+          label: opts.label,
+        });
+        return api;
+      },
+      sankey(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "sankey",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colors: opts.colors,
+          label: opts.label,
+        });
+        return api;
+      },
+      polarArea(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "polar-area",
+          source: opts.source,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colors: opts.colors,
+          labelSource: opts.labelSource,
+          label: opts.label,
+        });
+        return api;
+      },
+      stepIndicator(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "step-indicator",
+          source: opts.source,
+          stepsSource: opts.stepsSource,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colorActive: opts.colorActive,
+          colorPending: opts.colorPending,
+          label: opts.label,
+        });
+        return api;
+      },
+      bulletChart(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "bullet-chart",
+          source: opts.source,
+          targetSource: opts.targetSource,
+          max: opts.max,
+          rangeBad: opts.rangeBad,
+          rangeAvg: opts.rangeAvg,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          colorActual: opts.colorActual,
+          label: opts.label,
+        });
+        return api;
+      },
+      numberBoard(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "number-board",
+          source: opts.source,
+          prefix: opts.prefix,
+          suffix: opts.suffix,
+          size: opts.size,
+          color: opts.color,
+          caption: opts.caption,
+          label: opts.label,
+        });
+        return api;
+      },
+      leaderboard(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "leaderboard",
+          source: opts.source,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      trafficLight(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "traffic-light",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          label: opts.label,
+        });
+        return api;
+      },
+      tagCloud(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "tag-cloud",
+          source: opts.source,
+          minSize: opts.minSize,
+          maxSize: opts.maxSize,
+          colors: opts.colors,
+          label: opts.label,
+        });
+        return api;
+      },
+      activityFeed(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "activity-feed",
+          source: opts.source,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      rating(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "rating",
+          source: opts.source,
+          count: opts.count,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      notification(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "notification",
+          kindSource: opts.kindSource,
+          titleSource: opts.titleSource,
+          bodySource: opts.bodySource,
+          label: opts.label,
+        });
+        return api;
+      },
+      diffCounter(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "diff-counter",
+          additionsSource: opts.additionsSource,
+          deletionsSource: opts.deletionsSource,
+          colorAdd: opts.colorAdd,
+          colorDel: opts.colorDel,
+          label: opts.label,
+        });
+        return api;
+      },
+      chatBubble(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "chat-bubble",
+          source: opts.source,
+          max: opts.max,
+          colorSelf: opts.colorSelf,
+          colorOther: opts.colorOther,
+          label: opts.label,
+        });
+        return api;
+      },
+      avatar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "avatar",
+          source: opts.source,
+          size: opts.size,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      checklist(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "checklist",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      circularGauge(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "circular-gauge",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          unit: opts.unit,
+          label: opts.label,
+        });
+        return api;
+      },
+      priceTag(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "price-tag",
+          oldSource: opts.oldSource,
+          newSource: opts.newSource,
+          currency: opts.currency,
+          colorNew: opts.colorNew,
+          colorOld: opts.colorOld,
+          colorDiscount: opts.colorDiscount,
+          label: opts.label,
+        });
+        return api;
+      },
+      spinner(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "spinner",
+          source: opts.source,
+          textSource: opts.textSource,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      grade(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "grade",
+          source: opts.source,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      stopwatch(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "stopwatch",
+          source: opts.source,
+          runningSource: opts.runningSource,
+          size: opts.size,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      confidenceMeter(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "confidence-meter",
+          source: opts.source,
+          lowThreshold: opts.lowThreshold,
+          highThreshold: opts.highThreshold,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          label: opts.label,
+        });
+        return api;
+      },
+      reactionBar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "reaction-bar",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      pillGroup(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "pill-group",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      fuelBar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "fuel-bar",
+          source: opts.source,
+          segments: opts.segments,
+          lowThreshold: opts.lowThreshold,
+          highThreshold: opts.highThreshold,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          label: opts.label,
+        });
+        return api;
+      },
+      metricsGrid(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "metrics-grid",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      thermometer(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "thermometer",
+          source: opts.source,
+          min: opts.min,
+          max: opts.max,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          unit: opts.unit,
+          label: opts.label,
+        });
+        return api;
+      },
+      iconTile(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "icon-tile",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      tokenList(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "token-list",
+          source: opts.source,
+          colorUp: opts.colorUp,
+          colorDown: opts.colorDown,
+          label: opts.label,
+        });
+        return api;
+      },
+      mapPin(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "map-pin",
+          source: opts.source,
+          xMin: opts.xMin,
+          xMax: opts.xMax,
+          yMin: opts.yMin,
+          yMax: opts.yMax,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      priorityBadge(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "priority-badge",
+          source: opts.source,
+          textSource: opts.textSource,
+          label: opts.label,
+        });
+        return api;
+      },
+      podium(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "podium",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          label: opts.label,
+        });
+        return api;
+      },
+      pollBar(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "poll-bar",
+          source: opts.source,
+          color: opts.color,
+          colorWinner: opts.colorWinner,
+          label: opts.label,
+        });
+        return api;
+      },
+      userStack(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "user-stack",
+          source: opts.source,
+          max: opts.max,
+          size: opts.size,
+          label: opts.label,
+        });
+        return api;
+      },
+      commitList(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "commit-list",
+          source: opts.source,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      mediaPlayer(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "media-player",
+          source: opts.source,
+          durationSource: opts.durationSource,
+          playingSource: opts.playingSource,
+          color: opts.color,
+          viewW: opts.viewW,
+          label: opts.label,
+        });
+        return api;
+      },
+      eventLog(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "event-log",
+          source: opts.source,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      searchResult(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "search-result",
+          source: opts.source,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      roadmap(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "roadmap",
+          source: opts.source,
+          viewW: opts.viewW,
+          viewH: opts.viewH,
+          label: opts.label,
+        });
+        return api;
+      },
+      weatherForecast(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "weather-forecast",
+          source: opts.source,
+          label: opts.label,
+        });
+        return api;
+      },
+      videoCard(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "video-card",
+          source: opts.source,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      orderStatus(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "order-status",
+          source: opts.source,
+          stepsSource: opts.stepsSource,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      attendanceGrid(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "attendance-grid",
+          source: opts.source,
+          membersSource: opts.membersSource,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      timezoneClock(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "timezone-clock",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      formSummary(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "form-summary",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      songQueue(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "song-queue",
+          source: opts.source,
+          currentSource: opts.currentSource,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      calendarMonth(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "calendar-month",
+          source: opts.source,
+          monthName: opts.monthName,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      terminal(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "terminal",
+          source: opts.source,
+          max: opts.max,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      chessBoard(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "chess-board",
+          source: opts.source,
+          cellSize: opts.cellSize,
+          label: opts.label,
+        });
+        return api;
+      },
+      kanbanBoard(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "kanban-board",
+          source: opts.source,
+          columnWidth: opts.columnWidth,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      breadcrumb(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "breadcrumb",
+          source: opts.source,
+          currentSource: opts.currentSource,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      timelineVertical(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "timeline-vertical",
+          source: opts.source,
+          color: opts.color,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      statusTimeline(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "status-timeline",
+          source: opts.source,
+          colorMap: opts.colorMap,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      calendarWeek(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "calendar-week",
+          source: opts.source,
+          cellSize: opts.cellSize,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      kpiComparison(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "kpi-comparison",
+          source: opts.source,
+          max: opts.max,
+          colorA: opts.colorA,
+          colorB: opts.colorB,
+          label: opts.label,
+        });
+        return api;
+      },
+      stepProgress(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "step-progress",
+          source: opts.source,
+          stepsSource: opts.stepsSource,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      userPresence(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "user-presence",
+          source: opts.source,
+          max: opts.max,
+          label: opts.label,
+        });
+        return api;
+      },
+      ratingThumb(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "rating-thumb",
+          source: opts.source,
+          colorUp: opts.colorUp,
+          colorDown: opts.colorDown,
+          label: opts.label,
+        });
+        return api;
+      },
+      orgChartMini(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "org-chart-mini",
+          source: opts.source,
+          color: opts.color,
+          label: opts.label,
+        });
+        return api;
+      },
+      kpiTrendTile(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "kpi-trend-tile",
+          source: opts.source,
+          prevSource: opts.prevSource,
+          historySource: opts.historySource,
+          unit: opts.unit,
+          colorPos: opts.colorPos,
+          colorNeg: opts.colorNeg,
+          label: opts.label,
+        });
+        return api;
+      },
+      quickPollEmoji(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "quick-poll-emoji",
+          source: opts.source,
+          colorWinner: opts.colorWinner,
+          label: opts.label,
+        });
+        return api;
+      },
+      voiceMessage(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "voice-message",
+          source: opts.source,
+          progressSource: opts.progressSource,
+          duration: opts.duration,
+          colorPlay: opts.colorPlay,
+          colorBar: opts.colorBar,
+          label: opts.label,
+        });
+        return api;
+      },
+      threadSummary(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "thread-summary",
+          source: opts.source,
+          colorUnread: opts.colorUnread,
+          label: opts.label,
+        });
+        return api;
+      },
+      readReceipt(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "read-receipt",
+          source: opts.source,
+          colorRead: opts.colorRead,
+          colorPending: opts.colorPending,
+          label: opts.label,
+        });
+        return api;
+      },
+      passwordStrength(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "password-strength",
+          source: opts.source,
+          colorStrong: opts.colorStrong,
+          colorWeak: opts.colorWeak,
+          label: opts.label,
+        });
+        return api;
+      },
+      otpInput(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "otp-input",
+          source: opts.source,
+          colorFocus: opts.colorFocus,
+          label: opts.label,
+        });
+        return api;
+      },
+      fileDropzone(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "file-dropzone",
+          source: opts.source,
+          colorActive: opts.colorActive,
+          label: opts.label,
+        });
+        return api;
+      },
+      logStream(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "log-stream",
+          source: opts.source,
+          label: opts.label,
+        });
+        return api;
+      },
+      alertBanner(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "alert-banner",
+          source: opts.source,
+          label: opts.label,
+        });
+        return api;
+      },
+      serviceHealth(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "service-health",
+          source: opts.source,
+          label: opts.label,
+        });
+        return api;
+      },
+      cartSummary(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "cart-summary",
+          source: opts.source,
+          currency: opts.currency,
+          colorTotal: opts.colorTotal,
+          label: opts.label,
+        });
+        return api;
+      },
+      pricingTier(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "pricing-tier",
+          source: opts.source,
+          colorAccent: opts.colorAccent,
+          currency: opts.currency,
+          label: opts.label,
+        });
+        return api;
+      },
+      couponCode(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "coupon-code",
+          source: opts.source,
+          colorApplied: opts.colorApplied,
+          label: opts.label,
+        });
+        return api;
+      },
+      articlePreview(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "article-preview",
+          source: opts.source,
+          colorAccent: opts.colorAccent,
+          label: opts.label,
+        });
+        return api;
+      },
+      tocNav(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "toc-nav",
+          source: opts.source,
+          colorActive: opts.colorActive,
+          label: opts.label,
+        });
+        return api;
+      },
+      shareButtons(readoutId, opts) {
+        assertUniqueReadoutId(readoutId);
+        readouts.push({
+          id: readoutId,
+          kind: "share-buttons",
+          source: opts.source,
+          label: opts.label,
+        });
+        return api;
+      },
+    },
+    animation: {
+      scroll(triggerId, opts) {
+        assertUniqueScrollTriggerId(triggerId);
+        const start = opts?.start ?? 1.0;
+        const end = opts?.end ?? 0.0;
+        const scrub = opts?.scrub ?? 1;
+        // 非有限値の fail-fast (CAR #263、 NaN は < 0 / > 1 で silent pass する)
+        assertFiniteNumber(start, `scroll trigger '${triggerId}' start`);
+        assertFiniteNumber(end, `scroll trigger '${triggerId}' end`);
+        assertFiniteNumber(scrub, `scroll trigger '${triggerId}' scrub`);
+        // start / end は viewport 相対位置 (0 = viewport top、 1 = viewport bottom)、 0..1 範囲内に制限する。
+        // 範囲外を許容すると attach 側の IntersectionObserver in-view gate で recompute が止まり、
+        // element が viewport 外に出た瞬間に progress が中間値で stuck する (codex Round 2 finding)。
+        if (start < 0 || start > 1) {
+          throw new Error(
+            `scroll trigger '${triggerId}': start (${start}) は 0..1 範囲 (viewport 相対位置) である必要があります`,
+          );
+        }
+        if (end < 0 || end > 1) {
+          throw new Error(
+            `scroll trigger '${triggerId}': end (${end}) は 0..1 範囲 (viewport 相対位置) である必要があります`,
+          );
+        }
+        // 注 = start === end は center-to-center 系 trigger (element height の scroll 距離で progress 0→1)、
+        // valid pattern。 zero-range の degenerate case (element height 0) は runtime で判定 (builder では element 未 attach)。
+        if (scrub < 0 || scrub > 1) {
+          throw new Error(
+            `scroll trigger '${triggerId}': scrub (${scrub}) は 0..1 範囲内である必要があります`,
+          );
+        }
+        scrollTriggers.push({ id: triggerId, start, end, scrub, label: opts?.label });
+        return api;
+      },
+    },
+    phase(phaseId, opts, build) {
+      const acc: PhaseAcc = { activate: [], tweens: [], sets: [] };
+      build(makePhaseBuilder(acc));
+      phases.push({
+        id: phaseId,
+        duration: opts.duration ?? 1800,
+        title: opts.title,
+        body: opts.body,
+        activate: acc.activate,
+        tweens: acc.tweens,
+        sets: acc.sets,
+        badge: acc.badge,
+      });
+      return api;
+    },
+    build() {
+      // 全 array を copy して builder accumulator の参照を切る (builder 再利用時の
+      // 過去 build 結果を汚さない、 codex PR #260 review MAJOR #1 対応)。
+      const built = {
+        id,
+        topic: options.topic,
+        // 既定 (extract) は省略して JSON 形状を変えない。 exclude を明示した図だけ持たせる。
+        ...(options.structuredData === "exclude" ? { structuredData: "exclude" as const } : {}),
+        // inputs / formulas / scrollTriggers / eventBindings は空なら省略 (static diagram の JSON 形状維持)
+        ...(inputs.length > 0 ? { inputs: [...inputs] } : {}),
+        ...(formulas.length > 0 ? { formulas: [...formulas] } : {}),
+        ...(scrollTriggers.length > 0 ? { scrollTriggers: [...scrollTriggers] } : {}),
+        ...(eventBindings.length > 0 ? { eventBindings: [...eventBindings] } : {}),
+        ...(readouts.length > 0 ? { readouts: [...readouts] } : {}),
+        lanes: [...lanes],
+        nodes: [...nodes],
+        edges: [...edges],
+        states: [...states],
+        phases: [...phases],
+      };
+      // in-place mutation guard (CAR #260)。 caller が diagram.formulas[0].expression = "..." 等の
+      // mutation を試みると strict mode で throw、 non-strict でも silent 無効化される。
+      // これにより interactive schemaKey memoize (identity dep) が in-place mutation で stale
+      // cache に落ちる regression を builder 層で構造的に防ぐ。 immutable 契約は SSOT として
+      // README / doc に明記、 diagram を差替たい場合は builder で新規生成すること。
+      return deepFreezeDiagram(built);
+    },
+  };
+
+  return api;
+}
+
+// 型 re-export
+export type { EdgeStyle, NodeKind, Side, Tone };