@cardenelabs/dragon 0.28.0 → 0.30.0

package/src/compile/flow.ts

@@ -0,0 +1,54 @@
+import { diagram, flow } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+import { compileGenericWithAnimate } from "./generic";
+import { 描ける種別 } from "./kinds";
+import { 鎖でつなぐ形か, 鎖に並べる登場人物 } from "./chain";
+import { 箱の題 } from "./node-title";
+import { slugify } from "./slug";
+export function compileFlow(
+  doc: DslDocument,
+  /** 鎖に並べない部品を決める一覧 (#1987) */
+  partsCatalog?: Record<string, CdlDiagram>,
+): CdlDiagram {
+  // v0.4 ... animation あり時 builder 直接経路で複数 phase 注入
+  // **縦列を書いた形は動きの有無に関わらず generic 経路へ** (#1263)。 動く図だけで効かせると、
+  // 同じ記法でも静止図では指定が黙って消える (実測 = 縦列 3 本のはずが 1 本になり知らせも出ない)
+  // **向きを書いた形も generic 経路へ** (#1494)。 静止図の経路は並びを固定で持つので、
+  // ここを通さないと書いた向きが黙って消える (縦列を書いた形と同じ理由)
+  //
+  // 振り分けは行の対応と端の知らせと同じ判定で行う (#1986)
+  if (!鎖でつなぐ形か(doc)) {
+    return compileGenericWithAnimate(doc, { kind: "flow", laneId: "main", laneWidth: 400 });
+  }
+  // 登場人物が 0 人なら枠も作らない。 描画側の `flow()` は枠を必ず 1 つ作るため、 そのまま
+  // 通すと中身の無い枠が残る (実測 = `title` と `type` だけの本文で枠 `flow` が空)。
+  // 枠を持たない図として返す = `swimlane` / `c4` が 0 人で枠 0 になるのと揃う。
+  // 鎖に並べる登場人物で見る = 行に書かれていない部品しか居ない図も枠を作らない (#1987)
+  const 並び = 鎖に並べる登場人物(doc, partsCatalog);
+  if (並び.length === 0) {
+    return diagram(slugify(doc.title), { topic: doc.title, type: "flow" }).build();
+  }
+  // flow preset は actors を順に step として配置、 step 間に edge auto
+  const flowBuilder = flow({
+    id: slugify(doc.title),
+    topic: doc.title,
+  });
+  // 各 actor を step として登録、 edge label は流れ から拾う
+  for (const a of 並び) {
+    // 名前から id を作れない時の番号は、書いた順の番号にする (部品を飛ばしても変わらない)
+    const i = doc.actors.indexOf(a);
+    // 直前の step との edge label = この actor を to に持つ flow から拾う
+    const incomingEdge = doc.flow.find((s) => s.to === a.name);
+    const edgeLabel = incomingEdge?.label;
+    flowBuilder.step(
+      {
+        id: slugify(a.name) || `n${i}`,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      },
+      edgeLabel,
+    );
+  }
+  return flowBuilder.build();
+}

package/src/compile/funnel.ts

@@ -0,0 +1,75 @@
+import { diagram } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+import {
+  parseChartValue,
+  数の欄から参照できる名前,
+  参照する名前,
+  図表の大きさ,
+} from "./chart-fields";
+
+import { 箱の題 } from "./node-title";
+import type { CompileNotice } from "./notice";
+import { slugify } from "./slug";
+import { 図の小見出し } from "./subtitle";
+/**
+ * 漏斗 (`type: funnel`) の組み立て (#1154)。 描画側に 1 つの箱で渡す。
+ *
+ * 登場人物ごとに **数** を読む (`- 訪問: "12000"`)。 段の人数なので負の数は読めない値として扱う。
+ */
+export function compileFunnel(doc: DslDocument, onNotice?: (n: CompileNotice) => void): CdlDiagram {
+  const b = diagram(slugify(doc.title), { topic: doc.title, type: "funnel" });
+  const { w: W, h: H } = 図表の大きさ.funnel;
+  b.lane("chart", { width: W + 64 });
+  const data: NonNullable<CdlDiagram["nodes"][number]["funnelData"]> = [];
+  const 読めない: string[] = [];
+  const 未宣言: string[] = [];
+  const 参照できる = 数の欄から参照できる名前(doc);
+  for (const a of doc.actors) {
+    const v = parseChartValue(a.value ?? a.subtitle);
+    // 段の数なので負に意味が無い (状態を読む欄は符号が決まらないので通す)
+    if (v === null || (typeof v === "number" && v < 0)) {
+      読めない.push(a.name);
+      continue;
+    }
+    // 数にならない参照は落とす (棒 / 折れ線 / 円と同じ扱い)
+    const 名前 = 参照する名前(v);
+    if (名前 !== null && !参照できる.has(名前)) {
+      未宣言.push(a.name);
+      continue;
+    }
+    data.push({ id: slugify(a.name), title: 箱の題(a), count: v });
+  }
+  if (未宣言.length > 0) {
+    const m3 = `type: funnel で数にならない値を参照した項目があります (段に載せません): ${未宣言.join(", ")}。 \`states:\` にその名前を数で書いてください`;
+    onNotice?.({ kind: "chart-value-unreadable", actor: 未宣言[0]!, line: 0, message: m3 });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${m3}`);
+  }
+  if (読めない.length > 0) {
+    const m = `type: funnel で数を読めない項目があります (段に載せません): ${読めない.join(", ")}。 \`- 訪問: "12000"\` の形で書いてください`;
+    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: funnel では矢印を描けません (${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) || "funnel"}-chart`, {
+    lane: "chart",
+    stack: 0,
+    kind: "funnel-stages",
+    title: doc.title,
+    ...図の小見出し(doc),
+    w: W,
+    h: H,
+    funnelData: data,
+  });
+  return b.build();
+}

package/src/compile/gantt.ts

@@ -0,0 +1,232 @@
+import { diagram } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslDocument } from "../types";
+
+import { actorRefTable } from "./actors";
+import { 書いた多重度を読む } from "./er-relation";
+import type { CompileNotice } from "./notice";
+import { slugify } from "./slug";
+import { 箱の題 } from "./node-title";
+import { truncateForMessage, 図の小見出し } from "./subtitle";
+/**
+ * 工程表 (`type: gantt`) の組み立て (#2030 で `compile.ts` から移した)。
+ */
+
+export function compileGantt(doc: DslDocument, onNotice?: (n: CompileNotice) => void): CdlDiagram {
+  const b = diagram(slugify(doc.title), { topic: doc.title, type: "gantt" });
+  const CHART_W = 720;
+  b.lane("gantt", { width: CHART_W });
+
+  /**
+   * 書いたのに効かない形を伝える。 **`console.warn` だけにしない** (#2111) = 編集画面は知らせだけを
+   * 画面に出すため、log だけだと書いている人に理由が見えない。 値の図 (`value-chart.ts`) と同じ形
+   */
+  const 伝える = (種類: CompileNotice["kind"], 名前: string, message: string, line = 0): void => {
+    onNotice?.({ kind: 種類, actor: 名前, line, message });
+    if (typeof console !== "undefined" && console.warn) console.warn(`[dragon] ${message}`);
+  };
+
+  // 目盛りは **書かれた順** に並べる。 以前は `Q1=200 / Q2=600 / ...` の決め打ちで、 Q1-Q4 以外は
+  // 全て同じ位置に落ちていた。 順に並べれば月名でも週番号でも同じ規則で置ける
+  const 目盛り: string[] = [];
+  const 目盛りなし: string[] = [];
+  // 最初に時期を読めなかった項目の行。 画面が案内できるようにする (値の図と同じ)
+  let 目盛りなし行 = 0;
+  const タスク: {
+    name: string;
+    title: string;
+    label: string;
+    line: number;
+    tone?: DslDocument["actors"][number]["tone"];
+    owner?: string;
+    end?: string;
+  }[] = [];
+  for (const a of doc.actors) {
+    const label = (a.value ?? a.subtitle ?? "").trim();
+    if (label === "") {
+      if (目盛りなし.length === 0) 目盛りなし行 = a.pos?.line ?? 0;
+      目盛りなし.push(a.name);
+      continue;
+    }
+    if (!目盛り.includes(label)) 目盛り.push(label);
+    // 色は帯にそのまま渡す。 箱が 1 つになっても、 書いた色が消えないようにする
+    タスク.push({
+      name: a.name,
+      title: 箱の題(a),
+      label,
+      line: a.pos?.line ?? 0,
+      ...(a.tone !== undefined ? { tone: a.tone } : {}),
+      ...(a.owner !== undefined ? { owner: a.owner } : {}),
+      ...(a.end !== undefined ? { end: a.end } : {}),
+    });
+  }
+  if (目盛りなし.length > 0) {
+    伝える(
+      "chart-value-unreadable",
+      目盛りなし[0]!,
+      `type: gantt で時期を読めない項目があります (帯に載せません): ${目盛りなし.join(", ")}。` +
+        ` \`- 設計: "Q1"\` の形で書いてください`,
+      目盛りなし行,
+    );
+  }
+
+  // 矢印は依存として読む (`- 設計 -> 実装` = 実装は設計の後)。 帯どうしを結ぶ線は描画側が
+  // 依存として描くので、 書いた矢印を捨てずに使う
+  const タスク名 = new Set(タスク.map((t) => t.name));
+  // 矢印の端の名前を引く表。 全ての図種に共通の「居ない名前」 の知らせと同じ表を使う
+  const 名前の表 = actorRefTable(doc);
+  const 依存元 = new Map<string, string>();
+  for (const s of doc.flow) {
+    const line = s.pos?.line ?? 0;
+    const 矢印 = `${truncateForMessage(s.from)} -> ${truncateForMessage(s.to)}`;
+    if (!タスク名.has(s.from) || !タスク名.has(s.to)) {
+      // `actors` に居ない名前を指す矢印は、全ての図種に共通の知らせ (`flow-actor-missing`) が
+      // 書いた行で伝えている。 ここでも伝えると同じ行に 2 件並ぶ (#2111)
+      if (!名前の表.has(s.from) || !名前の表.has(s.to)) continue;
+      const 時期なし = [s.from, s.to].filter((n) => !タスク名.has(n)).map(truncateForMessage);
+      伝える(
+        "chart-edge-dropped",
+        s.from,
+        `type: gantt で ${矢印} の依存を結べません (${時期なし.join(" / ")} に時期がありません)`,
+        line,
+      );
+      continue;
+    }
+    依存元.set(s.to, s.from);
+    // 帯の依存は「どちらが先か」 だけを持つ。 矢印に書いた文字や色は描けないので伝える。
+    // 多重度もここに含める = 多重度の知らせ (#2107) と同じ行に 2 件並べない
+    const 効かない = [
+      (s.label ?? "") !== "" || (s.sub ?? "") !== "" ? "文字" : "",
+      s.tone !== undefined ? "色" : "",
+      s.style !== undefined ? "線種" : "",
+      書いた多重度を読む(s.cardinality) !== undefined ? "多重度" : "",
+    ].filter((x) => x !== "");
+    if (効かない.length > 0) {
+      伝える(
+        "edge-option-not-honored",
+        s.from,
+        `type: gantt で ${矢印} に書いた ${効かない.join(" / ")} は描けません (工程表の矢印は前後の関係だけを使います)`,
+        line,
+      );
+    }
+  }
+
+  // 高さは件数から決める。 描画側は 1 行 28 以上 + 行間 20 で積み、 上下に 32 / 44 の余白を取る
+  // (`kinds/gantt.tsx`)。 360 の固定だと 8 件目から最後の帯が枠の外に出る (実測 = 8 件で 56 はみ出す)
+  const CHART_H = Math.max(360, 48 * タスク.length + 96);
+
+  b.node(`${slugify(doc.title) || "gantt"}-chart`, {
+    lane: "gantt",
+    stack: 0,
+    kind: "gantt-timeline",
+    title: doc.title,
+    ...図の小見出し(doc),
+    w: CHART_W,
+    h: CHART_H,
+    ganttData: タスク.map((t) => {
+      const idx = 目盛り.indexOf(t.label);
+      const from = 依存元.get(t.name);
+      // 帯の向きの誤りは、その項目を書いた行で伝える
+      const 逆向きを伝える = (名: string, message: string): void =>
+        伝える("gantt-end-before-start", 名, message, t.line);
+      const 終わり = 終わる位置(t.end, idx, 目盛り, t.name, 逆向きを伝える, doc);
+      return {
+        id: slugify(t.name) || t.name,
+        title: t.title,
+        startIdx: idx,
+        endIdx: 終わり.idx,
+        startLabel: t.label,
+        endLabel: 終わり.label ?? t.label,
+        ...(t.owner !== undefined ? { owner: t.owner } : {}),
+        ...(from !== undefined ? { dependsOn: slugify(from) || from } : {}),
+        ...(t.tone !== undefined ? { tone: t.tone } : {}),
+      };
+    }),
+  });
+
+  return b.build();
+}
+
+/**
+ * `{名前}` が指す状態が取りうる値を、記法に書かれた範囲で集める (#1251)。
+ *
+ * 初期値と、段が動かす先 (`tween:` の両端と `set:` の値) を見る。 数として読めない値は
+ * 落とす = 位置として使われないため、下限の判定には関係しない。
+ */
+function 状態が取る値(参照: string, doc: DslDocument): number[] {
+  const 名 = 参照.slice(1, -1);
+  const out: number[] = [];
+  const 数にする = (v: unknown): void => {
+    if (typeof v === "number") {
+      if (Number.isFinite(v)) out.push(v);
+      return;
+    }
+    // **空文字と空白だけの値を数にしない**。 `Number("")` は 0 を返すため、そのままだと
+    // 位置 0 として扱われ、始まりが 1 以降の帯に誤った知らせが出る。 描画側はこの値を
+    // 解けず始まりへ倒すので、警告する相手ではない
+    const 文字 = String(v).trim();
+    if (文字 === "") return;
+    const n = Number(文字);
+    if (Number.isFinite(n)) out.push(n);
+  };
+  for (const st of doc.animate?.states ?? []) if (st.name === 名) 数にする(st.initial);
+  for (const p of doc.animate?.phases ?? []) {
+    for (const t of p.tweens ?? []) {
+      if (t.state !== 名) continue;
+      数にする(t.from);
+      数にする(t.to);
+    }
+    for (const v of p.sets ?? []) if (v.state === 名) 数にする(v.value);
+  }
+  return out;
+}
+
+/**
+ * 工程が終わる位置を決める (#1251)。
+ *
+ * 書かなければ始まりと同じ = 帯が 1 コマ (従来の挙動)。
+ *
+ * `{名前}` を書いたらそのまま渡す。 描画側が状態を解いて位置に直すため、段で帯が伸び縮みする。
+ * その場合 **時期の名前は始まりのものを使う** = 状態が指すのは位置であって時期の名前ではなく、
+ * 帯の端に出す字が段ごとに変わるわけではない。
+ *
+ * 時期の名前を書いたら、その名前の位置に終わる。 書いた名前が目盛りに無い形は始まりと同じに
+ * 倒す = 目盛りは書かれた順に作るため、載っていない名前は位置を持たない。
+ */
+function 終わる位置(
+  end: string | undefined,
+  始まり: number,
+  目盛り: readonly string[],
+  名前: string,
+  伝える: (名: string, message: string) => void,
+  doc: DslDocument,
+): { idx: number | string; label?: string } {
+  if (end === undefined) return { idx: 始まり };
+  if (/^\{\w+\}$/.test(end)) {
+    // **状態が取る値は記法に全部書いてある**。 初期値と、段が動かす先 (`tween:` の両端と
+    // `set:` の値) を集めれば、始まりより前に落ちる値をここで見つけられる。
+    //
+    // 覆えないのは `values:` の式から決まる値だけ = 他の状態から計算されるため、
+    // 段ごとの結果を組み立ての時点では出せない
+    const 低い = 状態が取る値(end, doc).filter((v) => v < 始まり);
+    if (低い.length > 0) {
+      伝える(
+        名前,
+        `type: gantt で ${truncateForMessage(名前)} の終わり (${truncateForMessage(end)}) が始まりより前になる値を取ります (${[...new Set(低い)].join(", ")})。 始まりは ${始まり} 番目です`,
+      );
+    }
+    return { idx: end };
+  }
+  const i = 目盛り.indexOf(end);
+  if (i < 0) return { idx: 始まり };
+  // 始まりより前に終わる帯は描けない。 そのまま渡すと横幅が負になり、帯が始まりの位置から
+  // 左へはみ出す。 始まりと同じに倒して伝える (黙って倒すと「書いたのに 1 コマのまま」 になる)
+  if (i < 始まり) {
+    伝える(
+      名前,
+      `type: gantt で ${truncateForMessage(名前)} の終わり (${truncateForMessage(end)}) が始まりより前です (始まりと同じに倒しました)`,
+    );
+    return { idx: 始まり };
+  }
+  return { idx: i, label: end };
+}

package/src/compile/generic.ts

@@ -0,0 +1,284 @@
+import { diagram } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import { parseFocusEntry } from "../focus";
+import type { DslDocument, DslPhase } from "../types";
+import { 始まりと終わりの決め方 } from "./actors";
+import { 並べる向き, 後ろへ戻る矢印か, type GenericKind } from "./direction";
+import { ERの関係の指定を作る, ERの関係の矢印 } from "./er-relation";
+import { 描ける種別 } from "./kinds";
+import { 書いた縦列に置く } from "./lanes";
+import { 箱の題 } from "./node-title";
+import { slugify } from "./slug";
+/**
+ * 段を持つ図種の共通の組み立て (#2030 で `compile.ts` から移した)。
+ *
+ * `flow` / `swimlane` / `er` / `state` / `topology` の 5 図種が、段を書いた時にここを通る。
+ */
+
+export type GenericOpts = {
+  kind: GenericKind;
+  /** flow / topology は 1 lane に全 actor、 swimlane / state は actor ごと lane */
+  laneId?: string;
+  laneWidth: number;
+};
+
+/**
+ * v0.4 ... 5 preset (flow / swimlane / er / state / topology) 共通 animation compile。
+ * sequence preset と異なり header / footer / step box 構造はない、 シンプルな lane + node + edge 構造。
+ * preset kind ごとに lane 配置と layout を切替。
+ */
+export function compileGenericWithAnimate(doc: DslDocument, opts: GenericOpts): CdlDiagram {
+  const { kind, laneWidth } = opts;
+  const b = diagram(slugify(doc.title), { topic: doc.title, type: kind });
+
+  // lane / node 配置 ... preset kind に応じて切替
+  const actorToNodeId = new Map<string, string>();
+  if (書いた縦列に置く(kind, doc)) {
+    /*
+     * **書いた縦列に置く** (#1263)。 縦列を並べるための入れ物として使う図種でだけ効く。
+     *
+     * 縦列の並びは **`lanes:` に書いた順** を優先する (#1394)。 箱が最初に使った順で
+     * 並べていた間、`lanes:` で左から順に宣言しても箱の書き順で入れ替わっていた
+     * (実測 = 中心を先に書いた放射の図で、左端の縦列が中心の右へ回った)。
+     *
+     * `lanes:` に無い縦列は、これまでどおり箱が使った順で後ろに続ける。
+     */
+    const 使った: string[] = [];
+    for (const a of doc.actors) {
+      const lid = a.lane;
+      if (lid !== undefined && !使った.includes(lid)) 使った.push(lid);
+    }
+    const 書いた順 = doc.lanes ? Object.keys(doc.lanes) : [];
+    const 並び = [
+      ...書いた順.filter((lid) => 使った.includes(lid)),
+      ...使った.filter((lid) => !書いた順.includes(lid)),
+    ];
+    for (const lid of 並び) {
+      b.lane(lid, { width: laneWidth, ...(kind === "topology" ? { contain: true } : {}) });
+    }
+    /*
+     * 段は **書いた番号をそのまま持つ** (#1394)。
+     *
+     * 書き順で 0 から詰め直していた間、`stack: 1` と書いた箱が 0 へ落ちていた。
+     * 決定木のように「同じ高さに並ばない」 ことが図の意味そのものになる形では、
+     * 詰めた瞬間に別の図になる (実測 = 3 段の木の根が 1 段目へ上がった)。
+     *
+     * 書かなかった箱は、その縦列で **空いている一番小さい段** に置く。 単に数え上げると
+     * 書いた番号と重なり、2 つの箱が同じ段に載る。
+     */
+    const 埋まった段 = new Map<string, Set<number>>();
+    const 埋める = (lid: string, stack: number): void => {
+      const 集合 = 埋まった段.get(lid) ?? new Set<number>();
+      集合.add(stack);
+      埋まった段.set(lid, 集合);
+    };
+    for (const a of doc.actors) {
+      if (a.lane !== undefined && a.stack !== undefined) 埋める(a.lane, a.stack);
+    }
+    doc.actors.forEach((a, idx) => {
+      const id = slugify(a.name) || `n${idx}`;
+      actorToNodeId.set(a.name, id);
+      const lid = a.lane!;
+      let stack = a.stack;
+      if (stack === undefined) {
+        stack = 0;
+        const 集合 = 埋まった段.get(lid);
+        while (集合?.has(stack)) stack += 1;
+        埋める(lid, stack);
+      }
+      b.node(id, {
+        lane: lid,
+        stack,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      });
+    });
+  } else if (並べる向き(kind, doc) === "縦") {
+    // 1 lane に全 actor を縦 stack
+    const lid = opts.laneId ?? "main";
+    b.lane(lid, {
+      width: laneWidth,
+      /*
+       * **見出しは自然に縦へ積む図種だけ** (#1494)。
+       *
+       * `direction: 縦` を書いた泳法図がここへ来るようになった。 その図に題を渡すと、図の題が
+       * 縦列の見出しとしてもう 1 度出る (実測 = 「認証の流れ」 が題と見出しの 2 箇所に並んだ)。
+       */
+      ...(kind === "flow" || kind === "topology" ? { label: doc.title } : {}),
+      ...(kind === "topology" ? { contain: true } : {}),
+    });
+    doc.actors.forEach((a, idx) => {
+      const id = slugify(a.name) || `n${idx}`;
+      actorToNodeId.set(a.name, id);
+      b.node(id, {
+        lane: lid,
+        stack: idx,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+      });
+    });
+  } else {
+    // actor ごとに 1 lane (横並び)。 `swimlane` / `er` / `state` の既定と、
+    // `向き: 横` を書いた流れ図がここに来る (#1494)
+    //
+    // **見出しを付けるのは `swimlane` だけ** (#1241)。 3 図種とも箱を 1 つずつ持ち、
+    // その箱が既に名前を描く。 縦列にも同じ名前を渡すと **同じ字が縦に 2 つ並ぶ**
+    // (実測 = 描いた絵に `Alpha` `Beta` が 2 度出る)。
+    //
+    // `swimlane` は縦列そのものが「誰の担当か」 を読ませる図なので見出しが要る。
+    // `er` の縦列は表を並べるための入れ物、 `state` の縦列は状態を並べるための入れ物で、
+    // どちらも読む人に見せる意味を持たない (組立て API 側も見出しを空のまま置く)。
+    const 見出しを付ける = kind === "swimlane";
+    const 決め方2 = 始まりと終わりの決め方(doc);
+    doc.actors.forEach((a, idx) => {
+      const lid = `lane-${slugify(a.name) || idx}`;
+      b.lane(lid, { width: laneWidth, ...(見出しを付ける ? { label: a.name } : {}) });
+      const id = slugify(a.name) || `n${idx}`;
+      actorToNodeId.set(a.name, id);
+      // er は entity、 state は initial/final marker、 swimlane はそのまま actor
+      const isInitial = kind === "state" && 決め方2.始まり(a, idx);
+      const isFinal = kind === "state" && 決め方2.終わり(a, idx);
+      b.node(id, {
+        lane: lid,
+        stack: 0,
+        kind: 描ける種別(a.kind),
+        title: 箱の題(a),
+        ...(isInitial ? { eyebrow: "初期" } : {}),
+        ...(isFinal ? { eyebrow: "最終" } : {}),
+      });
+    });
+  }
+
+  // edge ... flow の各 step を edge として登録
+  //
+  // 解決できない名前の矢印は **落とす** (#1209)。 以前は名前をそのまま id として使っており、
+  // 存在しない node を指す図ができて描画の直前で落ちていた
+  // (実測 = `unknown-ref: edge "e0-v-c" の from "v" が node に存在しません`)。
+  // 書いた人には `flow-actor-missing` の知らせが届く。
+  // 箱の並び。 後ろへ戻る矢印を見分けるために使う (#1260)
+  const 箱の並び = new Map([...actorToNodeId.values()].map((id, i) => [id, i]));
+  const edgeIds: string[] = [];
+  doc.flow.forEach((s, idx) => {
+    // 名前は入口で正規化済 (`canonicalizeFlowActors`)。 ここで slug を受け直すと、
+    // 動きを書いていない図の組み立てと扱いが割れる
+    const fromId = actorToNodeId.get(s.from);
+    const toId = actorToNodeId.get(s.to);
+    if (fromId === undefined || toId === undefined) return;
+    const edgeId = `e${idx}-${fromId}-${toId}`;
+    // ER の多重度は、段の無い図 (`compileEr`) と同じ 1 か所から名前と名前の下の行と両端を作る (#2105)。
+    // 札に `(1:N)` と添えるだけだった間、段を持つ ER 図には端の形が 1 つも付かなかった
+    const 関係 = kind === "er" ? ERの関係の矢印(ERの関係の指定を作る(s)) : undefined;
+    b.edge(fromId, toId, {
+      id: edgeId,
+      label: 関係?.label ?? s.label,
+      ...(後ろへ戻る矢印か(kind, fromId, toId, 箱の並び)
+        ? { routing: "back-detour" as const }
+        : {}),
+      ...(関係?.sub ? { sub: 関係.sub } : {}),
+      ...(関係?.head ? { head: 関係.head } : {}),
+      ...(関係?.tailHead ? { tailHead: 関係.tailHead } : {}),
+      ...(s.sub ? { sub: s.sub } : {}),
+      ...(s.side ? { side: s.side } : {}),
+
+      ...(s.tone ? { tone: s.tone } : {}),
+      ...(s.style ? { style: s.style } : {}),
+    });
+    edgeIds.push(edgeId);
+  });
+
+  // state 登録
+  for (const st of doc.animate?.states ?? []) {
+    b.state(st.name, { initial: st.initial });
+  }
+
+  // phase 注入
+  for (const p of doc.animate?.phases ?? []) {
+    b.phase(
+      slugify(p.name) || p.name,
+      {
+        duration: p.durationMs,
+        title: p.name,
+        body: p.body ?? "",
+      },
+      (pb) => {
+        const activateIds = resolveHighlightGeneric(p, doc, actorToNodeId, edgeIds);
+        if (activateIds.length > 0) {
+          pb.activate(...activateIds);
+        }
+        for (const t of p.tweens ?? []) {
+          pb.tween(t.state, t.from, t.to);
+        }
+        for (const s of p.sets ?? []) {
+          pb.set(s.state, s.value);
+        }
+        if (p.badge) {
+          pb.badge(p.badge);
+        }
+        return pb;
+      },
+    );
+  }
+
+  return b.build();
+}
+
+/**
+ * 5 preset 共通 ... highlight item (actor 名 or "A→B") を node/edge id に解決。
+ * sequence と異なり header/footer/step box はないのでシンプル。
+ */
+export function resolveHighlightGeneric(
+  phase: DslPhase,
+  doc: DslDocument,
+  actorToNodeId: Map<string, string>,
+  edgeIds: string[],
+): string[] {
+  const out: string[] = [];
+  const knownNames = new Set(actorToNodeId.keys());
+  for (const raw of phase.highlight ?? []) {
+    const entry = parseFocusEntry(raw, knownNames);
+    // 矢印あり → edge を特定
+    if (entry.kind === "edge") {
+      const fromId = actorToNodeId.get(entry.from) ?? slugify(entry.from);
+      const toId = actorToNodeId.get(entry.to) ?? slugify(entry.to);
+      // edge id は `e{idx}-{fromId}-{toId}` の形。 末尾一致で見る。
+      // 部分一致で見ると、 名前に `-` を含む箱 (`api-gateway`) の id が別の矢印の id に
+      // 混ざって当たる (実測 = 箱を光らせたい指定で矢印が光った)
+      for (const edgeId of edgeIds) {
+        if (edgeId.endsWith(`-${fromId}-${toId}`)) {
+          out.push(edgeId);
+        }
+      }
+      continue;
+    }
+    // actor 名 → node id。 見つからなければ slug の形でも探す。
+    // 順序図だけが slug を受理する状態にすると、 同じ記述が図種で別の意味になる
+    // (実測 = `api-gateway` が順序図では光り、 流れ図では何も光らなかった)
+    const nodeId = actorToNodeId.get(entry.name) ?? slugLookup(actorToNodeId, entry.name);
+    if (nodeId) {
+      out.push(nodeId);
+    }
+  }
+  return out;
+}
+
+/**
+ * 名前が見つからない時に、 slug の形でも探す。
+ *
+ * 記法は表示名で書くが、 書く人は id の形 (`api-gateway`) で書くこともある。 図種によって
+ * 受理する / しないが分かれると、 同じ記述が別の意味になる。
+ *
+ * 2 つ以上の名前が同じ slug になる時は解決しない。 どちらを指したか決められないため、
+ * 黙ってどちらかを選ぶより光らせない方が書いた人が気付ける。
+ */
+export function slugLookup(
+  byName: ReadonlyMap<string, string>,
+  wanted: string,
+): string | undefined {
+  let hit: string | undefined;
+  for (const [name, id] of byName) {
+    if (slugify(name) !== wanted) continue;
+    if (hit !== undefined) return undefined;
+    hit = id;
+  }
+  return hit;
+}