@cardenelabs/dragon 0.7.0

package/src/relative-pos.ts

@@ -0,0 +1,182 @@
+/**
+ * 位置を他の要素からの相対で書くための解決。
+ *
+ * `位置: Web の右 200` のように、 座標の代わりに「誰の」「どちら側に」「どれだけ離して」 を書く。
+ * 書く人も LLM も座標を知らないので、 数値を当てさせない形を用意する。
+ *
+ * 解決結果は絶対座標 (`posX` / `posY`) で、 座標を直接書いた時と同じ経路を通る。
+ * 書き方が増えるだけで、 効き方は変わらない。
+ *
+ * 座標を決める場所が組み立て側 (`compile.ts`) と画面側 (playground の `overlay-dsl.ts`) の
+ * 2 つあるため、 解決の規則は本 file に 1 つだけ置いて両方から呼ぶ。 片方だけ直すと画面が
+ * 直らない事故を、 規則を共有することで構造的に防ぐ。
+ */
+
+/** 基準からどちら側に置くか。 */
+export type RelativeDirection = "right" | "left" | "above" | "below";
+
+/** 相対で書かれた位置の指定。 */
+export type RelativePos = {
+  /** 基準にする相手の名前。 `actors:` に書かれた名前をそのまま持つ。 */
+  anchor: string;
+  dir: RelativeDirection;
+  /** 相手との間隔。 書かなかった時は `RELATIVE_GAP_DEFAULT`。 */
+  gap?: number;
+};
+
+/** 位置を決めるのに必要な、 基準の中心と大きさ。 */
+export 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 はその間に収まる。
+ * 隣に置いたと読める近さと、 詰まって見えない広さの両方を満たす。
+ */
+export const RELATIVE_GAP_DEFAULT = 160;
+
+/**
+ * 書かれた向きの語。 日本語と英語の両方を受け付ける。
+ *
+ * 項目名が日本語でも英語でもよい (`種類` / `kind`) のと揃える。
+ */
+const DIRECTION_WORDS: Readonly<Record<string, RelativeDirection>> = {
+  右: "right",
+  左: "left",
+  上: "above",
+  下: "below",
+  right: "right",
+  left: "left",
+  above: "above",
+  below: "below",
+};
+
+/**
+ * 間隔として受け付ける数の形。
+ *
+ * 負の数は含めない (向きが裏返るため)。 小数と指数表記は受け付ける。 整数だけに絞ると、
+ * 有効な数を書いたのに「書き方が読めません」 と返す (実測 = `1e2` / `.5` が弾かれた)。
+ */
+const GAP_NUM = String.raw`(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?`;
+
+/**
+ * 日本語の形。 `Web の右` / `Web の右 200` / `Web の右200`。
+ *
+ * 相手の名前は控えめ (`.+?`) に取る。 名前自体が `の右` で終わる場合 (`Aの右 の左`) でも、
+ * 後戻りして末尾の向きを先に確定するため取り違えない。
+ */
+const RE_JA = new RegExp(String.raw`^(.+?)\s*の\s*(右|左|上|下)(?:\s*(${GAP_NUM}))?$`);
+
+/** 英語の形。 `Web right` / `Web right 200`。 向きの前後は空白で区切る。 */
+const RE_EN = new RegExp(String.raw`^(.+?)\s+(right|left|above|below)(?:\s+(${GAP_NUM}))?$`, "i");
+
+/**
+ * `位置:` に書かれた値を相対指定として読む。 相対の形でなければ null。
+ *
+ * 座標の形 (`300,200`) は呼ぶ側が先に判定する。 ここは相対だけを見る。
+ */
+export function parseRelativePos(raw: string): RelativePos | null {
+  const s = raw.trim();
+  if (s === "") return null;
+  const m = s.match(RE_JA) ?? s.match(RE_EN);
+  if (!m) return null;
+  const anchor = m[1]!.trim();
+  if (anchor === "") return null;
+  const dir = DIRECTION_WORDS[m[2]!.toLowerCase()];
+  if (dir === undefined) return null;
+  const gapRaw = m[3];
+  if (gapRaw === undefined) return { anchor, dir };
+  const gap = Number(gapRaw);
+  // 数として読めない間隔は書かなかった扱いにする。 既定の間隔で置く方が、
+  // 図から消えるより書いた人が気付きやすい。
+  return Number.isFinite(gap) ? { anchor, dir, gap } : { anchor, dir };
+}
+
+/**
+ * 相対指定を絶対座標に直す。
+ *
+ * `posX` / `posY` は箱の中心。 間隔は箱の縁と縁の間の距離として扱う。 中心間の距離にすると、
+ * 大きさの違う箱を並べた時に見た目の隙間が揃わない。
+ */
+export function resolveRelativePos(
+  rel: RelativePos,
+  anchor: AnchorBox,
+  target: { w: number; h: number },
+): { posX: number; posY: number } {
+  // 負の間隔は向きを裏返す。 `Web の右 -1000` が Web の左に置かれ、 確かめる側も同じ値で
+  // 期待を作るので矛盾に気付けない (実測 = 右と書いて左に出た)。 間隔は 0 以上として扱う。
+  // 記法から来る値は parser が弾くが、 本関数は公開しているので入口で閉じる
+  const raw = rel.gap ?? RELATIVE_GAP_DEFAULT;
+  const gap = Number.isFinite(raw) && raw >= 0 ? raw : RELATIVE_GAP_DEFAULT;
+  const dx = anchor.w / 2 + gap + target.w / 2;
+  const dy = anchor.h / 2 + gap + target.h / 2;
+  switch (rel.dir) {
+    case "right":
+      return { posX: anchor.cx + dx, posY: anchor.cy };
+    case "left":
+      return { posX: anchor.cx - dx, posY: anchor.cy };
+    case "below":
+      return { posX: anchor.cx, posY: anchor.cy + dy };
+    case "above":
+      return { posX: anchor.cx, posY: anchor.cy - dy };
+  }
+}
+
+/**
+ * 相対指定を解く順番を決める。
+ *
+ * 基準にした相手がまた相対で書かれていることがある (`B は A の右`、 `C は B の右`)。
+ * 先に相手が決まっていないと座標を出せないので、 依存の浅い順に並べ替える。
+ *
+ * 輪になっている分 (`A は B の右`、 `B は A の右`) は解けないため、 順番からは外して
+ * 名前だけを返す。 呼ぶ側が誤りとして扱う。
+ */
+export function orderByDependency(
+  items: ReadonlyArray<{ name: string; rel?: RelativePos }>,
+): { order: string[]; cyclic: string[] } {
+  const relOf = new Map<string, RelativePos>();
+  const known = new Set<string>();
+  for (const it of items) {
+    known.add(it.name);
+    if (it.rel) relOf.set(it.name, it.rel);
+  }
+  const order: string[] = [];
+  const done = new Set<string>();
+  const cyclic = new Set<string>();
+
+  // 再帰にすると基準の連鎖の長さだけ stack を積む。 連鎖の長さは書く人が決めるので
+  // 上限を置けない。 明示的な配列で辿る。
+  for (const it of items) {
+    if (done.has(it.name) || cyclic.has(it.name)) continue;
+    // path は [自分, 基準, 基準の基準, ...] の順に伸びる
+    const path: string[] = [];
+    const onPath = new Set<string>();
+    let cur: string | undefined = it.name;
+    while (cur !== undefined) {
+      if (done.has(cur) || cyclic.has(cur)) break;
+      if (onPath.has(cur)) {
+        // 輪を見つけた。 輪に含まれる分だけを外す。 輪に入る手前の分は解けるので残す
+        for (const n of path.slice(path.indexOf(cur))) cyclic.add(n);
+        break;
+      }
+      path.push(cur);
+      onPath.add(cur);
+      const rel = relOf.get(cur);
+      // 相対で書かれていない、 または相手が居ない = ここで辿り終わり
+      if (rel === undefined || !known.has(rel.anchor)) break;
+      cur = rel.anchor;
+    }
+    // 奥 (基準側) から順に並べる。 基準が先に決まっていないと座標を出せない
+    for (let i = path.length - 1; i >= 0; i -= 1) {
+      const n = path[i]!;
+      if (cyclic.has(n) || done.has(n)) continue;
+      done.add(n);
+      order.push(n);
+    }
+  }
+  return { order, cyclic: [...cyclic] };
+}

package/src/schema.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 するだけ。
+ */
+
+import schemaJson from "./schemas/diagram.json" with { type: "json" };
+
+/**
+ * Dragon DSL JSON Schema (Draft 7)。 Anthropic / OpenAI の tool schema にそのまま注入可能。
+ */
+export const diagramJsonSchema = schemaJson;

package/src/schemas/diagram.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/cardene777/dragon/schemas/diagram.json",
+  "title": "Dragon DSL Diagram",
+  "description": "LLM 向け Dragon DSL の JSON Schema。 Anthropic Claude tool use / OpenAI GPT structured output の schema field に注入して使う。 生成された JSON は jsonToDiagram() に渡して CdlDiagram に変換する。",
+  "type": "object",
+  "required": ["title", "type", "actors", "flow"],
+  "additionalProperties": false,
+  "properties": {
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "図の title (画面上部に表示される見出し)"
+    },
+    "type": {
+      "type": "string",
+      "enum": ["sequence", "flow", "swimlane", "er", "state", "topology", "solidity", "gantt", "class", "pie", "c4", "mind"],
+      "description": "preset type = 図の種類。 sequence (時系列 API 呼び出し) / flow (処理 flow) / swimlane (責務分担 flow) / er (DB schema) / state (状態遷移) / topology (network) / solidity (contract) / gantt (schedule) / class (UML class) / pie (円グラフ) / c4 (architecture) / mind (mind map)"
+    },
+    "actors": {
+      "type": "array",
+      "minItems": 1,
+      "description": "登場人物 (node) の配列。 文字列で name のみ、 または object で kind / subtitle 等を指定。",
+      "items": {
+        "oneOf": [
+          {
+            "type": "string",
+            "description": "actor 名のみ (kind は default 'actor')"
+          },
+          {
+            "type": "object",
+            "required": ["name"],
+            "additionalProperties": false,
+            "properties": {
+              "name": {"type": "string", "minLength": 1, "description": "actor 名 (flow の from / to で参照される)"},
+              "kind": {
+                "type": "string",
+                "description": "node kind。 shape-* を指定して 49 shape 中から選ぶ。 例: 'shape-wallet' / 'shape-smart-contract' / 'shape-cloud' / 'shape-file' / 'actor' (default) / 'function' / 'storage' / 'event' 等"
+              },
+              "subtitle": {"type": "string", "description": "node 下部の補足テキスト"},
+              "eyebrow": {"type": "string", "description": "node 上部の分類ラベル (accent 色)"},
+              "value": {"type": "string", "description": "actor 数値表示 (kind: actor 用)"},
+              "rows": {"type": "array", "items": {"type": "string"}, "description": "storage 内の column 列 (kind: storage 用)"},
+              "lane": {"type": "string", "description": "swimlane / topology で属する lane id"},
+              "stack": {"type": "integer", "minimum": 0, "description": "lane 内の縦位置 (0-based)"},
+              "initial": {"type": "boolean", "description": "state 開始点 (kind: state 用)"},
+              "final": {"type": "boolean", "description": "state 終了点 (kind: state 用)"}
+            }
+          }
+        ]
+      }
+    },
+    "flow": {
+      "type": "array",
+      "description": "step の配列 (矢印で actor 間を繋ぐ)。 sequence では順序が意味を持つ。",
+      "items": {
+        "type": "object",
+        "required": ["from", "to", "label"],
+        "additionalProperties": false,
+        "properties": {
+          "from": {"type": "string", "description": "起点 actor 名"},
+          "to": {"type": "string", "description": "終点 actor 名"},
+          "label": {"type": "string", "description": "矢印上のラベル (関数呼出し名 / メッセージ等)"},
+          "sub": {"type": "string", "description": "ラベル下の補足"},
+          "tone": {"type": "string", "enum": ["accent", "success", "warning", "danger"], "description": "矢印の色調"},
+          "style": {"type": "string", "enum": ["solid", "dashed", "dotted", "dotted-flow"], "description": "矢印の線種"},
+          "guard": {"type": "string", "description": "state 遷移の条件 (kind: state 用)"},
+          "cardinality": {"type": "string", "description": "ER の多重度 (1..N 等、 kind: er 用)"},
+          "labelOffsetX": {"type": "number", "description": "ラベル位置 x 調整"},
+          "labelOffsetY": {"type": "number", "description": "ラベル位置 y 調整"}
+        }
+      }
+    },
+    "animation": {
+      "type": "array",
+      "description": "アニメーション phase 配列。 各 phase で focus 対象を highlight する。 optional。",
+      "items": {
+        "type": "object",
+        "required": ["step"],
+        "additionalProperties": false,
+        "properties": {
+          "step": {"type": "string", "minLength": 1, "description": "phase 名"},
+          "duration": {"type": "number", "minimum": 0.1, "description": "phase 時間 (秒、 default 1.4)"},
+          "focus": {"type": "array", "items": {"type": "string"}, "description": "この phase で active 化する actor 名 or edge 'A -> B' の配列"},
+          "body": {"type": "string", "description": "phase 説明文"},
+          "badge": {"type": "string", "description": "phase 中に表示する badge label"}
+        }
+      }
+    },
+    "viewport": {
+      "type": "object",
+      "description": "全体 canvas サイズ + gap の調整。 optional。",
+      "additionalProperties": false,
+      "properties": {
+        "width": {"type": "number", "minimum": 100},
+        "height": {"type": "number", "minimum": 100},
+        "laneWidth": {"type": "number", "minimum": 100},
+        "gap": {"type": "number", "minimum": 0},
+        "laneGap": {"type": "number", "minimum": 0},
+        "nodeGap": {"type": "number", "minimum": 0},
+        "labelMargin": {"type": "number", "minimum": 0}
+      }
+    },
+    "lanes": {
+      "type": "object",
+      "description": "swimlane / topology で使う lane 宣言。 key = lane id、 value = lane 定義。",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "x": {"type": "number"},
+          "width": {"type": "number", "minimum": 50},
+          "label": {"type": "string"},
+          "contain": {"type": "boolean"},
+          "lifeline": {"type": "boolean"}
+        }
+      }
+    },
+    "groups": {
+      "type": "object",
+      "description": "topology で使う group 宣言。 key = group id、 value = { label, lanes }。",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["lanes"],
+        "additionalProperties": false,
+        "properties": {
+          "label": {"type": "string"},
+          "lanes": {"type": "array", "items": {"type": "string"}, "minItems": 1}
+        }
+      }
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,294 @@
+/**
+ * Text DSL の AST 型定義
+ * docs/cdl/text-dsl-spec.md の文法を AST に変換した中間表現
+ */
+
+import type { NodeKind, Tone, EdgeStyle } from "@cardenelabs/cdl";
+import type { RelativePos } from "./relative-pos";
+
+export type PresetType =
+  | "sequence"
+  | "flow"
+  | "swimlane"
+  | "er"
+  | "state"
+  | "topology"
+  | "solidity"
+  | "gantt"
+  | "class"
+  | "pie"
+  | "c4"
+  | "mind";
+
+export 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 層設計。
+ */
+export 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 として使う予定。
+ */
+export type LayoutMode = "auto" | "manual";
+
+/** トップレベル AST */
+export 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 拡張) */
+export 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 の上書き。
+ */
+export type DslActorNodeOverride = {
+  posX?: number;
+  posY?: number;
+  posW?: number;
+  posH?: number;
+};
+
+/** 流れ (1 行 = 1 step) (v0.5+ ... inline option 拡張) */
+export 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) */
+export 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 専用) */
+export type DslGroup = {
+  id: string;
+  label?: string;
+  lanes: string[]; // 内包する lane id
+  pos: Position;
+};
+
+/** viewport 全体仕様 (v0.5+ top-level viewport section) */
+export 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;
+};
+
+/** アニメーション ブロック */
+export type DslAnimate = {
+  states: DslState[];
+  phases: DslPhase[];
+  pos: Position;
+};
+
+/** 状態宣言 */
+export type DslState = {
+  name: string;
+  initial: number | string;
+  pos: Position;
+};
+
+/** ステップ (phase) */
+export type DslPhase = {
+  name: string;
+  durationMs: number;
+  highlight?: string[]; // active 化対象 (node 名 / edge 名)
+  tweens?: DslTween[]; // state lerp
+  sets?: DslSet[]; // state 即時遷移
+  body?: string;
+  badge?: string;
+  pos: Position;
+};
+
+/** state lerp (遷移) */
+export type DslTween = {
+  state: string;
+  from: number;
+  to: number;
+  pos: Position;
+};
+
+/** state 即時遷移 (切替) */
+export type DslSet = {
+  state: string;
+  value: string | number;
+  pos: Position;
+};
+
+/** Parser error (行番号付き) */
+export type DslError = {
+  line: number;
+  message: string;
+  hint?: string;
+};

package/src/v05/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Text DSL v0.5 public API
+ *
+ * 新 DSL (英語 keyword + 日本語値 quote 必須 + YAML 風 syntax)。
+ * v0.4 (日本語 keyword) は deprecated、 6 ヶ月後削除予定。
+ */
+
+export { parseTextDslV05 } from "./parser";
+export type { V05ParseResult } from "./parser";