@cardenelabs/dragon 0.27.0 → 0.30.0

package/src/compile/placement.ts

@@ -0,0 +1,15 @@
+/**
+ * 置けたかどうかの判定に使う幅 (#2034 で `compile.ts` から移した)。
+ *
+ * **葉に置く** = 配置を確かめる側 (`verifyPlacement` / `applyLayoutOffsets`) と
+ * 部品の取り込み側 (`縦列に置いた部品を揃える`) の両方が読む。 どちらかに置くと、
+ * もう片方から逆向きの取り込みが生まれて輪になる。
+ */
+
+/**
+ * 書いた通りに置けたと見なす誤差。
+ *
+ * 補正が効いた図種では実測 0.0 で一致する。 効かない向き (順序図の縦) は数百ずれるので、
+ * その間で切る。 丸めと配置計算の揺れを吸収する幅として 1 を取る。
+ */
+export const PLACEMENT_TOLERANCE = 1;

package/src/compile/quadrant.ts

@@ -0,0 +1,110 @@
+import { diagram } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+import { 図表の大きさ, 語の欄から参照できる名前 } from "./chart-fields";
+import { 箱の題 } from "./node-title";
+import type { CompileNotice } from "./notice";
+import { slugify } from "./slug";
+import { 図の小見出し } from "./subtitle";
+import { 区画 } from "./word-state";
+/**
+ * 四象限 (`type: quadrant`) の組み立て (#1154)。 描画側に 1 つの箱で渡す。
+ *
+ * 登場人物ごとに **どの区画か** を読む (`- 重複削除: "左上"`)。 使える語は `区画` が持つ。
+ */
+export function compileQuadrant(
+  doc: DslDocument,
+  onNotice?: (n: CompileNotice) => void,
+): CdlDiagram {
+  const b = diagram(slugify(doc.title), { topic: doc.title, type: "quadrant" });
+  const { w: W, h: H } = 図表の大きさ.quadrant;
+  b.lane("chart", { width: W + 64 });
+  const items: NonNullable<CdlDiagram["nodes"][number]["quadrantData"]>["items"] = [];
+  const 読めない: string[] = [];
+  const 参照できる = 語の欄から参照できる名前(doc, 区画);
+  for (const a of doc.actors) {
+    const 語 = (a.value ?? a.subtitle ?? "").trim();
+    const 参照 = 語.match(/^\{(\w+)\}$/);
+    if (参照) {
+      if (!参照できる.has(参照[1]!)) {
+        読めない.push(a.name);
+        continue;
+      }
+      items.push({ id: slugify(a.name), title: 箱の題(a), quadrant: 語 });
+      continue;
+    }
+    const q = 区画.get(語);
+    if (q === undefined) {
+      読めない.push(a.name);
+      continue;
+    }
+    items.push({ id: slugify(a.name), title: 箱の題(a), quadrant: q });
+  }
+  if (読めない.length > 0) {
+    const m = `type: quadrant で区画を読めない項目があります (図に載せません): ${読めない.join(", ")}。 \`- 重複削除: "左上"\` の形で、 ${[...区画.keys()].join(" / ")} のどれかを書いてください`;
+    onNotice?.({ kind: "chart-value-unreadable", actor: 読めない[0]!, line: 0, message: m });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${m}`);
+  }
+  // 矢印は描けない。 書かれていたら伝える (黙って捨てると「書いたのに効かない」 が残る)
+  if (doc.flow.length > 0) {
+    const m2 = `type: quadrant では矢印を描けません (${doc.flow.length} 本を無視しました)。 関係を描くなら type: flow を使ってください`;
+    onNotice?.({
+      kind: "chart-edge-dropped",
+      actor: doc.flow[0]?.from ?? "",
+      line: doc.flow[0]?.pos?.line ?? 0,
+      message: m2,
+    });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${m2}`);
+  }
+  b.node(`${slugify(doc.title) || "quadrant"}-chart`, {
+    lane: "chart",
+    stack: 0,
+    kind: "quadrant-matrix",
+    title: doc.title,
+    ...図の小見出し(doc),
+    w: W,
+    h: H,
+    quadrantData: { ...軸と区画の名前(doc), items },
+  });
+  return b.build();
+}
+
+/** 軸を書かなかった時の名前。 何の軸か分からないため、位置をそのまま出す */
+const 軸の既定 = {
+  xAxis: { left: "小さい", right: "大きい" },
+  yAxis: { bottom: "小さい", top: "大きい" },
+  quadrantLabels: { topLeft: "左上", topRight: "右上", bottomLeft: "左下", bottomRight: "右下" },
+} as const;
+
+/**
+ * 2 軸で仕分ける図の軸と区画の名前を決める (#1251)。
+ *
+ * `axes:` を書かなければ従来どおり位置の名前 (`左上` 等) を出す = 既に描いてある図が動かない。
+ *
+ * 書いたら区画の名前は **軸の名前から決める** (`{上} × {右}`)。 組立て API 側が同じ規則で
+ * 導いており (実測 = `xAxis: {left: "L", right: "R"}` / `yAxis: {bottom: "B", top: "T"}` で
+ * `topLeft: "T × L"`)、 別の規則にすると同じ内容を書いても図が食い違う。
+ *
+ * 片側だけ書いた形では、書かなかった側は既定のままにする。 空文字を渡すと名前の無い軸が描かれる。
+ */
+function 軸と区画の名前(doc: DslDocument): {
+  xAxis: { left: string; right: string };
+  yAxis: { bottom: string; top: string };
+  quadrantLabels: { topLeft: string; topRight: string; bottomLeft: string; bottomRight: string };
+} {
+  if (doc.axes === undefined) return 軸の既定;
+  const left = doc.axes.x?.left ?? 軸の既定.xAxis.left;
+  const right = doc.axes.x?.right ?? 軸の既定.xAxis.right;
+  const bottom = doc.axes.y?.bottom ?? 軸の既定.yAxis.bottom;
+  const top = doc.axes.y?.top ?? 軸の既定.yAxis.top;
+  return {
+    xAxis: { left, right },
+    yAxis: { bottom, top },
+    quadrantLabels: {
+      topLeft: `${top} × ${left}`,
+      topRight: `${top} × ${right}`,
+      bottomLeft: `${bottom} × ${left}`,
+      bottomRight: `${bottom} × ${right}`,
+    },
+  };
+}

package/src/compile/rows.ts

@@ -0,0 +1,40 @@
+/**
+ * 箱に書いた行を読み取る (#2030 で `compile.ts` から移した)。
+ *
+ * `compileC4` と、`compile.ts` に残る v0.5 の拡張の両方が呼ぶ。
+ *
+ * **葉に置く** = どちらかの側に置くと、もう片方から逆向きの取り込みが生まれる。
+ */
+
+/**
+ * 段の目印を読み取る。 目印と、 それを落とした残りの説明を返す (#1098)。
+ *
+ * 目印 (`L1` / `L2` / `L3`) は「どの段に置くか」 を組み立てに伝えるためのもので、 読む人には
+ * 意味を持たない。 段の名前は枠のラベル (`全体の見取り図` 等) が出すので二重でもある。
+ * 読み取ったら説明から落とす = 書いた人が説明として書いた部分だけが箱に出る。
+ *
+ * | 書いた文字 | 段 | 残る説明 |
+ * |---|---|---|
+ * | `"L1"` | 1 | (無し) |
+ * | `"L2: container"` | 2 | `container` |
+ * | `"L1 利用者"` | 1 | `利用者` |
+ * | `"利用者"` | 1 (既定) | `利用者` |
+ *
+ * 目印の直後の区切り (`:` と空白) も落とす。 残さないと `: container` のように区切りだけが
+ * 先頭に残る。 `L2X` のような別の語を目印と読み違えないよう、 数字の直後が英数字でないことを
+ * 条件にする。
+ */
+export function 段を読み取る(subtitle: string | undefined): {
+  段: number;
+  説明: string | undefined;
+} {
+  const 元 = (subtitle ?? "").trim();
+  const m = 元.match(/^L([123])(?![0-9A-Za-z])/i);
+  if (m === null) return { 段: 1, 説明: subtitle };
+  // 目印と、 その直後の区切り (`:` / 全角コロン / 空白) を落とす
+  const 残り = 元
+    .slice(m[0].length)
+    .replace(/^[:：\s]+/, "")
+    .trim();
+  return { 段: Number(m[1]), 説明: 残り === "" ? undefined : 残り };
+}

package/src/compile/sequence.ts

@@ -0,0 +1,226 @@
+import { sequence, sequenceStepId } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+
+import { parseFocusEntry } from "../focus";
+import { 箱の題 } from "./node-title";
+
+import { slugify } from "./slug";
+
+export function compileSequence(doc: DslDocument): CdlDiagram {
+  // v0.3 ... アニメーション 有無で経路を分岐。
+  // 有り = builder 直接経路で state / 複数 phase を注入。
+  /*
+   * **段があっても組み立て器へ渡す** (#1466)。
+   *
+   * 順序図は 1 つの箱が図を丸ごと描く形になり、言づては箱の中の行になった。 段ごとに
+   * 別経路で箱と縦線を組む形 (`compileSequenceWithAnimate`) では、その骨格が出ない。
+   */
+  const seqBuilder = sequence({
+    id: slugify(doc.title),
+    topic: doc.title,
+    /*
+     * 見出しに出すのは **書いた題** (#1466)。 名前は矢印の端として指すためのもので、
+     * `title:` を書いたらそちらを出す (`箱の題`)。 板でも他の図種と同じ規約にする。
+     */
+    actors: doc.actors.map((a) =>
+      a.subtitle ? { name: 箱の題(a), subtitle: a.subtitle } : 箱の題(a),
+    ),
+    ...(doc.bands && doc.bands.length > 0 ? { bands: doc.bands } : {}),
+  });
+  for (const s of doc.flow) {
+    seqBuilder.step({
+      from: s.from,
+      to: s.to,
+      label: s.label,
+      ...(s.sub ? { sub: s.sub } : {}),
+      ...(s.side ? { side: s.side } : {}),
+      ...(s.tone ? { tone: s.tone } : {}),
+      ...(s.style ? { style: s.style } : {}),
+      ...(s.msgKind ? { kind: s.msgKind } : {}),
+    });
+  }
+  const built = seqBuilder.build();
+  const 段 = doc.animate?.phases ?? [];
+  if (段.length === 0) return built;
+  /*
+   * 書いた段を「今どの言づてか」 に読み替える (#1466)。
+   *
+   * 記法は段ごとに光らせる矢印を並べる (`focus: [A -> B, ...]`) が、言づては矢印ではなく
+   * 箱の中の行になった = 光らせる先が無い。 代わりに **その段までに出た言づての番号** を
+   * 状態へ書き、箱がそこまでを描く。 番号の導き方は `段の番号` が持つ。
+   */
+  const 番号 = 段の番号(doc);
+  const 状態名 = sequenceStepId();
+  return {
+    ...built,
+    states: [...built.states, { id: 状態名, initial: "0" }],
+    phases: 段.map((p, i) => {
+      const 番 = 番号[i]!;
+      return {
+        id: `p${i}`,
+        duration: p.durationMs,
+        title: p.name,
+        body: p.body ?? "",
+        activate: [slugify(doc.title)],
+        ...(p.badge ? { badge: p.badge } : {}),
+        /*
+         * **書いた状態の動きも一緒に運ぶ** (#1466)。 板の段は「今どの言づてか」 を状態に
+         * 書くが、記法は同じ段に `遷移:` / `切替:` も書ける。 板の分だけを載せると、
+         * 書いた動きが黙って落ちる (実測で `tweens` が 0 件になっていた)。
+         */
+        sets: [
+          ...(p.sets ?? []).map((x) => ({ stateId: x.state, value: x.value })),
+          { stateId: 状態名, value: 番 },
+        ],
+        tweens: (p.tweens ?? []).map((t) => ({ stateId: t.state, from: t.from, to: t.to })),
+      };
+    }),
+  };
+}
+
+/** 名前が同じ箱を指すか。 書いた名前のほか、 id の形 (`api-gateway`) で書いた指定も受ける */
+function 同じ箱(a: string, b: string): boolean {
+  return a === b || slugify(a) === slugify(b);
+}
+
+type 言づて = { from: string; to: string };
+
+/**
+ * 段の `focus:` を、 言づてが合うかを返す関数にする。 何も書いていない段は `undefined`。
+ *
+ * | 書いたもの | 合う言づて |
+ * |---|---|
+ * | 矢印 `A -> B` | 元が A で先が B |
+ * | 箱の名前 2 つ以上 | 元と先の両方が書いた箱に含まれる |
+ * | 箱の名前 1 つ | 元か先がその箱 |
+ *
+ * 矢印は 1 本ずつ、 箱の名前はまとめて 1 件として扱い、 どれか 1 つに合えば合うとする。
+ *
+ * **矢印を 1 本でも書いた段は、 矢印だけで言づてを選ぶ**。 同じ段に並べた箱の名前は縦線を
+ * 光らせるための指定で、 言づてを選ぶには広すぎる。 `["利用者側 -> 処理側", 利用者側]` の
+ * 箱の名前まで数えると、 利用者側が関わる全ての言づてに合い、 矢印で指した言づてが決まらない
+ * (見本 `websocket` / `retryBackoff` で実測)。
+ */
+function 合い方(
+  focus: readonly string[],
+  箱の名前: ReadonlySet<string>,
+): ((f: 言づて) => boolean) | undefined {
+  const 合う: ((f: 言づて) => boolean)[] = [];
+  const 名前: string[] = [];
+  for (const raw of focus) {
+    const e = parseFocusEntry(raw, 箱の名前);
+    if (e.kind === "edge") 合う.push((f) => 同じ箱(f.from, e.from) && 同じ箱(f.to, e.to));
+    else 名前.push(e.name);
+  }
+  const 矢印がある = 合う.length > 0;
+  if (!矢印がある && 名前.length === 1) {
+    const n = 名前[0]!;
+    合う.push((f) => 同じ箱(f.from, n) || 同じ箱(f.to, n));
+  } else if (!矢印がある && 名前.length >= 2) {
+    const 含む = (x: string) => 名前.some((n) => 同じ箱(x, n));
+    合う.push((f) => 含む(f.from) && 含む(f.to));
+  }
+  return 合う.length === 0 ? undefined : (f) => 合う.some((c) => c(f));
+}
+
+/**
+ * 切り分けの良さ。 前から順に比べ、 大きい方を良いとする。
+ *
+ * [合う言づてを 1 通以上持つ段の数, 段に合う言づての数, 合った言づてを置いた段の広さの合計に負号を付けたもの]
+ */
+type 得点 = readonly [number, number, number];
+
+function 上回る(x: 得点, y: 得点): boolean {
+  for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return x[i]! > y[i]!;
+  return false;
+}
+
+/**
+ * 段ごとに、 板が今どの言づてを強調するかを導く (#2133)。
+ *
+ * 板は番号の言づてを強調し、 それより前を描き済みとして残し、 後ろを隠す。
+ *
+ * **言づてを先頭から段の数に切り分ける**。 `focus:` を書いた段ごとに続きの言づてを 1 区間ずつ
+ * 受け持たせ、 次の順で最も良い切り分けを選ぶ。
+ *
+ * 1. 合う言づてを 1 通以上持つ段が多い (どの段も板を進める)
+ * 2. 段に合う言づての数が多い (段が束ねる言づてを、 束ねた段に置く)
+ * 3. 両方の段に合う言づてを、 狭く指した段に置く。 段の広さは、 図の全ての言づてのうち
+ *    その段に合う数
+ * 4. それでも並んだら、 前の段の区間を短くする
+ *
+ * 段の番号は、 その区間で `focus:` に合う最後の言づてにする。 箱の名前で書いた段は複数の
+ * 言づてを束ね、 見本の段の題は束の最後を指している (`[利用者, 認証窓口, DB]` の段の題は 2 通目の
+ * 「照合」)。
+ *
+ * 前の段から順に「合う最初の言づて」 を取る形では、 次の 3 つを同時に解けない。
+ *
+ * | 形 | 段の `focus:` | 起きること | 決める順 |
+ * |---|---|---|---|
+ * | 見本 `cacheReadThrough` (直す前) | `[利用者側, API, 一時置き場, DB]` → `[API, 一時置き場]` | 次の段が 2 通目 (探す) を先に取り、 前の段が 1 通目で止まる | 2 |
+ * | 見本 `rateLimit` | `[利用者側, 流量制限, API]` → `[利用者側, 流量制限]` | 5 通目は両方に合う。 前の段が取ると、 次の段の題「超過」 の前の要求が前の段で出る | 3 |
+ * | まとめの段 | `[C -> A]` → `[A -> B, B -> C, C -> A]` | 3 通目は両方に合う。 まとめの段が取ると `C -> A` の段が進まない | 3 |
+ *
+ * **合う言づてが無い段は前の段の番号を保つ**。 見出しだけの段や、 描いた矢印をまとめて並べる
+ * 段で板が 0 へ巻き戻らないようにする。
+ *
+ * 以前は「元 -> 先」 の組から番号を引く表だけを持っていた。 箱の名前は表に無いので全ての段が
+ * 0 になり (カタログの見本 30 件のうち 26 件)、 同じ組の言づてが複数あると表が最後の番号で
+ * 上書きされて、 最初の段で最後の言づてまで飛んでいた (3 件)。
+ */
+export function 段の番号(doc: DslDocument): number[] {
+  const 段 = doc.animate?.phases ?? [];
+  const 箱の名前 = new Set(doc.actors.map((a) => a.name));
+  const 合う = 段.map((p) => 合い方(p.highlight ?? [], 箱の名前));
+  const 対象 = 合う.flatMap((c, k) => (c ? [k] : []));
+  const n = doc.flow.length;
+  const m = 対象.length;
+
+  // 累計[t][i] = 対象 t の段に、 先頭から i 通のうち何通が合うか。 累計[t][n] がその段の広さ
+  const 累計 = 対象.map((k) => {
+    const c = 合う[k]!;
+    const a = [0];
+    doc.flow.forEach((f, i) => a.push(a[i]! + (c(f) ? 1 : 0)));
+    return a;
+  });
+
+  // 最良[t][a] = 対象 t 以降の段で a 通目以降を切り分けた時の最良。 切れ目[t][a] = 対象 t の区間の終わり
+  const 最良: 得点[][] = Array.from({ length: m + 1 }, () => Array<得点>(n + 1).fill([0, 0, 0]));
+  const 切れ目: number[][] = Array.from({ length: m }, () => Array<number>(n + 1).fill(n));
+  for (let t = m - 1; t >= 0; t--) {
+    const 広さ = 累計[t]![n]!;
+    for (let a = 0; a <= n; a++) {
+      // 最後の段は残りを全て受け持つ。 短い区間から試し、 上回った時だけ置き換える (並んだら短い方)
+      for (let b = t === m - 1 ? n : a; b <= n; b++) {
+        const 数 = 累計[t]![b]! - 累計[t]![a]!;
+        const 次 = 最良[t + 1]![b]!;
+        const s: 得点 = [(数 > 0 ? 1 : 0) + 次[0], 数 + 次[1], -数 * 広さ + 次[2]];
+        if (b === (t === m - 1 ? n : a) || 上回る(s, 最良[t]![a]!)) {
+          最良[t]![a] = s;
+          切れ目[t]![a] = b;
+        }
+      }
+    }
+  }
+
+  const 番号 = new Map<number, number>();
+  let a = 0;
+  for (let t = 0; t < m; t++) {
+    const b = 切れ目[t]![a]!;
+    const c = 合う[対象[t]!]!;
+    for (let j = b - 1; j >= a; j--) {
+      if (c(doc.flow[j]!)) {
+        番号.set(対象[t]!, j);
+        break;
+      }
+    }
+    a = b;
+  }
+
+  let 今 = 0;
+  return 段.map((_, k) => {
+    今 = 番号.get(k) ?? 今;
+    return 今;
+  });
+}

package/src/compile/slug.ts

@@ -0,0 +1,29 @@
+/**
+ * 名前から id を作る (#2030 で `compile.ts` から移した)。
+ *
+ * この repo で最も広く使われる小道具で、組み立ての全域から 37 箇所が呼ぶ。
+ *
+ * **葉に置く** = ここが他の file を 1 つも取り込まないことで、どこから呼んでも取り込みの輪が
+ * できない。 図種ごとの file と `compile.ts` の両方が呼ぶため、どちらかの側に置くと
+ * もう片方から逆向きの取り込みが生まれる。
+ */
+
+/** id の長さの上限。 これを超える名前は切り詰める */
+export const ID_MAX = 64;
+
+/**
+ * 名前を id に直す。
+ *
+ * 英数字と日本語と `-` `_` だけを残し、それ以外は `-` にまとめる。 前後の `-` は落とす。
+ * 何も残らなければ `n` を返す = 空の id は図の参照先にできないため。
+ */
+export function slugify(s: string): string {
+  return (
+    s
+      .toLowerCase()
+      .normalize("NFKC")
+      .replace(/[^a-z0-9ぁ-んァ-ヶ一-龯\-_]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, ID_MAX) || "n"
+  );
+}

package/src/compile/solidity.ts

@@ -0,0 +1,39 @@
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+import { compileSequence } from "./sequence";
+/**
+ * Solidity 専用 preset。
+ *
+ * 設計:
+ * - actors を kind=contract / eoa / multisig 等で配置 (EOA は左、 contract は中央、 storage は右など layered layout)
+ * - flow は function call の sequence (msg.sender → contract.fn() → internal call → emit event)
+ * - storage 更新は state + rows binding で自動 (kind: storage の actor に rows: ["bal[A]: {balA}", ...])
+ * - event は kind: event の actor を右端に並べ、 emit edge で発火を表現
+ * - revert は tone: error の edge で表現
+ *
+ * sequence preset を base に使い、 Solidity 文脈に最適化した default を載せる:
+ * - default tone: accent (call) / success (emit) / error (revert)
+ * - default style: solid (call) / dotted-flow (state-change)
+ */
+export function compileSolidity(doc: DslDocument): CdlDiagram {
+  // sequence preset と同等構造で組み立てる、 lane 順は eoa / contract / storage / event の優先順で sort
+  const kindOrder: Record<string, number> = {
+    eoa: 0,
+    actor: 0,
+    multisig: 0,
+    signer: 0,
+    wallet: 0,
+    contract: 1,
+    proxy: 1,
+    library: 1,
+    interface: 1,
+    storage: 2,
+    event: 3,
+  };
+  const sorted = [...doc.actors].sort(
+    (a, b) => (kindOrder[a.kind] ?? 5) - (kindOrder[b.kind] ?? 5),
+  );
+  // sorted を doc.actors に上書きしてから sequence preset 経由で compile
+  const sortedDoc: DslDocument = { ...doc, actors: sorted };
+  return compileSequence(sortedDoc);
+}

package/src/compile/state.ts

@@ -0,0 +1,71 @@
+import { stateMachine } from "@cardenelabs/cdl";
+import type { NodeKind } from "@cardenelabs/cdl";
+import { 箱の題 } from "./node-title";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+
+import { compileGenericWithAnimate } from "./generic";
+import { 描ける種別 } from "./kinds";
+
+import { slugify } from "./slug";
+import { 始まりと終わりの決め方 } from "./actors";
+export function compileState(doc: DslDocument): CdlDiagram {
+  // v0.4 ... animation あり時 builder 直接経路 (各 state を lane で配置、 transition を edge)
+  //
+  // **種類を書いた形は動きの有無に関わらず generic 経路へ** (#1450、 #1263 と同じ理由)。
+  // 動く図だけで効かせると、同じ記法でも静止図では指定が黙って消える
+  // (実測 = `kind: mark-start` を書いた箱が `card` になり知らせも出ない)
+  if ((doc.animate && doc.animate.phases.length > 0) || 既定と違う種類を書いた(doc)) {
+    return compileGenericWithAnimate(doc, { kind: "state", laneWidth: 360 });
+  }
+  // stateMachine preset ... actors を state に、 流れ を transition に
+  const fsm = stateMachine({
+    id: slugify(doc.title),
+    topic: doc.title,
+  });
+  const 決め方 = 始まりと終わりの決め方(doc);
+  for (let i = 0; i < doc.actors.length; i++) {
+    const a = doc.actors[i]!;
+    // 書いた `initial:` / `final:` が勝つ。 1 つも書いていなければ順序で決める
+    const initial = 決め方.始まり(a, i);
+    const final = 決め方.終わり(a, i);
+    fsm.state({
+      id: slugify(a.name) || `s${i}`,
+      title: 箱の題(a),
+      ...(initial ? { initial: true } : {}),
+      ...(final ? { final: true } : {}),
+    });
+  }
+  for (const s of doc.flow) {
+    fsm.transition({
+      from: slugify(s.from),
+      to: slugify(s.to),
+      trigger: s.label,
+      ...(s.sub ? { guard: s.sub } : {}),
+      ...(s.tone ? { tone: s.tone } : {}),
+    });
+  }
+  return fsm.build();
+}
+
+/** 状態の図で `stateMachine` preset が全ての箱に使う種類 */
+export const 状態の図の既定の種類: NodeKind = "card";
+
+/**
+ * 状態の図で、既定と違う種類を書いた登場人物がいるか (#1450)。
+ *
+ * `stateMachine` preset は全ての状態を `card` で描くため、書いた `kind:` が黙って消える。
+ * 始点終点の印 (`mark-start` / `mark-end`) を書けるようにするには、書いた形を効かせる必要がある。
+ *
+ * **「書いたか」 だけでは広すぎる**。 記法だけの種類 (`kind: state` 等) は `card` に読み替わり、
+ * preset の出す形と同じになる = 書いても何も変わらないので経路を切り替える理由が無い。
+ * 切り替えると既存の図の id と枠の作りが変わる (実測で golden 8 件が落ちた)。
+ *
+ * 読み替えた後の種類が既定と違う時だけ切り替える。 こうすると「書いたのに効かない」 は消え、
+ * 「書いたが結果が同じ」 は従来の経路に留まる。
+ */
+export function 既定と違う種類を書いた(doc: DslDocument): boolean {
+  return doc.actors.some(
+    (a) => a.kindWritten === true && 描ける種別(a.kind) !== 状態の図の既定の種類,
+  );
+}

package/src/compile/subtitle.ts

@@ -0,0 +1,22 @@
+import type { DslDocument } from "../types";
+/**
+ * 図の小見出しと、知らせに出す字の切り詰め (#2030 で `compile.ts` から移した)。
+ *
+ * 7 図種が小見出しを使う。 切り詰めは知らせを出す全域が使う。
+ */
+
+/**
+ * 図全体を 1 箱にする図種で、 その箱の上に出す小見出しを渡す (#1247)。
+ *
+ * 書かなければ何も渡さない = 従来どおり小見出しは付かない。 `undefined` を明示して渡すと、
+ * 組立て側が「空の小見出しを書いた」 と区別できなくなるので、 項目ごと落とす。
+ */
+export function 図の小見出し(doc: DslDocument): { eyebrow?: string } {
+  return doc.eyebrow === undefined ? {} : { eyebrow: doc.eyebrow };
+}
+
+/** 知らせに載せる値を短く切る。 長い URL をそのまま出すと画面の帯が読めなくなる */
+export function truncateForMessage(v: string): string {
+  const s = v.trim();
+  return s.length <= 40 ? s : `${s.slice(0, 37)}...`;
+}

package/src/compile/swimlane.ts

@@ -0,0 +1,83 @@
+import { swimlane } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+import { compileGenericWithAnimate } from "./generic";
+import { 描ける種別 } from "./kinds";
+import { 書いた縦列に置く } from "./lanes";
+import { 箱の題 } from "./node-title";
+import { slugify } from "./slug";
+export function compileSwimlane(doc: DslDocument): CdlDiagram {
+  // v0.4 ... animation あり時 builder 直接経路 (各 actor 別 lane で配置)
+  // **縦列を書いた形は動きの有無に関わらず generic 経路へ** (#1263)。 動く図だけで効かせると、
+  // 同じ記法でも静止図では指定が黙って消える (実測 = 縦列 3 本のはずが 1 本になり知らせも出ない)
+  // **向きを書いた形も generic 経路へ** (#1494)。 静止図の経路は並びを固定で持つので、
+  // ここを通さないと書いた向きが黙って消える (縦列を書いた形と同じ理由)
+  if (
+    (doc.animate && doc.animate.phases.length > 0) ||
+    書いた縦列に置く("swimlane", doc) ||
+    doc.direction !== undefined
+  ) {
+    return compileGenericWithAnimate(doc, { kind: "swimlane", laneWidth: 400 });
+  }
+  // swimlane preset は lane 配置 + 自由 node/edge。
+  // v0.2 では actors を lane 化、 流れ の各 step から node を生成、 edge を引く。
+  const swim = swimlane({
+    id: slugify(doc.title),
+    topic: doc.title,
+    lanes: doc.actors.map((a) => a.name),
+  });
+
+  // 各 step で from / to の node を lane 内 stack 配置
+  const placedNodes = new Set<string>();
+  const laneStackCount = new Map<string, number>();
+  let edgeIdx = 0;
+
+  for (const s of doc.flow) {
+    for (const actorName of [s.from, s.to]) {
+      if (placedNodes.has(actorName)) continue;
+      const laneId = swim.laneId(actorName);
+      const actor = doc.actors.find((a) => a.name === actorName);
+      const stack = laneStackCount.get(laneId) ?? 0;
+      const nodeId = slugify(actorName) || `n${placedNodes.size}`;
+      swim.node(nodeId, {
+        lane: laneId,
+        stack,
+        kind: 描ける種別(actor?.kind),
+        title: actorName,
+      });
+      laneStackCount.set(laneId, stack + 1);
+      placedNodes.add(actorName);
+    }
+    const fromId = slugify(s.from);
+    const toId = slugify(s.to);
+    swim.edge(fromId, toId, {
+      id: `e${edgeIdx++}-${fromId}-${toId}`,
+      label: s.label,
+      ...(s.sub ? { sub: s.sub } : {}),
+      ...(s.side ? { side: s.side } : {}),
+
+      ...(s.tone ? { tone: s.tone } : {}),
+      ...(s.style ? { style: s.style } : {}),
+    });
+  }
+
+  // **箱が 1 つも置けなかった時は、 登場人物をそのまま置く** (#1219)。
+  //
+  // この図種は矢印の端から箱を作るため、 矢印が 1 本も無いと箱が 0 件になり `compile` が
+  // 落ちる (実測 = 矢印を書かない図は本 Issue の前から落ちていた)。 解決できない矢印を
+  // 外すと同じ形になるので、 受け皿を置く。
+  //
+  // **1 つでも置けた時は触らない**。 矢印に出てこない登場人物にも箱を置くと、 今まで枠だけ
+  // だった所に箱が増えて既存の図の見た目が変わる (それを変えるかは別の判断)。
+  if (placedNodes.size === 0) {
+    doc.actors.forEach((a, i) => {
+      swim.node(slugify(a.name) || `n${i}`, {
+        lane: swim.laneId(a.name),
+        stack: 0,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      });
+    });
+  }
+  return swim.build();
+}