@cardenelabs/cdl 0.5.0

package/dist/render-C78lIXeC.d.cts

@@ -0,0 +1,2449 @@
+import { JSX } from 'react';
+
+/**
+ * mutable な reactive value。 `.value` getter / setter で読み書き、
+ * 読み取り時に current subscriber (computed / effect) を dep として自動登録する。
+ *
+ * `.peek()` は依存追跡なしで現 value を読み取る (effect 内で「値は見たいが再実行 trigger にしたくない」 用途)。
+ * `.subscribe(fn)` は effect 経路を通さず手動で notification listener を登録する
+ * (framework 統合 / 外部 stream との bridge 用途、 dispose function を返す)。
+ */
+interface Signal<T> {
+    get value(): T;
+    set value(v: T);
+    peek(): T;
+    subscribe(fn: (v: T) => void): () => void;
+}
+declare function signal<T>(initial: T): Signal<T>;
+
+/**
+ * dependency 変化時に自動で再計算される derived value。 lazy evaluation で、
+ * `.value` が read されるまでは fn を評価しない。 memoize して dep が変化しない限り再計算しない。
+ *
+ * computed は subscriber (dep 変化を受け取る) かつ dependency (下流の computed / effect の dep になる)
+ * の両側面を持つ = graph の中間 node。
+ */
+interface Computed<T> {
+    get value(): T;
+    peek(): T;
+}
+declare function computed<T>(fn: () => T): Computed<T>;
+
+/** 意味付きの色の名前。 検査・描画・test はこの 1 つの列を出所にする。 */
+declare const TONES: readonly ["accent", "teal", "success", "error", "warning", "info"];
+type Tone = (typeof TONES)[number];
+/** 描画できる箱の種類。 検査・記法一覧・型はこの 1 つの列を出所にする。 */
+declare const NODE_KINDS: readonly ["dyn-rect", "dyn-circle", "dyn-arc", "dyn-wave", "dyn-polygon", "actor", "function", "storage", "event", "card", "person", "user-group", "admin", "developer", "external-user", "database", "cache", "queue", "message-bus", "cloud", "cdn", "service", "api", "frontend", "backend", "webhook", "microservice", "signer", "oracle", "merkle-tree", "decision", "chart-pie", "chart-line", "chart-bar", "gantt-timeline", "mind-map", "mind-radial", "funnel-stages", "quadrant-matrix", "tree-hierarchy", "journey-map", "shape-file", "shape-folder", "shape-cloud", "shape-cylinder", "shape-hexagon", "shape-diamond", "shape-stack", "shape-person", "shape-window", "shape-terminal", "shape-code-block", "shape-kanban-card", "shape-message-bubble", "shape-gear", "shape-server-rack", "shape-network-node", "shape-mobile-device", "shape-iot-sensor", "shape-robot-arm", "shape-satellite", "shape-smart-contract", "shape-blockchain-block", "shape-rpc-node", "shape-wallet", "shape-nft", "shape-token", "shape-blockchain", "shape-bitcoin-chain", "shape-ethereum-chain", "shape-blockchain-node", "shape-bank", "shape-trust-bank", "shape-payment-provider", "shape-credit-card", "shape-brokerage", "shape-exchange", "shape-atm", "shape-website", "shape-storefront", "shape-warehouse", "shape-online-shop", "shape-cdn-edge", "shape-api-gateway", "shape-auditor", "shape-regulator", "shape-notary", "shape-lawyer", "shape-trader", "shape-customer-service"];
+type NodeKind = (typeof NODE_KINDS)[number];
+type Side = "top" | "right" | "bottom" | "left";
+/**
+ * edge の visual style variant。
+ * - "solid" (default) ... 実線 + 矢頭、 inactive は dashed grey
+ * - "dotted-flow" ... 点線 + active phase で粒子が path 沿いに流れる。
+ *   path が経由 node を貫通する場合は自動で粒子が node 中心を貫通する動きに切替。
+ */
+type EdgeStyle = "solid" | "dotted-flow";
+type CdlLane = {
+    id: string;
+    /** lane の x 座標 (optional、 未指定なら engine が前 lane 右端 + gap で auto 計算) */
+    x?: number;
+    /**
+     * lane の幅 (world 単位)。
+     *
+     * engine が `max(指定値, 中の node の最大幅 + 左右余白 × 2)` まで広げる。
+     *
+     * 左右余白は最低 25 で、 隣の lane を詰めて置くほど大きくなる。 隣り合う node の間隔は
+     * 「lane 間隔 + 左右余白 × 2」 で決まるため、 lane を詰めた分を余白で埋め合わせて
+     * node 同士が近づきすぎないようにしている (目標 = node 同士の clearance policy + 余裕)。
+     * lane を十分に離して置いた図では最低値の 25 が使われ、 幅は `node 最大幅 + 50` になる。
+     *
+     * `role: "overlay"` の lane が絡む対はこの埋め合わせの対象外 (重ねることが目的の配置を
+     * engine が引き剥がさないため)。
+     *
+     * それ以外の lane 対は重なっていても埋め合わせるが、 重なり幅そのものは埋めない
+     * (重なり 0 として扱う)。 重なり幅を足し込むと lane が青天井に太るため、 余白の上限は
+     * 「間隔 0 で並べた時に必要な値」 で頭打ちになる。
+     *
+     * この上限があるため、 node 同士の間隔の保証には境界がある。
+     *
+     * - 離して置いた lane (間隔 0 以上) ... 目標値を必ず満たす
+     * - 重ねて置いた lane ... 目標値から重なり幅を引いた値になる。 重なりが「目標値 - 下限値」
+     *   を超えると下限を割り、 engine は直さず `visualValidate` の clearance が報告する
+     *   (engine が直すには lane を動かすしかなく、 著者が置いた位置を engine が動かすことになるため)
+     *
+     * `posX` と `posY` を両方指定した lane はこの auto 拡張の対象外で、 `posW` があれば
+     * そちら、 無ければこの値が使われる。 座標を固定した lane は上記の埋め合わせにも
+     * 参加しないため、 その隣で間隔を満たすかは著者の配置次第になる。
+     */
+    width: number;
+    label?: string;
+    contain?: boolean;
+    /**
+     * この lane を何のために置いているか (既定 = `"column"`)。
+     *
+     * - `"column"` ... 他の lane と横に並べる。 隣と近づきすぎないよう engine が幅で間隔を調整する
+     * - `"overlay"` ... 他の lane に重ねることが目的。 group を囲む枠や gantt の timeline 帯など。
+     *   重ねるのが意図なので **間隔の調整対象から外れる** (自身の幅を隣との間隔のために広げず、
+     *   隣の lane にとっても「隣接する lane」 として数えられない)
+     *
+     * `"overlay"` でも幅と位置が完全に固定される訳ではない。 中に node があれば収まる幅までは
+     * 広がり、 左側の lane が広がった分は位置が右へ動く (帯だけ取り残されると重ねている対象から
+     * ずれるため)。 固定したい場合は `posX` / `posY` を使う。
+     *
+     * 未指定は `"column"` として扱う。 `"overlay"` を付け忘れた lane が他と重なっていても
+     * engine は幅を青天井には広げない (重なり幅は埋めず、 間隔 0 相当までで頭打ちにする) ため、
+     * 付け忘れが図の崩壊にはつながらない。
+     */
+    role?: "column" | "overlay";
+    /** UML sequence diagram の lifeline (= lane の中央 x に縦の点線を描画) */
+    lifeline?: boolean;
+    /**
+     * 明示指定した座標。 `posX` と `posY` の **両方**が揃った lane は「置いた位置に置く」
+     * 扱いになる。 片方だけでは何も変わらない。
+     *
+     * 位置の自動計算 (前 lane の右端からの送り) も、 中の node や edge label に合わせた幅の
+     * 自動拡張も走らない。 いずれも「指定した位置と幅から動かさない」 ための扱い。
+     */
+    posX?: number;
+    posY?: number;
+    /**
+     * 明示指定した大きさ。 `posX` と `posY` が揃っている時だけ効く。
+     *
+     * 大きさだけを変えたい場合は `width` を使う。
+     */
+    posW?: number;
+    posH?: number;
+};
+type CdlNode = {
+    id: string;
+    lane: string;
+    stack: number;
+    kind: NodeKind;
+    title: string;
+    eyebrow?: string;
+    subtitle?: string;
+    /** mono 数値表示用、 `{stateId}` を含めれば state 値で動的置換 */
+    value?: string;
+    /** kind=storage 時の行 (各 mono、 state 参照可) */
+    rows?: string[];
+    /** width override (default は NodeKind 別 NODE_SIZE)、 catalog thumbnail 用に縮小可 */
+    w?: number;
+    /** height override */
+    h?: number;
+    /**
+     * 明示指定した座標。 `posX` と `posY` の **両方**が揃った node は「置いた位置に置く」
+     * 扱いになる。 片方だけでは何も変わらない。
+     *
+     * 効果は位置計算だけではない。 stack 順の配置を skip して指定値を使うことに加えて、
+     * 重なり解消で動かされなくなり、 lane 中心との整合を見る検証の対象からも外れる。
+     * いずれも「指定した位置から動かさない」 ための扱い。
+     */
+    posX?: number;
+    posY?: number;
+    /**
+     * 明示指定した大きさ。 `posX` と `posY` が揃っている時だけ効く。
+     *
+     * 採用されるのは `posX !== undefined && posY !== undefined` の時だけで、 行高さの計算には
+     * 参加しない。 大きさだけを変えたい場合は `w` / `h` を使う。
+     */
+    posW?: number;
+    posH?: number;
+    /**
+     * node の主色。 未指定なら kind ごとの既定色。
+     *
+     * 変わるのは kind の既定色を使って描かれる部分で、 枠線 / eyebrow の文字色 / icon /
+     * 強調表示中の行の値。 本文の文字色と背景は変わらない。
+     *
+     * 効くのは `actor` / `function` / `storage` / `event` / `card` と `person` 以降の汎用 kind の
+     * 計 26 種。 それ以外は自前の配色を持つため指定しても変わらず、 検査も通す。 効く kind の
+     * 一覧は `test/node-styling.test.tsx` が実装から計算した集合と突き合わせている。
+     *
+     * 既定色と同じ名前を明示指定しても色が変わる kind がある (既定色の hex が `render/tone.ts`
+     * の値とずれているため)。
+     */
+    tone?: Tone;
+    /**
+     * visual binding: width の render-time template (CAR visual-binding foundation)。
+     * `.node('bar', { w: 40, wBind: '{barW}' })` の様に書くと、 signal 'barW' の値で width が
+     * リアルタイム変化する。 template は `{signal-id}` or interpolate 式、 解決失敗時は layout の
+     * w にフォールバック。 layout は wBind を無視して static w を使う (edge routing は静的 layout
+     * を維持、 visual は signal に追随、 の分離設計)。
+     */
+    wBind?: string;
+    /** visual binding: height の render-time template (wBind と同 semantics) */
+    hBind?: string;
+    /**
+     * node opacity (0..1)、 numeric 直接指定 or `{signal-id}` template で signal 追随可。
+     * fade-in / attention 変化 / conditional 表示に使う。 未指定なら 1 (完全表示)。
+     */
+    opacity?: number | string;
+    /**
+     * dynamic shape spec (CAR: shape primitive)。 kind が dyn-rect / dyn-circle / dyn-arc /
+     * dyn-wave / dyn-polygon の時、 内部 fill / size / angle 等を signal 値で駆動する。
+     * fixed template (chart-pie / gantt 等) ではなく汎用 container として組合せ可能な直交
+     * primitive。 shape 経路の詳細 field は CdlDynShape 型を参照。
+     */
+    shape?: CdlDynShape;
+    /**
+     * conditional visibility = truthy 判定で表示切替、 signal template で dynamic 制御可能。
+     * "1" / "true" / 非 "0" / 非 "false" / 非空文字を truthy と判定。
+     */
+    visibleIf?: string;
+    /**
+     * render-time X offset (pixel、 numeric or `{signal}` template)、 layout 計算後の cx を
+     * offsetX だけ shift して SVG 描画する。 edges / auto-layout は shift 前の base position を
+     * 使うため、 radial / free-form position 表示専用 (network 図 hub-and-spoke で spoke node を
+     * 円周上に見せる等)。 signal template で reactive 移動も可能。
+     */
+    renderOffsetX?: number | string;
+    /** render-time Y offset (pixel or `{signal}` template)、 renderOffsetX と同 semantics */
+    renderOffsetY?: number | string;
+    /**
+     * Chart 系 kind (chart-pie / chart-line / chart-bar) 専用の datum payload。
+     * 数値 chart の全 datum を 1 node に格納し、 kinds/chart-*.tsx が自己完結で SVG 描画する。
+     */
+    chartData?: ChartDatumPayload[];
+    /**
+     * gantt-timeline 専用の task payload。 task 全件を 1 node に格納し、
+     * kinds/gantt.tsx が縦軸 task lane + 横軸日付 rect bar で SVG 描画する。
+     */
+    ganttData?: GanttTaskPayload[];
+    /**
+     * mind-map / mind-radial 専用の branch payload。 tree 構造を 1 node に格納し、
+     * kinds/mind-map.tsx / mind-radial.tsx が中心 + 放射で SVG 描画する。
+     */
+    mindData?: MindBranchPayload;
+    /** funnel-stages 専用の stage 配列 payload、 逆三角形 stage 描画に使う */
+    funnelData?: FunnelStagePayload[];
+    /** quadrant-matrix 専用の 2 軸 + item 配列 payload、 十字軸 + 4 象限描画に使う */
+    quadrantData?: QuadrantPayload;
+    /** tree-hierarchy 専用の tree node payload、 縦階層 hierarchical 描画に使う */
+    treeData?: TreeNodePayload[];
+    /** journey-map 専用の step 配列 payload、 感情曲線 + touchpoint 描画に使う */
+    journeyData?: JourneyStepPayload[];
+};
+/** Chart 系 kind の 1 datum payload。 label + value + optional tone (color) */
+type ChartDatumPayload = {
+    label: string;
+    value: number;
+    tone?: Tone;
+};
+/** gantt-timeline kind の 1 task payload。 label + start/end + owner + dependsOn */
+type GanttTaskPayload = {
+    id: string;
+    title: string;
+    /** 開始 index (0-based 相対位置) */
+    startIdx: number;
+    /** 終了 index (0-based 相対位置、 startIdx と同じなら 1 cell 幅) */
+    endIdx: number;
+    /** 開始 label (例 "Q1" / "2026-01") */
+    startLabel: string;
+    /** 終了 label (例 "Q2" / "2026-03") */
+    endLabel: string;
+    owner?: string;
+    dependsOn?: string;
+    tone?: Tone;
+};
+/** mind-map / mind-radial kind の branch tree payload。 rootId + branch 配列 */
+type MindBranchPayload = {
+    rootId: string;
+    rootTitle: string;
+    branches: MindBranchNode[];
+};
+/** 1 branch node = id + title + parent + optional tone + subtitle */
+type MindBranchNode = {
+    id: string;
+    title: string;
+    parent: string;
+    tone?: Tone;
+    subtitle?: string;
+};
+/** funnel-stages kind の 1 stage payload。 title + count + optional subtitle */
+type FunnelStagePayload = {
+    id: string;
+    title: string;
+    count: number;
+    subtitle?: string;
+};
+/** quadrant-matrix kind の 2 軸 + item 配列 payload */
+type QuadrantPayload = {
+    xAxis: {
+        left: string;
+        right: string;
+    };
+    yAxis: {
+        bottom: string;
+        top: string;
+    };
+    quadrantLabels: {
+        topLeft: string;
+        topRight: string;
+        bottomLeft: string;
+        bottomRight: string;
+    };
+    items: QuadrantItemPayload[];
+};
+/** quadrant-matrix の 1 item payload */
+type QuadrantItemPayload = {
+    id: string;
+    title: string;
+    quadrant: "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+    subtitle?: string;
+};
+/** tree-hierarchy kind の 1 node payload */
+type TreeNodePayload = {
+    id: string;
+    title: string;
+    parent?: string;
+    subtitle?: string;
+    eyebrow?: string;
+};
+/** journey-map kind の 1 step payload */
+type JourneyStepPayload = {
+    id: string;
+    title: string;
+    /** emotion 5 段階 (delighted / happy / neutral / frustrated / angry) */
+    emotion: "delighted" | "happy" | "neutral" | "frustrated" | "angry";
+    touchpoint?: string;
+    opportunity?: string;
+};
+type CdlEdge = {
+    id: string;
+    from: string;
+    to: string;
+    label: string;
+    sub?: string;
+    tone: Tone;
+    side?: Side;
+    /** visual style、 default "solid" */
+    style?: EdgeStyle;
+    /**
+     * FSM transition の guard 条件 (例 "if validated")。
+     * stateMachine preset では sub に併合される、 text-dsl v0.5 では guard 単独で渡せる。
+     */
+    guard?: string;
+    /**
+     * ER 関係 cardinality を author が宣言した文字列 (例 "1:N" / "N:M" / "1..*")。
+     * compileEr 経路で edge label に "(1:N)" 形式で併記、 他 preset では透過。
+     */
+    cardinality?: string;
+    /** label の x 方向 fine offset (default 0)、 著者が細かく位置調整するための逃げ道 */
+    labelOffsetX?: number;
+    /** label の y 方向 fine offset (default 0、 + で下、 - で上) */
+    labelOffsetY?: number;
+    /** routing mode (default "default" = 自動 routing、 "back-detour" = back transition 用の上方 detour 強制) */
+    routing?: "default" | "back-detour";
+    /**
+     * CAR-549 SSOT ... label を edge path 上に「被せる」 か「離す」 かの制御 flag。
+     * default (false or undefined) = LABEL_INIT_CLEARANCE (34 world、 CAR-630 で 26 → 34 復帰) 離して配置。
+     * true = label center を edge path 上に重ねる (flowchart の true/false condition label 等、
+     * edge の semantic を強調するため path と label を重ね表示する)。
+     */
+    overlay?: boolean;
+    /**
+     * signal binding: edge stroke-width の render-time template。
+     * `.edge('a', 'b', { widthBind: '{flow}' })` の様に書くと signal で edge 太さが動く。
+     * fallback = active 2 / inactive 1.5、 signal 経由の template で number 解釈。
+     */
+    widthBind?: string;
+    /**
+     * signal binding: edge stroke color の template、 signal で色が変わる。
+     * fallback = tone 別 color。 hex or css color 文字列を signal に持たせて置換。
+     */
+    strokeBind?: string;
+    /**
+     * signal binding: edge stroke-dashoffset の template (0..N)、 SVG stroke-dasharray + dashoffset で流れる線を表現。
+     * timeline signal と組合わせて chain の流れを animate 可能。
+     */
+    dashOffsetBind?: string;
+    /**
+     * canvas pivot 新 spec (dragon canvas pivot spec §layout-role-conversion)。
+     * posX1 / posY1 = edge の from 端 point の絶対座標、 posX2 / posY2 = edge の to 端 point の絶対座標。
+     * 両 point が set 済なら CDL の layoutEdges 経路が該当 edge の routing 再計算を skip し、
+     * 直線 path (posX1, posY1) → (posX2, posY2) を最終 path として採用する。
+     * 未指定なら従来通り orthogonal L 字 routing + label placement が計算 (catalog 100+ backward compat 保証)。
+     */
+    posX1?: number;
+    posY1?: number;
+    posX2?: number;
+    posY2?: number;
+};
+type CdlState = {
+    id: string;
+    initial: number | string;
+};
+/**
+ * interactive input widget spec (v0.5+、 CAR #243)。
+ *
+ * consumer app 側 (React / plain HTML 等) が widget を描画、 signal 経由で cdl の SVG 内 text / rect / path
+ * と bind する data model。 cdl 自身は widget を描画せず、 metadata としてのみ持つ。
+ *
+ * `id` は signal 名として使われ、 consumer が `createInputSignals(diagram).<id>` で対応する Signal を取得する。
+ * discriminated union で kind ごとに options / defaultValue の型を厳密化する。
+ */
+type CdlInput = {
+    id: string;
+    kind: "slider";
+    /** 最小値 (inclusive) */
+    min: number;
+    /** 最大値 (inclusive) */
+    max: number;
+    /** 刻み幅 (default 1) */
+    step?: number;
+    defaultValue: number;
+    label?: string;
+} | {
+    id: string;
+    kind: "number";
+    /** 最小値 (省略時は制約なし) */
+    min?: number;
+    /** 最大値 (省略時は制約なし) */
+    max?: number;
+    defaultValue: number;
+    label?: string;
+} | {
+    id: string;
+    kind: "dropdown";
+    /** 選択肢一覧 (非空必須、 defaultValue はこの中の 1 つ) */
+    options: readonly string[];
+    defaultValue: string;
+    label?: string;
+} | {
+    id: string;
+    kind: "toggle";
+    defaultValue: boolean;
+    label?: string;
+}
+/**
+ * XY pad = 2 軸 slider、 `.input.xypad(id)` は 実は 2 個の signal (id_x / id_y) を生成する
+ * 仕組みではなく、 単一 signal に `{x, y}` object を保持する経路を採用 (widget が 2D point 選択)。
+ * 但し template で使う場合の複雑度を下げるため、 実装上は id と id_y の 2 signal ペアで管理する。
+ */
+ | {
+    id: string;
+    kind: "xypad";
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+    defaultX: number;
+    defaultY: number;
+    label?: string;
+}
+/** stepper = +/- ボタンで integer を増減、 min / max / step を持つ */
+ | {
+    id: string;
+    kind: "stepper";
+    min?: number;
+    max?: number;
+    step?: number;
+    defaultValue: number;
+    label?: string;
+}
+/** radio group = 排他選択、 dropdown と同じ options / defaultValue だが視覚は横並び button */
+ | {
+    id: string;
+    kind: "radio";
+    options: readonly string[];
+    defaultValue: string;
+    label?: string;
+}
+/** color picker = hex color 文字列 (#RRGGBB) を signal に保持 */
+ | {
+    id: string;
+    kind: "color";
+    defaultValue: string;
+    label?: string;
+}
+/** range slider = 2 thumb で min/max を独立指定、 単一 signal に "lo,hi" で格納 */
+ | {
+    id: string;
+    kind: "range";
+    min: number;
+    max: number;
+    step?: number;
+    defaultLo: number;
+    defaultHi: number;
+    label?: string;
+}
+/** multi-select = 複数 option を chip 選択、 signal に "a,b,c" (comma sep) で格納 */
+ | {
+    id: string;
+    kind: "multi-select";
+    options: readonly string[];
+    defaultValues: readonly string[];
+    label?: string;
+}
+/** tabs = 排他 tab UI、 dropdown と同 semantics だが視覚は tab bar */
+ | {
+    id: string;
+    kind: "tabs";
+    options: readonly string[];
+    defaultValue: string;
+    label?: string;
+}
+/** date-time = HTML native datetime-local、 ISO string を signal に */
+ | {
+    id: string;
+    kind: "datetime";
+    defaultValue: string;
+    label?: string;
+}
+/** text input = 短い文字列入力、 signal に string を反映 */
+ | {
+    id: string;
+    kind: "text";
+    defaultValue: string;
+    placeholder?: string;
+    maxLength?: number;
+    label?: string;
+}
+/**
+ * timeline = 時間軸を signal 化、 0..1 の progress を保持 + play / pause / seek /
+ * speed 制御 UI を提供。 phase 制御と独立、 汎用的な animation clock。
+ */
+ | {
+    id: string;
+    kind: "timeline";
+    /** loop 1 周期の ms (default 3000) */
+    duration: number;
+    /** 起動時 autoplay (default true) */
+    autoplay?: boolean;
+    /** loop するか (default true)、 false なら 1 周で停止 */
+    loop?: boolean;
+    /** 選択可能な speed (default [0.5, 1, 2, 4]) */
+    speeds?: readonly number[];
+    /** 初期 speed index (default speeds の 1 index、 即 1x) */
+    defaultSpeedIdx?: number;
+    label?: string;
+};
+/**
+ * dynamic shape spec (CAR: shape primitive)。 SVG stage 内に描画される汎用 container、
+ * signal 値で fill / radius / angle 等が動く。 chart-* / gantt-* のような fixed template
+ * ではなく orthogonal に組合せ可能な primitive、 EIP1559 相当の「rect 3 個縦並びで各 fill
+ * が signal 追随」 や「circle の radius が signal で伸縮」 のような表現を可能にする。
+ */
+type CdlDynShape = {
+    kind: "rect";
+    /** 内部を埋める値 (0..fillMax)、 signal template `{id}` or numeric */
+    source: string | number;
+    /** source の最大値 (fill が 100% になる値) */
+    fillMax: number;
+    /** fill 方向 = 'up' (下から上)、 'down' (上から下)、 'left' (右から左)、 'right' (左から右) */
+    orient?: "up" | "down" | "left" | "right";
+    /** fill 色、 template で signal 追随可 */
+    fill?: string;
+    /** 枠線色 */
+    stroke?: string;
+    /** 角丸 radius (px) */
+    radius?: number;
+} | {
+    kind: "circle";
+    /** 半径 (px) を signal 追随、 numeric or template */
+    radius?: number | string;
+    /** 中央から放射状 fill (0..1) を signal 追随、 progress ring 用 */
+    fillProgress?: number | string;
+    fill?: string;
+    stroke?: string;
+} | {
+    kind: "arc";
+    /** 内側 / 外側 radius (default: h/2 と w/2 の小さい方) */
+    innerRadius?: number;
+    outerRadius?: number;
+    /** 開始角度 (度、 3 時方向を 0 とする、 時計回り + 、 default -90) */
+    startAngle?: number;
+    /** 現在の角度を signal で駆動、 numeric or template */
+    angle: number | string;
+    /** 最大 sweep (360 で full circle) */
+    sweepMax?: number;
+    fill?: string;
+    stroke?: string;
+} | {
+    kind: "wave";
+    /** 現在の水位 (0..amplitude)、 signal 追随 */
+    level: number | string;
+    /** 最大水位 (level = amplitude で 100% fill) */
+    amplitude: number;
+    /** 波の周波数 (山の数、 default 2) */
+    frequency?: number;
+    /** 波の振幅 (px、 default 6) */
+    waveHeight?: number;
+    fill?: string;
+    stroke?: string;
+} | {
+    kind: "polygon";
+    /** 頂点数 (3-12、 3=triangle / 4=square / 5=pentagon / 6=hexagon 等) */
+    sides: number;
+    /** 半径 = 中心から頂点までの距離、 signal 追随可 */
+    radius?: number | string;
+    /** 回転角度 (度)、 signal 追随可 */
+    rotation?: number | string;
+    fill?: string;
+    stroke?: string;
+};
+/**
+ * readout widget spec (visual displays)、 signal / state 値を可視化する widget primitive
+ * (CAR: interactive widget 拡充)。 input が「値を入れる」 のに対し、 readout は「値を見せる」。
+ */
+type CdlReadout = {
+    id: string;
+    kind: "bar";
+    source: string;
+    min: number;
+    max: number;
+    color?: string;
+    label?: string;
+} | {
+    id: string;
+    kind: "gauge";
+    source: string;
+    min: number;
+    max: number;
+    color?: string;
+    label?: string;
+} | {
+    id: string;
+    kind: "stat";
+    source: string;
+    caption?: string;
+    unit?: string;
+    label?: string;
+} | {
+    id: string;
+    kind: "sparkline";
+    source: string;
+    history?: number;
+    color?: string;
+    label?: string;
+}
+/** countup = signal 値変化を animation で補間表示、 「50 → 80 に 800ms でカウントアップ」 */
+ | {
+    id: string;
+    kind: "countup";
+    source: string;
+    /** アニメ時間 ms (default 600) */
+    durationMs?: number;
+    /** 小数点桁数 (default 0) */
+    decimals?: number;
+    /** 単位 (例 "%", "ms") */
+    unit?: string;
+    label?: string;
+}
+/** typewriter = string signal を 1 字ずつ表示、 explanatory reveal 用 */
+ | {
+    id: string;
+    kind: "typewriter";
+    source: string;
+    /** 1 字あたり ms (default 40) */
+    charMs?: number;
+    label?: string;
+}
+/** delta = 前回値との差分を ↑/↓ + 数値で表示、 KPI 変化に */
+ | {
+    id: string;
+    kind: "delta";
+    source: string;
+    /** 小数点桁数 (default 1) */
+    decimals?: number;
+    unit?: string;
+    label?: string;
+}
+/** percent-ring = 円形の環状 progress、 gauge より compact */
+ | {
+    id: string;
+    kind: "percent-ring";
+    source: string;
+    /** source の最大値 (progress = source / max) */
+    max: number;
+    color?: string;
+    label?: string;
+}
+/** heat cell = signal 値を色 gradient で表現、 heatmap や status pill に */
+ | {
+    id: string;
+    kind: "heat-cell";
+    source: string;
+    min: number;
+    max: number;
+    /** 色 gradient (低い → 高い)、 default ["#e0e6ef", "#2d6a8f"] */
+    colors?: readonly string[];
+    label?: string;
+}
+/** badge = 数値をそのまま pill 表示、 stat より小さい */
+ | {
+    id: string;
+    kind: "badge";
+    source: string;
+    /** color source (default source と同じ)、 別 signal で色を切替可能 */
+    colorSource?: string;
+    /** 値と色 mapping (例: [{value: 'ok', color: 'green'}])、 未指定なら brand 色 */
+    map?: readonly {
+        value: string;
+        color: string;
+    }[];
+    label?: string;
+}
+/** status-dot = 3-4 状態を色 dot + text で、 online/offline 系 */
+ | {
+    id: string;
+    kind: "status-dot";
+    source: string;
+    map: readonly {
+        value: string;
+        color: string;
+        label?: string;
+    }[];
+    label?: string;
+}
+/** path-progress = SVG path を signal (0-100) の割合で stroke-dashoffset 進行、 progress bar の path 版 */
+ | {
+    id: string;
+    kind: "path-progress";
+    source: string;
+    /** SVG path d attribute (M x y L x y ... 形式) */
+    pathD: string;
+    /** viewBox 幅 (default 200) */
+    viewW?: number;
+    /** viewBox 高さ (default 40) */
+    viewH?: number;
+    /** stroke 幅 (default 6) */
+    strokeWidth?: number;
+    color?: string;
+    /** source 値の最大 (default 100)、 進行率 = source / max */
+    max?: number;
+    label?: string;
+}
+/** array-list = array signal を bullet list 表示、 各 element を row 化 */
+ | {
+    id: string;
+    kind: "array-list";
+    source: string;
+    /** row template (`{item}` = element 値) */
+    itemTemplate?: string;
+    /** 最大表示件数 (超過分は "…" 表示) */
+    max?: number;
+    label?: string;
+}
+/** array-bar = array signal の各 element を bar 高さで一列に並べる、 histogram 的 */
+ | {
+    id: string;
+    kind: "array-bar";
+    source: string;
+    /** 個別 bar の min/max (bar 高さ 0-100% 換算) */
+    min: number;
+    max: number;
+    color?: string;
+    label?: string;
+}
+/** line-chart = array signal を line chart 表示 (連続 point / 折れ線)、 time-series 的 */
+ | {
+    id: string;
+    kind: "line-chart";
+    source: string;
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    /** area fill も描画 (default false) */
+    fill?: boolean;
+    label?: string;
+}
+/** stacked-bar = 2 array signal を並列 bar で比較、 A / B の高さ比較 diagram 用 */
+ | {
+    id: string;
+    kind: "stacked-bar";
+    sourceA: string;
+    sourceB: string;
+    min: number;
+    max: number;
+    colorA?: string;
+    colorB?: string;
+    label?: string;
+}
+/**
+ * waterfall = array signal を左から累積、 各 element を差分 bar として表示 (財務 / 決算 waterfall chart 用)。
+ * `[100, -20, 30, -10, 40]` なら 100 → 80 → 110 → 100 → 140 の累積を bar で示す。 正 = colorPos、 負 = colorNeg。
+ */
+ | {
+    id: string;
+    kind: "waterfall";
+    source: string;
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    colorPos?: string;
+    colorNeg?: string;
+    label?: string;
+}
+/**
+ * matrix = 2D array (array of arrays) を色 gradient セルで表示 (confusion matrix / heatmap / grid state 用)。
+ * source signal は `[[1,2,3],[4,5,6],[7,8,9]]` 形式の JSON string を保持。
+ */
+ | {
+    id: string;
+    kind: "matrix";
+    source: string;
+    min: number;
+    max: number;
+    cellSize?: number;
+    colors?: readonly string[];
+    showValue?: boolean;
+    label?: string;
+}
+/**
+ * progress-group = array signal を progress bar list として表示 (task list progress 用)、
+ * 各 element を 0-max 割合の bar として並列。 labelSource で optional label array を指定可能。
+ */
+ | {
+    id: string;
+    kind: "progress-group";
+    source: string;
+    max: number;
+    labelSource?: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * sequence-timeline = array signal を横 timeline 上の event marker として表示。
+ * source は各 event の [t, name] pair の JSON string 想定 (`[[0,"login"],[100,"auth"],[400,"resp"]]`)
+ * 又は t のみ配列 (`[0,100,400]`) で index を name として使う。 time axis は min-max で正規化。
+ */
+ | {
+    id: string;
+    kind: "sequence-timeline";
+    source: string;
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * radar = array signal (N 次元 value) を N-gon spider chart で表示。
+ * source は N 個の 数値 array (`[8, 5, 7, 3, 9]`)、 各 axis は 0-max 正規化、
+ * labelSource で optional axis 名 array。
+ */
+ | {
+    id: string;
+    kind: "radar";
+    source: string;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    labelSource?: string;
+    label?: string;
+}
+/**
+ * bubble-chart = 3D data (x, y, r) の bubbles、 source は `[[x,y,r], ...]` の 3-tuple array。
+ * x-min/max、 y-min/max、 r-min/max で正規化、 SVG viewBox 内に配置。
+ */
+ | {
+    id: string;
+    kind: "bubble-chart";
+    source: string;
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+    rMin: number;
+    rMax: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * donut = array signal を multi-segment donut chart で表示 (percentage-ring の N segment 版)。
+ * 各 segment は array[i] / sum で角度、 color rotate で色分け、 center hole 半径可調整。
+ */
+ | {
+    id: string;
+    kind: "donut";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    colors?: readonly string[];
+    innerRatio?: number;
+    label?: string;
+}
+/**
+ * calendar-heatmap = 1 年分の日次 count を week × day matrix で表示 (GitHub contribution graph 系)。
+ * source は 365 element の numeric array、 各 index が day 0-364、 color gradient で count 表現。
+ */
+ | {
+    id: string;
+    kind: "calendar-heatmap";
+    source: string;
+    /** count max value (color intensity の 100% 到達点) */
+    max: number;
+    /** cell size px (default 10) */
+    cellSize?: number;
+    /** cell gap px (default 2) */
+    cellGap?: number;
+    colors?: readonly string[];
+    label?: string;
+}
+/**
+ * mini-map = 大 canvas 上の現在 viewport を縮小表示 (overview 系)。
+ * source は `[vx, vy, vw, vh]` の 4-tuple JSON (viewport rect in canvas coords)、
+ * canvasW / canvasH で大 canvas 全体の座標系を宣言。
+ */
+ | {
+    id: string;
+    kind: "mini-map";
+    source: string;
+    canvasW: number;
+    canvasH: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * kpi-card = 現在値 + 直前値との delta + mini sparkline を 1 tile に composite (dashboard 用 KPI 単体)。
+ * source = 現在値 signal、 historySource = 数値 array signal (sparkline)、 comparisonSource = 直前値 signal (delta 計算用)。
+ */
+ | {
+    id: string;
+    kind: "kpi-card";
+    source: string;
+    historySource: string;
+    comparisonSource: string;
+    unit?: string;
+    colorPos?: string;
+    colorNeg?: string;
+    label?: string;
+}
+/**
+ * candlestick = OHLC array (`[[open, high, low, close], ...]`) を蝋燭足で表示 (finance chart 用)。
+ * close >= open は colorUp、 close < open は colorDown で色分け、 wick (high/low) は 縦線。
+ */
+ | {
+    id: string;
+    kind: "candlestick";
+    source: string;
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    colorUp?: string;
+    colorDown?: string;
+    label?: string;
+}
+/**
+ * venn = 2-set Venn diagram、 source = `[|A|, |B|, |A∩B|]` の 3-tuple。
+ * 円 A と円 B の中心を A, B の相対 size 比で position、 intersection を色 blend 表示。
+ */
+ | {
+    id: string;
+    kind: "venn";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    colorA?: string;
+    colorB?: string;
+    labelA?: string;
+    labelB?: string;
+    label?: string;
+}
+/**
+ * slope = before/after slope chart。 source = `[[beforeVal, afterVal, name], ...]` の 3-tuple array、
+ * 2 column の dot + connecting line で before → after 変化を表示。
+ */
+ | {
+    id: string;
+    kind: "slope";
+    source: string;
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    colorUp?: string;
+    colorDown?: string;
+    label?: string;
+}
+/**
+ * funnel = conversion funnel chart。 source = `[[stage, count], ...]` の 2-tuple array (order 順)、
+ * 各 stage を trapezoid で描画、 段階的 narrowing で conversion rate を可視化。
+ */
+ | {
+    id: string;
+    kind: "funnel";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    colorTop?: string;
+    colorBottom?: string;
+    label?: string;
+}
+/**
+ * gantt = task timeline。 source = `[[name, start, duration], ...]` の 3-tuple array、
+ * 各 task を bar で表示 (start-x / duration-w)、 timelime 上に色分け。
+ */
+ | {
+    id: string;
+    kind: "gantt";
+    source: string;
+    /** timeline 全体の min / max (day / hour 単位任意) */
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * treemap = hierarchical rectangles。 source = `[[name, size], ...]` array (top level のみ、 nested 非対応)、
+ * squarified 風 layout で area 比例配置。
+ */
+ | {
+    id: string;
+    kind: "treemap";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    colors?: readonly string[];
+    label?: string;
+}
+/**
+ * sankey = 2 column flow diagram。 source = `[[fromName, toName, flow], ...]`、
+ * left column = source group、 right column = target group、 flow の合計高さを bar 化、 flow を curve で結ぶ。
+ */
+ | {
+    id: string;
+    kind: "sankey";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    colors?: readonly string[];
+    label?: string;
+}
+/**
+ * polar-area (nightingale rose) = array を極座標 area chart で表示。
+ * 各 element は 360/n 度の扇形、 area (r^2) 比例で 値を表現、 radar と異なり sector 単位。
+ */
+ | {
+    id: string;
+    kind: "polar-area";
+    source: string;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    colors?: readonly string[];
+    labelSource?: string;
+    label?: string;
+}
+/**
+ * step-indicator = wizard step progress。 source = 現在 step index (数値)、 stepsSource = step 名 array。
+ * 各 step を dot + label で横に並べ、 現在 step までを active、 それ以降を pending 色で表示。
+ */
+ | {
+    id: string;
+    kind: "step-indicator";
+    source: string;
+    stepsSource: string;
+    viewW?: number;
+    viewH?: number;
+    colorActive?: string;
+    colorPending?: string;
+    label?: string;
+}
+/**
+ * bullet-chart = target vs actual + 3 range (bad / avg / good) horizontal bar (KPI dashboard 用)。
+ * source = actual value、 targetSource = target value、 max で正規化。 range 3 段階を背景色 gradient で。
+ */
+ | {
+    id: string;
+    kind: "bullet-chart";
+    source: string;
+    targetSource: string;
+    max: number;
+    /** 3 range boundary (`[bad, avg]`)、 default = [max*0.4, max*0.7] */
+    rangeBad?: number;
+    rangeAvg?: number;
+    viewW?: number;
+    viewH?: number;
+    colorActual?: string;
+    label?: string;
+}
+/**
+ * number-board = 大 numeric display + optional prefix / suffix (scoreboard style)。
+ * source = 数値 signal、 subtitle 可能。 stat より格段に大きい表示。
+ */
+ | {
+    id: string;
+    kind: "number-board";
+    source: string;
+    prefix?: string;
+    suffix?: string;
+    /** 数字 font size px (default 42) */
+    size?: number;
+    color?: string;
+    /** small subtitle 表示用 */
+    caption?: string;
+    label?: string;
+}
+/**
+ * leaderboard = ranked list。 source = `[[name, value], ...]` array、 value desc sort、 rank + name + value を行表示。
+ * medal 色 (top 3) 装飾 + max 表示件数。
+ */
+ | {
+    id: string;
+    kind: "leaderboard";
+    source: string;
+    /** 最大表示件数 (default 5) */
+    max?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * traffic-light = 3-color status indicator (red / yellow / green)、 source は "red" | "yellow" | "green" | 数値 (0=red / 1=yellow / 2=green)。
+ * 大きい 3 光 dot、 active のみ光る、 build / deploy / health status 定番。
+ */
+ | {
+    id: string;
+    kind: "traffic-light";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    label?: string;
+}
+/**
+ * tag-cloud = `[[tag, weight], ...]` array を weight 比例 font-size で並列表示、 keyword prominence を可視化。
+ */
+ | {
+    id: string;
+    kind: "tag-cloud";
+    source: string;
+    /** min / max font size (default 10 / 24) */
+    minSize?: number;
+    maxSize?: number;
+    colors?: readonly string[];
+    label?: string;
+}
+/**
+ * activity-feed = `[[actor, action, time], ...]` array を activity list として表示。
+ * 各 row = actor bullet + action text + relative time、 recent-first 表示。
+ */
+ | {
+    id: string;
+    kind: "activity-feed";
+    source: string;
+    max?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * rating = 0-max の value を N star 表示、 half-star 対応、 review score / product rating 用。
+ */
+ | {
+    id: string;
+    kind: "rating";
+    source: string;
+    /** 星の総数 (default 5) */
+    count?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * notification = alert card、 kindSource で "info" / "warn" / "error" / "success" を signal 経由切替。
+ * title + body の 2 段表示、 kind 別 color + icon (emoji)。
+ */
+ | {
+    id: string;
+    kind: "notification";
+    /** kind signal (info / warn / error / success) */
+    kindSource: string;
+    /** title text signal */
+    titleSource: string;
+    /** body text signal (optional、 未指定なら title のみ表示) */
+    bodySource?: string;
+    label?: string;
+}
+/**
+ * diff-counter = +N / -N の 2 stat を signal 経由で表示 (git commit style)、 addition/deletion。
+ */
+ | {
+    id: string;
+    kind: "diff-counter";
+    additionsSource: string;
+    deletionsSource: string;
+    colorAdd?: string;
+    colorDel?: string;
+    label?: string;
+}
+/**
+ * chat-bubble = conversation thread。 source = `[[author, text, isSelf], ...]` array (3-tuple)、
+ * isSelf=true で右寄せ + 別色、 false で左寄せ、 message thread 定番 layout。
+ */
+ | {
+    id: string;
+    kind: "chat-bubble";
+    source: string;
+    max?: number;
+    colorSelf?: string;
+    colorOther?: string;
+    label?: string;
+}
+/**
+ * avatar = user avatar circle (initials + background color)、 source = user 名 (initials 抽出) or `[name, colorHex]` の 2-tuple。
+ * simple 用途 = 名前だけ / 高度 = [name, color] で per-user 色制御。
+ */
+ | {
+    id: string;
+    kind: "avatar";
+    source: string;
+    /** サイズ px (default 40) */
+    size?: number;
+    /** default color (source が name のみで color 未指定時) */
+    color?: string;
+    label?: string;
+}
+/**
+ * checklist = `[[label, checked], ...]` の 2-tuple array を checked/unchecked check-box list で表示、 progress % 併記。
+ */
+ | {
+    id: string;
+    kind: "checklist";
+    source: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * circular-gauge = 270° dial (open bottom) の gauge、 speedometer / tachometer 用。
+ * source = 現在値、 min-max で正規化、 needle 表示 + gradient arc。
+ */
+ | {
+    id: string;
+    kind: "circular-gauge";
+    source: string;
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    /** 中央 unit / 単位 表示 */
+    unit?: string;
+    label?: string;
+}
+/**
+ * price-tag = old / new / discount% を表示 (e-commerce 定番)、
+ * oldSource / newSource を signal 経由取得、 discount は自動計算。
+ */
+ | {
+    id: string;
+    kind: "price-tag";
+    oldSource: string;
+    newSource: string;
+    /** 通貨 prefix (例 "$", "¥") */
+    currency?: string;
+    colorNew?: string;
+    colorOld?: string;
+    colorDiscount?: string;
+    label?: string;
+}
+/**
+ * spinner = loading state indicator、 running/done/error 3 状態を signal 経由切替、 label text 併記。
+ */
+ | {
+    id: string;
+    kind: "spinner";
+    source: string;
+    textSource: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * grade = 0-100 score を A/B/C/D/F letter grade で表示、 color band 別。 education / review 定番。
+ */
+ | {
+    id: string;
+    kind: "grade";
+    source: string;
+    /** score max value (default 100)、 A cutoff = max*0.9、 B = 0.8、 C = 0.7、 D = 0.6 未満 = F */
+    max?: number;
+    label?: string;
+}
+/**
+ * stopwatch = ms 数値 signal を MM:SS.ms 形式で表示 (large font display)。
+ */
+ | {
+    id: string;
+    kind: "stopwatch";
+    /** ms value signal */
+    source: string;
+    /** running=true で緑 running color、 false で gray idle color */
+    runningSource?: string;
+    size?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * confidence-meter = 0-100 % を 3 color band (low/mid/high) で bar + label 表示、 ML/AI 定番。
+ */
+ | {
+    id: string;
+    kind: "confidence-meter";
+    source: string;
+    lowThreshold?: number;
+    highThreshold?: number;
+    viewW?: number;
+    viewH?: number;
+    label?: string;
+}
+/**
+ * reaction-bar = `[[emoji, count], ...]` array を emoji + count の pill list で表示、 social reactions 用。
+ */
+ | {
+    id: string;
+    kind: "reaction-bar";
+    source: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * pill-group = string array or `[[label, colorHex], ...]` を small pill badge list で表示。
+ */
+ | {
+    id: string;
+    kind: "pill-group";
+    source: string;
+    /** default color (source が string array のみで color 未指定時) */
+    color?: string;
+    label?: string;
+}
+/**
+ * fuel-bar = 0-100% を segmented horizontal bar で表示 (battery / fuel / stamina 定番)、 3 color band。
+ */
+ | {
+    id: string;
+    kind: "fuel-bar";
+    source: string;
+    segments?: number;
+    lowThreshold?: number;
+    highThreshold?: number;
+    viewW?: number;
+    viewH?: number;
+    label?: string;
+}
+/**
+ * metrics-grid = `[[name, value, unit?], ...]` を 2×2 grid で 4 stat 表示、 dashboard header 定番。
+ */
+ | {
+    id: string;
+    kind: "metrics-grid";
+    source: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * thermometer = 縦 bar で温度表示、 min-max で正規化、 現在値のみ signal 経由。
+ */
+ | {
+    id: string;
+    kind: "thermometer";
+    source: string;
+    min: number;
+    max: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    /** 単位 (default "°") */
+    unit?: string;
+    label?: string;
+}
+/**
+ * icon-tile = `[[icon, label, value], ...]` を icon + label + value の tile 列で表示。 stat 系の visual 版。
+ */
+ | {
+    id: string;
+    kind: "icon-tile";
+    source: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * token-list = `[[icon, name, amount, deltaPct], ...]` の crypto/asset list、 icon + name + amount + delta% で表示。
+ */
+ | {
+    id: string;
+    kind: "token-list";
+    source: string;
+    colorUp?: string;
+    colorDown?: string;
+    label?: string;
+}
+/**
+ * map-pin = `[[name, x, y], ...]` を 2D coord 上の pin として表示、 mini map / seat map / world map 定番。
+ */
+ | {
+    id: string;
+    kind: "map-pin";
+    source: string;
+    /** 座標 min/max (map の world 座標系) */
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+    viewW?: number;
+    viewH?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * priority-badge = high/med/low priority indicator + label、 issue / ticket 定番。
+ */
+ | {
+    id: string;
+    kind: "priority-badge";
+    source: string;
+    textSource?: string;
+    label?: string;
+}
+/**
+ * podium = 1st/2nd/3rd の 3 top winner を表彰台 (縦 bar) で表示、 competition / ranking 定番。
+ * source は `[[1st_name, 1st_score], [2nd_name, 2nd_score], [3rd_name, 3rd_score]]` (順位順 3 entries)。
+ */
+ | {
+    id: string;
+    kind: "podium";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    label?: string;
+}
+/**
+ * poll-bar = poll option list、 各 option + % で表示、 max 選択に winner 装飾。
+ * source は `[[option, count], ...]` array (2-tuple)、 合計 % を自動計算。
+ */
+ | {
+    id: string;
+    kind: "poll-bar";
+    source: string;
+    color?: string;
+    colorWinner?: string;
+    label?: string;
+}
+/**
+ * user-stack = stacked circular avatars (GitHub reviewers style)、 name array を initials で表示、 overlap で層状に。
+ * source は string array of names、 max 表示 + overflow +N。
+ */
+ | {
+    id: string;
+    kind: "user-stack";
+    source: string;
+    max?: number;
+    size?: number;
+    label?: string;
+}
+/**
+ * commit-list = `[[sha, msg, author], ...]` の git commit history、 短 sha + 1 行 msg + author で行表示。
+ */
+ | {
+    id: string;
+    kind: "commit-list";
+    source: string;
+    max?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * media-player = play/pause + progress bar + time display (audio/video mini player)。
+ * source = 現在再生位置 sec、 durationSource = 総時間 sec、 playingSource = 再生 flag。
+ */
+ | {
+    id: string;
+    kind: "media-player";
+    source: string;
+    durationSource: string;
+    playingSource: string;
+    color?: string;
+    viewW?: number;
+    label?: string;
+}
+/**
+ * event-log = `[[timestamp, severity, msg], ...]` の event stream、 info/warn/error 色分け、 timestamp + msg 表示。
+ */
+ | {
+    id: string;
+    kind: "event-log";
+    source: string;
+    max?: number;
+    label?: string;
+}
+/**
+ * search-result = `[[title, snippet, url], ...]` の search hit rows。
+ */
+ | {
+    id: string;
+    kind: "search-result";
+    source: string;
+    max?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * roadmap = `[[quarter, items[]]]` 形式の quarterly roadmap (Q1-Q4)、 quarter 別に task list。
+ * source は `[["Q1", ["Task A", "Task B"]], ["Q2", ["Task C"]], ...]`。
+ */
+ | {
+    id: string;
+    kind: "roadmap";
+    source: string;
+    viewW?: number;
+    viewH?: number;
+    label?: string;
+}
+/**
+ * weather-forecast = `[[day, icon, high, low], ...]` の 5-day weather、 icon (☀ ☁ ☂ ⚡) + 高低 temp。
+ */
+ | {
+    id: string;
+    kind: "weather-forecast";
+    source: string;
+    label?: string;
+}
+/**
+ * video-card = `[[emoji, title, duration, viewCount], ...]` の video thumbnail list、 icon + title + duration + views。
+ */
+ | {
+    id: string;
+    kind: "video-card";
+    source: string;
+    max?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * order-status = order tracking steps、 source = 現在 step (0-3)、 stepsSource = step names array。 step 別 icon (📦 → 🚚 → 🏠 → ✅)。
+ */
+ | {
+    id: string;
+    kind: "order-status";
+    source: string;
+    stepsSource: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * attendance-grid = 出席表、 source = `[[day, present1, present2, ...], ...]` の 2D array (行=日、 列=member)、 present で ● / absent で ○ 表示。
+ */
+ | {
+    id: string;
+    kind: "attendance-grid";
+    source: string;
+    membersSource: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * timezone-clock = `[[city, offsetHours, HH:MM], ...]` の multi-timezone clock、 都市名 + オフセット + 時刻表示。
+ */
+ | {
+    id: string;
+    kind: "timezone-clock";
+    source: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * form-summary = `[[fieldName, value], ...]` の form 送信内容 summary、 label + value の 2 column layout。
+ */
+ | {
+    id: string;
+    kind: "form-summary";
+    source: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * song-queue = `[[title, artist, duration], ...]` の song playlist queue、 現在再生曲を highlight。
+ */
+ | {
+    id: string;
+    kind: "song-queue";
+    source: string;
+    currentSource?: string;
+    max?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * calendar-month = 1 month calendar view、 source = `[[day, isEvent, isToday], ...]` の day 情報。
+ * 6 週 × 7 日 grid、 event 有り day は dot marker、 today は border 強調。
+ */
+ | {
+    id: string;
+    kind: "calendar-month";
+    source: string;
+    /** 月名 (例 "January 2026") */
+    monthName?: string;
+    color?: string;
+    label?: string;
+}
+/**
+ * terminal = CLI terminal output、 source = `[[prompt, cmd, output], ...]` の command history。
+ * mono font + prompt color + output preformatted 表示。
+ */
+ | {
+    id: string;
+    kind: "terminal";
+    source: string;
+    max?: number;
+    color?: string;
+    label?: string;
+}
+/**
+ * chess-board = 8×8 chess board、 source = `[[file, rank, piece], ...]` の piece 配置 (file=a-h、 rank=1-8、 piece=♔♕♖♗♘♙♚♛♜♝♞♟)。
+ */
+ | {
+    id: string;
+    kind: "chess-board";
+    source: string;
+    /** cell size px (default 24) */
+    cellSize?: number;
+    label?: string;
+}
+/**
+ * kanban-board = 3 column task board (Todo / In Progress / Done)、 source = `[[column, task, priority?], ...]` の task 配置。
+ * column は "todo" / "inprogress" / "done" のいずれか (case insensitive、 別名 "in-progress" / "in_progress" 許容)。 layout diversity pattern taxonomy § 1 state-based split と共鳴、 task を state 別に card 並列表示。
+ */
+ | {
+    id: string;
+    kind: "kanban-board";
+    source: string;
+    /** column width px (default 130) */
+    columnWidth?: number;
+    /** column max task 数 (default 5、 超過は "+N more") */
+    max?: number;
+    label?: string;
+}
+/**
+ * breadcrumb = navigation path、 source = `["Home", "Docs", "API", ...]` の label array、 currentSource で active index を指定。
+ * `Home > Docs > API > Reference` の pattern で表示、 current は bold + accent color。 layout diversity pattern taxonomy § 4 pipeline flow と共鳴、 navigation 遷移を可視化。
+ */
+ | {
+    id: string;
+    kind: "breadcrumb";
+    source: string;
+    /** current active index を保持する signal id (未指定なら last item を active 扱い) */
+    currentSource?: string;
+    /** active color (default "#2563eb") */
+    color?: string;
+    label?: string;
+}
+/**
+ * timeline-vertical = 縦 timeline (dot + line + text)、 source = `[[timestamp, title, description], ...]` の event array。
+ * layout diversity pattern taxonomy § 7 individual element split と共鳴、 各 event を dot marker で連続表示、 event log / history 定番。
+ */
+ | {
+    id: string;
+    kind: "timeline-vertical";
+    source: string;
+    /** dot color (default "#2563eb") */
+    color?: string;
+    /** 最大表示 event 数 (default 8) */
+    max?: number;
+    label?: string;
+}
+/**
+ * status-timeline = 時系列 status 遷移 (Active/Idle/Error 等)、 source = `[[timestamp, status], ...]`。
+ * status 別 color band で横 timeline strip 表示、 uptime / server state monitoring 定番。 layout diversity pattern taxonomy § 4 pipeline flow と共鳴。
+ */
+ | {
+    id: string;
+    kind: "status-timeline";
+    source: string;
+    /** status → color の対応 (default = "active":green / "idle":gray / "error":red) */
+    colorMap?: Array<{
+        status: string;
+        color: string;
+    }>;
+    /** 最大表示 event 数 (default 10) */
+    max?: number;
+    label?: string;
+}
+/**
+ * calendar-week = 7-day mini calendar、 source = `[[dayLabel, hasEvent, isToday], ...]` の 7 day tuple。 calendar-month の縮小版、 週間 dashboard 用。
+ * layout diversity pattern taxonomy § 7 individual element split と共鳴。
+ */
+ | {
+    id: string;
+    kind: "calendar-week";
+    source: string;
+    /** cell size px (default 40) */
+    cellSize?: number;
+    /** event color (default "#2563eb") */
+    color?: string;
+    label?: string;
+}
+/**
+ * kpi-comparison = 2 KPI を horizontal bar で並列比較、 source = `[[label, value], [label, value]]` の 2-tuple。
+ * A vs B の直接比較を可視化、 A/B test / period comparison 定番。 layout diversity pattern taxonomy § 3 category split と共鳴。
+ */
+ | {
+    id: string;
+    kind: "kpi-comparison";
+    source: string;
+    /** value 最大値 (bar width の基準、 default = max(A, B)) */
+    max?: number;
+    /** A color (default "#2563eb") */
+    colorA?: string;
+    /** B color (default "#f97316") */
+    colorB?: string;
+    label?: string;
+}
+/**
+ * step-progress = numbered step + progress line、 source = current step index (0-indexed number)。
+ * stepsSource で step ラベル array。 layout diversity pattern taxonomy § 4 pipeline flow + § 5 fan-out と共鳴、 wizard progress の可視化。
+ */
+ | {
+    id: string;
+    kind: "step-progress";
+    source: string;
+    /** step ラベル array を保持する signal id */
+    stepsSource: string;
+    /** active color (default "#2563eb") */
+    color?: string;
+    label?: string;
+}
+/**
+ * user-presence = user list + presence dot、 source = `[[name, status], ...]` の tuple。
+ * status = "online" (green) / "away" (yellow) / "offline" (gray)、 team collaboration 定番。 layout diversity pattern taxonomy § 1 state-based split と共鳴。
+ */
+ | {
+    id: string;
+    kind: "user-presence";
+    source: string;
+    /** max 表示人数 (default 6、 超過は "+N more") */
+    max?: number;
+    label?: string;
+}
+/**
+ * rating-thumb = thumbs up/down rating、 source = `[up_count, down_count]` の 2-tuple。
+ * total votes + up %計算 + colored bar 表示、 review / feedback 定番。 layout diversity pattern taxonomy § 3 category split と共鳴 (2 category)。
+ */
+ | {
+    id: string;
+    kind: "rating-thumb";
+    source: string;
+    /** up color (default "#22c55e") */
+    colorUp?: string;
+    /** down color (default "#ef4444") */
+    colorDown?: string;
+    label?: string;
+}
+/**
+ * org-chart-mini = organization hierarchy 3 level (CEO → Manager → IC)、 source = `[[name, level], ...]` の tuple。
+ * level = 0 (root) / 1 (mid) / 2 (leaf) の 3 tier で自動配置、 layout diversity pattern taxonomy § 8 tree depth split と共鳴。
+ */
+ | {
+    id: string;
+    kind: "org-chart-mini";
+    source: string;
+    /** node color (default "#2563eb") */
+    color?: string;
+    label?: string;
+}
+/**
+ * kpi-trend-tile = KPI current value + delta arrow + mini sparkline を 1 tile 表示、 sources = `[current, prev]`、 historySource = 履歴 array。
+ * layout diversity pattern taxonomy § 5 fan-out と共鳴 (1 tile が current + delta + spark の 3 view を fan-out)。
+ */
+ | {
+    id: string;
+    kind: "kpi-trend-tile";
+    /** current value signal id */
+    source: string;
+    /** previous value signal id (delta 計算用) */
+    prevSource: string;
+    /** history array signal id (sparkline 用) */
+    historySource: string;
+    /** unit (例 "%" / "$M") */
+    unit?: string;
+    /** positive color (default "#22c55e") */
+    colorPos?: string;
+    /** negative color (default "#ef4444") */
+    colorNeg?: string;
+    label?: string;
+}
+/**
+ * quick-poll-emoji = 3-4 emoji poll (👍/❤️/🎉 等)、 source = `[[emoji, count], ...]`。
+ * 各 emoji + count で pill 表示、 total 合計、 winner emoji に highlight border。 layout diversity pattern taxonomy § 3 category split と共鳴 (emoji 別 category)。
+ */
+ | {
+    id: string;
+    kind: "quick-poll-emoji";
+    source: string;
+    /** winner border color (default "#2563eb") */
+    colorWinner?: string;
+    label?: string;
+}
+/**
+ * voice-message = audio playback UI、 source = arraySignal `[amp, amp, ...]` (0..1 amplitudes)。
+ * horizontal bar 群 + play triangle + duration text、 progressSource 指定で playback progress overlay。
+ * layout diversity pattern taxonomy § 7 dense sequence と共鳴 (waveform bar の連続配置)。
+ */
+ | {
+    id: string;
+    kind: "voice-message";
+    source: string;
+    /** state id for playback progress 0..1 (optional) */
+    progressSource?: string;
+    /** total duration seconds (default 30) */
+    duration?: number;
+    /** play button color (default "#2563eb") */
+    colorPlay?: string;
+    /** bar color (default "#cbd5e1") */
+    colorBar?: string;
+    label?: string;
+}
+/**
+ * thread-summary = conversation thread summary card、 source = arraySignal `[unreadNum, participantsNum, lastAuthorStr, timeAgoStr]` の 4-tuple。
+ * unread badge + participant count + last author + time ago の 4 情報を 1 card に集約。
+ * layout diversity pattern taxonomy § 3 category split と共鳴 (4 field 分割 layout)。
+ */
+ | {
+    id: string;
+    kind: "thread-summary";
+    source: string;
+    /** unread badge color (default "#ef4444") */
+    colorUnread?: string;
+    label?: string;
+}
+/**
+ * read-receipt = message read status、 source = state (number 0=sent / 1=delivered / 2=read)。
+ * status 0 = single check gray、 1 = double check gray、 2 = double check colored (read)。
+ * layout diversity pattern taxonomy § 2 state-driven visibility と共鳴 (status 別 icon)。
+ */
+ | {
+    id: string;
+    kind: "read-receipt";
+    source: string;
+    /** read color (default "#2563eb") */
+    colorRead?: string;
+    /** pending color (default "#94a3b8") */
+    colorPending?: string;
+    label?: string;
+}
+/**
+ * password-strength = パスワード強度 4 段階 meter、 source = state (number 0=too weak / 1=weak / 2=fair / 3=good / 4=strong)。
+ * 4 bar segment を strength 分 fill、 label text (too weak / weak / fair / good / strong) 表示。
+ * layout diversity pattern taxonomy § 4 rank-based split と共鳴 (level 別 rank)。
+ */
+ | {
+    id: string;
+    kind: "password-strength";
+    source: string;
+    /** strong color (default "#22c55e") */
+    colorStrong?: string;
+    /** weak color (default "#ef4444") */
+    colorWeak?: string;
+    label?: string;
+}
+/**
+ * otp-input = 6-digit OTP entry box grid、 source = arraySignal `[d0, d1, d2, d3, d4, d5]` (0-9 or -1 未入力)。
+ * 6 box を横並び、 各 box に digit 表示、 focus (次の empty box) を highlight border。
+ * layout diversity pattern taxonomy § 7 dense sequence と共鳴 (dense box row)。
+ */
+ | {
+    id: string;
+    kind: "otp-input";
+    source: string;
+    /** focus color (default "#2563eb") */
+    colorFocus?: string;
+    label?: string;
+}
+/**
+ * file-dropzone = drag-and-drop file upload zone、 source = state (string filename or "" for empty)。
+ * empty = dashed border + icon + prompt、 filled = filename card + size 表示。
+ * layout diversity pattern taxonomy § 2 state-driven visibility と共鳴 (empty / filled 状態切替)。
+ */
+ | {
+    id: string;
+    kind: "file-dropzone";
+    source: string;
+    /** active border color (default "#2563eb") */
+    colorActive?: string;
+    label?: string;
+}
+/**
+ * log-stream = real-time log tail、 source = arraySignal `[[timestamp, level, message], ...]` の 3-tuple。
+ * level = 0=debug (gray) / 1=info (blue) / 2=warn (orange) / 3=error (red)、 最新 5 行表示。
+ * layout diversity pattern taxonomy § 7 dense sequence と共鳴 (log row 連続配置)。
+ */
+ | {
+    id: string;
+    kind: "log-stream";
+    source: string;
+    label?: string;
+}
+/**
+ * alert-banner = severity 別 alert banner、 source = arraySignal `[severity, message]` の 2-tuple (severity = 0=info / 1=success / 2=warn / 3=error)。
+ * severity 別 bg color + icon + message、 1 line 表示。
+ * layout diversity pattern taxonomy § 2 state-driven visibility と共鳴 (severity 別視覚切替)。
+ */
+ | {
+    id: string;
+    kind: "alert-banner";
+    source: string;
+    label?: string;
+}
+/**
+ * service-health = service health matrix、 source = arraySignal `[[serviceName, status], ...]` の 2-tuple (status = 0=down / 1=degraded / 2=up)。
+ * 各 service tile に status dot (red / yellow / green)、 grid layout 3-column。
+ * layout diversity pattern taxonomy § 3 category split と共鳴 (service 別 category)。
+ */
+ | {
+    id: string;
+    kind: "service-health";
+    source: string;
+    label?: string;
+}
+/**
+ * cart-summary = shopping cart totals、 source = arraySignal `[itemCount, subtotal, shipping, total]` の 4-tuple (numbers)。
+ * 4 row (Items / Subtotal / Shipping / Total) の label + value 表示、 Total 行は bold + colored。
+ * layout diversity pattern taxonomy § 4 rank-based split と共鳴 (order rank の 4 段)。
+ */
+ | {
+    id: string;
+    kind: "cart-summary";
+    source: string;
+    /** currency prefix (default "$") */
+    currency?: string;
+    /** total color (default "#2563eb") */
+    colorTotal?: string;
+    label?: string;
+}
+/**
+ * pricing-tier = pricing plan card、 source = arraySignal `[planName, price, feature1, feature2, feature3]` の 5-tuple。
+ * plan name header + price 大文字 + 3 feature bullet + CTA button 表示、 1 card layout。
+ * layout diversity pattern taxonomy § 3 category split と共鳴 (plan tier category)。
+ */
+ | {
+    id: string;
+    kind: "pricing-tier";
+    source: string;
+    /** highlight color for price + CTA (default "#2563eb") */
+    colorAccent?: string;
+    /** currency prefix (default "$") */
+    currency?: string;
+    label?: string;
+}
+/**
+ * coupon-code = coupon code entry + apply status、 source = arraySignal `[code, discountPct]` の 2-tuple (code = string、 discountPct = number 0-100)。
+ * code entry box + "% off" badge (discountPct > 0 なら success color、 0 なら未適用)。
+ * layout diversity pattern taxonomy § 2 state-driven visibility と共鳴 (applied / not applied 切替)。
+ */
+ | {
+    id: string;
+    kind: "coupon-code";
+    source: string;
+    /** applied color (default "#22c55e") */
+    colorApplied?: string;
+    label?: string;
+}
+/**
+ * article-preview = blog article preview card、 source = arraySignal `[title, excerpt, author, timeAgo]` の 4-tuple。
+ * thumbnail placeholder + title + excerpt + author/timeAgo meta の 1 card layout。
+ * layout diversity pattern taxonomy § 3 category split と共鳴 (4 field split)。
+ */
+ | {
+    id: string;
+    kind: "article-preview";
+    source: string;
+    /** accent color for title (default "#2563eb") */
+    colorAccent?: string;
+    label?: string;
+}
+/**
+ * toc-nav = table of contents nav with active section、 source = arraySignal `[[level, title, isActive], ...]` の 3-tuple (level = 0/1/2 indent、 isActive = 0/1)。
+ * level 別 indent、 active item に highlight border + colored text。
+ * layout diversity pattern taxonomy § 8 tree depth split と共鳴 (level 別 indent)。
+ */
+ | {
+    id: string;
+    kind: "toc-nav";
+    source: string;
+    /** active color (default "#2563eb") */
+    colorActive?: string;
+    label?: string;
+}
+/**
+ * share-buttons = social share button row、 source = arraySignal `[[platform, count], ...]` の 2-tuple (platform = "tw" | "fb" | "li" | "rd" 等、 count = shares)。
+ * horizontal button row + platform icon + count 表示。
+ * layout diversity pattern taxonomy § 7 dense sequence と共鳴 (button 連続配置)。
+ */
+ | {
+    id: string;
+    kind: "share-buttons";
+    source: string;
+    label?: string;
+};
+type CdlPhase = {
+    id: string;
+    duration: number;
+    title: string;
+    body: string;
+    activate: string[];
+    /** 数値 state の線形補間 (write phase で 100→90 等) */
+    tweens: Array<{
+        stateId: string;
+        from: number;
+        to: number;
+    }>;
+    /** 任意型 state の即時切替 (この phase に到達したら値を上書き、 lerp なし) */
+    sets: Array<{
+        stateId: string;
+        value: string | number;
+    }>;
+    badge?: string;
+};
+/**
+ * formula spec (v0.5+、 CAR #244)。
+ * builder chain の `.formula(id, expression)` で追加、 expression は safe subset の算術 mini-DSL。
+ * consumer は createFormulaComputeds(diagram, signals) で id → computed の map を得て bind する。
+ */
+type CdlFormula = {
+    id: string;
+    /** safe subset expression 文字列。 例 `"gasBase * (1 + delta/8)"` */
+    expression: string;
+};
+/**
+ * event handler の bind target (CAR #246)。 node / edge / lane の id 指定 or diagram 全体 (root)。
+ * consumer app 側で該当 element を data-cdl-node / data-cdl-edge / data-cdl-lane 属性で識別する前提。
+ */
+type CdlEventTarget = {
+    kind: "node";
+    id: string;
+} | {
+    kind: "edge";
+    id: string;
+} | {
+    kind: "lane";
+    id: string;
+} | {
+    kind: "diagram";
+};
+/**
+ * DOM event 種別 (CAR #246)。 現状 click / hover の 2 種、 将来 focus / keydown 等の拡張余地あり。
+ * hover は mouseenter に対応 (mouseleave での逆 event は別途 handler で分岐)。
+ */
+type CdlEventKind = "click" | "hover" | "double-click" | "long-press" | "drag" | "drop" | "keydown" | "focus" | "blur";
+/**
+ * event handler binding spec (v0.5+、 CAR #246)。
+ * builder chain の `.on.click(target, handlerId)` / `.on.hover(target, handlerId)` で追加、
+ * consumer は attachEventHandlers(root, diagram, handlers) で { handlerId → function } map を渡して bind。
+ *
+ * JSON DSL 互換のため handler 実体は string id のみ格納、 実際の関数は attach 時に caller が渡す。
+ * LLM 生成経路が handler id を string で書き、 consumer 側で id → function 対応表を管理する design。
+ */
+type CdlEventBinding = {
+    id: string;
+    event: CdlEventKind;
+    target: CdlEventTarget;
+    handlerId: string;
+};
+/**
+ * scroll-driven animation trigger spec (v0.5+、 CAR #245)。
+ *
+ * scroll 位置に応じて 0..1 の progress を生成する trigger。 arc-intro 風 narrative や scroll 連動 timeline
+ * の起点となる。 consumer は createScrollProgressSignal(spec) で { signal, attach, detach } を得て、
+ * DOM element に IntersectionObserver / getBoundingClientRect 経由で bind する。
+ *
+ * start / end は viewport 相対位置の割合 (0 = viewport top、 1 = viewport bottom)。
+ * 「element top が viewport 中央に来た時点で 0、 element bottom が viewport 中央に来た時点で 1」 の
+ * classic scroll narrative pattern。
+ */
+type CdlScrollTrigger = {
+    id: string;
+    /**
+     * scroll progress 0 (未開始) となる viewport 相対位置。
+     * default = 1.0 (element top が viewport bottom に達した瞬間 = 進捗開始)。
+     */
+    start?: number;
+    /**
+     * scroll progress 1 (完了) となる viewport 相対位置。
+     * default = 0.0 (element bottom が viewport top に達した瞬間 = 進捗完了)。
+     */
+    end?: number;
+    /**
+     * scrub 値 = 進捗の直接反映度合い (0 = 完全 step、 1 = 完全 scrub)。 default = 1 (連続追随)。
+     * 現実装では常に scrub (getBoundingClientRect 直接反映)、 将来 tween 補間で step 対応の余地。
+     */
+    scrub?: number;
+    label?: string;
+};
+type CdlDiagram = {
+    id: string;
+    topic: string;
+    /**
+     * この図を structured-data (schema.org) 抽出の対象とみなすか (既定 = `"extract"`)。
+     *
+     * - `"extract"` ... 抽出対象。 名前付き node が足りなければ `visualValidate` が warn を出す
+     * - `"exclude"` ... 抽出対象外。 図形 1 つを見せる見本や、 文字を持たない装飾図など、
+     *   そもそも文章として取り出す中身を持たせるつもりが無い図に付ける
+     *
+     * `"exclude"` を **著者が明示する** ための field。 engine 側で図の形から推測すると、
+     * 「意図的に文字を持たない図」 と「名前を付け忘れた図」 を区別できず、 後者を見逃す。
+     *
+     * 既定は `"extract"` = 付け忘れても検知が緩まない向き。
+     */
+    structuredData?: "extract" | "exclude";
+    /**
+     * interactive input widgets (v0.5+、 CAR #243)。
+     * builder chain の `.input.slider() / .number() / .dropdown() / .toggle()` で追加。
+     * consumer app が widget UI を描画、 signal 経由で cdl の SVG と bind する。
+     * 省略時は空 array 相当で下位互換 (static diagram 動作は不変)。
+     */
+    inputs?: CdlInput[];
+    /**
+     * derived value formulas (v0.5+、 CAR #244)。
+     * builder chain の `.formula(id, expression)` で追加、 expression は algebraic mini-DSL。
+     * consumer は createFormulaComputeds(diagram, signals) で computed を得る。
+     * 省略時は空 array 相当で下位互換 (static diagram 動作は不変)。
+     */
+    formulas?: CdlFormula[];
+    /**
+     * scroll-driven animation triggers (v0.5+、 CAR #245)。
+     * builder chain の `.animation.scroll(id, opts)` で追加、 consumer は createScrollProgressSignal(spec)
+     * で { signal, attach(element), detach } を得て DOM element に bind する。
+     * 省略時は空 array 相当で下位互換。
+     */
+    scrollTriggers?: CdlScrollTrigger[];
+    /**
+     * event handler bindings (v0.5+、 CAR #246)。
+     * builder chain の `.on.click(target, handlerId)` / `.on.hover(target, handlerId)` で追加、
+     * consumer は attachEventHandlers(root, diagram, handlers) で DOM listener を bind、
+     * event 発火時に handlers[handlerId] を呼出す (signal set / computed 参照 / batch update 等)。
+     * 省略時は空 array 相当で下位互換。
+     */
+    eventBindings?: CdlEventBinding[];
+    /**
+     * readout widgets (visual displays for signal / state values、 CAR: widget 拡充)。
+     * builder chain の `.readout.bar(id, opts)` / `.gauge` / `.stat` / `.sparkline` で追加。
+     * 省略時は空 array 相当で下位互換。
+     */
+    readouts?: CdlReadout[];
+    lanes: CdlLane[];
+    nodes: CdlNode[];
+    edges: CdlEdge[];
+    states: CdlState[];
+    phases: CdlPhase[];
+    /** v0.5+ ... canvas 全体仕様 (viewport.width / height で全体 size を author が宣言) */
+    viewport?: CdlViewport;
+};
+/** Canvas 全体仕様 (v0.5+ syntax `viewport: { width, height, scale, gap, laneGap, nodeGap, labelMargin }`)。
+ * 未指定時は layout が node 配置から自動算出する従来挙動。
+ *
+ * 細粒度 gap field (laneGap / nodeGap / labelMargin) は viewport.gap (全体 default) を上書きする。
+ * 個別 field 未指定なら viewport.gap → engine default の順で fallback。 */
+type CdlViewport = {
+    width?: number;
+    height?: number;
+    /**
+     * SVG stage の倍率 (default 1)。 箱 / 文字 / 線 / 間隔のすべてが等比で拡大縮小される。
+     *
+     * 対象は SVG stage だけ。 `CdlDiagramView` が stage の上に描く header と interactive
+     * panel は SVG の外の HTML なので倍率で変わらない。
+     *
+     * 倍率なしと同じ扱いになる値 = 未指定 / 1 との差が 1e-6 未満 / 0 / 負値 / NaN /
+     * ±Infinity。 この時は倍率用の指定を一切出さず、 倍率を導入する前と完全に同一の markup に
+     * なる。 それ以外の値は `[0.125, 8]` に丸める (`scale: 100` なら 8 倍)。
+     *
+     * layout は変わらない。 座標も viewBox も等倍のままで、 変わるのは描画される大きさだけ。
+     * 画面座標との換算は `layout/px-projection.ts` と `dom-verify.ts` にある。
+     *
+     * 倍率を上げると図は親をはみ出す。 収め方 (scroll / pan / clip) は consumer 側の責務。
+     * なお cdl は root に `overflow-hidden` class を出力するので、 それが効く環境では clip
+     * される。 scroll させたい場合はまずその指定を上書きする。
+     *
+     * 間隔を変える `laneGap` / `nodeGap` や、 lane 幅を変える `CdlLane.width` と違い、
+     * 本 field は全要素を等比で拡大する。 各 field の挙動はそれぞれの JSDoc を見る。
+     *
+     * 実装の詳細と、 現在の方式を選んだ理由は `render/stage.tsx` の該当箇所に書く。
+     */
+    scale?: number;
+    /** 全体 default gap、 個別 laneGap / nodeGap / labelMargin の fallback として使われる (互換維持)。
+     * laneGap の fallback として使われる場合は laneGap と同じ下限 (requiredGap) が適用される。 */
+    gap?: number;
+    /** lanes 間 horizontal gap (default DEFAULT_LANE_GAP=80)。
+     *
+     * **下限つき指定 + 全対均一化**である点に注意。 指定値がそのまま lane 間隔になるとは限らない。
+     * `expandLaneGapsForEdgeLabels` (CAR-470 / Issue #202、 `layout/lanes.ts`) が 2 段階で調整する。
+     *
+     * 段階 1 = 各 隣接 lane 対について、 その対を跨ぐ edge の label が両端 node に被らない
+     * gap を先手で確保する。 指定値が下記を下回ると safety 拡張が優先される。
+     *
+     *   requiredGap = computeLabelBoxW(edge.label, edge.sub)
+     *               + CLEARANCE_NODE_LABEL * 2   (= 32 * 2)
+     *               + EDGE_STUB_OUT * 2          (= 40 * 2)
+     *
+     * 段階 2 = 全対の pitch (lane 中心間距離) を最も広い対の pitch に揃える。
+     * lane diagram の node.cx は lane 中心に固定されるため、 pitch が不揃いだと
+     * visualValidate の row-gap-uniform (Axis 65) が node 間隔のばらつきとして検出する。
+     *
+     *   pitch = max(全対の max(currentGap, requiredGap) + 両 lane の半幅和)
+     *
+     * 実測例 (2 lane、 label "msg"、 requiredGap ≈ 236.32)。
+     *   laneGap: 0 / 10 / 50 / 80 / 150 / 200 / 236 → いずれも実効 236.32 (safety 拡張が優先)
+     *   laneGap: 240 / 300 / 600                    → 指定値がそのまま反映
+     *
+     * 3 lane 以上では、 他の対がより広い pitch を要求すると指定値も同じ pitch まで引き上げられる。
+     * lane 幅が均一なら pitch 均一 = gap 均一、 lane 幅が不揃いなら gap ではなく中心間距離が揃う
+     * (node が等間隔に並ぶ)。
+     *
+     * lane 間隔を確実に広げたい場合は、 全対の requiredGap を上回る値を指定する。 */
+    laneGap?: number;
+    /** nodes 間 vertical gap within lane (default DEFAULT_NODE_GAP=24、 内部 row_gap 100 から差し引いて適用) */
+    nodeGap?: number;
+    /** edge label 周辺余白 (default DEFAULT_LABEL_MARGIN=8、 label と node / path の clearance に加算) */
+    labelMargin?: number;
+};
+/** Layout 計算結果 (compile 後)、 lane.x は layout で必須解決 */
+type LaidLane = Omit<CdlLane, "x"> & {
+    x: number;
+    y: number;
+    height: number;
+};
+type LaidNode = CdlNode & {
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+    /** lane が描く boundary 内側に居るか */
+    insideContainedLane: boolean;
+};
+type LaidEdge = CdlEdge & {
+    /** 線 dot 用の visible path d (node 端で stop、 node 内を貫通しない) */
+    d: string;
+    /**
+     * 進行点 glow 用の hidden path d (style="dotted-through" のみ生成、 node 中心同士)。
+     * 粒子の animateMotion mpath 参照先として使い、 粒子が node を貫通する視覚を作る。
+     */
+    dThrough?: string;
+    fromSide: Side;
+    toSide: Side;
+    labelX: number;
+    labelY: number;
+    labelAnchor: "start" | "middle" | "end";
+};
+/**
+ * AABB (axis-aligned bounding box)。
+ * engine がキャンバス上で「ここに何があるか」 を全部 把握するための共通 type。
+ */
+type BBox = {
+    /** 要素種別 */
+    kind: "node" | "lane-label" | "edge-label" | "edge-path";
+    /** 元の id (node id / lane id / edge id) */
+    id: string;
+    /** 左端 x */
+    x: number;
+    /** 上端 y */
+    y: number;
+    /** 幅 */
+    w: number;
+    /** 高さ */
+    h: number;
+};
+type LaidDiagram = {
+    id: string;
+    topic: string;
+    viewBox: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * 図全体の倍率 (`CdlViewport.scale` を正規化した値)。
+     *
+     * 素通しではない。 `[0.125, 8]` に丸め、 倍率なしと同じ扱いになる値 (未指定 /
+     * 1 との差が 1e-6 未満 / 0 / 負値 / NaN / ±Infinity) は `undefined` にする。
+     * `scale: 100` なら `8`、 `scale: -1` なら `undefined` が入る。
+     *
+     * layout の座標には掛かっていない = `viewBox` も `nodes[].cx` も等倍のまま。
+     * 描画側 (stage.tsx) が SVG の表示幅 (`width: {k × 100}%`) だけで倍率を表す。
+     * 座標を layout 段階で掛けない理由は、 衝突検出や validation の閾値が
+     * 等倍前提で書かれており、 拡大後の座標で判定すると基準がずれるため。
+     *
+     * consumer が倍率を DOM から読む場合は SVG 要素の `data-cdl-scale` を見る。
+     * 載るのはこの正規化後の値で、 `undefined` のときは属性自体が出ない。
+     */
+    diagramScale?: number;
+    lanes: LaidLane[];
+    nodes: LaidNode[];
+    edges: LaidEdge[];
+    states: CdlState[];
+    phases: CdlPhase[];
+    /**
+     * キャンバス全要素の bounding box list。
+     * engine が「ここに何があるか」 を全部把握、 衝突検証 / debug 表示 / validation で使う。
+     */
+    bboxes: BBox[];
+    /** layout で検出された overlap warning list (engine が認識した衝突) */
+    collisions: Array<{
+        a: BBox;
+        b: BBox;
+        overlap_area: number;
+    }>;
+    /**
+     * near-collision = 矩形交差はないが clearance (N px) 未満で接近している組合せ。
+     * 詰まって見える箇所を engine が機械検出するための情報源。
+     */
+    nearCollisions: Array<{
+        a: BBox;
+        b: BBox;
+        gap: number;
+        required: number;
+    }>;
+};
+
+/**
+ * 1 scroll trigger 用の progress signal + attach/detach 制御 handle (CAR #245)。
+ */
+type ScrollProgressHandle = {
+    /** progress signal (0..1)。 attach 前は初期値 0、 attach 後 scroll に追随して更新される。 */
+    readonly progress: Signal<number>;
+    /**
+     * 対象 element に scroll listener + IntersectionObserver を attach、 initial progress を計算する。
+     * 二重 attach は前 element を detach してから再 attach する挙動。
+     */
+    attach: (element: Element) => void;
+    /** 現 element から離脱、 listener + observer を解除。 progress signal は最終値を保持。 */
+    detach: () => void;
+};
+/**
+ * diagram の scrollTriggers から progress signal handles を生成 (CAR #245)。
+ * consumer は各 handle の attach(element) を DOM element に対して呼び、 signal.value で progress を read する。
+ *
+ * SSR safe = attach() 呼出前は browser API を触らないので Node.js / SSR 環境でも生成可能。
+ */
+declare function createScrollProgressSignals(diagram: CdlDiagram): Record<string, ScrollProgressHandle>;
+/**
+ * 1 CdlScrollTrigger spec から ScrollProgressHandle を生成。 単体でも export、 動的追加 use case で使う。
+ */
+declare function createScrollProgressHandle(spec: CdlScrollTrigger): ScrollProgressHandle;
+
+/**
+ * consumer が渡す handler map。 handlerId (`.on.click(target, handlerId)` で書いた string) →
+ * 実際の関数。 handler 内で signal を更新することで SVG に reactive 反映される。
+ * signals 引数で input / computed / scroll の全 signal に access 可能。
+ */
+type InteractiveHandlerMap = Record<string, (event: Event, signals: InteractiveSignalsAccessor) => void>;
+/**
+ * handler / consumer が signal に access する API (CAR #255 拡張)。
+ *
+ * 従来 (#253) の `{ input, formula, scroll }` を non-breaking で維持しつつ、 typed 経路を
+ * optional で追加する。 factory (`createInteractiveSignalsAccessor`) 経由の accessor は必ず
+ * 全 member を提供、 手動 mock で 3 member だけ提供する consumer も引き続き compile 通る。
+ *
+ * - `input` は互換性のため `Signal<unknown>` の raw map を維持、 advanced use 経路。
+ * - `set*` は kind 別 typed setter、 kind mismatch は warn + no-op。 optional のため consumer
+ *   の mock で欠落しても compile 通る (呼出側は `accessor.setNumber?.(id, v)` or 型 narrowing)。
+ * - `get*` は kind 別 typed getter、 mismatch / 未登録は warn + undefined を返す (setter との
+ *   symmetry、 read 側の silent failure も debuggable にする、 codex M2 fix)。
+ * - `warnMissingSignal` = kind check pass 後に signals map から signal が消えている stale
+ *   ケースも warn する (codex m3 fix)。
+ *
+ * 従来の `signals.input[id].value = "wrong-type"` は compile pass するが runtime に
+ * default 値へ silent fallback する silent failure を招く。 typed setter 経路で kind 契約を
+ * 明示することで consumer handler の実装ミスを早期検出する。
+ */
+type InteractiveSignalsAccessor = {
+    /** 互換 raw map (advanced use)、 typed setter / getter を優先すること */
+    input: Record<string, Signal<unknown>>;
+    formula: Record<string, Computed<number | boolean>>;
+    scroll: Record<string, ScrollProgressHandle>;
+    /**
+     * 以下 6 member は optional。 factory 経由の accessor は必ず提供、 手動 mock で 3 member
+     * だけ提供する consumer も compile 通る (codex M1 non-breaking 保証)。
+     * consumer が呼び出す時は factory 由来と分かっている場面が多いが、 mock 対応で
+     * `accessor.setNumber?.(id, value)` パターンも許容される。
+     */
+    /** number 型 signal (slider / number) に value を書き込む、 kind mismatch は warn + no-op */
+    setNumber?: (id: string, value: number) => void;
+    /** string 型 signal (dropdown) に value を書き込む、 kind mismatch は warn + no-op */
+    setString?: (id: string, value: string) => void;
+    /** boolean 型 signal (toggle) に value を書き込む、 kind mismatch は warn + no-op */
+    setBool?: (id: string, value: boolean) => void;
+    /** number 型 signal の値を取得、 mismatch / 未登録は warn + undefined */
+    getNumber?: (id: string) => number | undefined;
+    /** string 型 signal の値を取得、 mismatch / 未登録は warn + undefined */
+    getString?: (id: string) => string | undefined;
+    /** boolean 型 signal の値を取得、 mismatch / 未登録は warn + undefined */
+    getBool?: (id: string) => boolean | undefined;
+};
+/**
+ * accessor を diagram + signals から構築する SSOT (CAR #255)。
+ *
+ * diagram.inputs から kind map を構築、 各 typed setter / getter で id → 期待 kind を
+ * runtime check する。 mismatch / 未登録 / signals map stale は console.warn + no-op or
+ * undefined (throw ではない = production の user session を crash させない、 dev 環境で
+ * 気付ける、 の両立)。
+ */
+declare function createInteractiveSignalsAccessor(diagram: CdlDiagram, signals: Record<string, Signal<unknown>>, formula: Record<string, Computed<number | boolean>>, scroll: Record<string, ScrollProgressHandle>): InteractiveSignalsAccessor & Required<Omit<InteractiveSignalsAccessor, "input" | "formula" | "scroll">>;
+declare function computeInputSignalKey(diagram: CdlDiagram): string;
+declare function computeFormulaKey(diagram: CdlDiagram): string;
+declare function computeScrollTriggerKey(diagram: CdlDiagram): string;
+/**
+ * event binding の schema key、 event handler useEffect の invalidation を diagram identity
+ * から narrow するための SSOT (CAR #264)。 event + target 形状 + handlerId が同じなら key
+ * は同一、 caller が毎 render 新 diagram object を渡しても event handler の detach/reattach
+ * が起きない (hover 中の miss window / observer churn を防ぐ)。
+ */
+declare function computeEventBindingKey(diagram: CdlDiagram): string;
+/**
+ * diagram 内 interactive primitive の有無判定 (SSR safe、 window / DOM 触らない)。
+ */
+declare function hasInteractivePrimitives(diagram: CdlDiagram): boolean;
+
+type CdlDiagramViewProps = {
+    diagram: CdlDiagram;
+    /**
+     * 配置まで済ませた図。 渡すとここでは組み立て直さない。
+     *
+     * 呼出側が既に `compile` を呼んでいる場合 (組み立ての結果を検査や図枠の原点に使う等)、
+     * ここで測り直すと同じ図の配置を 2 度計算する。 図の規模に比例して重く、 辺 500 本で
+     * 約 300ms かかる (実測)。
+     *
+     * 渡す時は `diagram` と対にする。 別の図の配置を渡すと、 描く内容と位置がずれる。
+     * 対応が取れているかはここでは確かめない (確かめる費用が、 省く費用を上回る)。
+     */
+    laid?: LaidDiagram;
+    hideHeader?: boolean;
+    /**
+     * `hideHeader` 時に下部へ出る phase の小さな指標 (点列 + 現在 phase の題) を出さない。
+     *
+     * 下流が独自の phase UI を持つ場合に使う。 CSS で消す形にすると、 こちらの class 名や
+     * 要素構造が変わった時に黙って効かなくなる (下流の hack が壊れたことに気付けない)。
+     */
+    hideMiniPhaseIndicator?: boolean;
+    focusPhaseId?: string;
+    /** debug mode = engine の bbox + collision を半透明で重ね描き (開発確認用) */
+    debug?: boolean;
+    /**
+     * dev warn mode = 生成時に visualValidate を走らせ warn / error を console に流す。
+     * default = process.env.NODE_ENV === "development" 相当を caller 側で判定して渡す設計。
+     * true 明示指定で production build でも有効化可 (Playwright 実測時など)。
+     */
+    emitGeometryWarn?: boolean;
+    /**
+     * CdlHeader 内 phase title の heading tag level (2 | 3 | 4)、 default 3。
+     * downstream で h1 直後配置なら 2、 h2 直後なら 3 (default)、 h3 直後なら 4 を渡す。
+     * heading order skip を防ぐ用途、 hideHeader=true 時は無視される。
+     */
+    headingLevel?: 2 | 3 | 4;
+    /**
+     * interactive event handler 関数 map (CAR #246 / render integration)。
+     * diagram.eventBindings が非空の時、 handlerId → (event, signals) => void の map で consumer が
+     * signal 更新 etc を実装する。 未指定の場合 event handler は skip される。
+     */
+    interactiveHandlers?: InteractiveHandlerMap;
+};
+declare function CdlDiagramView({ diagram, laid: laidProp, hideHeader, hideMiniPhaseIndicator, focusPhaseId, debug, emitGeometryWarn, headingLevel, interactiveHandlers }: CdlDiagramViewProps): JSX.Element;
+
+export { computed as A, type BBox as B, type CdlDiagram as C, createInteractiveSignalsAccessor as D, type EdgeStyle as E, createScrollProgressHandle as F, createScrollProgressSignals as G, hasInteractivePrimitives as H, type InteractiveHandlerMap as I, signal as J, type LaidDiagram as L, type NodeKind as N, type Signal as S, type Tone as T, type CdlInput as a, type CdlLane as b, type CdlNode as c, type Side as d, type CdlState as e, type CdlEventTarget as f, type Computed as g, type CdlScrollTrigger as h, type CdlDiagramViewProps as i, type LaidEdge as j, type LaidNode as k, type CdlEdge as l, CdlDiagramView as m, type CdlEventBinding as n, type CdlEventKind as o, type CdlFormula as p, type CdlPhase as q, type InteractiveSignalsAccessor as r, type LaidLane as s, NODE_KINDS as t, type ScrollProgressHandle as u, TONES as v, computeEventBindingKey as w, computeFormulaKey as x, computeInputSignalKey as y, computeScrollTriggerKey as z };