@cardenelabs/cdl 0.5.0

package/dist/index.d.cts

@@ -0,0 +1,3415 @@
+import { C as CdlDiagram, S as Signal, a as CdlInput, b as CdlLane, c as CdlNode, T as Tone, d as Side, E as EdgeStyle, e as CdlState, f as CdlEventTarget, g as Computed, h as CdlScrollTrigger, L as LaidDiagram, i as CdlDiagramViewProps, j as LaidEdge, k as LaidNode, l as CdlEdge, B as BBox, N as NodeKind } from './render-C78lIXeC.cjs';
+export { m as CdlDiagramView, n as CdlEventBinding, o as CdlEventKind, p as CdlFormula, q as CdlPhase, I as InteractiveHandlerMap, r as InteractiveSignalsAccessor, s as LaidLane, t as NODE_KINDS, u as ScrollProgressHandle, v as TONES, w as computeEventBindingKey, x as computeFormulaKey, y as computeInputSignalKey, z as computeScrollTriggerKey, A as computed, D as createInteractiveSignalsAccessor, F as createScrollProgressHandle, G as createScrollProgressSignals, H as hasInteractivePrimitives, J as signal } from './render-C78lIXeC.cjs';
+import { JSX } from 'react';
+
+declare function effect(fn: () => void | (() => void)): () => void;
+
+/**
+ * 複数の signal set を 1 tick に集約する。 batch 内では effect の実行が deferred queue に蓄積、
+ * batch 終了時にまとめて flush される (同じ effect が dep 変化で複数回 trigger されても 1 回に集約)。
+ *
+ * nested batch は最外側の batch 終了時にのみ flush、 途中の内側 batch では実行しない。
+ */
+declare function batch<T>(fn: () => T): T;
+/**
+ * fn 内の signal / computed read を dependency 追跡から除外する。 effect 内で
+ * 「値は見たいが再実行 trigger にしたくない」 用途 (initial state だけ読みたい 等)。
+ */
+declare function untrack<T>(fn: () => T): T;
+
+/**
+ * diagram の `inputs` から signal を生成、 id をキーにした map を返す helper (CAR #243)。
+ *
+ * consumer app 側 = 「HTML widget → onChange で signal.value 更新 → SVG 内 bind が signal.value を read」
+ * の bind 経路の起点。 static SSR では signal 生成せず defaultValue を SVG に埋込むだけで良い、
+ * client hydration の時点で本 helper を呼んで signal を生成、 widget と bind する。
+ *
+ * diagram に inputs がない場合は空 object を返す。 id が重複する diagram は builder 側で error になるため
+ * 本 helper 内では重複チェックしない (fail-fast は builder 責務)。
+ */
+declare function createInputSignals(diagram: CdlDiagram): Record<string, Signal<unknown>>;
+/**
+ * CdlInput から default value を kind-safe に取り出す。 discriminated union なので type narrowing が効く。
+ * default 節 assertNever で新 kind 追加時 compile error 検知する (CAR #262)。
+ */
+declare function inputDefaultValue(input: CdlInput): number | string | boolean;
+
+/**
+ * `.animation.scroll(id, opts)` を提供する chain-facing helper。 将来 `.animation.time(...)` 等の
+ * time-based primitive を追加する余地を残すため animation namespace として分離。
+ */
+type AnimationChain = {
+    scroll: (id: string, opts?: {
+        start?: number;
+        end?: number;
+        scrub?: number;
+        label?: string;
+    }) => DiagramBuilder;
+};
+/**
+ * `.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 に含めない)。
+ */
+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.slider()` / `.number()` / `.dropdown()` / `.toggle()` を提供する chain-facing helper。
+ * 各 method は widget spec を `CdlInput` として累積し、 DiagramBuilder を返して chain 継続を許す。
+ */
+/**
+ * ReadoutChain = visual readout widget を diagram に追加する chain (CAR: widget 拡充)。
+ * 各 method は CdlReadout として累積する。
+ */
+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;
+};
+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;
+};
+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 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;
+};
+declare function diagram(id: string, options: {
+    topic: string;
+    /**
+     * structured-data (schema.org) 抽出の対象とみなすか (既定 = `"extract"`)。
+     * figure 1 つを見せる見本など、 文章として取り出す中身を持たせるつもりが無い図に
+     * `"exclude"` を付ける。 詳細は `CdlDiagram.structuredData` の doc 参照。
+     */
+    structuredData?: "extract" | "exclude";
+}): DiagramBuilder;
+
+/**
+ * formula expression の AST 型 (CAR #244)。
+ *
+ * safe subset のみを表現する。 演算子 (+ - * / %) / 比較 (< <= > >= == !=) / 三項 (?:) / 括弧 /
+ * 数値リテラル / identifier (signal 名) / Math.* 関数呼出の 7 pattern。
+ *
+ * discriminated union で kind ごとに fields を厳密化、 evaluator / extractor が type narrowing で走査する。
+ */
+type FormulaAst = {
+    type: "number";
+    value: number;
+} | {
+    type: "identifier";
+    name: string;
+} | {
+    type: "binaryOp";
+    op: BinaryOp;
+    left: FormulaAst;
+    right: FormulaAst;
+} | {
+    type: "unaryOp";
+    op: "-";
+    operand: FormulaAst;
+} | {
+    type: "ternary";
+    condition: FormulaAst;
+    whenTrue: FormulaAst;
+    whenFalse: FormulaAst;
+} | {
+    type: "call";
+    fn: MathFnName;
+    args: FormulaAst[];
+};
+type BinaryOp = "+" | "-" | "*" | "/" | "%" | "<" | "<=" | ">" | ">=" | "==" | "!=";
+type MathFnName = "Math.min" | "Math.max" | "Math.abs" | "Math.floor" | "Math.ceil" | "Math.round";
+
+/**
+ * expression 文字列を parse して AST に変換する。 syntax error は Error を throw する。
+ * 空文字列は Error。
+ */
+declare function parseFormula(expression: string): FormulaAst;
+/**
+ * AST 内で参照される identifier (signal 名) を全て収集する。 evaluator が signal 経由で
+ * runtime value を lookup する時の識別子リスト作成に使う。
+ */
+declare function extractIdentifiers(ast: FormulaAst, out?: Set<string>): Set<string>;
+
+/**
+ * formula 評価 context = identifier 名 → runtime value の map。 caller が signal.value 等から構築して渡す。
+ * `evaluate` に直接渡す eager 経路の型 (簡易 use case)。
+ */
+type FormulaContext = Record<string, number | boolean>;
+/**
+ * formula 評価 resolver = identifier 名 を受け取って値を返す関数。
+ * lazy evaluation を可能にする (ternary の unselected branch で undefined identifier / division by zero を回避)。
+ */
+type FormulaResolver = (name: string) => number | boolean;
+/**
+ * AST を pure に評価して結果を返す (CAR #244)。
+ * safe subset のみサポート (parser 側で syntax error は既に排除済)。
+ *
+ * 第 2 引数は `FormulaContext` (record) or `FormulaResolver` (function) のどちらも受け付ける。
+ * ternary の unselected branch を skip したい caller は resolver 経路を使う (evaluator が identifier
+ * node に到達した時のみ resolver を呼ぶので、 unselected branch の identifier は lookup されない)。
+ *
+ * runtime error として:
+ * - undefined identifier (resolver / ctx が throw)
+ * - number 期待箇所に boolean が来た (or 逆)
+ * - division by zero (`/ 0` and `% 0`)
+ * - ternary condition が boolean でない
+ */
+declare function evaluate(ast: FormulaAst, ctxOrResolver: FormulaContext | FormulaResolver): number | boolean;
+
+/**
+ * diagram の `formulas` から computed を生成、 formula.id をキーにした map を返す helper (CAR #244)。
+ *
+ * 各 formula は expression を parse し、 参照する identifier (signal 名) を signals map から lookup して
+ * computed を生成する。 computed.value を read すると:
+ *   1. formula 内 identifier に対応する signal.value を read (自動 dep 登録)
+ *   2. AST を evaluate して結果を返す
+ * signal 変化で computed が自動再計算される (Step 2 の reactive graph に統合)。
+ *
+ * `Object.create(null)` で prototype pollution safe (input-signals.ts と同 pattern)。
+ */
+declare function createFormulaComputeds(diagram: CdlDiagram, signals: Record<string, Signal<unknown>>): Record<string, Computed<number | boolean>>;
+
+/**
+ * scroll progress 計算 (pure function、 CAR #245)。
+ *
+ * spec.start / spec.end の semantics:
+ * - progress 0 = element top が viewport 相対位置 start に到達した瞬間
+ *   (default start = 1.0 = element top が viewport bottom に到達 = 進捗開始)
+ * - progress 1 = element bottom が viewport 相対位置 end に到達した瞬間
+ *   (default end = 0.0 = element bottom が viewport top に到達 = 進捗完了)
+ *
+ * 中心基準ではなく edge 基準にすることで、 element の height に依存しない一貫した scroll 距離での
+ * 進捗計算になる (codex Round 1 finding fix、 中心基準だと element height の半分だけ range が縮まる)。
+ *
+ * @param elementRect getBoundingClientRect 相当 (top / bottom は viewport 相対座標)
+ * @param viewportHeight window.innerHeight 相当
+ * @param spec CdlScrollTrigger の start / end
+ * @returns 0..1 の progress (clamp 済)
+ */
+declare function computeScrollProgress(elementRect: {
+    top: number;
+    bottom: number;
+}, viewportHeight: number, spec: Pick<CdlScrollTrigger, "start" | "end">): number;
+
+/**
+ * event handler function type (CAR #246)。
+ * consumer が signal update / computed 参照 / batch update 等を実装する。
+ * event 引数は DOM Event 本体 (target / clientX / preventDefault 等が使える)。
+ */
+type CdlEventHandler = (event: Event) => void;
+/**
+ * attach 結果 handle (CAR #246)。 dispose 呼出で全 listener を cleanup。
+ */
+type EventAttachHandle = {
+    /** 全 event listener を DOM から解除、 hydration unmount 経路。 */
+    dispose: () => void;
+};
+/**
+ * diagram の eventBindings を DOM element に attach する (CAR #246)。
+ *
+ * root element 内で target 記述に応じて element を lookup:
+ * - node: `[data-cdl-node="{id}"]` selector
+ * - edge: `[data-cdl-edge="{id}"]` selector
+ * - lane: `[data-cdl-lane="{id}"]` selector
+ * - diagram: root 自身
+ *
+ * event 種別:
+ * - click: `click` event
+ * - hover: `mouseenter` + `mouseleave` の 2 event を同 handler に bind、 consumer は
+ *   `event.type` で enter / leave を分岐する (tooltip / highlight の enter+clear を 1 binding で表現)
+ *
+ * listener は passive: true で登録 (scroll blocking 回避)。 target element が見つからない場合は
+ * silent skip + console warn (initial render 未完了の可能性、 fatal ではない)。
+ * handler map に該当 handlerId がない場合も silent skip + warn。
+ *
+ * 戻り値の dispose() で全 listener を解除。 hydration lifecycle (React useEffect の cleanup / unmount)
+ * と紐付けて use する。
+ */
+declare function attachEventHandlers(root: Element, diagram: CdlDiagram, handlers: Record<string, CdlEventHandler>): EventAttachHandle;
+/**
+ * event target 記述から実 DOM element を 1 つ lookup (最初の一致)。 test / debug 用途。
+ * edge target で label sibling も対象にする場合は resolveTargetAll を使う。
+ */
+declare function resolveTarget(root: Element, target: CdlEventTarget): Element | null;
+/**
+ * event target 記述から実 DOM element を全て lookup (attach 経路の SSOT)。
+ * edge target は本体 `[data-cdl-edge="{id}"]` + label sibling `[data-cdl-edge-label-for="{id}"]` の 2 系統
+ * を含める (label 上での click / hover を miss しないため、 codex Round 2 P2 finding)。
+ * 該当 element がなければ空配列を返す (silent skip 判定は attach 側)。
+ */
+declare function resolveTargetAll(root: Element, target: CdlEventTarget): Element[];
+
+/**
+ * discriminated union の exhaustive check helper (CAR #262)。
+ *
+ * switch case で全 union member を処理した後 `default: return assertNever(x)` と書くと、
+ * union に新 member が追加された時に compile error で検知できる (x: never が narrow できずに
+ * TypeScript 側で type error になる)。 runtime に到達した場合は Error を throw する
+ * (typing 通り不到達だが、 想定外 kind が type check bypass 経路で流れ込んだ時の fail-fast)。
+ *
+ * 適用対象は builder / factory / render 内で input.kind / edge.style / node.kind 等の
+ * discriminated union を分岐する経路。 新 kind 追加時に silent fallthrough を防ぐ。
+ */
+declare function assertNever(value: never, context?: string): never;
+
+/**
+ * compile = validate → layout で LaidDiagram を返す。
+ * render は別 file (render.tsx) が LaidDiagram を消費。
+ */
+declare function compile(diag: CdlDiagram): LaidDiagram;
+
+/**
+ * Layout engine
+ *
+ * 規約 (SPEC.md §Layout engine 規約 と一致)。
+ * - lane が x 軸 column を決める
+ * - node は lane 内 stack 順で縦並び、 各 stack 間 gap 80px、 上端 80px
+ * - lane label は lane 上部 30px 高
+ * - contain: true の lane は内部 node 全部を 24px padding で囲む boundary
+ * - edge routing は orthogonal L 字 (起点 side → 中継 → 終点 side)、 左右 lane 跨ぎは S 字 bezier
+ * - edge label は path 中点から path 進行方向の垂直方向に 50-80px、 node bbox を避ける
+ * - viewBox は cdl が auto 計算 (右端 +80 / 下端 +80)
+ */
+declare function layout(diag: CdlDiagram): LaidDiagram;
+
+/**
+ * cdl が compile される前に通る validator。
+ * 構造的破綻 (重複 id / 不存在 id 参照 / 必須要素 0 件 等) は throw、
+ * 文体警告 (japanese-only 違反) は console.warn で build を止めない。
+ *
+ * error 統一 format ... `[cdl] {category}: {detail}` で grep / 著者の locate が楽に。
+ */
+declare function validate(diag: CdlDiagram): void;
+
+/**
+ * edge label の 2 行の文字仕様 SSOT。
+ *
+ * 描画 (`render/edges.tsx`) と検査 (`visual-validate.ts` の軸 27 `contrast-basics`) が同じ
+ * 値を読む。 描画側に literal を残して検査側が「描画はこうなっているはず」 と書き写す形は
+ * 使わない。 書き写しは片方だけが変わった時に検知できず、 検査が実在しない描画を測る
+ * (軸 27 が sub 行を通常文字として測っていた間、 描画は 19px のままで検査だけが正しかった
+ * ように見えていた)。
+ */
+/** edge label の行。 `main` = `label`、 `sub` = `sub`。 */
+type EdgeLabelLine = "main" | "sub";
+interface EdgeLabelTextSpec {
+    fontSize: number;
+    fontWeight: number;
+    /**
+     * 文字を背景に重ねる不透明度。 1 = 合成なし。
+     *
+     * 1 未満だと実際に目に入る色は背景との合成結果になり、 対比が必ず下がる。
+     */
+    opacity: number;
+    /**
+     * 描画で指定する font-family の先頭。 指定せず継承する行は null。
+     *
+     * 下流が「その太さの face を読み込んでいるか」 を確かめる時、 どの family を見ればよいかが
+     * ここで決まる。 主題が family を宣言しない時の落とし先でもある。
+     */
+    fontFamily: string | null;
+}
+declare const EDGE_LABEL_TEXT: Record<EdgeLabelLine, EdgeLabelTextSpec>;
+/** WCAG AA の large text (24px 以上 or 太字 18.66px 以上) の閾値。 */
+declare const WCAG_AA_LARGE = 3;
+/** WCAG AA の通常文字の閾値。 */
+declare const WCAG_AA_NORMAL = 4.5;
+/**
+ * WCAG の large text (14pt 太字 = 18.66px、 または 18pt = 24px) に当たるか。
+ *
+ * 太字の下限を 700 に取るのは WCAG が「bold」 の具体値を定めておらず、 CSS の `bold` が
+ * 700 に対応するため。 600 を太字と見なすと、 実際には満たさない対比を通す。
+ */
+declare function isLargeText(spec: EdgeLabelTextSpec): boolean;
+/** 文字仕様から WCAG AA が要求する対比を返す。 */
+declare function requiredContrastRatio(spec: EdgeLabelTextSpec): number;
+
+/**
+ * Visual validator ... layout 出力 (LaidDiagram) を 67 軸で検証する。
+ *
+ * cdl 著者が「component が render される」 までで完成と思いがちな問題に対し、
+ * 「視覚的に正しい」 を engine 層で機械判定する。
+ *
+ * 軸の一覧は `VisualAxis` 型が SSOT。 Axis 48 (`axis-documentation-completeness`) が見るのは
+ * **手で並べた `allAxes` の要素数が `EXPECTED_AXIS_COUNT` と一致するか** だけで、 `VisualAxis` /
+ * `emptyCounts` / `allAxes` の 3 つが揃っているかまでは見ない。 型と `emptyCounts` のずれは
+ * 型検査が捕まえるが、 `allAxes` への追記漏れは捕まらない (#381)。
+ *
+ * 戻り値 ... ViolationReport (各軸の違反一覧 + sum + ok flag)。
+ * 既存 validate (構造的破綻) と別 layer。 throw せず report のみ返す純粋関数。
+ *
+ * ───────────────────────────────────────────────────────────
+ * ## 新しい軸を足す時の判断基準 (#381)
+ *
+ * **軸は、 品質と結びつく量を、 検証済の前提の下で測る**。 これを外すと、 件数が 0 でも品質を
+ * 表さない軸ができる。 0 件は「問題がない」 とも「測れていない」 とも読めるが、 軸の側からは
+ * 区別できない。
+ *
+ * 2026-07-31 の 1 セッションで、 同じ性質の欠陥を 9 例続けて直した。 件数は dragon の見本
+ * 512 図での実測。
+ *
+ * | 軸 | 何がずれていたか | 件数 |
+ * |---|---|---|
+ * | `lane-lane-gap` | `contain: false` の帯は境界を描かないのに、 境界どうしの間隔を測っていた | 99 |
+ * | `text-readability` / `accessibility-basics` | 題名を一度も描かない種別と、 常に非表示の節を対象にしていた | 50 |
+ * | `responsive-viewport` | 幅の下限の判定が **反転** していた (十分広い時に警告) | 17 |
+ * | `mermaid-parity` | 外部ライブラリの対応表が古く、 対応物がある 3 種を「なし」 としていた | 3 |
+ * | `edge-label-proximity` | label の **中心** から **弦** までを測っていた (弦は描かれず、 中心は label の長さで動く) | 3 |
+ * | `grid-alignment` | 箱の **中心** が 16 の格子に載るかを見ていた (中心を格子に載せる実装は無い) | 2 |
+ * | 衝突判定 (label × 線) | 弦に落とした線と label 矩形の交差を見て、 自分の弦と一致する segment を除いていた。 端点が同じ弧は弦も一致するため、 兄弟の弧が丸ごと消えていた | **-3** |
+ * | `accessibility-basics` (再) | `role="img"` の子孫は支援技術に公開されないのに、 節ごとの題名を見ていた | 0 |
+ * | `mermaid-parity` (再) | 図の id から組み立て器を推定していた (id は著者が付ける値で無関係) | 0 |
+ *
+ * `-3` は「見えていなかった破綻が 3 件あった」 の意味。 直すと件数が **増える** 側の例。
+ *
+ * ずれ方は 4 つに分かれる。
+ *
+ * - **描かれない図形を測る** ... 見えない帯の境界 / 弦 / 箱の中心。 幾何の代表点を実際の
+ *   描画物と取り違える形
+ * - **描かれない情報を測る** ... 題名を描かない種別 / 支援技術に公開されない節。 データには
+ *   あるが出力に出ない値を測る形
+ * - **意図を形から推測する** ... id からの組み立て器推定。 著者が持つ情報を図の形から当てよう
+ *   とする形。 推測は必ず両方向に外れる (偽陽性と偽陰性が同時に出る)
+ * - **外部の情報が古びる** ... mermaid の対応表。 外部が更新されても軸は気付かない
+ *
+ * `responsive-viewport` だけは別で、 測る量 (`viewBox` の幅) は実在した。 **判定の向きが逆**
+ * だっただけで、 これは片方向の例しか試さないと通ってしまう。
+ *
+ * 足す前に 6 点を確かめる。
+ *
+ *   1. **測る量が出力から取れるか**。 DOM / SVG の `d` / 描画結果のいずれかから取れないなら、
+ *      その軸は書けない。 データ構造の値で代用しない
+ *   2. **その量が品質と結びつく根拠を、 実装か規約で示せるか**。 「箱の中心が 16 の格子に載る」
+ *      のように、 **誰も実装していない不変条件** を軸が勝手に決めていないか確かめる。 出力から
+ *      取れる量でも、 品質と結びついていなければ測る意味が無い
+ *   3. **発火する例と発火しない例を両方書いたか**。 判定の向きの誤りは片方だけでは通る
+ *   4. **0 件になった時、 それが「実在しない」 ことを示せるか**。 示せないなら、 発火する反例を
+ *      1 つ作って test に置く (軸が dead になっていないことの証明)
+ *   5. **著者の意図を要する判定は、 形から推測せず宣言させる**。 宣言の例 =
+ *      `structuredData: "exclude"`
+ *   6. **外部の情報に依存するなら、 基準にした版を書き、 いつ確かめ直すかを決める**。 例 =
+ *      `MERMAID_PARITY_BASIS_VERSION`。 版だけでは外部の更新に気付けないので、 版を書いた上で
+ *      「次にこの表を見直す条件」 も併せて残す
+ *
+ * 同じことを静的 test が拾えるなら、 図ごとの軸は要らない。 静的 test は実際の export を
+ * 列挙でき、 推測が要らない (例 = `test/mermaid-parity.test.ts` が `presets.ts` の export を
+ * 全件列挙する)。
+ *
+ * 直した後は、 手で持つ一覧が実装とずれない仕組みを併せて置く。 全 90 種別の描画結果と述語の
+ * 一致 / 全 export と対応表の照合 / 生成物と種別集合の一致 のように、 **実装を列挙して照合する**
+ * test が無いと、 次に種別を足した時に同じ状態へ戻る。
+ * ───────────────────────────────────────────────────────────
+ */
+
+interface Violation {
+    axis: VisualAxis;
+    diagramId: string;
+    detail: string;
+    severity: "error" | "warn";
+}
+type VisualAxis = "node-visibility" | "edge-label-overlap" | "edge-label-proximity" | "text-readability" | "row-format" | "alignment" | "clearance" | "arrow-endpoint-anchoring" | "label-char-range" | "node-overlap" | "edge-crossing" | "edge-node-cross" | "edge-segment-orthogonality" | "label-inside-viewbox" | "lane-cx-consistency" | "row-vertical-spacing" | "group-boundary-clearance" | "node-vertical-clearance" | "lane-lane-gap" | "arrow-marker-clearance" | "grid-alignment" | "phase-layout-stability" | "responsive-viewport" | "accessibility-basics" | "animation-frame-integrity" | "i18n-cjk-detection" | "contrast-basics" | "print-media-compat" | "color-blind-safety" | "marker-gradient-def-integrity" | "subpixel-precision" | "dom-complexity-budget" | "reduced-motion-compat" | "touch-target-size" | "row-content-typing" | "terminal-safe-text" | "gpu-layer-efficiency" | "memory-budget" | "svg-injection-safety" | "seo-metadata-quality" | "bidi-hyphenation" | "structured-data-extraction" | "diagram-version-semver" | "migration-path-consistency" | "axis-coverage-meta" | "axis-documentation-completeness" | "fixture-drift-detection" | "locale-parity" | "validate-performance-budget" | "node-inside-viewbox" | "node-inside-lane" | "edge-inside-viewbox" | "lane-label-inside-viewbox" | "lane-label-overlap" | "row-alignment" | "column-alignment" | "edge-stubout-min" | "fan-origin-single-point" | "detour-slot-distinct" | "arrow-endpoint-center" | "lane-border-clearance" | "row-gap-uniform" | "column-gap-uniform" | "rows-not-rendered" | "malformed-input" | "validation-interrupted";
+/**
+ * 検査の用途。 用途によって見るべき軸が違う。
+ *
+ * - `production` = 公開する web ページ。 全ての軸を見る (既定)
+ * - `catalog` = 記法の見本。 SEO の軸を見ない
+ *
+ * 見本は「記法をどう書くか」 を示すもので、 検索結果に出す対象ではない。 SEO の軸
+ * (`seo-metadata-quality` / `structured-data-extraction`) は題名の長さや有名な節の数を見るため、
+ * 短い題名の見本を足すたびに警告が出る。
+ *
+ * 経緯 = cardene777/dragon#887 の起票時は見本 412 図で 179 件出ていたが、 その後 見本側の題名が
+ * 整備されて現在は 0 件 (実測 = 316 図で 0 件)。 本区分は「今ある noise を消す」 のではなく
+ * 「見本に SEO の軸を課さない」 契約を先に置くもの。
+ */
+type ValidationProfile = "production" | "catalog";
+/** 検査の設定。 */
+interface ValidateOptions {
+    /** 検査の用途。 既定は `production` (全ての軸を見る)。 */
+    profile?: ValidationProfile;
+}
+interface VisualValidationReport {
+    diagramId: string;
+    ok: boolean;
+    violations: Violation[];
+    counts: Record<VisualAxis, number>;
+    /** 検査した用途。 report を保存して後から読む時に、 何を見たかが分かる。 */
+    profile: ValidationProfile;
+    /**
+     * 用途によって見なかった軸。
+     *
+     * `counts` はこれらも 0 を返す。 載せないと「検査して 0 件」 と「検査していない」 を
+     * 区別できず、 集計した時に見た範囲を過大に読む。
+     */
+    skippedAxes: VisualAxis[];
+}
+/**
+ * 辺どうしの交差を **実際に描かれる曲線** で数える (軸 11、 #385)。
+ *
+ * 弦のまま数えていた頃は、 弦どうしが平行で弧だけが交わる形を落としていた (#383 の反例 =
+ * 弦 0 件 / 実曲線 2 件)。
+ *
+ * 折れ線に開くだけでは直らない。 `segmentsIntersect` は端点の接触を交差に数えないため、
+ * 交差が分割点にちょうど乗ると隣り合う 2 本の分割片が両方とも端点接触になり、 交差が
+ * **消える** (#384 実測 = `M 0 0 Q 80 80, 160 160` と y=40/80/120 の 3 本で 弦 3 件 → 折れ線
+ * 0 件)。 端点を数える判定に替えると、 今度は同じ節から出る辺どうしの共有端点を数える。
+ *
+ * そこで交点の **座標** を返す判定を使い、 辺の元の端点に一致する交点だけを除く。 分割で
+ * 生まれた節は除かない。 残りを座標で重複排除すると、 分割点に乗った交差が 2 度数えられる
+ * ことも無くなる。
+ *
+ * 関数に切り出してあるのは、 計算量を test から直接測れるようにするため。 検証全体の時間で
+ * 測ると、 曲線では他の軸も分割の分だけ重くなって本軸の寄与が読めない (実測 = 全体の差 138ms に
+ * 対し本軸の寄与は 41ms)。
+ *
+ * @param warnAt 数えるのをやめる件数。 判定は「この件数以上か」 だけなので、 達したら打ち切る。
+ * @returns `complete` は最後まで数え切れたか。 比較回数の上限で止めた時は `false` になり、
+ *   「交差が無い」 と「数え切れなかった」 を呼出側が区別できる。
+ */
+declare function countEdgeCrossings(edges: ReadonlyArray<{
+    id: string;
+    d: string;
+    from?: string;
+    to?: string;
+}>, warnAt?: number): {
+    count: number;
+    pairs: string[];
+    complete: boolean;
+};
+declare function visualValidateLaid(laid: LaidDiagram, diag: CdlDiagram, opts?: ValidateOptions): VisualValidationReport;
+/**
+ * 1 つの cdl diagram を 6 軸で視覚検証する。
+ *
+ * layout 計算込みで実行する。 `diag` は CdlDiagram (compile 前の builder 出力)。
+ * layout 中の console.warn ([cdl layout] overlap / near) は本 validator が再判定するため抑止する。
+ */
+declare function visualValidate(diag: CdlDiagram, opts?: ValidateOptions): VisualValidationReport;
+/**
+ * 複数 diagram を sweep して合計 report を返す。
+ */
+interface SweepReport {
+    total: number;
+    pass: number;
+    fail: number;
+    reports: VisualValidationReport[];
+    totalCounts: Record<VisualAxis, number>;
+    /** Axis 47 / 48 meta 判定結果 (per-diagram でなく engine 全体) */
+    metaViolations: Violation[];
+    /** 検査した用途。 */
+    profile: ValidationProfile;
+    /** 用途によって見なかった軸。 `totalCounts` はこれらも 0 を返す。 */
+    skippedAxes: VisualAxis[];
+}
+declare function visualValidateAll(diagrams: CdlDiagram[], opts?: ValidateOptions): SweepReport;
+
+/**
+ * layout + visualValidate を 1 回 loop 化して自動修復する SSOT 経路。
+ *
+ * `layout()` は 1 pass の layout 計算、 17 軸 visualValidate の warn / error は fixWithRetry で
+ * 3 loop まで自動修復を試みる。 修復不能な error は throw 前に戻り値の `report.violations` に集約。
+ *
+ * 呼出しモデル。
+ *  - CI / test = `layoutWithValidation(diag, { fix: false })` で diagnose のみ
+ *  - dragon build = `layoutWithValidation(diag)` (fix default true) で修復 pass
+ *  - 開発中 = `layoutWithValidation(diag, { emitConsole: true })` で warn を console に流す
+ *
+ * 修復 heuristics (順次適用、 1 loop で全 heuristic を試行 → 再 validate)。
+ *  - h1 label-offset-reset ... label-char-range / label-inside-viewbox / edge-label-overlap を
+ *      持つ edge の labelOffsetX/Y を 0 にリセット (作者の手動 offset で bbox 範囲外に押し出された
+ *      label を default 位置に戻す)
+ *  - h2 node-shift-down ... node-overlap error node pair の下 node の stack を +1
+ *  - h3 edge-back-detour ... edge-node-cross error edge の routing を "back-detour" に切替
+ */
+
+interface LayoutWithValidationOptions {
+    /** 修復 loop の最大回数 (default 3)。 0 で修復 skip。 */
+    maxFixLoops?: number;
+    /** true なら warn / error を console.warn / console.error に流す (dev のみ推奨)。 */
+    emitConsole?: boolean;
+    /** true なら修復 heuristics 適用、 false なら diagnose のみ (default true)。 */
+    fix?: boolean;
+}
+interface LayoutWithValidationResult {
+    laid: LaidDiagram;
+    report: VisualValidationReport;
+    /** 実際に走った修復 loop 数 (0 = 修復不要 or fix:false or maxFixLoops:0) */
+    fixLoops: number;
+    /** loop ごとに適用された heuristic 名の履歴 */
+    appliedHeuristics: string[];
+}
+declare function layoutWithValidation(diag: CdlDiagram, opts?: LayoutWithValidationOptions): LayoutWithValidationResult;
+
+/**
+ * 幾何演算 helper SSOT。
+ *
+ * visual-validate / collisions / dragon test で共通利用する
+ * 2D geometry primitive を 1 箇所に集約。 前 visual-validate.ts 内 local helper と
+ * Playwright test 内 local helper で 2 度書きだったのを engine から export で統一。
+ */
+interface Segment {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** 点 (px, py) と矩形の縁 (外周) までの最短距離。 内側なら 0、 外側なら実距離。 */
+declare function pointRectEdgeDistance(px: number, py: number, rect: Rect): number;
+/** 矩形同士の重なり面積 (world 単位)。 重ならなければ 0。 */
+declare function rectRectOverlapArea(a: Rect, b: Rect): number;
+/** 矩形同士の clearance (最短距離)。 重なっていれば 0、 離れていれば実距離。 */
+declare function rectRectClearance(a: Rect, b: Rect): number;
+/** 2 線分の交差判定 (端点共有は交差扱いしない)。 */
+declare function segmentsIntersect(a: Segment, b: Segment): boolean;
+
+/**
+ * dom-verify-core / dom-verify (cdl adapter) 両方で共有する types。
+ *
+ * PageLike を独立 file に切り出すことで、 core / adapter の循環 import を避ける。
+ */
+/**
+ * Playwright Page-like 抽象。 packages/cdl は Playwright を直接 import せず、
+ * 利用側で Page を渡す。 これで cdl が browser dependency 持たない。
+ */
+interface PageLike {
+    /** querySelector の thin wrapper */
+    $$eval<T>(selector: string, fn: (els: Element[]) => T): Promise<T>;
+    $eval<T>(selector: string, fn: (el: Element) => T): Promise<T>;
+    /** 任意 JS を browser context で evaluate */
+    evaluate<T, A>(fn: (arg: A) => T, arg: A): Promise<T>;
+    /** sleep (ms) */
+    waitForTimeout(ms: number): Promise<void>;
+    /** click selector */
+    click(selector: string): Promise<void>;
+}
+
+/**
+ * dom-verify core (library 化前段 = adapter pattern の足場)。
+ *
+ * cdl-specific 型 (CdlDiagram / LaidDiagram) に依存しない、 任意の SVG diagram tool に
+ * attach 可能な generic 検証 core。 将来 @cardenelabs/diagram-verifier として独立化する際の
+ * 「枝葉に依存しない API 設計」 を確立する。
+ *
+ * 利用側 (cdl adapter / Mermaid adapter / D2 adapter 等) は GenericDiagramSpec を満たす
+ * object を構築し、 verifyGenericDom(page, spec) で検証を回す。
+ *
+ * 既存 dom-verify.ts は本 file の上に cdl adapter として乗る (cdl の CdlDiagram → GenericDiagramSpec に変換)。
+ */
+
+/**
+ * 任意 diagram tool が「目」 で検証されるために提供すべき構造的 spec。
+ * cdl-specific な型を排し、 generic な primitive (id / cx / cy / w / h / path d / activate set 等) のみ。
+ */
+interface GenericDiagramSpec {
+    /** diagram の一意 id ([data-cdl-diagram="..."] でも別 attr でも良い、 adapter で selector を構築) */
+    id: string;
+    /** root selector の DOM attribute (default "data-cdl-diagram") */
+    rootAttribute?: string;
+    /** node selector の DOM attribute (default "data-cdl-node") */
+    nodeAttribute?: string;
+    /** edge selector の DOM attribute (default "data-cdl-edge") */
+    edgeAttribute?: string;
+    /** particle selector の DOM attribute (default "data-cdl-particle") */
+    particleAttribute?: string;
+    /** node 一覧 (id / cx / cy / w / h) */
+    nodes: Array<{
+        id: string;
+        cx: number;
+        cy: number;
+        w: number;
+        h: number;
+    }>;
+    /** edge 一覧 (id / from / to / d / labelX / labelY / style) */
+    edges: Array<{
+        id: string;
+        from: string;
+        to: string;
+        d: string;
+        labelX: number;
+        labelY: number;
+        /** "dotted-flow" 相当のスタイル (particle 検証対象判定用) */
+        hasParticle: boolean;
+    }>;
+    /** phase 一覧 (id / activate set) */
+    phases: Array<{
+        id: string;
+        activate: string[];
+    }>;
+}
+/**
+ * 検証種別。
+ */
+type GenericDiscrepancyKind = "missing-node-element" | "missing-edge-element" | "node-position-mismatch" | "node-size-mismatch" | "edge-path-endpoint-mismatch" | "edge-label-position-mismatch" | "particle-out-of-path" | "activation-mismatch" | "phase-transition-failure";
+interface GenericDiscrepancy {
+    kind: GenericDiscrepancyKind;
+    diagramId: string;
+    elementId: string;
+    expected: unknown;
+    actual: unknown;
+    detail: string;
+}
+interface GenericVerifyOptions {
+    positionTolerance?: number;
+    edgeEndpointTolerance?: number;
+    particleTolerance?: number;
+    particleFrameCount?: number;
+    particleConsecutiveFailThreshold?: number;
+    bboxTolerance?: number;
+    skipBbox?: boolean;
+    skipParticle?: boolean;
+    skipPhase?: boolean;
+}
+/**
+ * 任意 diagram tool の adapter が満たすべき contract。
+ *
+ * cdl の場合 ... CdlDiagram → GenericDiagramSpec を返す純関数。
+ * Mermaid の場合 ... mermaid.parse() で AST 取得 → GenericDiagramSpec に変換。
+ * D2 の場合 ... d2 CLI で JSON dump → GenericDiagramSpec に変換。
+ */
+interface DiagramAdapter<DiagramType> {
+    /** diagram type 名 (例 "cdl" / "mermaid" / "d2") */
+    readonly name: string;
+    /** diagram 型から GenericDiagramSpec への変換 */
+    toSpec(diagram: DiagramType): GenericDiagramSpec;
+}
+
+/**
+ * cdl 定義 ↔ 実画面整合性 verifier (「目」 v3 の core)。
+ *
+ * cdl で宣言した node / edge / phase / particle が、 実際の SVG render と一致しているかを
+ * DOM scrape + 数値判定で自動検証する。 LLM 不要、 課金 0。
+ *
+ * 検証 5 種類。
+ *   1. node 位置 ... data-cdl-node="{id}" 要素の boundingBox cx/cy が layout() 計算値と一致
+ *   2. edge path 起点終点 ... <path id="cdl-edge-{id}"> の d 属性の起点 / 終点が from / to node の側面と一致
+ *   3. particle 位置 ... animation N frame 撮影で particle SVG の中心が path 上の点と < tolerance
+ *   4. activation ... phase 切替時に data-cdl-active="true" が phase.activate() で宣言した element のみ
+ *   5. phase 切替 ... phase index 進行で active class set が正確に切替わる
+ */
+
+/**
+ * 図を描く `<svg>` を取る selector (cdl#336)。
+ *
+ * `[data-cdl-diagram]` の中には `<svg>` が複数ある。 interactive panel が widget ごとに 1 つ
+ * ずつ持ち (readout の ring / gauge / sparkline 等)、 **DOM 順では panel が stage より先**
+ * (`render.tsx` = panel → `CdlStage`)。 `querySelector("svg")` は document 順の最初を返すので、
+ * interactive な図では widget の `<svg>` を掴む。 その `viewBox` (`0 0 64 64` 等) で node 座標を
+ * 換算するため、 照合結果は意味を持たない数字になる。
+ *
+ * 属性で名指しする。 interactive でない図では `<svg>` が 1 つしかないため、 従来と同じものを
+ * 取る (挙動は変わらない)。
+ *
+ * `data-cdl-role` を使わないのは、 あれが consumer の CSS 契約 (`CdlRole`、 `types.ts`) だから。
+ * stage は装飾の対象になる部品ではなく図全体の入れ物で、 role に混ぜると
+ * `[data-cdl-role]` を広く拾う selector が外側の `<svg>` にも当たる。
+ */
+declare const STAGE_SVG_SELECTOR = "svg[data-cdl-stage]";
+/**
+ * node の実寸の枠を取る selector (#390)。
+ *
+ * `data-cdl-w/h` は layout の静的値で、 `wBind` / `hBind` の縮小や `renderOffsetX/Y` の移動を
+ * 含まない。 行が枠に収まっているかを実 DOM で測る側はこの要素を見る。
+ *
+ * `STAGE_SVG_SELECTOR` と同じ理由で `data-cdl-role` に置かない。 この矩形は
+ * `fill="none" stroke="none" pointer-events="none"` で、 描画されない計測用の目印。
+ *
+ * **`$$eval` / `evaluate` の callback からこの定数を参照してはいけない**。 callback は文字列
+ * として browser に渡るので module scope が消え、 実行時に `ReferenceError` になる。 callback
+ * 内では同じ値を literal で書くか、 `STAGE_SVG_SELECTOR` のように引数として渡す。
+ */
+declare const NODE_FRAME_SELECTOR = "[data-cdl-frame]";
+type DiscrepancyKind = "missing-node-element" | "missing-edge-element" | "node-position-mismatch" | "node-size-mismatch" | "edge-path-endpoint-mismatch" | "edge-label-position-mismatch" | "node-row-overflow" | "node-row-unverifiable" | "particle-out-of-path" | "activation-mismatch" | "phase-transition-failure";
+interface Discrepancy {
+    kind: DiscrepancyKind;
+    diagramId: string;
+    elementId: string;
+    expected: unknown;
+    actual: unknown;
+    detail: string;
+}
+interface VerifyOptions {
+    /** node 位置の許容誤差 (px、 default 2) */
+    positionTolerance?: number;
+    /** edge path 起点終点と node 側面の許容誤差 (px、 default 4) */
+    edgeEndpointTolerance?: number;
+    /**
+     * particle 位置 vs path 上の点との許容誤差 (px、 default 250)。
+     * Chrome / Firefox の animateMotion + getBoundingClientRect が animation 中の particle 位置を
+     * 必ずしも正確に返さない (frame 1 で static 0,0 fallback / mpath transform が screen CTM に反映されない 等)
+     * ため、 user 視覚的に同 diagram 内で許容できる 250px (= 1 lane 程度) を default に。
+     * 実エンジン bug (particle が画面外 / 別 diagram 領域へ飛ぶ) は依然検知できる。
+     */
+    particleTolerance?: number;
+    /** particle 検証時の animation frame 撮影数 (default 8、 0.25s 間隔) */
+    particleFrameCount?: number;
+    /** particle が「path から外れている」 と判定する連続 frame 数の閾値 (default 3、 偶発的 1 frame ずれを許容) */
+    particleConsecutiveFailThreshold?: number;
+    /** boundingBox 照合の許容誤差 (px、 viewBox transform scale を考慮するため大きめ default 8) */
+    bboxTolerance?: number;
+    /** boundingBox 照合を skip (高速 partial run 用) */
+    skipBbox?: boolean;
+    /** particle 検証を skip (animation がない static diagram 用) */
+    skipParticle?: boolean;
+    /** phase 切替検証を skip (single phase diagram 用) */
+    skipPhase?: boolean;
+    /**
+     * 行の文字が node の枠に収まっているかの検査を skip する。
+     *
+     * 実 font に依存するので、 font が読み込まれていない環境では意味のある判定にならない。
+     */
+    skipRowBounds?: boolean;
+    /**
+     * 行の文字が枠から出ていると判定する許容量 (screen px、 default 2)。
+     *
+     * 0 にしない理由は 2 つ。 `getBoundingClientRect()` は字形の外接矩形を返すので、 letter-spacing や
+     * antialias の分だけ数値が揺れる。 加えて枠の角が丸い (`rx`) ため、 角の近くでは枠の内側でも
+     * 矩形としては外に出る。 「明らかに出ている」 だけを拾う。
+     */
+    rowBoundsTolerance?: number;
+}
+
+/**
+ * 1 つの diagram について 5 種類の verifier を全部走らせる。
+ *
+ * options.skipBbox / skipParticle / skipPhase で各検証を skip 可能 (動作確認 / partial run 用)。
+ */
+declare function verifyDiagramDom(page: PageLike, diagram: CdlDiagram, options?: VerifyOptions): Promise<Discrepancy[]>;
+/**
+ * 複数 diagram を一括 verify。
+ */
+interface DomVerifyReport {
+    total: number;
+    pass: number;
+    fail: number;
+    discrepancies: Discrepancy[];
+}
+declare function verifyAllDiagramsDom(page: PageLike, diagrams: CdlDiagram[], options?: VerifyOptions): Promise<DomVerifyReport>;
+/**
+ * cdl-adapter: CdlDiagram → GenericDiagramSpec への変換 (目 v4 library 化前段)。
+ *
+ * 将来 @cardenelabs/diagram-verifier を独立 npm publish する際、
+ * dom-verify-core.ts (generic) + 本 adapter (cdl 用) の 2 層構成にする。
+ * 同様の adapter を Mermaid / D2 / 任意 SVG tool 用に増やせる構造。
+ */
+declare const cdlAdapter: DiagramAdapter<CdlDiagram>;
+
+/**
+ * 「目」 v5 = author intent verifier。
+ *
+ * cdl で人が宣言した意味的事実 (= 作者意図) が、 実画面 (SVG render) に
+ * 期待通り反映されているかを 6 軸で照合する。 LLM 不要、 課金 0、 規則ベース。
+ *
+ * これまでの dom-verify は engine の自己整合 (cdl 計算値 ↔ DOM attribute 同期) しか見ていなかった。
+ * v5 では「人が `.node("user", { title: "User" })` と書いた時、 画面に `User` という文字が
+ * 出ているか」 のような mermaid 的に当然期待される事実を確認する。
+ *
+ * 6 軸。
+ *   1. node-in-lane ... node が宣言した lane の領域内に居る
+ *   2. node-text-visible ... node.title / subtitle / eyebrow が文字として SVG に存在
+ *   3. edge-label-visible ... edge.label / sub が文字として SVG に存在
+ *   4. edge-connected ... edge path 起点 / 終点が from / to node の bbox の近く
+ *   5. activation-visible ... phase.activate() で宣言した要素が画面で「強調」 されている
+ *   6. tone-color ... edge.tone の指定色が SVG stroke / fill に反映
+ */
+
+type IntentDiscrepancyKind = "node-outside-lane" | "node-title-missing" | "node-subtitle-missing" | "node-eyebrow-missing" | "edge-label-missing" | "edge-sub-missing" | "edge-disconnected-from-source" | "edge-disconnected-from-target" | "activation-not-visible" | "tone-color-mismatch";
+interface IntentDiscrepancy {
+    kind: IntentDiscrepancyKind;
+    diagramId: string;
+    elementId: string;
+    expected: unknown;
+    actual: unknown;
+    detail: string;
+}
+interface AuthorIntentOptions {
+    /** edge 起点 / 終点と from / to node bbox の許容距離 (px、 default 80) */
+    edgeConnectionTolerance?: number;
+    /**
+     * lane bbox からの node はみ出し許容 (px、 default 500)。
+     * lane height 計算が node h 全部を含まないケースが engine layer に存在し、
+     * 視覚的には許容範囲 (同じ diagram 内に収まる) なので default は緩く設定。
+     * engine bug hunting は --strict (= 24px) で。
+     */
+    laneContainmentTolerance?: number;
+    /** tone 色判定の RGB 距離許容 (default 30) */
+    toneColorTolerance?: number;
+    /** activation 視覚効果判定の opacity / scale 差最小値 (default 0.1) */
+    activationVisualDelta?: number;
+    /** 軸を skip する flag (個別 disable 用) */
+    skipNodeInLane?: boolean;
+    skipNodeText?: boolean;
+    skipEdgeLabel?: boolean;
+    skipEdgeConnected?: boolean;
+    skipActivation?: boolean;
+    skipToneColor?: boolean;
+}
+/**
+ * 1 つの diagram について 6 軸検証を全部走らせる。
+ */
+declare function verifyAuthorIntent(page: PageLike, diagram: CdlDiagram, options?: AuthorIntentOptions): Promise<IntentDiscrepancy[]>;
+/**
+ * 複数 diagram を一括 verify。
+ */
+interface AuthorIntentReport {
+    total: number;
+    pass: number;
+    fail: number;
+    discrepancies: IntentDiscrepancy[];
+}
+declare function verifyAuthorIntentAll(page: PageLike, diagrams: CdlDiagram[], options?: AuthorIntentOptions): Promise<AuthorIntentReport>;
+
+/**
+ * CdlDiagramThumbnail ... 通常は CdlDiagramView を縮小表示、
+ * クリックでモーダル開いて viewport いっぱい (94vw x 90vh) に拡大表示する。
+ * Escape / 背景クリック / × ボタンで close。
+ */
+declare function CdlDiagramThumbnail(props: CdlDiagramViewProps): JSX.Element;
+
+/**
+ * World 座標系 (engine viewBox 内) と DOM 実測 px の相互変換を提供する pixel-perfect projection layer。
+ *
+ * 背景 ...
+ *   engine は viewBox world 単位で全 layout (node.cx / cy / w / h、 edge.d、 label.x / y) を確定する。
+ *   実 DOM 描画は SVG viewBox → CSS width の scale で 縮小 / 拡大され、 world 単位と DOM px は
+ *   一致しない (dragon 実測 scale = displayWidth 490 / viewBox 幅 1820 ≒ 0.269)。
+ *
+ *   従来 routing v8 / v10.1 では WORLD_SCALE = 4.0 の経験係数で world 座標の
+ *   label 幅 / clearance を 「DOM px 相当」 に補正していたが、 実は viewBox 幅 / displayWidth の
+ *   比率で数式的に算出可能。 本 module で計算を SSOT 化し、 全 downstream (edges routing / gate 判定 /
+ *   visual regression) が正確な変換を使う。
+ *
+ * 提供する変換 ...
+ *   1. worldToPx(worldValue, scale) ... 単一値 world → px
+ *   2. pxToWorld(pxValue, scale) ... 単一値 px → world (WORLD_SCALE 逆算)
+ *   3. computeViewportScale(viewBoxWidth, displayWidth) ... scale factor = viewBoxWidth / displayWidth
+ *   4. projectNode / projectEdgeLabel / projectPathSegment ... 各要素の px 予測 bbox / point
+ *
+ * SSOT ...
+ *   本 module の変換式は SVG viewBox の projection と完全に一致する (SVG spec `preserveAspectRatio`
+ *   default = xMidYMid meet で uniform scale)。 fontSize は viewBox 単位で描画時に scale される
+ *   ため、 world font 幅 × scale = DOM 実測 幅。
+ */
+
+/**
+ * viewBox width と CSS display width から scale factor を計算する。
+ *
+ * scale factor = viewBoxWidth / displayWidth
+ *   例 = dragon CdlDiagramThumbnail は viewBox width 1820 world unit、 display width 490 CSS px
+ *        → scale = 1820 / 490 ≒ 3.714
+ *   world 座標を DOM px に落とす場合は `world / scale`、
+ *   DOM px を world に戻す場合は `px * scale`。
+ *
+ * @param viewBoxWidth SVG viewBox の width 属性値 (world 単位)
+ * @param displayWidth CSS 描画時の width (px)
+ * @returns world unit per DOM px (常に > 0)
+ */
+declare function computeViewportScale(viewBoxWidth: number, displayWidth: number): number;
+/**
+ * world 座標値を DOM px に変換する。 scale = viewBoxWidth / displayWidth。
+ */
+declare function worldToPx(worldValue: number, scale: number): number;
+/**
+ * DOM px を world 座標に変換する。 scale = viewBoxWidth / displayWidth。
+ */
+declare function pxToWorld(pxValue: number, scale: number): number;
+/**
+ * Node の px 予測 bbox。 world 座標 (cx, cy, w, h) を DOM px 実測相当に変換する。
+ *
+ * SVG viewBox は uniform scale (preserveAspectRatio xMidYMid meet)、 x / y 両軸同一 scale。
+ * node cx / cy / w / h は viewBox 内 world 座標そのまま、 SVG viewBox → CSS 描画時に scale で
+ * 縮小される。 実 DOM getBoundingClientRect().width == worldW / scale。
+ *
+ * @param n LaidNode (engine 計算後の world 座標)
+ * @param scale viewBox width / display width (world unit per DOM px)
+ * @param svgOffsetPx SVG 要素の CSS 位置 offset (通常 svgClientRect.left / top、 省略時 0)
+ * @returns 予測 DOM px bbox { x, y, w, h }
+ */
+declare function projectNode(n: LaidNode, scale: number, svgOffsetPx?: {
+    x: number;
+    y: number;
+}, viewBoxOrigin?: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Edge label の px 予測 bbox。 label.x / y は world 座標での中心 (anchor middle 時) or
+ * 起点 / 終点 (anchor start / end 時)、 labelBoxW を world 単位で受け取り px 換算する。
+ *
+ * @param edge LaidEdge (labelX, labelY, labelAnchor 既確定)
+ * @param labelBoxWorldW world 単位での label bbox 幅 (measureTextWidth + padding)
+ * @param labelBoxWorldH world 単位での label bbox 高 (36 default、 sub あり時 64)
+ * @param scale viewBox width / display width
+ * @param svgOffsetPx SVG 要素の CSS 位置 offset
+ * @param viewBoxOrigin viewBox の (x_min, y_min)、 auto viewBox で 0 でない
+ */
+declare function projectEdgeLabel(edge: LaidEdge, labelBoxWorldW: number, labelBoxWorldH: number, scale: number, svgOffsetPx?: {
+    x: number;
+    y: number;
+}, viewBoxOrigin?: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Path segment (start point → end point) を DOM px に投影する。
+ *
+ * @param seg { x1, y1, x2, y2 } の world 座標 segment
+ * @param scale viewBox width / display width
+ * @param svgOffsetPx SVG 要素の CSS 位置 offset
+ * @param viewBoxOrigin viewBox の (x_min, y_min)
+ */
+declare function projectPathSegment(seg: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}, scale: number, svgOffsetPx?: {
+    x: number;
+    y: number;
+}, viewBoxOrigin?: {
+    x: number;
+    y: number;
+}): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+/**
+ * 2 bbox の距離 (rectangular gap、 交差時 0)。 px 単位で受け取り px 単位で返す。
+ * label と node の clearance 判定に使う。
+ */
+declare function bboxClearance(a: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, b: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): number;
+/**
+ * 点と segment の最短距離 (px 単位)。 label center → path segment 判定に使う。
+ */
+declare function pointToSegmentDistance(px: number, py: number, seg: {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}): number;
+
+/**
+ * Clearance / distance SSOT 定数 (world unit)。
+ *
+ * label × node / label × label / label × path の clearance と label × path 距離の
+ * 目標範囲を engine 内で SSOT 定義。 downstream (edges / collisions / visual-diagnostics / dragon
+ * gate) が本 module を import して同一値を使うことで、 threshold の食い違いを防ぐ。
+ *
+ * world unit = SVG viewBox 内の座標系単位。 実 DOM px は viewBox scale で 縮小 / 拡大される
+ * (px-projection 参照)。 gate 判定は px-projection でこれらの world 値を実測 scale に変換して
+ * 使う (pixel-perfect assertion)。
+ */
+/** node × edge-label ... 誤読を起こす重大事案、 32 world unit (edges.ts / collisions.ts SSOT) */
+declare const CLEARANCE_NODE_LABEL = 32;
+/** lane-label × edge-label ... lane 見出しと edge label の近接判定、 24 world unit */
+declare const CLEARANCE_LANE_LABEL = 24;
+/** edge-label × edge-label ... 2 label が近接して読みづらい、 36 world unit */
+declare const CLEARANCE_LABEL_LABEL = 36;
+/** edge-path × edge-label ... path 線が label 文字を貫通する誤読、 14 world unit */
+declare const CLEARANCE_PATH_LABEL = 14;
+/** label 箱 → path 最短距離の下限 (label が path に貼り付き) */
+declare const DIST_LABEL_PATH_MIN = 14;
+/**
+ * label 箱 → path 最短距離の上限 (label が path から浮遊)。
+ *
+ * 「見た目の隙間」 の上限で、 軸 7 (`edge-label-proximity`) の warn 閾値がこの値を使う。
+ * engine 自身が置く label は 16 world 以内に収まり、 これを超えるのは著者が `labelOffset`
+ * で動かした場合に限る。
+ */
+declare const DIST_LABEL_PATH_MAX = 80;
+/** label 位置 score の目標 path 距離 (routing v10 SSOT、 NORMAL 100 world = DOM ~25 px 相当) */
+declare const TARGET_LABEL_PATH_DIST = 100;
+/** arrow tail / head の折れ角許容 (degree) */
+declare const ARROW_ANGLE_MAX_DEG = 100;
+/** Fan-in / fan-out path 分散の slot 幅 (world unit) */
+declare const FAN_GAP = 120;
+/** Detour path の gap = obstacle bottom / top からの余白 (routing v10.1 SSOT、 44 → 94 拡張) */
+declare const DETOUR_GAP = 94;
+
+/**
+ * Layout spec SSOT (world unit)。
+ *
+ * CAR-421 (PR 1 / CAR-418 chain 伝搬 shift + spec 固定化) で新設した固定値 SSOT。
+ * 既存 `clearance-constants.ts` は clearance (near collision 距離下限) の SSOT だが、
+ * 本 file は「positive spec」 = engine が満たすべき正しい配置目標値 の SSOT。
+ *
+ * clearance-constants.ts と役割分担。
+ *   - clearance-constants.ts ... 「これ以下は誤読」 の下限 (near collision detection)
+ *   - spec.ts (本 file)       ... 「これを満たすと正しい」 の目標値 (positive-check axis)
+ *
+ * downstream (layout / edges / collisions / visual-validate) は本 module を import して同一値を
+ * 使うことで、 magic number の散在を防ぐ。 dragon 側 pixel-perfect gate も同 SSOT を参照する。
+ *
+ * world unit = SVG viewBox 内の座標系単位 (clearance-constants.ts と同定義)。
+ */
+
+/**
+ * その node が `rows` を文字として描くか (SSOT)。
+ *
+ * 描かない種別に対して「行が `key: value` 形式か」 (`row-format`) や「行が枠内に収まるか」
+ * (`row-vertical-spacing`) を判定しても、 前提が成り立たない。 逆に、 描かない種別に `rows` が
+ * 書かれていること自体は「書いた内容が消える」 という別の破綻で、 `rows-not-rendered` が見る。
+ */
+declare function rendersRows(kind: string | undefined): boolean;
+/**
+ * `rows` を持つ node に必要な高さ (SSOT)。
+ *
+ * 最終行の baseline から 1 行送りぶんとレイアウト余白を確保する。 行を描かない種別は `null`。
+ *
+ * `layout/nodes.ts` の `autoStorageHeight` と、 下流 (dragon の sequence header 等) が
+ * 同じ値を使う。 各所で式を写すと、 描画を変えた時に一部だけ古くなる。
+ *
+ * これは「そう置くとよい高さ」 で、 「これを下回ると破綻する高さ」 ではない。 後者は
+ * `rowBaselineY` + `rowGlyphDepth` で、 軸 16 はそちらを見る。
+ */
+declare function requiredRowsHeight(kind: string | undefined, rowCount: number): number | null;
+/**
+ * label pill 端 と path segment 距離 (world unit)。
+ *
+ * **engine が label を離して置く時の目標値**。 検証器の軸 59 `edge-label-clearance` が
+ * 「この値未満なら貼り付いている」 と判定していたが、 #386 で畳んだ = 中置き label (線の上に
+ * 載せて pill で線を隠す配置) が正常なので、 距離の下限を一律に課せない。
+ *
+ * 下限の契約は layout の test が持つ (`test/car202-edge-label-clearance.test.ts` が、 離して
+ * 置いた辺について実際に描かれる線との隙間を測る)。 検証器はこの値を見ない。
+ *
+ * clearance-constants.ts の `CLEARANCE_PATH_LABEL` (14) より大きい ... 本値は
+ * 「positive spec」 = 目標値、 CLEARANCE_PATH_LABEL は「これ以下は誤読」 の下限。
+ * 16 world unit = 大 diagram で ~4 px。 経緯 = CAR-483 で 8 → 16 拡大 → CAR-570 で
+ * 16 → 8 縮小 (「16 は離れすぎ」 判定) → CAR-630 で 8 → 16 に戻す (実描画で 8 world
+ * ~2 px は近すぎ、 user 目視判定「4px が最適」 で 16 world 復帰)。
+ */
+declare const LABEL_TO_PATH_CLEARANCE = 16;
+/**
+ * edge label center と path center の初期距離 (world unit)。
+ *
+ * routePath() が返す init labelY は path 中央から本値だけ離れた位置に配置する。
+ * pill 端 と path 実距離 = 本値 - LABEL_PILL_H_MAIN_ONLY / 2 = LABEL_TO_PATH_CLEARANCE。
+ *
+ * 計算式 = LABEL_TO_PATH_CLEARANCE (16) + LABEL_PILL_H_MAIN_ONLY (36) / 2 = 34 world。
+ * CAR-468 で 5 箇所 (旧 30 / 30 / 32 / 50 / 30 magic number) を本 SSOT に集約、 CAR-482 で
+ * LABEL_TO_PATH_CLEARANCE 4 → 8 拡大に伴い derived value 22 → 26、 CAR-483 で
+ * 8 → 16 拡大に伴い derived value 26 → 34、 CAR-570 で 16 → 8 縮小に伴い derived
+ * value 34 → 26 に戻す、 CAR-630 で 8 → 16 に戻し derived value 26 → 34 に復帰
+ * (user 目視判定 「4px が最適」)。
+ * spec.ts の 2 定数を組み合わせた derived value のため、 downstream から本定数を import する。
+ */
+declare const LABEL_INIT_CLEARANCE: number;
+/**
+ * dotted-flow style edge の marker glow 最外周 radius (world unit)。
+ *
+ * `render/edges.tsx` の EdgeGlowCircles で描画する 3 重 glow 円 (r=28/18/11 world) のうち最外周値。
+ * 動く marker が path 両側に広がる範囲 = 本値、 dotted-flow の label 距離拡張基準として使う。
+ * render 側 hard-code 値と一致必須、 render 側 radius 変更時は本値も同期。
+ */
+declare const MARKER_GLOW_RADIUS = 28;
+/**
+ * dotted-flow style edge の label center と path center の初期距離 (world unit)。
+ *
+ * CAR-518 で追加。 dotted-flow edge (Fan-out / Fan-in / Rollback / flow preset 等) は
+ * 動く marker glow (r=28 world) が path 両側に広がるため、 通常 LABEL_INIT_CLEARANCE (34) では
+ * pill 端 と marker 外周の実距離 = 16 - 28 = -12 world (marker が pill 内部に食い込む)。
+ *
+ * 計算式 = LABEL_INIT_CLEARANCE (34) + MARKER_GLOW_RADIUS (28) = 62 world。
+ * pill 端 と marker 外周実距離 = 62 - 18 - 28 = LABEL_TO_PATH_CLEARANCE (16) と等しくなり、
+ * solid edge と同じ視覚的 clearance を marker 通過帯を挟んで確保する。 CAR-570 で
+ * LABEL_TO_PATH_CLEARANCE 16 → 8 縮小に伴い derived value 62 → 54、 CAR-630 で
+ * 8 → 16 に戻し derived value 54 → 62 に復帰。
+ * routePath 内は `labelInitClearance(edge)` helper 経由でのみ本値を参照する (SSOT 単一経路)。
+ */
+declare const LABEL_INIT_CLEARANCE_DOTTED_FLOW: number;
+/**
+ * edge style に応じた label init clearance (world unit) を返す。
+ *
+ * routePath 内 labelY 計算 8 箇所の SSOT helper。 solid = 34 (LABEL_INIT_CLEARANCE)、
+ * dotted-flow = 62 (LABEL_INIT_CLEARANCE_DOTTED_FLOW)。 edge 未指定 (routePath 単体 test 経路) は
+ * solid 扱い。
+ *
+ * 分岐を 8 箇所に散らさず helper 化することで、 (a) 将来の新 style 追加時に 1 箇所修正で済む
+ * (b) test で helper を直叩きして分岐を全 style pattern で cover 可能、 という 2 利点を得る。
+ */
+declare function labelInitClearance(edge?: Pick<CdlEdge, "style" | "sub"> | null): number;
+/**
+ * edge 起点から水平方向に直進する最小距離 (world unit)。
+ *
+ * L 字 edge が起点即折れすると (起点直後で垂直方向 に turn すると) 「起点がどの
+ * node 由来か視覚判別困難」 になる。 EDGE_STUB_OUT world 以上直進すると起点が
+ * node bbox 縁から明確に離れる → 起点認識容易。
+ *
+ * 40 world = 通常 node w (200-400) の 10-20%、 detour 発火閾値と分離、 label pill
+ * 標準 h (36 world) より大きく起点 stub が label 位置と干渉しない値。
+ */
+declare const EDGE_STUB_OUT = 40;
+/**
+ * 同一 obstacle を迂回する複数 detour path の Y 分離距離 (world unit)。
+ *
+ * 例 = A → C と B → C の 2 edge が同 obstacle X を上方 detour するとき、 detour
+ * top Y が近すぎると 2 path が視覚的に重なる。 DETOUR_SLOT_GAP world 以上離すと
+ * どちらがどの edge か視認可能。
+ *
+ * 30 world = 通常 edge label h (36) より少し小さく、 detour 群が縦に密集しても label
+ * 表示スペースを圧迫しない値。 単一 obstacle の detour 3-4 本まで実用的に分離可能。
+ */
+declare const DETOUR_SLOT_GAP = 30;
+/**
+ * 同 row 内 node の cy 差分許容 (world unit)。
+ *
+ * 同 row 概念 = 同 stack index を持つ横並び node 群。 各 node の cy が完全一致
+ * (差 0) が理想だが、 subpixel 丸め誤差で 1 world 未満の差が発生し得る。 この値
+ * 未満は許容、 超過は positive-check axis `row-alignment` で fail 判定。
+ *
+ * 1 world = 大 diagram で subpixel 相当、 実測差 = 0 の場合のみ pass する厳格判定。
+ */
+declare const MIN_ROW_ALIGNMENT_TOLERANCE = 1;
+/**
+ * 同 column 内 node の cx 差分許容 (world unit)。
+ *
+ * 同 column 概念 = 同 lane 内で縦積みされた node 群。 cx は lane center に engine が
+ * 揃える設計、 差 0 が理想だが `MIN_ROW_ALIGNMENT_TOLERANCE` と同 tolerance を採用。
+ */
+declare const MIN_COLUMN_ALIGNMENT_TOLERANCE = 1;
+/**
+ * kind pair 別 clearance policy (world unit)。
+ *
+ * `collisions.ts` の CLEARANCE_POLICY (near collision 下限) と分離、 本 policy は
+ * 目標値を満たすかを見る軸 (`row-alignment` / `column-alignment` 等) が使う。
+ * `edge-label-clearance` は #386 で畳んだ。
+ *
+ * pair key format = `${kindA}|${kindB}` (アルファベット順)、 `requiredSpecClearance()` で
+ * 双方向 lookup。 未登録 pair は 0 = 判定対象外。
+ */
+declare const SPEC_CLEARANCE_POLICY: Record<string, number>;
+/**
+ * kind pair 別 spec clearance を返す。 未登録 pair は 0 (判定対象外)。
+ */
+declare function requiredSpecClearance(kindA: string, kindB: string): number;
+/**
+ * chain 伝搬 shift resolver の最大 iter 数。
+ *
+ * resolveOverlapsWithChain() で shift → 再検出 → 再 shift を loop するが、
+ * 発散防止のため N iter で強制収束。 通常 diagram は 3-5 iter で収束、 20 iter は
+ * 極端に密な layout でも十分な余裕。
+ */
+declare const CHAIN_SHIFT_MAX_ITER = 20;
+/**
+ * chain 伝搬 shift の最小 clearance (world unit)。
+ *
+ * overlap 検出時に shift する距離 = overlap 実測 + `CHAIN_MIN_CLEARANCE`。
+ * shift 後の gap が最低この値になる保証。 16 world = 通常 node gap の 20% 相当、
+ * shift 後に「くっつきすぎ」 を視覚防止する余裕距離。
+ */
+declare const CHAIN_MIN_CLEARANCE = 16;
+/**
+ * chain 伝搬 shift の 1 要素あたり累積 shift 上限 (world unit)。
+ *
+ * CAR-508 SSOT。 chain 伝搬 loop 内で label / edge-path が各軸方向にこの値以上
+ * 移動することを禁止し、 発散を止める。 Fan-out / Fan-in topology で label が互いに
+ * shift 連鎖して viewBox 外に飛ぶ regression の防止 guard。
+ *
+ * 100 world = label pill 高 (36) + label-label clearance (36) + 予備 (28) を目安、
+ * 通常の shift ケース (fail label ↔ retry path で 30-50 world 程度) には影響しない。
+ */
+declare const CHAIN_SHIFT_MAX_ACCUMULATED = 100;
+/**
+ * arrow 終点と終点 node の辺中央との距離許容 (world unit)。
+ *
+ * 終点 node の toSide (top/right/bottom/left) の辺中央 と、 arrow 実際の
+ * 終点座標との距離が本値以下なら「中央着地」 と判定。 超過は 4 隅当て症状。
+ *
+ * 8 world = 通常 node 短辺 (h=100 前後) の 8% 相当、 実描画上「辺の真ん中」
+ * と視覚判別できる余裕距離。 axis 8 (arrow-endpoint-anchoring) が「側 or 内側」
+ * を判定するのに対し、 本値は「側の中央 or 端」 を判定する棲み分け。
+ */
+declare const ARROW_ENDPOINT_CENTER_TOL = 8;
+/**
+ * 同 row 内 node 間の gap variance 許容 (world unit)。
+ *
+ * 同 stack index を持つ node 群を cx 昇順で並べ、 隣接 node cx 差 = gap を求める。
+ * gap の max - min が本値以下なら「均一」 判定。 超過は「片寄っている」 症状で
+ * axis `row-gap-uniform` で fail 判定。
+ *
+ * 40 world = 通常 node 間 gap (100-300) の 15-40% 相当、 layout engine が
+ * 均等配置に努めた結果として許容される subpixel 誤差 + 意図的 offset 余裕。
+ */
+declare const ROW_GAP_VARIANCE_TOL = 40;
+/**
+ * 同 column 内 node 間の端間 gap variance 許容 (world unit)。
+ *
+ * 同 lane 内 node 群を cy 昇順で並べ、 隣接 node の端間 gap
+ * (下の node の上端 - 上の node の下端) を求める。
+ * gap の max - min が本値以下なら「均一」 判定。 縦積み layout の gap uniform 判定。
+ * 40 world = row 側と同 tolerance で対称、 vertical stacking の意図的 offset 余裕を含む。
+ *
+ * 中心間距離 (cy 差) ではなく端間 gap を測る (Issue #202)。 node 高さは kind ごとに
+ * 異なるため、 中心間距離は端間 gap が完全に均一でも node 高さ差の分だけばらつく。
+ * engine が制御しているのは端間 gap であり、 検査もそれに合わせる。
+ */
+declare const COLUMN_GAP_VARIANCE_TOL = 40;
+/**
+ * edge-label bbox と lane border 貫通の判定 gap (world unit)。
+ *
+ * edge-label pill が lane 縁 (lane.x / lane.x+width) を貫通すると、 label の一部が
+ * 「別 lane に侵入」 したように見える。 label bbox 端が lane border から本値以下の
+ * 距離にあれば「貫通疑い」 として警告。
+ *
+ * 2 world = lane border の描画線幅 (通常 1-2 px) と bbox pill 端の許容誤差。
+ * 0 = 完全接触は許容、 内側に食い込むと fail。
+ */
+declare const LANE_BORDER_CLEARANCE_TOL = 2;
+/**
+ * near-collision 検出用 kind pair 別 clearance policy (world unit)。
+ *
+ * `SPEC_CLEARANCE_POLICY` (positive spec、 目標値) と分離、 本 policy は
+ * `detectNearCollisions()` (`collisions.ts`) が「これ以下は誤読」 の下限判定で使う。
+ *
+ * SSOT 集約 (CAR-424) — 旧実装は `collisions.ts` 内 module-local const `CLEARANCE_POLICY`
+ * として定義されていたが、 CAR-421 の `spec.ts` 追加後に「positive spec は spec.ts、
+ * near-collision は collisions.ts」 の分散所有になっていた。 本 file に集約する事で
+ * layout SSOT が 1 module に集中する (`clearance-constants.ts` の primitive 定数と
+ * 2 SSOT policy dict は組み合わせて downstream が使う)。
+ *
+ * default 未登録 pair は `NEAR_COLLISION_DEFAULT_MIN` (16 world unit)。
+ */
+declare const NEAR_COLLISION_POLICY: Record<string, number>;
+/**
+ * `NEAR_COLLISION_POLICY` に登録なし pair の default 下限 (world unit)。
+ */
+declare const NEAR_COLLISION_DEFAULT_MIN = 16;
+/**
+ * near-collision 用 kind pair 別 clearance を返す。 未登録 pair は
+ * `NEAR_COLLISION_DEFAULT_MIN` を返す (旧 collisions.ts `requiredClearance` 挙動保持)。
+ */
+declare function requiredNearClearance(kindA: string, kindB: string): number;
+
+/**
+ * rows[] から最低限必要な node width を算出。
+ * 左 padding + 左列 max 幅 + col gap + 右列 max 幅 + 右 padding。
+ *
+ * rows 空 / undefined なら 0 を返す (caller が default w と max() で安全 fallback)。
+ *
+ * `kind` で書体と字の大きさが変わる。 行を等幅の 26 で描くのは `storage` だけで、 列の間に
+ * 縦線を引くため間隔も広い (32)。 それ以外は `generic` の書式 (左が比例の 18 / 右が等幅の 21)。
+ *
+ * **`kind` を渡さない呼出には広い方を返す**。 どちらの書式で描かれるか決められないので、
+ * 狭い方を返すと行が箱からはみ出す。 広い方なら余白が増えるだけで済む。 呼び出し側が種別を
+ * 知っているなら渡した方が箱は締まる (`cardene777/dragon#1147`)。
+ *
+ * 上に丸めるのは、 送り幅が小数のため幅が小数になり、 図の座標が読みにくくなるから。 下に
+ * 丸めると 1 未満だけ足りない箱ができる。
+ */
+declare function requiredRowsWidth(rows: string[] | undefined, kind?: string): number;
+
+/**
+ * chain 伝搬 shift で node-node overlap を解消する (CAR-421 導入)。
+ *
+ * `resolveOverlaps` (後勝ち一発 shift) との違い ...
+ *   1. 検出 → shift → 再検出 → 影響先 shift の loop、 CHAIN_SHIFT_MAX_ITER で強制収束
+ *   2. shift 方向 = 後 declare node を「overlap 軸の逆方向」 に押し出す
+ *   3. shift 後に 他 node と新規 overlap した場合、 その他 node も 同方向同量 shift 連鎖
+ *   4. 収束条件 = 1 iter で shift が 1 件も発生しない、 or MAX_ITER 到達
+ *
+ * 保守性 = `resolveOverlaps` と同じく node-node のみ対象。 edge-path / edge-label
+ * との衝突は下流の resolveEdgeLabelOverlapsWithChain / detour routing に任せる。
+ *
+ * shift 量 = overlap 距離 (軸方向) + minClearance。 shift 後の gap は
+ * 少なくとも minClearance 保証、 shift 累積で「押し切った」 状態を作る。
+ *
+ * 適用範囲 = `layout()` の pipeline で `resolveOverlaps` の後に opt-in で呼ぶ経路を
+ * 想定。 sequence preset (lifeline stacking) を壊さないため、 現状 default OFF、
+ * 呼び出し側で明示的に有効化する。
+ *
+ * @param nodes 元 LaidNode 列 (順序保存で返す)
+ * @param minClearance shift 後の最小 gap (world unit、 default 16)
+ * @param maxIter 収束上限 iteration 数 (default 20)
+ * @returns shift 済 LaidNode 列 (input の順序を保持)
+ */
+declare function resolveOverlapsWithChain(nodes: LaidNode[], minClearance?: number, maxIter?: number): LaidNode[];
+/**
+ * chain 伝搬 shift で edge-label overlap を解消する (CAR-426 導入、 CAR-482 で node / lane-label
+ * 伝搬拡張)。
+ *
+ * `resolveOverlapsWithChain` の edge-label 拡張版。 node-node overlap は
+ * `resolveOverlapsWithChain` が担当、 本 function は edge-label ↔ edge-label /
+ * edge-label ↔ node / edge-label ↔ lane-label の overlap を chain 伝搬解消する。
+ *
+ * 設計指針。
+ *   1. edge-label が obstacles (node / lane-label) と overlap する場合、
+ *      label を path 側 normal 方向に押し出す (path から遠ざける方向)。
+ *   2. edge-label 同士が overlap する場合、 後 declare の label を normal 方向 shift。
+ *   3. shift 後に新規 overlap が生じた場合、 同方向で連鎖 shift (chain propagation)。
+ *   4. CAR-482 拡張 ... label が shift 方向に node / lane-label と衝突する場合、 その node /
+ *      lane-label も同方向同量 shift 連鎖 (旧 fixedObstacles → 可変 obstacles)。
+ *   5. 収束条件 = 1 iter で shift が 1 件も発生しない、 or MAX_ITER 到達。
+ *
+ * label 位置権限フロー (CAR-430 SSOT)。
+ *   1. `edges.ts routePath()` = 初期 label 位置を SSOT で決定
+ *   2. 本 function = overlap 検出時のみ chain 伝搬 shift で連鎖解消
+ *
+ * pipeline 配線 (`layout.ts` post-pass、 escape hatch = env `CDL_DISABLE_CHAIN_EDGE_LABEL=1`
+ * で OFF にすると edges.ts init 位置がそのまま最終 label 位置)。 CAR-429 で edges.ts の
+ * fan-in / fan-out offset 分散削除、 CAR-430 で label-shift.ts の shift 探索削除に伴い、
+ * label overlap 解消の単一 SSOT になった。
+ *
+ * @param edges 元 LaidEdge 列 (順序保存で返す)
+ * @param fixedObstacles 障害物 (node / lane-label の BBox 列)。 CAR-482 以前は不動、
+ *   現在は shift 対象 (CAR-482 chain 伝搬拡張)。 後方互換のため名前は fixedObstacles のまま。
+ * @param minClearance shift 後の最小 gap (world unit、 default 16)
+ * @param maxIter 収束上限 iter 数 (default 20、 spec.CHAIN_SHIFT_MAX_ITER と同値)
+ * @returns shift 済 LaidEdge 列 (input 順序を保持、 label 位置のみ変更、 path d は不変)
+ */
+declare function resolveEdgeLabelOverlapsWithChain(edges: LaidEdge[], fixedObstacles: BBox[], minClearance?: number, maxIter?: number): LaidEdge[];
+/**
+ * chain 伝搬 shift の拡張版 (CAR-482 導入、 CAR-485 で edge-path 拡張)。 label だけでなく node /
+ * lane-label / edge-path (別 edge) も同方向同量 shift 連鎖。
+ *
+ * `resolveEdgeLabelOverlapsWithChain` は edge-label のみ shift、 obstacles (node / lane-label) は不動。
+ * 本 function は「label が shift 方向にある obstacle / edge-path に衝突するなら、 その要素も同方向同量 shift 連鎖」
+ * を実装、 「押した先にある要素も押し出す」 user 期待に応える。
+ *
+ * shift 対象。
+ *   1. edge-label ... `resolveEdgeLabelOverlapsWithChain` と同経路
+ *   2. node ... label shift 方向にある node は同方向同量 shift、 chain 伝搬で再検出 → 再 shift
+ *   3. lane-label ... 同上
+ *   4. edge-path (別 edge、 CAR-485) ... label 近接 (LABEL_TO_PATH_CLEARANCE 未達) or 直接 overlap で
+ *      label を path 逆方向に shift + shift 方向にある edge-path も同方向連鎖 shift (path.d 平行移動)
+ *
+ * 保守性 = 収束条件は maxIter で強制、 発散防止。 shift 累積は各要素ごと Map で管理。
+ * 既存 preset で label overlap 発生しないなら shift 0 で edges / nodes / laneLabels / edgePathShifts 素通し。
+ *
+ * 自 edge の label × path は legit として shift 対象外 (routePath init 位置 = LABEL_INIT_CLEARANCE 34 world (CAR-630 で 26 → 34 復帰)
+ * で自 path から離した設計、 自 pair の近接判定はここでは無視する)。
+ *
+ * @param edges 元 LaidEdge 列 (順序保存で返す)
+ * @param obstacles 障害物 (node / lane-label の BBox 列)。 shift 対象。
+ * @param minClearance shift 後の最小 gap (default 16)
+ * @param maxIter 収束上限 iter 数 (default 20)
+ * @returns { edges, nodeShifts, laneLabelShifts, edgePathShifts } shift 済 edges + kind 別 shift map。
+ *   edgePathShifts は edge id → (dx, dy) の shift 量。 caller は `translatePathD(edge.d, dx, dy)` で
+ *   path.d を平行移動する。
+ */
+declare function resolveEdgeLabelOverlapsWithChainAndPropagate(edges: LaidEdge[], obstacles: BBox[], minClearance?: number, maxIter?: number, 
+/**
+ * CAR-485 = label × edge-path (別 edge) near-collision 判定に使う clearance (world unit)。
+ * `minClearance` は label × node / lane-label / label 用 (大きめ 32-36)、 本値は path 用
+ * (SSOT `LABEL_TO_PATH_CLEARANCE` = 16)、 pair 別 clearance を分離する事で fan-in / fan-out
+ * などで label が sibling path 近傍 (LABEL_INIT_CLEARANCE 26) にある正常状態を誤検知しない。
+ */
+pathLabelClearance?: number): {
+    edges: LaidEdge[];
+    nodeShifts: Map<string, {
+        dx: number;
+        dy: number;
+    }>;
+    laneLabelShifts: Map<string, {
+        dx: number;
+        dy: number;
+    }>;
+    edgePathShifts: Map<string, {
+        dx: number;
+        dy: number;
+    }>;
+};
+
+/**
+ * Engine が予測する label / node bbox の world 単位 public API。
+ *
+ * CAR-430 で label-shift.ts の shift 探索は削除、 label 位置 SSOT は edges.ts routePath() +
+ * collisions.ts resolveEdgeLabelOverlapsWithChain に移管。 CAR-431 で pill h/w/padding SSOT は
+ * spec.ts に集約 (render / layout / predict-bbox 3 箇所の drift 解消)、 本 file は spec.ts の
+ * `computeLabelBBoxWorld` を re-export する public API 層として engine 予測値と DOM 実測値を
+ * diff で assert する用途に特化した stable interface を提供する。
+ */
+
+/**
+ * Edge label の world 単位 bbox 予測 (spec.ts SSOT の re-export)。
+ *
+ * SSOT は `spec.ts` の `computeLabelBBoxWorld` に集約 (CAR-431)、 本 function は名前互換のため
+ * delegate wrapper。 render (render/edges.tsx) / layout (layout/collisions.ts) / predict-bbox (本 file)
+ * の 3 箇所で個別実装されていた bbox 計算の drift (boxH 64 vs 68、 labelY 位置の centered vs shifted)
+ * を解消。
+ *
+ * @param edge LaidEdge (labelX, labelY, labelAnchor, label, sub 既確定)
+ * @returns { x, y, w, h } の world 座標 bbox (render 実 rect 位置と一致)
+ */
+declare function predictLabelBBoxWorld(edge: LaidEdge): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * Node の world 単位 bbox 予測。
+ */
+declare function predictNodeBBoxWorld(n: LaidNode): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/**
+ * SVG font rendering の実測誤差 tolerance (world unit)。
+ *
+ * 用途別 2 種類。
+ * - `FONT_RENDER_TOLERANCE_WORLD` = 一般 bbox 予測との tolerance (label position / node size)、
+ *   80 world (実 DOM 約 22 px @ scale 3.7)
+ * - `LABEL_SIZE_TOLERANCE_WORLD` = **label bbox size 専用**、 150 world (約 40 px @ scale 3.7)
+ *
+ * label bbox tolerance を大きく取る理由 = getBoundingClientRect() は SVG `<g>` の外接矩形を
+ * 返し、 内部 `<text>` の glyph render (kerning / overhang / letter-spacing) が `<rect>` の
+ * pad から数-十 world 単位はみ出す。 measureTextWidth (advance width 集計) と DOM 実測
+ * (外接矩形) は本質的に別測定なので、 label size は 150 world で妥当な近似。
+ *
+ * engine measureTextWidth と SVG 実 render の乖離 breakdown:
+ *   - Inter font の hinting 差 ≈ ±0.5 px / char
+ *   - subpixel rendering の rounding ≈ ±1 px / bbox
+ *   - Playwright DOM 実測 と engine world 座標系の scale 差 ≈ ±10-15 world
+ *   - text glyph の rect padding 外 overhang ≈ ±20-40 world (label のみ)
+ */
+declare const FONT_RENDER_TOLERANCE_WORLD = 80;
+declare const LABEL_SIZE_TOLERANCE_WORLD = 150;
+/**
+ * bbox diff 計算 (world 単位)。 各辺の差の Math.abs の Math.max を返す。
+ * tolerance 内なら「engine 予測と実測が一致」 と判定。
+ */
+declare function bboxDiffWorld(predicted: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, actual: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}): {
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+    max: number;
+};
+
+/**
+ * 高位 API ... 著者が「lane / node / edge を 1 件ずつ宣言」 する低位 API を簡略化。
+ *
+ * - swimlane({ id, topic, lanes: ["送信元", "コントラクト", "出力"] }) で 3 lane 自動配置
+ * - flow().step("A", "func").step("B", "storage").build() で sequence diagram 風
+ */
+type SwimlanePreset = {
+    id: string;
+    topic: string;
+    /** lane label の配列。 各 lane width は固定 (default 400)、 x は auto-layout */
+    lanes: string[];
+    /** lane width (default 400) */
+    laneWidth?: number;
+    /** 各 lane が枠囲み contain か (default false、 true で全 lane contain) */
+    contain?: boolean;
+};
+/**
+ * 横並び 複数 lane を 1 行で生成する preset。
+ * 著者は lane label のみ指定、 x / width は engine が自動配置。
+ *
+ * @example
+ * swimlane({ id: "tx", topic: "Tx Flow", lanes: ["送信元", "Contract", "出力"] })
+ *   .node("client", { lane: "send-mototo", stack: 0, kind: "actor", title: "Client" })  // lane id は label を slug 化
+ *   ...
+ */
+/** swimlane の戻り値 ... DiagramBuilder + 各 lane の slug id を取得する getter */
+type SwimlaneResult = DiagramBuilder & {
+    /** lane label から自動生成された slug id を返す (label 順 0-indexed) */
+    laneId: (indexOrLabel: number | string) => string;
+};
+declare function swimlane(preset: SwimlanePreset): SwimlaneResult;
+type FlowStepInput = {
+    id: string;
+    kind: NodeKind;
+    title: string;
+    eyebrow?: string;
+    subtitle?: string;
+};
+type FlowPreset = {
+    id: string;
+    topic: string;
+    /** lane label (1 本のみ、 全 step が縦 stack で並ぶ) */
+    laneLabel?: string;
+    laneWidth?: number;
+    /** edge tone / style の default (各 step → next step の edge) */
+    defaultTone?: Tone;
+    defaultStyle?: EdgeStyle;
+};
+type FlowBuilder = {
+    /** step を順番に追加、 自動で前 step から edge 接続 */
+    step: (node: FlowStepInput, edgeLabel?: string) => FlowBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * flow preset ... 1 lane に縦 stack で node を並べ、 前 step → 次 step の edge を auto 接続。
+ * sequence diagram 風 (mermaid `sequenceDiagram` の cdl 版)。
+ *
+ * @example
+ * flow({ id: "auth", topic: "Auth Flow" })
+ *   .step({ id: "user", kind: "person", title: "User" })
+ *   .step({ id: "api", kind: "api", title: "POST /login" }, "ログイン要求")
+ *   .step({ id: "db", kind: "database", title: "users 表" }, "credential 検証")
+ *   .build();
+ */
+declare function flow(preset: FlowPreset): FlowBuilder;
+type SequenceStep = {
+    /** from actor id (or label slug) */
+    from: string;
+    /** to actor id (or label slug) */
+    to: string;
+    /** message label */
+    label: string;
+    /** 補足 (2 行目、 例 ... POST /login の body 仕様等) */
+    sub?: string;
+    tone?: Tone;
+    style?: EdgeStyle;
+};
+type SequencePreset = {
+    id: string;
+    topic: string;
+    /** actor label の配列 (lifeline、 column 単位) */
+    actors: string[];
+    /** actor の lane width (default 220) */
+    laneWidth?: number;
+    /** lane gap (default 60) */
+    laneGap?: number;
+    /** default edge tone (default accent) */
+    defaultTone?: Tone;
+    /** default edge style (default solid) */
+    defaultStyle?: EdgeStyle;
+};
+type SequenceBuilder = {
+    /** message step を時系列順に追加、 from → to の水平 edge を引く */
+    step: (s: SequenceStep) => SequenceBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * sequence preset ... UML sequence diagram 風。 actors を column 化 (lifeline)、
+ * step({ from, to, label }) で時系列順に message edge を生成。
+ *
+ * @example
+ * sequence({ id: "auth-seq", topic: "Auth Sequence", actors: ["User", "API", "DB"] })
+ *   .step({ from: "User", to: "API", label: "POST /login" })
+ *   .step({ from: "API", to: "DB", label: "SELECT credentials" })
+ *   .step({ from: "DB", to: "API", label: "rows", tone: "success", style: "dotted-flow" })
+ *   .step({ from: "API", to: "User", label: "200 OK", tone: "success" })
+ *   .build();
+ */
+declare function sequence(preset: SequencePreset): SequenceBuilder;
+type TopologyContainer = {
+    id: string;
+    kind: NodeKind;
+    title: string;
+    eyebrow?: string;
+};
+type TopologyConnection = {
+    from: string;
+    to: string;
+    label: string;
+    sub?: string;
+    tone?: Tone;
+    style?: EdgeStyle;
+    labelOffsetX?: number;
+    labelOffsetY?: number;
+};
+type TopologyPreset = {
+    id: string;
+    topic: string;
+    /** group の lane width (default 360) */
+    groupWidth?: number;
+    defaultTone?: Tone;
+    defaultStyle?: EdgeStyle;
+};
+type TopologyGroupBuilder = {
+    add: (container: TopologyContainer) => TopologyGroupBuilder;
+};
+type TopologyBuilder = {
+    group: (id: string, opts: {
+        label: string;
+    }) => TopologyGroupBuilder;
+    connect: (from: string, to: string, opts: {
+        label: string;
+        sub?: string;
+        tone?: Tone;
+        style?: EdgeStyle;
+        labelOffsetX?: number;
+        labelOffsetY?: number;
+    }) => TopologyBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * topology preset ... 構成図 / deployment diagram 風。
+ * group で container を囲む、 add で内部 element を配置、 connect で element 間 connection。
+ *
+ * @example
+ * topology({ id: "aws", topic: "AWS Deployment" })
+ *   .group("aws", { label: "AWS" })
+ *     .add({ id: "alb", kind: "service", title: "ALB" })
+ *     .add({ id: "ecs", kind: "service", title: "ECS Task" })
+ *     .add({ id: "rds", kind: "database", title: "RDS" })
+ *   .group("client", { label: "Client" })
+ *     .add({ id: "browser", kind: "frontend", title: "Browser" })
+ *   .connect("browser", "alb", { label: "HTTPS" })
+ *   .connect("alb", "ecs", { label: "round-robin" })
+ *   .connect("ecs", "rds", { label: "TCP 5432" })
+ *   .build();
+ */
+declare function topology(preset: TopologyPreset): TopologyBuilder;
+type ErEntity = {
+    id: string;
+    /** entity 名 (例 "User") */
+    title: string;
+    /** 列定義 (例 "id: PK", "email: string", "userId: FK") */
+    rows: string[];
+};
+type ErRelationCardinality = "1:1" | "1:N" | "N:1" | "N:M" | "0..1" | "1..*";
+type ErRelation = {
+    from: string;
+    to: string;
+    cardinality: ErRelationCardinality;
+    /** 関係名 (例 "places", "belongs_to") */
+    label?: string;
+    tone?: Tone;
+};
+type ErPreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    /**
+     * 実体 1 個の箱の幅 (world unit、 既定 = `storage` の既定幅)。
+     *
+     * 帯ではなく **箱** の幅。 帯は `箱の幅 + 余白 × 2` で宣言する (engine が帯を同じ式まで
+     * 広げるため、 狭く宣言すると宣言座標と実座標がずれる)。
+     */
+    entityWidth?: number;
+};
+type ErBuilder = {
+    entity: (e: ErEntity) => ErBuilder;
+    relation: (r: ErRelation) => ErBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * er preset ... ER 図 (Entity Relationship)。 entity を table 風 node (rows 構造) で配置、
+ * relation を edge で接続、 cardinality は edge label に記法 (1:1 / 1:N / N:M / 0..1 / 1..*) で表記。
+ * mermaid ER 図の cdl 版。
+ *
+ * @example
+ * er({ id: "user-order", topic: "User-Order ER" })
+ *   .entity({ id: "user", title: "User", rows: ["id: PK", "email: string", "createdAt: timestamp"] })
+ *   .entity({ id: "order", title: "Order", rows: ["id: PK", "userId: FK", "total: number"] })
+ *   .relation({ from: "user", to: "order", cardinality: "1:N", label: "places" })
+ *   .build();
+ */
+declare function er(preset: ErPreset): ErBuilder;
+type FsmState = {
+    id: string;
+    title: string;
+    /** initial state (1 つだけ) */
+    initial?: boolean;
+    /** final state (複数可) */
+    final?: boolean;
+};
+type FsmTransition = {
+    from: string;
+    to: string;
+    /** 遷移 trigger (例 "submit" / "success" / "fail") */
+    trigger: string;
+    /** guard 条件 (例 "if validated") */
+    guard?: string;
+    tone?: Tone;
+};
+type StateMachinePreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    /**
+     * 状態 1 個の箱の幅 (world unit、 既定 320 = card の既定幅)。
+     *
+     * 帯の幅ではなく **箱の幅** を指す。 帯は engine が「箱の幅 + 余白 × 2」 まで広げるので、
+     * 帯だけを狭く指定しても図は縮まない (#357 以前はここが帯にしか渡っておらず、
+     * 370 未満の指定が全て無視されていた)。
+     *
+     * 80 未満と有限でない値は例外を投げる。 箱の幅として使う以上、 描画が壊れる値を
+     * 黙って受け取らない。
+     */
+    stateWidth?: number;
+};
+type StateMachineBuilder = {
+    state: (s: FsmState) => StateMachineBuilder;
+    transition: (t: FsmTransition) => StateMachineBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * stateMachine preset ... FSM (Finite State Machine) / workflow。
+ * state を card kind で配置、 transition を edge で接続、 trigger は edge label、 guard は sub。
+ * initial / final state は eyebrow + tone で識別表現。
+ *
+ * @example
+ * stateMachine({ id: "auth-fsm", topic: "Auth FSM" })
+ *   .state({ id: "idle", title: "Idle", initial: true })
+ *   .state({ id: "loading", title: "Loading" })
+ *   .state({ id: "done", title: "Done", final: true })
+ *   .state({ id: "error", title: "Error" })
+ *   .transition({ from: "idle", to: "loading", trigger: "submit" })
+ *   .transition({ from: "loading", to: "done", trigger: "success", tone: "success" })
+ *   .transition({ from: "loading", to: "error", trigger: "fail", tone: "error" })
+ *   .transition({ from: "error", to: "idle", trigger: "retry", guard: "if attempts < 3" })
+ *   .build();
+ */
+declare function stateMachine(preset: StateMachinePreset): StateMachineBuilder;
+type InfraNode = {
+    id: string;
+    kind: NodeKind;
+    title: string;
+    /** 表示位置 (col, row)、 0-indexed。 grid 上の配置を author が制御 */
+    col: number;
+    row: number;
+    subtitle?: string;
+    eyebrow?: string;
+};
+type InfraConnection = {
+    from: string;
+    to: string;
+    label: string;
+    sub?: string;
+    tone?: Tone;
+    style?: EdgeStyle;
+    /** label の水平方向 fine offset (default 0)、 preset 交互 ±60 を override */
+    labelOffsetX?: number;
+    /** label の垂直方向 fine offset (default 0、 preset 交互 ±60 を override) */
+    labelOffsetY?: number;
+};
+type InfrastructurePreset = {
+    id: string;
+    topic: string;
+    /** col あたりの lane width (default 380) */
+    laneWidth?: number;
+    defaultTone?: Tone;
+    defaultStyle?: EdgeStyle;
+};
+type InfrastructureBuilder = {
+    node: (n: InfraNode) => InfrastructureBuilder;
+    connect: (c: InfraConnection) => InfrastructureBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * infrastructure preset ... AWS / GCP / Azure 等の cloud / system 構成図。
+ * node を col + row の grid で配置、 connect で接続線 + edge label。
+ * topology preset (group + container 包含) と違って flat grid 配置 + 各 node が
+ * 独立 lane を持つので、 BFF / Lambda / CDN 等を散在配置するシステム概要図に適する。
+ *
+ * @example
+ * infrastructure({ id: "saas-infra", topic: "SaaS Architecture" })
+ *   .node({ id: "user", kind: "person", title: "User", col: 0, row: 0 })
+ *   .node({ id: "cdn", kind: "cdn", title: "CloudFront", col: 1, row: 0 })
+ *   .node({ id: "alb", kind: "service", title: "ALB", col: 2, row: 0 })
+ *   .node({ id: "app", kind: "service", title: "App", col: 2, row: 1 })
+ *   .node({ id: "db", kind: "database", title: "RDS", col: 3, row: 1 })
+ *   .connect({ from: "user", to: "cdn", label: "HTTPS" })
+ *   .connect({ from: "cdn", to: "alb", label: "origin" })
+ *   .connect({ from: "alb", to: "app", label: "route" })
+ *   .connect({ from: "app", to: "db", label: "TCP 5432" })
+ *   .build();
+ */
+declare function infrastructure(preset: InfrastructurePreset): InfrastructureBuilder;
+type ClassRelationType = "extends" | "implements" | "uses" | "aggregates" | "composes";
+type UmlClass = {
+    id: string;
+    title: string;
+    /** 属性 (例 "+name: string" / "-id: number") */
+    attributes?: string[];
+    /** メソッド (例 "+login(): void") */
+    methods?: string[];
+    /** stereotype (例 "abstract" / "interface" / "trait") */
+    stereotype?: string;
+};
+type UmlRelation = {
+    from: string;
+    to: string;
+    type: ClassRelationType;
+    /** 関係 label (default は type 名) */
+    label?: string;
+    /** 多重度 (例 "1..*" / "0..1") */
+    cardinality?: string;
+    tone?: Tone;
+};
+type ClassDiagramPreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    /**
+     * クラス 1 個の箱の幅 (world unit、 既定 = `storage` の既定幅)。
+     *
+     * 帯ではなく **箱** の幅。 帯は `箱の幅 + 余白 × 2` で宣言する。
+     */
+    classWidth?: number;
+};
+type ClassDiagramBuilder = {
+    class: (c: UmlClass) => ClassDiagramBuilder;
+    relation: (r: UmlRelation) => ClassDiagramBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * classDiagram preset ... UML クラス図。 attributes + methods を rows で表現、
+ * relation を edge で接続。 extends / implements / uses / aggregates / composes 5 種対応。
+ *
+ * @example
+ * classDiagram({ id: "user-class", topic: "User domain model" })
+ *   .class({ id: "User", title: "User", attributes: ["+name: string", "+email: string"], methods: ["+login(): void"] })
+ *   .class({ id: "Admin", title: "Admin", attributes: ["+permissions: string[]"], methods: ["+banUser(): void"] })
+ *   .relation({ from: "Admin", to: "User", type: "extends" })
+ *   .build();
+ */
+declare function classDiagram(preset: ClassDiagramPreset): ClassDiagramBuilder;
+type TreeNode = {
+    id: string;
+    title: string;
+    parent?: string;
+    /** 表示 kind (default "card") */
+    kind?: NodeKind;
+    subtitle?: string;
+    eyebrow?: string;
+};
+type TreePreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    /** depth ごとの lane width (default 320) */
+    nodeWidth?: number;
+};
+type TreeBuilder = {
+    node: (n: TreeNode) => TreeBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * tree preset ... parent-child の階層構造を縦列の lane stack で表現。
+ * 各 node は parent を指定、 親が同 lane stack の上に配置される lane (depth 別) を auto 計算。
+ * 組織図 / file tree / class 階層 / 製品カテゴリ等の階層図に使う。
+ *
+ * @example
+ * tree({ id: "org", topic: "組織図" })
+ *   .node({ id: "ceo", title: "CEO" })
+ *   .node({ id: "cto", title: "CTO", parent: "ceo" })
+ *   .node({ id: "cfo", title: "CFO", parent: "ceo" })
+ *   .node({ id: "eng-mgr", title: "Eng Manager", parent: "cto" })
+ *   .build();
+ */
+declare function tree(preset: TreePreset): TreeBuilder;
+type JourneyEmotion = "delighted" | "happy" | "neutral" | "frustrated" | "angry";
+type JourneyStep = {
+    id: string;
+    title: string;
+    emotion: JourneyEmotion;
+    /** どの touchpoint (例 "Website", "Email", "Support") */
+    touchpoint?: string;
+    /** opportunity (改善余地のメモ) */
+    opportunity?: string;
+};
+type UserJourneyPreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    stepWidth?: number;
+};
+type UserJourneyBuilder = {
+    step: (s: JourneyStep) => UserJourneyBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * userJourney preset ... User research / UX research の journey map。
+ * step を時系列に横並びで並べ、 emotion を tone で色分け、 touchpoint / opportunity を subtitle で示す。
+ *
+ * @example
+ * userJourney({ id: "signup", topic: "Signup journey" })
+ *   .step({ id: "land", title: "Land on /", emotion: "neutral", touchpoint: "Website" })
+ *   .step({ id: "form", title: "Fill form", emotion: "frustrated", touchpoint: "Form" })
+ *   .step({ id: "verify", title: "Email verify", emotion: "happy", touchpoint: "Email" })
+ *   .step({ id: "done", title: "Done", emotion: "delighted", touchpoint: "Dashboard" })
+ *   .build();
+ */
+declare function userJourney(preset: UserJourneyPreset): UserJourneyBuilder;
+type MindBranch = {
+    id: string;
+    title: string;
+    /** 親 branch (root の子は parent=root id) */
+    parent: string;
+    /** 色 tone (default は parent の tone を継承) */
+    tone?: Tone;
+    subtitle?: string;
+};
+type MindMapPreset = {
+    id: string;
+    topic: string;
+    /** 中心 topic ID + label */
+    rootId: string;
+    rootTitle: string;
+    branchWidth?: number;
+    defaultTone?: Tone;
+};
+type MindMapBuilder = {
+    branch: (b: MindBranch) => MindMapBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * mindMap preset ... 中心 root topic から放射状に branch を伸ばす mind map。
+ * tree との違いは「root は 1 つ固定 + 第 1 階層の branch ごとに tone を auto rotate」。
+ *
+ * @example
+ * mindMap({ id: "ideas", topic: "Project ideas", rootId: "root", rootTitle: "Project" })
+ *   .branch({ id: "feat", title: "Features", parent: "root" })
+ *   .branch({ id: "ui", title: "UI design", parent: "root" })
+ *   .branch({ id: "auth", title: "Auth", parent: "feat" })
+ *   .build();
+ */
+declare function mindMap(preset: MindMapPreset): MindMapBuilder;
+type FunnelStage = {
+    id: string;
+    title: string;
+    /** この stage の人数 / 件数 */
+    count: number;
+    /** stage 詳細 */
+    subtitle?: string;
+};
+type FunnelPreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    stageWidth?: number;
+};
+type FunnelBuilder = {
+    stage: (s: FunnelStage) => FunnelBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * funnel preset ... Sales / marketing funnel。 Awareness → Conversion の階層を縦に並べ、
+ * 各 stage の count と drop rate (前 stage 比) を可視化。
+ *
+ * @example
+ * funnel({ id: "sales", topic: "Sales funnel" })
+ *   .stage({ id: "visit", title: "Visit", count: 10000 })
+ *   .stage({ id: "signup", title: "Sign up", count: 1500 })
+ *   .stage({ id: "trial", title: "Trial", count: 800 })
+ *   .stage({ id: "paid", title: "Paid", count: 200 })
+ *   .build();
+ */
+declare function funnel(preset: FunnelPreset): FunnelBuilder;
+type QuadrantQuadrantLabel = "topLeft" | "topRight" | "bottomLeft" | "bottomRight";
+type QuadrantItem = {
+    id: string;
+    title: string;
+    /** どの象限 (4 象限) */
+    quadrant: QuadrantQuadrantLabel;
+    subtitle?: string;
+};
+type QuadrantPreset = {
+    id: string;
+    topic: string;
+    /** x 軸 label (left / right) */
+    xAxis: {
+        left: string;
+        right: string;
+    };
+    /** y 軸 label (bottom / top) */
+    yAxis: {
+        bottom: string;
+        top: string;
+    };
+    /** 各象限の label */
+    quadrantLabels?: Record<QuadrantQuadrantLabel, string>;
+    defaultTone?: Tone;
+};
+type QuadrantBuilder = {
+    item: (i: QuadrantItem) => QuadrantBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * quadrant preset ... 2 軸 マトリクス (Priority matrix / SWOT / Eisenhower 等)。
+ * 4 象限 (topLeft / topRight / bottomLeft / bottomRight) に item を配置。
+ * lane = 2 col (left / right)、 stack = 2 row (top / bottom)。
+ *
+ * @example
+ * quadrant({ id: "priority", topic: "Priority matrix",
+ *           xAxis: { left: "Low effort", right: "High effort" },
+ *           yAxis: { bottom: "Low value", top: "High value" } })
+ *   .item({ id: "a", title: "Quick win", quadrant: "topLeft" })
+ *   .item({ id: "b", title: "Major project", quadrant: "topRight" })
+ *   .item({ id: "c", title: "Fill in", quadrant: "bottomLeft" })
+ *   .item({ id: "d", title: "Thankless", quadrant: "bottomRight" })
+ *   .build();
+ */
+declare function quadrant(preset: QuadrantPreset): QuadrantBuilder;
+type ChartType = "pie" | "bar" | "line";
+type ChartDatum = {
+    id: string;
+    label: string;
+    value: number;
+    /** 個別 tone (default は preset の defaultTone) */
+    tone?: Tone;
+};
+type ChartPreset = {
+    id: string;
+    topic: string;
+    type: ChartType;
+    defaultTone?: Tone;
+    itemWidth?: number;
+};
+type ChartBuilder = {
+    datum: (d: ChartDatum) => ChartBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * chart preset ... 統計チャート (Pie / Bar / Line)、 CAR-994 Phase A で SVG geometry render 導入。
+ *
+ * datum 配列を 1 大 node (kind=chart-line / chart-pie / chart-bar) の chartData payload に
+ * 格納し、 kinds/chart-*.tsx が自己完結で折れ線 / 円 / 棒グラフを SVG 描画する。
+ * layout は 1 lane + 1 node (chart canvas サイズ) で完結、 lane / edge を datum 数だけ増やさない。
+ *
+ * @example
+ * chart({ id: "share", topic: "Market share", type: "pie" })
+ *   .datum({ id: "a", label: "A", value: 45 })
+ *   .datum({ id: "b", label: "B", value: 30 })
+ *   .datum({ id: "c", label: "C", value: 25 })
+ *   .build();
+ */
+declare function chart(preset: ChartPreset): ChartBuilder;
+type GanttTask = {
+    id: string;
+    title: string;
+    /** 開始 (例 "2026-Q1" / "Day 1") */
+    start: string;
+    /** 終了 (例 "2026-Q2") */
+    end: string;
+    /** owner / assignee */
+    owner?: string;
+    /** 依存 task id */
+    dependsOn?: string;
+};
+type GanttPreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    laneWidth?: number;
+};
+type GanttBuilder = {
+    task: (t: GanttTask) => GanttBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * gantt preset ... Gantt chart / sprint planning / release timeline。
+ * task ごとに 1 lane を作り、 start - end + owner を subtitle、 dependsOn で前 task → 次 task の edge を auto 生成。
+ *
+ * @example
+ * gantt({ id: "release", topic: "Release timeline" })
+ *   .task({ id: "design", title: "Design", start: "Q1", end: "Q1" })
+ *   .task({ id: "build", title: "Build", start: "Q2", end: "Q2", dependsOn: "design" })
+ *   .task({ id: "test", title: "Test", start: "Q3", end: "Q3", dependsOn: "build" })
+ *   .build();
+ */
+declare function gantt(preset: GanttPreset): GanttBuilder;
+type FlowchartNodeShape = "process" | "decision" | "start" | "end" | "loop";
+type FlowchartNode = {
+    id: string;
+    title: string;
+    shape: FlowchartNodeShape;
+    /** swimlane (role) */
+    lane: string;
+};
+type FlowchartEdge = {
+    from: string;
+    to: string;
+    /** decision shape の場合 "true" / "false" / null */
+    label?: string;
+    tone?: Tone;
+};
+type FlowchartPreset = {
+    id: string;
+    topic: string;
+    /** swimlane の lane (role) ラベル */
+    lanes: string[];
+    defaultTone?: Tone;
+    laneWidth?: number;
+};
+type FlowchartBuilder = {
+    node: (n: FlowchartNode) => FlowchartBuilder;
+    edge: (e: FlowchartEdge) => FlowchartBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * flowchart preset ... swimlane + decision diamond + loop 枠を扱うビジネス process diagram。
+ * mermaid flowchart より「lane 別の役割分担」 と「decision / loop」 を明示できる。
+ *
+ * @example
+ * flowchart({ id: "approve", topic: "Approval flow", lanes: ["User", "Manager"] })
+ *   .node({ id: "submit", title: "Submit", shape: "start", lane: "User" })
+ *   .node({ id: "review", title: "Review", shape: "decision", lane: "Manager" })
+ *   .node({ id: "approve", title: "Approve", shape: "end", lane: "Manager" })
+ *   .node({ id: "revise", title: "Revise", shape: "process", lane: "User" })
+ *   .edge({ from: "submit", to: "review" })
+ *   .edge({ from: "review", to: "approve", label: "true" })
+ *   .edge({ from: "review", to: "revise", label: "false" })
+ *   .build();
+ */
+declare function flowchart(preset: FlowchartPreset): FlowchartBuilder;
+type NetworkDeviceKind = "router" | "switch" | "firewall" | "server" | "client";
+type NetworkDevice = {
+    id: string;
+    title: string;
+    kind: NetworkDeviceKind;
+    segment?: string;
+    /** 表示 col + row */
+    col: number;
+    row: number;
+};
+type NetworkLink = {
+    from: string;
+    to: string;
+    /** プロトコル / VLAN 等 */
+    protocol?: string;
+    tone?: Tone;
+};
+type NetworkPreset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    laneWidth?: number;
+};
+type NetworkBuilder = {
+    device: (d: NetworkDevice) => NetworkBuilder;
+    link: (l: NetworkLink) => NetworkBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * network preset ... NW topology (router / switch / firewall / server / client) を col × row 配置、
+ * link で接続 (protocol / VLAN を label)。 On-prem / hybrid NW 構成図向け。
+ *
+ * @example
+ * network({ id: "office-nw", topic: "Office NW" })
+ *   .device({ id: "fw", title: "Firewall", kind: "firewall", col: 0, row: 0 })
+ *   .device({ id: "sw1", title: "Switch A", kind: "switch", col: 1, row: 0 })
+ *   .device({ id: "srv", title: "Server", kind: "server", col: 2, row: 0 })
+ *   .link({ from: "fw", to: "sw1", protocol: "VLAN 10" })
+ *   .link({ from: "sw1", to: "srv", protocol: "TCP 22" })
+ *   .build();
+ */
+declare function network(preset: NetworkPreset): NetworkBuilder;
+type FsmStateNested = {
+    id: string;
+    title: string;
+    initial?: boolean;
+    final?: boolean;
+    /** 親 state (nested state、 例 "loading" の親 "active") */
+    parent?: string;
+    /** entry action (例 "onEnter: startTimer") */
+    entry?: string;
+    /** exit action */
+    exit?: string;
+};
+type FsmTransitionExt = {
+    from: string;
+    to: string;
+    trigger: string;
+    guard?: string;
+    /** action (例 "onTransition: incrementCounter") */
+    action?: string;
+    tone?: Tone;
+};
+type StateMachine2Preset = {
+    id: string;
+    topic: string;
+    defaultTone?: Tone;
+    /**
+     * 状態 1 個の箱の幅 (world unit、 既定 320 = card の既定幅)。
+     *
+     * 帯の幅ではなく **箱の幅** を指す。 帯は engine が「箱の幅 + 余白 × 2」 まで広げるので、
+     * 帯だけを狭く指定しても図は縮まない (#357 以前はここが帯にしか渡っておらず、
+     * 370 未満の指定が全て無視されていた)。
+     *
+     * 80 未満と有限でない値は例外を投げる。 箱の幅として使う以上、 描画が壊れる値を
+     * 黙って受け取らない。
+     */
+    stateWidth?: number;
+};
+type StateMachine2Builder = {
+    state: (s: FsmStateNested) => StateMachine2Builder;
+    transition: (t: FsmTransitionExt) => StateMachine2Builder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * stateMachine2 preset ... 拡張 FSM (UML statechart)。
+ * stateMachine と違って (a) nested state (parent 指定) (b) entry / exit action (c) transition action サポート。
+ * subtitle / sub で action / guard を表示。
+ *
+ * @example
+ * stateMachine2({ id: "auth", topic: "Auth FSM" })
+ *   .state({ id: "idle", title: "Idle", initial: true, entry: "clearForm" })
+ *   .state({ id: "active", title: "Active" })
+ *   .state({ id: "loading", title: "Loading", parent: "active" })
+ *   .state({ id: "done", title: "Done", final: true })
+ *   .transition({ from: "idle", to: "loading", trigger: "submit", action: "startSpinner" })
+ *   .transition({ from: "loading", to: "done", trigger: "success" })
+ *   .build();
+ */
+declare function stateMachine2(preset: StateMachine2Preset): StateMachine2Builder;
+type MindMapRadialBranch = {
+    id: string;
+    title: string;
+    /** 色 tone (default は defaultTone)。 8 方向で auto rotate も可 */
+    tone?: Tone;
+    subtitle?: string;
+};
+type MindMapRadialPreset = {
+    id: string;
+    topic: string;
+    /** 中心 node の title (id は builder が "center" で内部生成) */
+    centerTitle: string;
+    /** 中心 node の id override (default "center") */
+    centerId?: string;
+    /** 中心から branch までの距離 (world coord、 default 350) */
+    radius?: number;
+    /** branch node の width (default 260) */
+    branchWidth?: number;
+    /** 中心 node の width (default 260) */
+    centerWidth?: number;
+    defaultTone?: Tone;
+};
+type MindMapRadialBuilder = {
+    branch: (b: MindMapRadialBranch) => MindMapRadialBuilder;
+    build: () => ReturnType<DiagramBuilder["build"]>;
+};
+/**
+ * mindMapRadial preset ... 中心 node を軸に 8 方向 (0°/45°/90°/135°/180°/225°/270°/315°)
+ * へ branch を放射状に配置する。 現行 mindMap (左から右へ水平 tree) と使い分ける用途。
+ *
+ * 実装戦略 ... engine の lane × stack grid を活用し、 3 lane (left / center / right) を
+ * radius に基づき explicit x で配置、 3 stack row (top / middle / bottom) を stack index 0/1/2 で
+ * 割当てる。 branch 順は position 順 (E/SE/S/SW/W/NW/N/NE) に固定し、 index → grid cell mapping。
+ *
+ * @example
+ * mindMapRadial({ id: "mr", topic: "Product Radial", centerTitle: "Product" })
+ *   .branch({ id: "users", title: "Users" })      // 0° (right)
+ *   .branch({ id: "road", title: "Roadmap" })     // 45° (bottom-right)
+ *   .branch({ id: "metrics", title: "Metrics" })  // 90° (bottom)
+ *   ...
+ *   .build();
+ */
+declare function mindMapRadial(preset: MindMapRadialPreset): MindMapRadialBuilder;
+
+export { ARROW_ANGLE_MAX_DEG, ARROW_ENDPOINT_CENTER_TOL, type AnimationChain, type AuthorIntentOptions, type AuthorIntentReport, type BinaryOp, CHAIN_MIN_CLEARANCE, CHAIN_SHIFT_MAX_ACCUMULATED, CHAIN_SHIFT_MAX_ITER, CLEARANCE_LABEL_LABEL, CLEARANCE_LANE_LABEL, CLEARANCE_NODE_LABEL, CLEARANCE_PATH_LABEL, COLUMN_GAP_VARIANCE_TOL, CdlDiagram, CdlDiagramThumbnail, CdlEdge, type CdlEventHandler, CdlEventTarget, CdlInput, CdlLane, CdlNode, CdlScrollTrigger, CdlState, type ChartBuilder, type ChartDatum, type ChartPreset, type ChartType, type ClassDiagramBuilder, type ClassDiagramPreset, type ClassRelationType, Computed, DETOUR_GAP, DETOUR_SLOT_GAP, DIST_LABEL_PATH_MAX, DIST_LABEL_PATH_MIN, type DiagramAdapter, type DiagramBuilder, type Discrepancy, type DiscrepancyKind, type DomVerifyReport, EDGE_LABEL_TEXT, EDGE_STUB_OUT, type EdgeLabelLine, type EdgeLabelTextSpec, EdgeStyle, type ErBuilder, type ErEntity, type ErPreset, type ErRelation, type ErRelationCardinality, type EventAttachHandle, type EventChain, FAN_GAP, FONT_RENDER_TOLERANCE_WORLD, type FlowBuilder, type FlowPreset, type FlowStepInput, type FlowchartBuilder, type FlowchartEdge, type FlowchartNode, type FlowchartNodeShape, type FlowchartPreset, type FormulaAst, type FormulaContext, type FsmState, type FsmStateNested, type FsmTransition, type FsmTransitionExt, type FunnelBuilder, type FunnelPreset, type FunnelStage, type GanttBuilder, type GanttPreset, type GanttTask, type GenericDiagramSpec, type GenericDiscrepancy, type GenericDiscrepancyKind, type GenericVerifyOptions, type Rect as GeometryRect, type Segment as GeometrySegment, type InfraConnection, type InfraNode, type InfrastructureBuilder, type InfrastructurePreset, type InputChain, type IntentDiscrepancy, type IntentDiscrepancyKind, type JourneyEmotion, type JourneyStep, LABEL_INIT_CLEARANCE, LABEL_INIT_CLEARANCE_DOTTED_FLOW, LABEL_SIZE_TOLERANCE_WORLD, LABEL_TO_PATH_CLEARANCE, LANE_BORDER_CLEARANCE_TOL, LaidDiagram, LaidEdge, LaidNode, type LayoutWithValidationOptions, type LayoutWithValidationResult, MARKER_GLOW_RADIUS, MIN_COLUMN_ALIGNMENT_TOLERANCE, MIN_ROW_ALIGNMENT_TOLERANCE, type MathFnName, type MindBranch, type MindMapBuilder, type MindMapPreset, type MindMapRadialBranch, type MindMapRadialBuilder, type MindMapRadialPreset, NEAR_COLLISION_DEFAULT_MIN, NEAR_COLLISION_POLICY, NODE_FRAME_SELECTOR, type NetworkBuilder, type NetworkDevice, type NetworkDeviceKind, type NetworkLink, type NetworkPreset, NodeKind, type PageLike, type PhaseBuilder, type QuadrantBuilder, type QuadrantItem, type QuadrantPreset, type QuadrantQuadrantLabel, ROW_GAP_VARIANCE_TOL, SPEC_CLEARANCE_POLICY, STAGE_SVG_SELECTOR, type SequenceBuilder, type SequencePreset, type SequenceStep, Side, Signal, type StateMachine2Builder, type StateMachine2Preset, type StateMachineBuilder, type StateMachinePreset, type SweepReport, type SwimlanePreset, TARGET_LABEL_PATH_DIST, Tone, type TopologyBuilder, type TopologyConnection, type TopologyContainer, type TopologyGroupBuilder, type TopologyPreset, type TreeBuilder, type TreeNode, type TreePreset, type UmlClass, type UmlRelation, type UserJourneyBuilder, type UserJourneyPreset, type ValidateOptions, type ValidationProfile, type VerifyOptions, type Violation, type VisualAxis, type VisualValidationReport, WCAG_AA_LARGE, WCAG_AA_NORMAL, assertNever, attachEventHandlers, batch, bboxClearance, bboxDiffWorld, cdlAdapter, chart, classDiagram, compile, computeScrollProgress, computeViewportScale, countEdgeCrossings, createFormulaComputeds, createInputSignals, diagram, effect, er, evaluate as evaluateFormula, extractIdentifiers, flow, flowchart, funnel, gantt, infrastructure, inputDefaultValue, isLargeText, labelInitClearance, layout, layoutWithValidation, mindMap, mindMapRadial, network, parseFormula, pointRectEdgeDistance, pointToSegmentDistance, predictLabelBBoxWorld, predictNodeBBoxWorld, projectEdgeLabel, projectNode, projectPathSegment, pxToWorld, quadrant, rectRectClearance, rectRectOverlapArea, rendersRows, requiredContrastRatio, requiredNearClearance, requiredRowsHeight, requiredRowsWidth, requiredSpecClearance, resolveEdgeLabelOverlapsWithChain, resolveEdgeLabelOverlapsWithChainAndPropagate, resolveOverlapsWithChain, resolveTarget, resolveTargetAll, segmentsIntersect, sequence, stateMachine, stateMachine2, swimlane, topology, tree, untrack, userJourney, validate, verifyAllDiagramsDom, verifyAuthorIntent, verifyAuthorIntentAll, verifyDiagramDom, visualValidate, visualValidateAll, visualValidateLaid, worldToPx };