@cardenelabs/dragon 0.7.0

package/dist/index.d.cts

@@ -0,0 +1,1451 @@
+import { NodeKind, Tone, EdgeStyle, CdlDiagram, LaidDiagram } from '@cardenelabs/cdl';
+
+/**
+ * 位置を他の要素からの相対で書くための解決。
+ *
+ * `位置: Web の右 200` のように、 座標の代わりに「誰の」「どちら側に」「どれだけ離して」 を書く。
+ * 書く人も LLM も座標を知らないので、 数値を当てさせない形を用意する。
+ *
+ * 解決結果は絶対座標 (`posX` / `posY`) で、 座標を直接書いた時と同じ経路を通る。
+ * 書き方が増えるだけで、 効き方は変わらない。
+ *
+ * 座標を決める場所が組み立て側 (`compile.ts`) と画面側 (playground の `overlay-dsl.ts`) の
+ * 2 つあるため、 解決の規則は本 file に 1 つだけ置いて両方から呼ぶ。 片方だけ直すと画面が
+ * 直らない事故を、 規則を共有することで構造的に防ぐ。
+ */
+/** 基準からどちら側に置くか。 */
+type RelativeDirection = "right" | "left" | "above" | "below";
+/** 相対で書かれた位置の指定。 */
+type RelativePos = {
+    /** 基準にする相手の名前。 `actors:` に書かれた名前をそのまま持つ。 */
+    anchor: string;
+    dir: RelativeDirection;
+    /** 相手との間隔。 書かなかった時は `RELATIVE_GAP_DEFAULT`。 */
+    gap?: number;
+};
+/** 位置を決めるのに必要な、 基準の中心と大きさ。 */
+type AnchorBox = {
+    cx: number;
+    cy: number;
+    w: number;
+    h: number;
+};
+/**
+ * 間隔を書かなかった時の既定値。
+ *
+ * 8 図種 × 4 向きで間隔を変えながら、 cdl が出す近すぎ系の指摘の数を数えて決めた。
+ * 100 で 17 件、 130 で 10 件、 140 で 4 件と減り、 160 で 2 件に落ちて以降は変わらない。
+ * 残る 2 件は間隔と無関係な指摘なので、 減らなくなる 160 を既定にする。
+ *
+ * 自動配置が空ける隙間も実測では縦 100 / 横 256-406 で、 160 はその間に収まる。
+ * 隣に置いたと読める近さと、 詰まって見えない広さの両方を満たす。
+ */
+declare const RELATIVE_GAP_DEFAULT = 160;
+/**
+ * `位置:` に書かれた値を相対指定として読む。 相対の形でなければ null。
+ *
+ * 座標の形 (`300,200`) は呼ぶ側が先に判定する。 ここは相対だけを見る。
+ */
+declare function parseRelativePos(raw: string): RelativePos | null;
+/**
+ * 相対指定を絶対座標に直す。
+ *
+ * `posX` / `posY` は箱の中心。 間隔は箱の縁と縁の間の距離として扱う。 中心間の距離にすると、
+ * 大きさの違う箱を並べた時に見た目の隙間が揃わない。
+ */
+declare function resolveRelativePos(rel: RelativePos, anchor: AnchorBox, target: {
+    w: number;
+    h: number;
+}): {
+    posX: number;
+    posY: number;
+};
+/**
+ * 相対指定を解く順番を決める。
+ *
+ * 基準にした相手がまた相対で書かれていることがある (`B は A の右`、 `C は B の右`)。
+ * 先に相手が決まっていないと座標を出せないので、 依存の浅い順に並べ替える。
+ *
+ * 輪になっている分 (`A は B の右`、 `B は A の右`) は解けないため、 順番からは外して
+ * 名前だけを返す。 呼ぶ側が誤りとして扱う。
+ */
+declare function orderByDependency(items: ReadonlyArray<{
+    name: string;
+    rel?: RelativePos;
+}>): {
+    order: string[];
+    cyclic: string[];
+};
+
+/**
+ * Text DSL の AST 型定義
+ * docs/cdl/text-dsl-spec.md の文法を AST に変換した中間表現
+ */
+
+type PresetType = "sequence" | "flow" | "swimlane" | "er" | "state" | "topology" | "solidity" | "gantt" | "class" | "pie" | "c4" | "mind";
+type Position = {
+    line: number;
+    column?: number;
+};
+/**
+ * canvas pivot (CAR-1693 Phase 1) の DSL 表面 `pos: {x, y}` を保持する型。
+ * auto layout の compute value からの offset (dx, dy) を表す。 element の `layoutPos:` が
+ * undefined なら auto layout の値をそのまま採用 (catalog 100+ backward compat)、 set 済なら
+ * Phase 2 の applyPosOffset pass が offset として適用する。
+ *
+ * naming = DSL 表面 syntax は user 提案 wording (`pos:`) を維持、 内部 AST は既存 `pos: Position`
+ * (source line/column) との collision 回避のため `layoutPos:` に rename する 2 層設計。
+ */
+type LayoutPos = {
+    x: number;
+    y: number;
+};
+/**
+ * diagram-level layout mode (CAR-1693 Phase 1)。 未指定は "auto" default で catalog 100+ は
+ * byte-identical 動作。 "manual" は Phase 4 で drag interaction が「auto layout を skip して
+ * pos: 値をそのまま採用する」 mode として使う予定。
+ */
+type LayoutMode = "auto" | "manual";
+/** トップレベル AST */
+type DslDocument = {
+    title: string;
+    type: PresetType;
+    actors: DslActor[];
+    flow: DslStep[];
+    animate?: DslAnimate;
+    /** v0.5+ 拡張 ... viewport / lanes / groups */
+    viewport?: DslViewport;
+    lanes?: Record<string, DslLane>;
+    groups?: Record<string, DslGroup>;
+    /**
+     * canvas pivot (CAR-1693 Phase 1) diagram-level layout mode。 未指定は "auto" default で
+     * catalog 100+ backward compat。 "manual" は Phase 4 で drag → pos: 保存の完全 manual mode。
+     */
+    layout?: LayoutMode;
+    pos: Position;
+};
+/** 登場人物 (v0.5+ ... inline option 拡張) */
+type DslActor = {
+    name: string;
+    kind: NodeKind;
+    /**
+     * 著者が種類を書いたか。 書かなかった時 `kind` には既定の `actor` が入るため、
+     * `kind` の値だけでは「書いた `actor`」 と「書かなかった」 を区別できない。
+     *
+     * 順序図の名札は小型の箱 (`h: 72`) で作られる。 描画側は `card` に小型用の分岐を持つが
+     * `actor` には無く、 名札の文字が箱の下端をはみ出す。 書いた時だけ種類を名札に載せ、
+     * 書かなかった時は小型に耐える形のまま残すために、 この 2 つを区別する (#1058)。
+     */
+    kindWritten?: boolean;
+    /** v0.5+ inline option */
+    subtitle?: string;
+    eyebrow?: string;
+    value?: string;
+    rows?: string[];
+    lane?: string;
+    stack?: number;
+    initial?: boolean;
+    final?: boolean;
+    /**
+     * 箱の色。 未指定なら種類ごとの既定色。
+     *
+     * 矢印 (`DslStep.tone`) と同じ名前と別名を受け付ける (`成功` / `success` 等)。
+     * 効く種類は cdl 側の 26 種で、 それ以外は指定しても色が変わらない。
+     */
+    tone?: Tone;
+    /**
+     * CAR-1657 parts unified syntax = kind が既存 NODE_KIND_VALID に無い値 (parts identifier 候補)
+     * だった時、 parser は partId に格納して compile 側に委譲する。 compile 時に partsCatalog から
+     * 対応する CdlDiagram を lookup + merge する経路。 partId set 時は kind = "actor" (default) fallback。
+     */
+    partId?: string;
+    /**
+     * `色:` に色番号を書いた時の値。 どの状態に入れるかは組み立て時に決める。
+     *
+     * 色を保持する状態の名前はパーツごとに違う (`bg` / `stFill` / `gFill` / `hue` など 17 種)。
+     * 解析の時点ではパーツの定義を知らないため、 名前を決めずに持っておく。
+     */
+    colorHex?: string;
+    /**
+     * parts state override (partId set 時のみ有効)。 kind + 既存 reserved fields を除いた
+     * inline option の残り (`v: 50` / `count: 100` 等) を state 名 → initial 値 map として保持。
+     * compile 時に parts.states[i].initial を上書きする。
+     */
+    stateOverride?: Record<string, number | string | boolean>;
+    /**
+     * canvas pivot 新 spec (dragon canvas pivot spec §layout-role-conversion)。
+     * user drag / resize で明示的に固定した絶対座標 / サイズ。 4 field set 済なら CDL layout が
+     * 該当 actor 由来 lane / node の位置計算を skip、 posX / posY / posW / posH をそのまま採用する。
+     * 未指定なら従来の auto layout (catalog 100+ backward compat 保証)。
+     */
+    posX?: number;
+    posY?: number;
+    posW?: number;
+    posH?: number;
+    /**
+     * 見本を何倍で描くか (`倍率: 2` / `scale: 2`、 #1026)。 partId set 時のみ有効。
+     *
+     * `大きさ:` (`posW` / `posH`) とは掛け合わさる。 画面側も同じ意味で読むため、
+     * `scale` は状態の名前としては使えない (予約語)。 状態を上書きしたい時は
+     * `state: { scale: 2 }` と明示するか、別の名前を使う。
+     */
+    scale?: number;
+    /**
+     * 倍率として書かれた項目名 (`scale` / `倍率`、 #1026)。
+     *
+     * 値が読めない形 (`scale: x`) と書いていない形を見分けるために持つ。 見本が同じ名前の
+     * 状態を持つ時の知らせ (`scale-reserved`) が、値の読めなさに左右されないようにする。
+     */
+    scaleKeys?: string[];
+    /**
+     * 位置を他の要素からの相対で書いた時の指定 (`位置: Web の右 200`)。
+     *
+     * 組み立ての段階で 1 度配置を計算し、 基準の実座標から `posX` / `posY` に直す。 解決後は
+     * 座標を直接書いた時と同じ経路を通るため、 効き方は書き方によって変わらない。
+     */
+    posRel?: RelativePos;
+    /**
+     * canvas pivot UX 修正 (B1 individual node isolation)。 actor 1 件が生成する複数 sub-node
+     * (sequence の header / spacer / footer / s{N} 等) の中で「特定 sub-node だけを固定 / resize」
+     * するための nested override map。 key = sub-node id 相当の short key (`header` / `footer` /
+     * `spacer` / `s0` 等)、 value = posX/Y/W/H の 4 field。 compile 側は対応 CDL node に単独反映、
+     * 同 actor の他 sub-node は影響を受けない (lane 全体 posX とは独立経路)。
+     */
+    nodes?: Record<string, DslActorNodeOverride>;
+    /**
+     * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` 由来の layout offset。 未指定は auto
+     * layout の compute value そのまま (backward compat)、 set 済なら Phase 2 の applyPosOffset で
+     * (auto x + layoutPos.x, auto y + layoutPos.y) に shift される。 既存 posX/posY (絶対座標) は
+     * 別 mechanism で、 layoutPos は auto layout からの nudge (dx, dy)。
+     */
+    layoutPos?: LayoutPos;
+    pos: Position;
+};
+/**
+ * canvas pivot UX 修正 (B1) = actor 内 sub-node 単位で「絶対座標 / サイズ」 を固定するための
+ * override 値。 全 field optional、 posX / posY が両方 set 済なら CDL 側で該当 sub-node の
+ * auto layout を skip、 明示座標をそのまま採用する。 posW / posH は width / height の上書き。
+ */
+type DslActorNodeOverride = {
+    posX?: number;
+    posY?: number;
+    posW?: number;
+    posH?: number;
+};
+/** 流れ (1 行 = 1 step) (v0.5+ ... inline option 拡張) */
+type DslStep = {
+    no: number;
+    from: string;
+    to: string;
+    label: string;
+    sub?: string;
+    tone?: Tone;
+    style?: EdgeStyle;
+    /** v0.5+ inline option */
+    guard?: string;
+    cardinality?: string;
+    labelOffsetX?: number;
+    labelOffsetY?: number;
+    /**
+     * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` 由来の layout offset。 step の edge
+     * label 位置を auto layout compute から (dx, dy) shift する。 未指定は auto、 set 済は Phase 2 で適用。
+     */
+    layoutPos?: LayoutPos;
+    pos: Position;
+};
+/** lane 宣言 (v0.5+ top-level lanes section) */
+type DslLane = {
+    id: string;
+    x?: number;
+    width?: number;
+    label?: string;
+    contain?: boolean;
+    lifeline?: boolean;
+    /**
+     * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` 由来の layout offset。 lane の x 座標を
+     * auto layout compute から (dx, dy) shift する。 未指定は auto、 set 済は Phase 2 で適用。
+     */
+    layoutPos?: LayoutPos;
+    pos: Position;
+};
+/** group 宣言 (v0.5+ top-level groups section、 topology preset 専用) */
+type DslGroup = {
+    id: string;
+    label?: string;
+    lanes: string[];
+    pos: Position;
+};
+/** viewport 全体仕様 (v0.5+ top-level viewport section) */
+type DslViewport = {
+    width?: number;
+    height?: number;
+    /**
+     * 図全体の倍率 (default 1)。 箱 / 文字 / 線 / 間隔のすべてが等比で拡大縮小される。
+     *
+     * `laneWidth` / `laneGap` / `nodeGap` は **間隔だけ**を動かすため、 箱の大きさは変わらず
+     * 図に占める割合はむしろ下がる。 本 field は cdl 側で座標系ごと拡大するので、
+     * 見た目の比率が完全に保たれる (SVG user unit 固定の font-size も追従する)。
+     */
+    scale?: number;
+    laneWidth?: number;
+    /** 全体 default gap (互換維持、 個別 laneGap / nodeGap / labelMargin の fallback) */
+    gap?: number;
+    /** lanes 間 horizontal gap */
+    laneGap?: number;
+    /** nodes 間 vertical gap within lane */
+    nodeGap?: number;
+    /** edge label 周辺余白 */
+    labelMargin?: number;
+    pos: Position;
+};
+/** アニメーション ブロック */
+type DslAnimate = {
+    states: DslState[];
+    phases: DslPhase[];
+    pos: Position;
+};
+/** 状態宣言 */
+type DslState = {
+    name: string;
+    initial: number | string;
+    pos: Position;
+};
+/** ステップ (phase) */
+type DslPhase = {
+    name: string;
+    durationMs: number;
+    highlight?: string[];
+    tweens?: DslTween[];
+    sets?: DslSet[];
+    body?: string;
+    badge?: string;
+    pos: Position;
+};
+/** state lerp (遷移) */
+type DslTween = {
+    state: string;
+    from: number;
+    to: number;
+    pos: Position;
+};
+/** state 即時遷移 (切替) */
+type DslSet = {
+    state: string;
+    value: string | number;
+    pos: Position;
+};
+/** Parser error (行番号付き) */
+type DslError = {
+    line: number;
+    message: string;
+    hint?: string;
+};
+
+/**
+ * Text DSL parser
+ * 入力: docs/cdl/text-dsl-spec.md 準拠の箇条書きテキスト
+ * 出力: DslDocument AST or DslError[]
+ */
+
+/**
+ * Parser 本体
+ */
+type ParseResult = {
+    ok: true;
+    doc: DslDocument;
+} | {
+    ok: false;
+    errors: DslError[];
+};
+declare function parseTextDsl(src: string): ParseResult;
+
+/**
+ * AST (DslDocument) → 既存 preset API 経由 → LaidDiagram
+ *
+ * v0.3 ... アニメーション ブロック full compile 対応 (sequence preset のみ、 他 preset は v0.4 で順次)
+ *   - state / tween / set / highlight / badge / body を実 phase に注入
+ *   - アニメーション ありなら builder 直接経路 ... preset の標準 phase を置換
+ *   - アニメーション なしは v0.2 と同じく preset 経由
+ *
+ * v0.2 ... 6 preset 全対応 (sequence / flow / swimlane / er / state / topology)
+ */
+
+interface CompileToCdlOpts {
+    /**
+     * CAR-1657 = parts identifier lookup catalog、 caller (CdlEditor / test) が inject。
+     * DslActor.partId が set された actor を検出したら partsCatalog[partId] から CdlDiagram を
+     * lookup + mergePartIntoDiagram で target に統合。 未渡し時は parts kind actor を skip + warn。
+     */
+    partsCatalog?: Record<string, CdlDiagram>;
+    /**
+     * 組み立ての途中で分かった「書いたのに効かなかったこと」 の受け取り口。
+     *
+     * 図は出せるので誤りにはしないが、 黙って捨てると書いた人が理由を追えない。 editor は
+     * これを受けて画面に出す。 判定は組み立て側だけが持ち、 画面側は表示に徹する。
+     */
+    onNotice?: (notice: CompileNotice) => void;
+    /**
+     * edge が DSL のどの行から来たかの受け取り口 (#998)。
+     *
+     * preset によっては書いた step と生成される edge が一致しない (`type: flow` は actor を鎖状に
+     * 繋ぐため `a -> c` と書いても `a -> b` になる)。 edge を起点に本文の行を直す機能は、 この
+     * 対応が無いと別の行を書き換える。
+     *
+     * **対応が取れない edge については呼ばれない**。 「対応が無い」 と「行 0」 を区別するため。
+     */
+    onEdgeSource?: (edgeId: string, line: number) => void;
+}
+/** 図は出せるが書いた通りにならなかった、 という知らせ。 */
+type CompileNotice = {
+    kind: "relative-position-ignored" | "focus-target-missing" | "state-override-rejected" | "external-paint-dropped" | "part-not-drawn" | "scale-reserved";
+    /** 対象の名前。 光らせる相手なら書かれた指定そのまま */
+    actor: string;
+    /** 書かれていた行 */
+    line: number;
+    message: string;
+    hint?: string;
+};
+declare function compileToCdl(doc: DslDocument, opts?: CompileToCdlOpts): CdlDiagram;
+/**
+ * 登場人物ごとの、 図の上での中心と大きさを測る。
+ *
+ * 対応付けは箱に表示される名前で行う。 id を使わない理由は `applyNodeTones` と同じで、
+ * slug の作り方が dragon と cdl で違うため記号を含む名前で一致しない。
+ *
+ * 1 人が複数の箱に分かれる図種 (順序図の上端 / 下端) では、 全部を囲む矩形を返す。
+ * 箱として現れない登場人物は縦列の矩形で代用する。
+ */
+declare function measureActorBoxes(diagram: CdlDiagram, 
+/**
+ * 配置まで済ませた図。 渡すとここでは測り直さない (#1006)。
+ *
+ * 呼出側が既に組み立てているなら、 ここで `layout` を呼ぶと同じ図の配置を 2 度計算する。
+ * 図の規模に比例して重く、 辺 500 本で約 300ms (実測)。
+ * 渡す時は `diagram` と対にする = 別の図の配置を渡すと、 測る位置がずれる。
+ */
+laidHint?: LaidDiagram): Map<string, AnchorBox>;
+/**
+ * この図を取り込んでよいか (#1015)。
+ *
+ * 見るのは **要素数が上限 (`MAX_INPUT_ELEMENTS`) を超えていないこと** だけ。
+ * 超えた図を取り込むと、既定の 400x200 の枠を確保した場所に中身が全て展開される。
+ * 上限を置いた意図 (大きすぎる入力で止まらないようにする) も達成されない。
+ *
+ * **配置計算が通るかは見ない**。 取り込みは lane を張り替えるため、単体では配置計算が
+ * 通らない図でも取り込みは成功する (実測 = 存在しない lane を指す箱を持つ見本が、
+ * 取り込み後は正しい lane に載った)。 配置計算で弾くと、動いている本文が描けなくなる。
+ */
+declare function partIsMeasurable(part: CdlDiagram): boolean;
+/**
+ * 倍率の上限 (#1020)。
+ *
+ * 図枠は数百 world 単位なので、1000 倍で数十万になる。 これを超える倍率は画面上で意味を持たず、
+ * 掛けた先が非有限になる危険だけが残る。
+ */
+declare const MAX_PART_SCALE = 1000;
+/**
+ * 本文に書かれた倍率を、描ける値に直す (#1020 / #1026)。
+ *
+ * 記法は `倍率: -2` も `倍率: 0` も、桁が溢れて `Infinity` になる値も書ける。 置き場所と
+ * 描画で別々に直すと、同じ見本が「置き場所は等倍・画面では消える」 状態になる (実測 =
+ * `scale: 0` が等倍の場所を占めるのに画面には出なかった)。 読んだ時点で直す。
+ *
+ * **画面側と組み立て側の両方から呼ぶ**。 別々に持つと、同じ本文が経路で別の絵になる (#1026)。
+ */
+declare function normalizePartScale(value: number): number;
+/**
+ * `大きさ:` と `倍率:` を合成した最終の伸縮率 (#1026)。
+ *
+ * **上限は合成した後に 1 度だけ掛ける**。 率ごとに掛けると、`大きさ:` 由来 1000 倍と
+ * `倍率: 2` で合わせて 2000 倍になり、1 度だけ掛ける経路 (1000 倍) と食い違う (実測)。
+ *
+ * 基準は `大きさ:` と同じ物差し (縦列の外接矩形と段の送り幅)。 図枠を基準にすると、
+ * 図枠と外接矩形の差のぶんだけ余分に掛かる (実測 = 3 倍と書いて 4.0875 倍になった)。
+ *
+ * 画面側 (重ねて描く時の `transform`) と組み立て側 (取り込む時の伸縮) が同じ値を使う。
+ */
+declare function partScaleFactor(part: CdlDiagram, posW: number | undefined, posH: number | undefined, scale: number | undefined): {
+    x: number;
+    y: number;
+};
+/**
+ * 見本 1 件の狙いの大きさ (#1026)。
+ *
+ * 合成した率を基準に掛けて返す。 取り込み側はこの値から自分で率を出し直すため、
+ * ここで上限を掛けておかないと「見積りは上限どまり・実体は青天井」 になる (実測 =
+ * 見積り 1000 倍に対して実体 10000 倍)。
+ *
+ * 何も書かれていない辺は「狙いなし」 のまま返す。 基準の値を入れると、取り込み側が
+ * 自前で測る外接矩形との差だけ伸縮が掛かってしまう。
+ */
+declare function partTargetSize(part: CdlDiagram, posW: number | undefined, posH: number | undefined, scale: number | undefined): {
+    w: number | undefined;
+    h: number | undefined;
+};
+/**
+ * `大きさ:` を書いた時に、見本を何倍にするか (#1018)。
+ *
+ * 横は縦列の幅、縦は段の数から出す。 どちらも書かなければ 1 倍。
+ *
+ * **縦は「書いた高さにする」 ではなく「段の送り幅の合計に対する倍率」**。 `大きさ: 2000,300` を
+ * 1 段の見本に書くと、横は 2000 になるが縦は 300 ではなく 409 になる (段の送り幅 220 に対して
+ * 300 なので 1.36 倍、それが箱の高さ 300 に掛かる)。 意図した仕様かは怪しいが、既に本文が
+ * この前提で書かれているため変えない。 画面側も同じ規則で拡大する。
+ *
+ * 組み立て側 (`partExtent`) と画面側 (playground) の両方から呼ぶ。 別々に持つと、`大きさ:` を
+ * 書いた見本だけ経路で大きさが変わる。
+ */
+declare function partTargetScale(part: CdlDiagram, targetW?: number, targetH?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * パーツ 1 個が実際に描かれる大きさ (#937)。
+ *
+ * 図枠 (`viewBox`) を返す。 箱の外接矩形 (`partVisualSize`) ではない。 2 つは別物で、
+ * 実測では図枠 525x520 に対し箱 380x400 と余白の分だけ違う。 SVG は図枠を基準に
+ * `preserveAspectRatio` で収めるため、 箱の値を渡すと縮んで描いた大きさと食い違う
+ * (実測 = achievement が箱の値で描くと約 275x275 になった)。
+ *
+ * 箱を持たないパーツ (実体が操作パネルの部品である 17 件) でも図枠は出る。 箱だけを見ると
+ * 1x1 になり、 その値で描くと潰れる。
+ *
+ * ただし **図枠は場所を確保するだけで、図の中に何か描かれることは保証しない**。 上の 17 件は
+ * 図の中に描く部品を持たず、重ねても図には出ない (`partDrawsInDiagram`、#1017)。
+ *
+ * 画面が描く大きさと、 組み立て側の格子が確保する場所の両方がこれを見る。 別々の物差しを
+ * 持っていた頃は、 同じ本文でも通った経路でパーツの位置が変わっていた (#937)。
+ *
+ * 組み立てに失敗する図では、 既定の大きさに落とす (呼出側は catalog を渡すので通常起きない)。
+ */
+declare function partRenderSize(part: CdlDiagram): {
+    w: number;
+    h: number;
+};
+/**
+ * この見本が、図の中に描かれる部品を持っているか (#1017)。
+ *
+ * 見本の中には実体が **操作パネルの部品** (`readouts`) だけのものがある。 配置計算も描画も
+ * `readouts` を図の中では扱わないため、図として重ねても何も出ない。 位置決めのための
+ * 1x1 の箱が 1 つあるだけになる。
+ *
+ * catalog 80 件を測ると、この 2 群は `readouts` の有無で完全に分かれた。
+ * `readouts` を持つ 17 件は箱と図枠の面積比が全件 0.0000 (箱は 1x1)、
+ * 持たない 63 件は最小でも 0.1877。 境目に入る件は無い。
+ *
+ * 判定は面積の閾値ではなく **`readouts` を持ち、かつ箱が図枠に対して極小** の 2 条件で行う。
+ * 閾値だけで見ると、小さい箱を意図して置いた見本を巻き込む。 `readouts` だけで見ると、
+ * 箱も実体も両方持つ見本 (現状 0 件だが作れる) を誤って弾く。
+ *
+ * 測れない図では「持っている」 側に倒す。 弾く側に倒すと、測れないだけの見本が使えなくなる。
+ */
+declare function partDrawsInDiagram(part: CdlDiagram): boolean;
+/**
+ * 図枠の中で、 箱の外接矩形がどこにどれだけの大きさで描かれるか (#1014)。
+ *
+ * `left` / `top` は図枠の左上からの余白、 `w` / `h` は箱の大きさ。 図枠は 1 対 1 で描かれるので、
+ * 画面上の箱の位置は「図枠の左上 + `left`/`top`」 になる。
+ *
+ * 相対で書いた位置 (`位置: Web の右 200`) の間隔は、 見えている箱の縁から測る。 図枠の縁で
+ * 測ると余白のぶんだけ広がる (実測 = 200 と書いて画面では 260 空いた)。 画面側が間隔を解く時に
+ * 図枠ではなくこちらを使うことで、 組み立て側と同じ間隔になる。
+ *
+ * 測れない図では図枠と同じ大きさ・余白 0 を返す。 箱を持たない図でも同じで、 図枠がそのまま
+ * 箱として扱われる。
+ */
+declare function partBoxInFrame(part: CdlDiagram): {
+    w: number;
+    h: number;
+    left: number;
+    top: number;
+};
+/**
+ * パーツ 1 個の箱の外接矩形。
+ *
+ * 図枠 (`partRenderSize`) とは別で、 余白を含まない。 相対指定を解く時の「縁からの距離」 に使う。
+ */
+declare function partVisualSize(part: CdlDiagram, targetW?: number, targetH?: number): {
+    w: number;
+    h: number;
+};
+/**
+ * 位置を書かなかったパーツを格子に並べた時の、 矩形の中心。
+ *
+ * 組み立て側 (`mergePartsFromActors`) と画面側 (playground の overlay) の両方から呼ぶ。
+ * 別々に計算すると、 同じ本文でも経路によってパーツの位置が変わる。
+ *
+ * 列の送り幅は並べる全パーツの最大幅で揃える。 個々の幅で送ると、 幅の違うパーツが混ざった時に
+ * 隣と重なる (実測 = 400 の次に 200 を置くと 280 重なった)。 段の高さも段内の最大高で揃える。
+ * 縦は自分の高さの半分だけ段の上端から下げて、 段内で上端を揃える。
+ *
+ * @param baseNodeCount パーツ以外の箱の数。 既存の図の下から並べ始めるために使う
+ */
+declare function partsGridCenters(baseNodeCount: number, items: ReadonlyArray<{
+    id: string;
+    w: number;
+    h: number;
+}>): Map<string, {
+    cx: number;
+    cy: number;
+}>;
+
+/**
+ * Text DSL v0.5 parser
+ *
+ * 設計方針:
+ * - keyword は英語のみ (title / type / actors / flow / states / animation / step / focus / tween / set / badge)
+ * - 値の日本語は quote 必須 (`title: "API call"` / `step: "request" 1.5s`)
+ * - YAML 風 + 短縮 keyword + 箇条書き構造
+ * - Mermaid 知ってる人にもゼロ学習、 非エンジニアにも直感的
+ *
+ * syntax 例:
+ *
+ *   title: "API call"
+ *   type: sequence
+ *
+ *   actors:
+ *     - Client
+ *     - API: function
+ *     - DB
+ *
+ *   flow:
+ *     - Client -> API: "GET /items"
+ *     - API -> DB: "SELECT" (success)
+ *
+ *   states:
+ *     request_count: 0
+ *     row_count: 0
+ *
+ *   animation:
+ *     - step: "request" 1.5s
+ *       focus: [Client, API]
+ *       tween:
+ *         request_count: 0 -> 1
+ *       badge: "request"
+ *
+ *     - step: "query" 1.5s
+ *       focus: [API, DB]
+ *       tween:
+ *         row_count: 0 -> 20
+ *       badge: "query"
+ *
+ * 出力は v0.4 と同じ DslDocument。 既存 compile.ts で CdlDiagram に変換できる。
+ */
+
+type V05ParseResult = {
+    ok: true;
+    doc: DslDocument;
+} | {
+    ok: false;
+    errors: DslError[];
+};
+/** 受け付ける図種。 記法一覧はここを見る。 */
+declare const PRESET_TYPES: ReadonlySet<PresetType>;
+/**
+ * 受け付ける箱の種類。 描画できる種類 (cdl の `NODE_KINDS`) に、 記法だけが持つ種類を足す。
+ *
+ * 以前は手書きの 31 種だった。 描画できる 90 種のうち 78 種が記法から書けず、 部品名として
+ * 扱われて「そんな部品は無い」 と警告が出るだけだった。 描画側を出所に加えることで
+ * 「描画できるものは書ける」 が成立する。
+ */
+/**
+ * 記法が受理する種類の全体。 これに載っていない種類は見本 (パーツ) の候補になる。
+ *
+ * 画面側が「本文が見本を使っているか」 を判定するのに使う (#1022)。 手書きの一覧を
+ * 別に持つと、種類が増えた時にそちらだけ取り残されて余分な読み込みが起きる。
+ */
+declare const NODE_KIND_VALID: ReadonlySet<string>;
+declare function parseTextDslV05(src: string): V05ParseResult;
+/**
+ * 対応する引用符だけを外す。
+ *
+ * 先頭と末尾を別々に外すと、対応しない形 (`'300,200"`) が中身だけ取り出せてしまう。
+ * 画面側も同じ関数を使う (#1028) = 別々に持つと、片方だけが読める本文ができる。
+ */
+declare function stripQuotes(s: string): string;
+
+/**
+ * Text DSL i18n キーワード一覧
+ * 日本語 / 英語両対応 (大文字小文字無視)
+ */
+
+/** NodeKind 別名 (日本語 → English) */
+declare const NODE_KIND_ALIAS: Record<string, NodeKind>;
+/** Tone 別名 */
+declare const TONE_ALIAS: Record<string, Tone>;
+
+/**
+ * Notation lint (author 向け修正システム)。
+ *
+ * cdl / dragon 記法で書かれた CdlDiagram を rule-based に検査し、
+ * 「もっと良い書き方」 を suggestion として返す純粋関数。 LLM 不要、 rule のみ。
+ *
+ * 検知システム (`check:cdl` / `check:dragon` / `check:kind`) は開発陣向けで
+ * 「実装バグ」 を検出するが、 本 notation-lint は **author 向け** で
+ * 「書き方の癖 / 冗長表現 / 未定義参照 / 空 payload」 等を検出する。
+ *
+ * 使い方:
+ *   import { lintDiagram } from "@cardenelabs/dragon";
+ *   const report = lintDiagram(diagram);
+ *   // report.issues[] = LintIssue[]
+ *   // report.fixed = LintIssue[] のうち自動修正で解消される件
+ *   // report.autoFix(diagram) = 修正済 CdlDiagram
+ *
+ * CLI:
+ *   pnpm dragon-lint apps/playground-spa/src/topics/catalog/presets.cdl.ts
+ */
+
+type LintSeverity = "warn" | "info";
+type LintIssue = {
+    /** rule 識別子 */
+    rule: string;
+    severity: LintSeverity;
+    /** 該当対象 (node id / edge id / diagram id) */
+    target: string;
+    /** 人間向けメッセージ */
+    message: string;
+    /** 修正案 (自動修正可能なら適用後の値、 手動修正必要なら null) */
+    suggestion?: string;
+    /** autoFix() が本 issue を自動解消できるか */
+    autoFixable: boolean;
+};
+type LintReport = {
+    diagramId: string;
+    issues: LintIssue[];
+    /** autoFix() が実際に解消できる issue の数 */
+    autoFixableCount: number;
+};
+/**
+ * 検査対象 diagram の全 rule を実行し LintReport を返す。
+ * 全 rule は純粋 (副作用なし / LLM 呼び出しなし)。
+ */
+declare function lintDiagram(d: CdlDiagram): LintReport;
+/**
+ * lintDiagram で detected な issue のうち autoFixable=true のものを機械的に適用して
+ * 修正済 CdlDiagram を返す。 手動修正必要な issue は残る (次回 lint 時に再検出)。
+ */
+declare function autoFix(d: CdlDiagram): CdlDiagram;
+
+/**
+ * canvas pivot 新 spec 図境界計算 helper (dragon canvas pivot spec §diagram-boundary)。
+ *
+ * 図の bounding box (点線四角) を「構成パーツの外接矩形 + 余白」 で計算する SSOT。
+ * CDL の layout() を呼んで LaidDiagram.viewBox から外接矩形を取得し、 spec 準拠の 20px 余白を加える。
+ *
+ * 用途:
+ *   - dragon editor で drag 中の overlay が「図の中」 に入ったか判定 (spec §4 自動調整発動)
+ *   - dragon renderer で図 hover 時に dashed rect を描画 (spec 項目 4 の視覚 UI)
+ *   - PR-B 以降で drag / resize / snap 判定の base rect として参照
+ */
+
+/** 図境界の padding (SVG unit)、 spec §diagram-boundary で 20 と定めた */
+declare const DIAGRAM_BOUNDARY_PADDING = 20;
+type DiagramBoundingBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * CdlDiagram の外接矩形 + 20px 余白を計算する。
+ * layout() が返す LaidDiagram.viewBox は既に全 element を包む rect (右端 +80 / 下端 +80 の CDL 既定余白付き)。
+ * それにさらに spec 準拠の 20px を加えて figure 判定 buffer とする。
+ */
+declare function computeDiagramBoundingBox(diag: CdlDiagram): DiagramBoundingBox;
+/**
+ * bbox 同士の重なり判定 (dragon canvas pivot spec §4 図内 drag 判定 SSOT)。
+ * user 明示 「1 部でも重なれば中」 = 交差面積 > 0 を判定。
+ */
+declare function rectsOverlap(a: DiagramBoundingBox, b: DiagramBoundingBox): boolean;
+
+/**
+ * 光らせる相手 (`focus:`) の書き方を読む。
+ *
+ * 書き方は 2 通り。 箱の名前 1 つか、 矢印 (`A -> B`) で 2 者を指す形。
+ *
+ * 読み方をここに 1 つだけ置く。 id の形は図種で違う (順序図は縦列の上端 / 下端 / 手順箱、
+ * 流れ図は箱 1 個) ため id への解決は図種ごとに残すが、 「どちらの書き方か」 の判断を
+ * 図種ごとに持つと、 同じ記述が図種によって別の意味になる。
+ *
+ * 以前は図種ごとに判定していて、 順序図と汎用の 2 経路が `-` 1 文字を矢印と見なしていた。
+ * その結果 `api-gateway` のような名前が「api から gateway への矢印」 と読まれ、 順序図では
+ * 光らず、 流れ図では名前に部分一致した別の矢印が光っていた (実測)。
+ */
+/** 光らせる相手の指定。 */
+type FocusEntry = {
+    kind: "edge";
+    from: string;
+    to: string;
+} | {
+    kind: "node";
+    name: string;
+};
+/**
+ * 書かれた 1 件を読む。
+ *
+ * 矢印の両側は 1 文字以上を要求するので、 片側だけの形 (`-> API` / `API ->`) は矢印に
+ * ならず名前として読まれる。
+ *
+ * `knownNames` に一致する名前は矢印より先に名前として読む。 引用符付きで矢印を含む名前
+ * (`"A -> B"`) を書いた箱は実在し得るので、 常に矢印と読むと光らせられない (実測 = 名前が
+ * 一致する箱があるのに何も光らず、 「矢印が流れにありません」 と誤報した)。
+ *
+ * @param knownNames 実在する箱の名前。 渡さない場合は書き方だけで判断する
+ */
+declare function parseFocusEntry(raw: string, knownNames?: ReadonlySet<string>): FocusEntry;
+
+/**
+ * 登場人物 1 人の位置を DSL 本文に書き込む。
+ *
+ * editor の画面で見えている座標を、 そのまま記法に落とすために使う。 書く人は図を見ながら
+ * 数値を決められないので、 今の位置を出発点として渡す経路が要る。
+ *
+ * 記法を知っているのは本 package なので、 本文の書き換えもここに置く。 画面側に置くと
+ * 記法が増えた時に画面側だけが取り残される。
+ *
+ * 書き方は 4 通りあり、 元の形を保ったまま位置だけを差し替える。 形を勝手に揃えると、
+ * 書いた人の見た目が変わって差分が読めなくなる。
+ */
+/** 位置の書き込み結果。 対象が見つからなければ null。 */
+declare function writeActorPosition(src: string, actorName: string, posX: number, posY: number): string | null;
+
+/**
+ * 色として読める値かの判定と、 図から外部参照を落とす処理 (#1004)。
+ *
+ * 図の中の文字列は最終的に SVG の属性になる。 色を塗る位置 (`fill` / `stroke` 等) に
+ * `url(https://example.invalid/x)` が入ると、 図を開いた人の環境からその URL へ要求が飛ぶ。
+ * 書き出した SVG を配布しても同じことが起きる。
+ *
+ * 入口は 1 つではない (状態の上書き / phase の `set` / 画面が直接書く背景色 / 埋め込んだ JSON)。
+ * 入口ごとに塞ぐと 1 つ見落とした時に穴が残るため、 **組み立ての最後に図全体を走査する**
+ * 出口の検査を置く。 入口側の判定 (`isColorValue`) は「正しい図を保つ」 ため、
+ * 出口の検査 (`stripExternalPaint`) は「漏れを塞ぐ」 ための二重の構えになっている。
+ */
+/**
+ * 色として読める値か。
+ *
+ * 状態の値は node の `fill` にそのまま入る。 そのため「色の状態を探す」 判定と
+ * 「上書きを受け入れるか」 の判定は同じ物差しでなければならない。 別々に持つと、
+ * 片方だけ直した時に片方が通してしまう。
+ *
+ * 通すのは 16 進の 3 形 (`#rgb` / `#rrggbb` / `#rrggbbaa`) と、 標準の色名。
+ * 桁数を絞るのは、 `#1234` のような半端な形を色として扱うと描画側の解釈に委ねる範囲が
+ * 広がるため。 見本のすべての色が 3 形に収まることは `parts-color-hex-format.test.ts` が検査している。
+ *
+ * `rgb(...)` / `hsl(...)` は通さない。 括弧を含む形を許すと、 括弧の中身を見る判定が要る。
+ * 見本のどのパーツも使っておらず、 通す理由が無い。
+ */
+declare function isColorValue(v: unknown): v is string;
+/**
+ * 図の外側を指す値か。
+ *
+ * SVG の `url(...)` は図の中の定義 (`url(#gradient-1)`) も指せる。 これは正当な用途なので、
+ * 括弧の中が `#` で始まる形だけを残し、 それ以外を外向きとみなす。
+ *
+ * 空白と大文字小文字は無視する。 `URL( https://... )` のような書き方で判定を抜けられないため。
+ */
+declare function pointsOutside(v: unknown): boolean;
+/** 落とした場所と値。 呼出側が書いた人に知らせるために使う */
+type StrippedPaint = {
+    path: string;
+    value: string;
+};
+/**
+ * 図の中から、 色を塗る位置に入った外部参照を落とす。
+ *
+ * 対象は 2 種類ある。
+ *
+ * - 色を塗る key (`fill` / `stroke` / `bg` 等) の値
+ * - 状態の値 (`states[].initial` と、 phase が状態へ入れる値)。 状態は `{名前}` の形で
+ *   `fill` に差し込まれるため、 色を塗る位置に届く
+ *
+ * 説明文 (`title` / `subtitle` / `value` / `rows`) は対象外。 文字として出るだけで
+ * 属性にはならないため、 URL を書く正当な用途を壊さない。
+ *
+ * 図を直接書き換える (返り値ではなく引数を変える)。 組み立ての最後に 1 度だけ呼ぶ前提。
+ */
+declare function stripExternalPaint(diagram: unknown): StrippedPaint[];
+
+/**
+ * 図を組み立てる前に、 大きすぎる入力を止める (#1005)。
+ *
+ * 組み立てにかかる時間は要素数の 2 乗で伸びる。 実測 (要素だけを並べた形)。
+ *
+ * | 要素 | 組み立て |
+ * |---|---|
+ * | 1,000 | 104ms |
+ * | 2,000 | 346ms |
+ * | 5,000 | 1,647ms |
+ * | 10,000 | 7,622ms |
+ *
+ * 待機 (500ms) の後に同じ流れの中で走るため、 この間 editor は操作を受け付けない。
+ * 貼ってしまうと tab を閉じるまで戻らない。
+ *
+ * 見本 (catalog) は 1 図あたり平均 4 要素、 最も多い file でも平均 7 要素。 実用の規模と
+ * 1 秒の境界 (約 3,000 要素) は桁が 2-3 つ違うため、 上限を置いても正当な図には当たらない。
+ *
+ * 既にある `dom-complexity-budget` (400 要素) とは別物。 あちらは組み立てた**後**に
+ * 「見やすさ」 の観点で警告を出すだけで、 組み立て自体は走る。 こちらは組み立てる**前**に
+ * 「固まらない」 ために止める。 400-2,000 の範囲は従来どおり警告が出て図も描ける。
+ */
+/** 組み立てを止める要素数。 1 秒を明確に下回る水準に置く (2,000 要素で約 350ms) */
+declare const MAX_INPUT_ELEMENTS = 2000;
+/**
+ * 組み立てを止める本文の大きさ (byte)。
+ *
+ * 要素数だけでは、 1 要素に極端に長い文字列を持つ形を捉えられない。 読み取り自体は速い
+ * (10,000 要素 98,936 byte で 2ms) ので、 実用の余裕を大きく取って置く。
+ */
+declare const MAX_INPUT_BYTES: number;
+/** 数えた結果。 超過した時に何がどれだけ超えたかを画面に出すために使う */
+interface InputSize {
+    elements: number;
+    bytes: number;
+}
+/**
+ * 記法の解析結果から要素数を数える。
+ *
+ * 数えるのは組み立ての重さに効くもの = 要素 / 流れ / 段 / 状態 / 段組み。
+ * 図の題名や表示の設定は数に入れない (何件あっても重さが変わらない)。
+ *
+ * **段の中身 (光らせる相手 / 遷移 / 即時変更) も数える**。 段の数だけを見ると、
+ * 1 段に 1,000 件の相手を書いた形が 1 件として通る。 実測ではこの形が組み立ての中で
+ * 約 100 万件に展開され、 呼び出しの深さが上限を超えて落ちた。
+ */
+declare function countDocElements(doc: DslDocument): number;
+/**
+ * 組み立て済みの図から要素数を数える。
+ *
+ * 記法を通らない入口 (本文に埋め込んだ図の定義) 用。 解析結果が無いため、 図の側で数える。
+ *
+ * **段の中身と読み取り部品も数える**。 段を 1 件として数えるだけだと、段の中に 10,000 件の
+ * 光らせる指定を持つ図が「1 要素」 と判定されて素通りする (実測)。 記法側の数え方
+ * (`countDocElements`) は段の中身を足しているので、こちらも揃える。
+ */
+declare function countDiagramElements(diagram: {
+    nodes?: unknown[];
+    edges?: unknown[];
+    lanes?: unknown[];
+    states?: unknown[];
+    phases?: unknown[];
+    readouts?: unknown[];
+    inputs?: unknown[];
+    formulas?: unknown[];
+    scrollTriggers?: unknown[];
+    eventBindings?: unknown[];
+}): number;
+/** 本文の大きさを byte で数える (文字数ではなく実際の大きさ) */
+declare function countBytes(src: string): number;
+/**
+ * 大きすぎる入力なら、 その旨を伝える文を返す。 収まっていれば `null`。
+ *
+ * 投げるのではなく文を返すのは、 呼出側が「誤りとして表示する」 か「別の扱いにする」 かを
+ * 選べるようにするため。
+ *
+ * `bytes` に 0 を渡すと大きさの検査を飛ばす (要素数だけを見たい合流点で使う)。
+ */
+declare function describeOversize(size: InputSize): string | null;
+/**
+ * 本文が大きすぎるなら、 その旨を伝える文を返す。 収まっていれば `null`。
+ *
+ * **読み取る前に呼ぶ**。 要素数の上限は読み取った後にしか分からないため、 巨大な本文を
+ * 渡された時の読み取り自体 (11.9MB で記憶 200MB) を防げない。
+ */
+declare function describeOversizeSource(src: string): string | null;
+
+/**
+ * LLM 向け JSON DSL parser。
+ *
+ * dragon の YAML DSL と 1:1 対応する JSON 記法を提供する。
+ * LLM (Anthropic Claude / OpenAI GPT) が structured output (tool call / response_format)
+ * で確実に生成できるよう、 flat な object array を優先した shape になっている。
+ *
+ * 使い方 (LLM):
+ *   1. `packages/dragon/schemas/diagram.json` の JSON Schema を LLM の tool schema に注入
+ *   2. LLM が JSON を返す
+ *   3. `jsonToDiagram(json)` で CdlDiagram に変換
+ *   4. validation error は throw、 retry loop で LLM に修正させる
+ *
+ * YAML との対応:
+ *   YAML `title: "..."` ⇔ JSON `{title: "..."}`
+ *   YAML `actors: [A, B: kind]` ⇔ JSON `{actors: [{name: "A"}, {name: "B", kind: "storage"}]}`
+ *   YAML `flow: [- A -> B: "label"]` ⇔ JSON `{flow: [{from: "A", to: "B", label: "label"}]}`
+ *   YAML `animation: [step: "..."]` ⇔ JSON `{animation: [{step: "...", duration: 1.4, focus: [...]}]}`
+ */
+
+/**
+ * LLM 向け JSON DSL の入力 shape。 YAML DSL と 1:1 対応、 top-level は flat な object。
+ */
+interface DragonJson {
+    /** 図の title (必須) */
+    title: string;
+    /** preset type (必須): sequence / flow / swimlane / er / state / topology / solidity / gantt / class / pie / c4 / mind */
+    type: PresetType;
+    /** 登場人物 (必須): 文字列 or { name, kind, ... } object */
+    actors: (string | JsonActor)[];
+    /** flow step 配列 (必須): { from, to, label, ... } */
+    flow: JsonStep[];
+    /** animation phase 配列 (optional) */
+    animation?: JsonPhase[];
+    /** viewport (optional): 全体 canvas size / gap */
+    viewport?: {
+        width?: number;
+        height?: number;
+        laneWidth?: number;
+        gap?: number;
+        laneGap?: number;
+        nodeGap?: number;
+        labelMargin?: number;
+    };
+    /** lanes (optional): topology / swimlane preset で使う lane 宣言 */
+    lanes?: Record<string, {
+        x?: number;
+        width?: number;
+        label?: string;
+        contain?: boolean;
+        lifeline?: boolean;
+        /**
+         * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` = auto layout offset。 未指定は
+         * backward compat、 set 済は Phase 2 の applyPosOffset で lane 位置を shift する。
+         */
+        pos?: LayoutPos;
+    }>;
+    /** groups (optional): topology preset で使う group 宣言 */
+    groups?: Record<string, {
+        label?: string;
+        lanes: string[];
+    }>;
+    /**
+     * canvas pivot (CAR-1693 Phase 1) diagram-level layout mode。 "auto" (default) は catalog 100+
+     * backward compat、 "manual" は Phase 4 で drag → pos: 保存の完全 manual mode として使う予定。
+     */
+    layout?: LayoutMode;
+}
+interface JsonActor {
+    name: string;
+    /**
+     * CAR-1657 unified syntax = 既存 NodeKind (28 個) に加えて parts identifier (arc-gauge 等) を
+     * accept する。 未知 kind 値は parts 候補として partId に格納、 compile 側 partsCatalog で解決。
+     * LLM structured output の typing 制約を緩めるため union に string 追加。
+     * `string & {}` = NodeKind の候補を IDE 補完で提示しつつ任意 string も許容する idiom。
+     * 素の `NodeKind | string` は no-redundant-type-constituents に抵触し補完も潰れる (#865)。
+     */
+    kind?: NodeKind | (string & {});
+    subtitle?: string;
+    eyebrow?: string;
+    value?: string;
+    rows?: string[];
+    lane?: string;
+    stack?: number;
+    initial?: boolean;
+    final?: boolean;
+    /**
+     * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` = auto layout offset。 未指定は
+     * backward compat、 set 済は Phase 2 の applyPosOffset で actor 由来 lane / node の位置を shift。
+     */
+    pos?: LayoutPos;
+    /**
+     * CAR-1657 parts state override (kind = parts identifier 時のみ有効)。
+     * LLM JSON DSL では nested 明示 = `{ "state": { "v": 50 } }` が natural、 human 側の
+     * inline 拡散 pattern (`- arc1: { kind: arc-gauge, v: 50 }`) とは記述形式が分岐する
+     * (spec § 2.3 分岐設計、 human = YAML 手書き最適 / LLM = JSON structured 最適)。
+     */
+    state?: Record<string, number | string | boolean>;
+}
+interface JsonStep {
+    from: string;
+    to: string;
+    label: string;
+    sub?: string;
+    tone?: Tone;
+    style?: EdgeStyle;
+    guard?: string;
+    cardinality?: string;
+    labelOffsetX?: number;
+    labelOffsetY?: number;
+    /**
+     * canvas pivot (CAR-1693 Phase 1) DSL 表面 `pos: {x, y}` = edge label offset。 未指定は
+     * backward compat、 set 済は Phase 2 の applyPosOffset で edge label 位置を shift する。
+     */
+    pos?: LayoutPos;
+}
+interface JsonPhase {
+    /** phase name (必須) */
+    step: string;
+    /** duration in seconds (default 1.4) */
+    duration?: number;
+    /** highlight 対象 (actor name / edge "A -> B") */
+    focus?: string[];
+    /** body 説明文 */
+    body?: string;
+    /** badge label */
+    badge?: string;
+}
+/**
+ * JSON DSL error。 line 概念がないため、 field path (JSON pointer style) で位置を示す。
+ */
+interface JsonDslError {
+    path: string;
+    message: string;
+    hint?: string;
+}
+/**
+ * LLM 向け JSON DSL の parse + compile 一発変換。
+ *
+ * @param json - DragonJson shape の object (parsed JSON、 not string)
+ * @returns CdlDiagram (@cardenelabs/cdl の CdlDiagramView 等に渡せる)
+ * @throws Error - validation error + hint 付きの詳細メッセージ、 LLM に retry させるための情報を含む
+ *
+ * @example
+ * const diagram = jsonToDiagram({
+ *   title: "ログインAPI",
+ *   type: "sequence",
+ *   actors: ["User", "API", { name: "DB", kind: "storage" }],
+ *   flow: [
+ *     { from: "User", to: "API", label: "login" },
+ *     { from: "API", to: "DB", label: "SELECT" },
+ *   ],
+ *   animation: [
+ *     { step: "call", duration: 1.4, focus: ["User", "API"] },
+ *   ],
+ * });
+ */
+declare function jsonToDiagram(json: unknown, opts?: {
+    partsCatalog?: Record<string, CdlDiagram>;
+}): CdlDiagram;
+/**
+ * JSON DSL を validate だけ実施 (compile しない)。 error 詳細を配列で取得したい場合に使う。
+ * LLM の structured output の retry loop で、 error path を prompt に注入する用途。
+ */
+declare function validateDragonJson(json: unknown): {
+    ok: true;
+    data: DragonJson;
+} | {
+    ok: false;
+    errors: JsonDslError[];
+};
+
+/**
+ * JSON Schema を TypeScript から使えるように export。
+ *
+ * 使い方 (LLM 呼出):
+ *   import Anthropic from "@anthropic-ai/sdk";
+ *   import { diagramJsonSchema, jsonToDiagram } from "@cardenelabs/dragon";
+ *   const client = new Anthropic();
+ *   const res = await client.messages.create({
+ *     model: "claude-sonnet-5",
+ *     max_tokens: 4096,
+ *     tools: [{ name: "create_diagram", description: "...", input_schema: diagramJsonSchema }],
+ *     messages: [{ role: "user", content: "..." }],
+ *   });
+ *   const diagram = jsonToDiagram(res.content[0].input);
+ *
+ * schema JSON は `packages/dragon/schemas/diagram.json` が SSOT、 本 file は import して再 export するだけ。
+ */
+/**
+ * Dragon DSL JSON Schema (Draft 7)。 Anthropic / OpenAI の tool schema にそのまま注入可能。
+ */
+declare const diagramJsonSchema: {
+    $schema: string;
+    $id: string;
+    title: string;
+    description: string;
+    type: string;
+    required: string[];
+    additionalProperties: boolean;
+    properties: {
+        title: {
+            type: string;
+            minLength: number;
+            description: string;
+        };
+        type: {
+            type: string;
+            enum: string[];
+            description: string;
+        };
+        actors: {
+            type: string;
+            minItems: number;
+            description: string;
+            items: {
+                oneOf: ({
+                    type: string;
+                    description: string;
+                    required?: undefined;
+                    additionalProperties?: undefined;
+                    properties?: undefined;
+                } | {
+                    type: string;
+                    required: string[];
+                    additionalProperties: boolean;
+                    properties: {
+                        name: {
+                            type: string;
+                            minLength: number;
+                            description: string;
+                        };
+                        kind: {
+                            type: string;
+                            description: string;
+                        };
+                        subtitle: {
+                            type: string;
+                            description: string;
+                        };
+                        eyebrow: {
+                            type: string;
+                            description: string;
+                        };
+                        value: {
+                            type: string;
+                            description: string;
+                        };
+                        rows: {
+                            type: string;
+                            items: {
+                                type: string;
+                            };
+                            description: string;
+                        };
+                        lane: {
+                            type: string;
+                            description: string;
+                        };
+                        stack: {
+                            type: string;
+                            minimum: number;
+                            description: string;
+                        };
+                        initial: {
+                            type: string;
+                            description: string;
+                        };
+                        final: {
+                            type: string;
+                            description: string;
+                        };
+                    };
+                    description?: undefined;
+                })[];
+            };
+        };
+        flow: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    from: {
+                        type: string;
+                        description: string;
+                    };
+                    to: {
+                        type: string;
+                        description: string;
+                    };
+                    label: {
+                        type: string;
+                        description: string;
+                    };
+                    sub: {
+                        type: string;
+                        description: string;
+                    };
+                    tone: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    style: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                    };
+                    guard: {
+                        type: string;
+                        description: string;
+                    };
+                    cardinality: {
+                        type: string;
+                        description: string;
+                    };
+                    labelOffsetX: {
+                        type: string;
+                        description: string;
+                    };
+                    labelOffsetY: {
+                        type: string;
+                        description: string;
+                    };
+                };
+            };
+        };
+        animation: {
+            type: string;
+            description: string;
+            items: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    step: {
+                        type: string;
+                        minLength: number;
+                        description: string;
+                    };
+                    duration: {
+                        type: string;
+                        minimum: number;
+                        description: string;
+                    };
+                    focus: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    body: {
+                        type: string;
+                        description: string;
+                    };
+                    badge: {
+                        type: string;
+                        description: string;
+                    };
+                };
+            };
+        };
+        viewport: {
+            type: string;
+            description: string;
+            additionalProperties: boolean;
+            properties: {
+                width: {
+                    type: string;
+                    minimum: number;
+                };
+                height: {
+                    type: string;
+                    minimum: number;
+                };
+                laneWidth: {
+                    type: string;
+                    minimum: number;
+                };
+                gap: {
+                    type: string;
+                    minimum: number;
+                };
+                laneGap: {
+                    type: string;
+                    minimum: number;
+                };
+                nodeGap: {
+                    type: string;
+                    minimum: number;
+                };
+                labelMargin: {
+                    type: string;
+                    minimum: number;
+                };
+            };
+        };
+        lanes: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                type: string;
+                additionalProperties: boolean;
+                properties: {
+                    x: {
+                        type: string;
+                    };
+                    width: {
+                        type: string;
+                        minimum: number;
+                    };
+                    label: {
+                        type: string;
+                    };
+                    contain: {
+                        type: string;
+                    };
+                    lifeline: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        groups: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                type: string;
+                required: string[];
+                additionalProperties: boolean;
+                properties: {
+                    label: {
+                        type: string;
+                    };
+                    lanes: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        minItems: number;
+                    };
+                };
+            };
+        };
+    };
+};
+
+/**
+ * Dragon — Text DSL public API
+ *
+ * Mermaid 感覚で animated SVG を生成する Text DSL。 cdl engine を呼出して CdlDiagram を返す。
+ *
+ * 使い方:
+ *   const diagram = textDslToDiagram(source);
+ *   // diagram は @cardenelabs/cdl の CdlDiagram、 そのまま CdlDiagramView 等に渡せる
+ */
+
+/**
+ * CAR-1657 = compile 時 parts identifier lookup 用 catalog。
+ * caller (CdlEditor 等) が loadPartsItems() の結果を Record<partId, CdlDiagram> で inject。
+ * 未渡し時 partId set actor は「未解決」 として skip + console.warn (diagram render は継続)。
+ */
+interface CompileOpts {
+    partsCatalog?: Record<string, CdlDiagram>;
+    /**
+     * 図は出せるが書いた通りにならなかったことの受け取り口 (`位置: Web の下` が順序図で
+     * 効かない等)。 判定は組み立て側が持ち、 呼出側は受け取って表示するだけにする。
+     */
+    onNotice?: (notice: CompileNotice) => void;
+    /**
+     * edge が DSL のどの行から来たかの受け取り口 (#998)。
+     *
+     * preset によっては書いた step と生成される edge が一致しない (`type: flow` は actor を鎖状に
+     * 繋ぐため `a -> c` と書いても `a -> b` になる)。 edge を起点に本文の行を直す機能 (自動修正の
+     * 書き戻し等) は、 この対応が無いと別の行を書き換える。
+     *
+     * **対応が取れない edge については呼ばれない**。 「対応が無い」 と「行 0」 を区別するため。
+     */
+    onEdgeSource?: (edgeId: string, line: number) => void;
+}
+/**
+ * Dragon DSL から CdlDiagram に一発変換。 v0.5 (英語 keyword) / v0.4 (日本語 keyword) を auto-detect。
+ *
+ * 判定 ... src 内に v0.5 専用 syntax (`animation:` block / `- A -> B` flow / `step: "..."` ) を含むなら v0.5、
+ * 含まなければ v0.4 (deprecated、 console.warn を出す)。
+ *
+ * エラー時は throw、 詳細を取りたい場合は parseTextDslV05 / parseTextDsl を直接呼ぶ。
+ * opts.partsCatalog を渡すと CAR-1657 parts kind (arc-gauge 等) の actor が merge 展開される。
+ */
+declare function textDslToDiagram(src: string, opts?: CompileOpts): CdlDiagram;
+
+export { type AnchorBox, type CompileNotice, type CompileOpts, DIAGRAM_BOUNDARY_PADDING, type DiagramBoundingBox, type DragonJson, type DslActor, type DslAnimate, type DslDocument, type DslError, type DslGroup, type DslLane, type DslPhase, type DslSet, type DslState, type DslStep, type DslTween, type DslViewport, type FocusEntry, type InputSize, type JsonActor, type JsonDslError, type JsonPhase, type JsonStep, type LayoutMode, type LayoutPos, type LintIssue, type LintReport, type LintSeverity, MAX_INPUT_BYTES, MAX_INPUT_ELEMENTS, MAX_PART_SCALE, NODE_KIND_ALIAS, NODE_KIND_VALID, PRESET_TYPES, type PresetType, RELATIVE_GAP_DEFAULT, type RelativeDirection, type RelativePos, TONE_ALIAS, autoFix, compileToCdl, computeDiagramBoundingBox, countBytes, countDiagramElements, countDocElements, describeOversize, describeOversizeSource, diagramJsonSchema, isColorValue, jsonToDiagram, lintDiagram, measureActorBoxes, normalizePartScale, orderByDependency, parseFocusEntry, parseRelativePos, parseTextDsl, parseTextDslV05, partBoxInFrame, partDrawsInDiagram, partIsMeasurable, partRenderSize, partScaleFactor, partTargetScale, partTargetSize, partVisualSize, partsGridCenters, pointsOutside, rectsOverlap, resolveRelativePos, stripExternalPaint, stripQuotes, textDslToDiagram, validateDragonJson, writeActorPosition };