@cardenelabs/dragon 0.28.0 → 0.32.0

package/src/compile/sequence.ts

@@ -0,0 +1,305 @@
+import { sequence, sequenceStepId } from "@cardenelabs/cdl";
+import type { CdlDiagram } from "@cardenelabs/cdl";
+import type { DslActor, DslDocument } from "../types";
+
+import { parseFocusEntry } from "../focus";
+import { 並べ替えた文書 } from "./order";
+import { 箱の題 } from "./node-title";
+
+import { slugify } from "./slug";
+
+export function compileSequence(doc: DslDocument): CdlDiagram {
+  // **書いた並び順を先に当てる** (#2655)。 以降は並べ替え済の箱で組む = 板の見出しも
+  // 端の番号も同じ並びから決まる。 書かなかった図は同じ文書がそのまま返る
+  doc = 並べ替えた文書(doc);
+  // v0.3 ... アニメーション 有無で経路を分岐。
+  // 有り = builder 直接経路で state / 複数 phase を注入。
+  /*
+   * **段があっても組み立て器へ渡す** (#1466)。
+   *
+   * 順序図は 1 つの箱が図を丸ごと描く形になり、言づては箱の中の行になった。 段ごとに
+   * 別経路で箱と縦線を組む形 (`compileSequenceWithAnimate`) では、その骨格が出ない。
+   */
+  /*
+   * **見出しと端の番号を別の組み立てで決める** (#2408)。
+   *
+   * 見出しに出すのは書いた題 (#1466)、 矢印の端と帯は名前で指す (`箱の題` の doc comment)。
+   * 組み立て器は渡された面の名前 1 つから「見出し」 と「端を引く表」 の両方を作るため、
+   * 題を渡すと名前で指した端が 1 度も見つからず、 番号 0 (先頭の面) に倒れる
+   * (実測 = 全ての面に題を付けると、 言づてが全て先頭の面の自分宛てになった)。
+   *
+   * 板の幅と高さは見出しの字幅と言づての文字と件数から決まり、 端の番号には依らない
+   * (組み立て器の `sequenceBoardMetrics`)。 そこで題で組んだ板を土台にし、 端の番号と帯だけを
+   * 名前で組んだ板から写す。 名前は図の中で 1 つに決まるので、 題が重なる図でも番号は正しい。
+   *
+   * 題と名前がどの面でも同じなら 2 回目は組まない = 題を書かない図は組み上がりが変わらない。
+   */
+  const 見出しの板 = 板を組む(doc, 箱の題);
+  const built = doc.actors.some((a) => 箱の題(a) !== a.name)
+    ? 端を写す(見出しの板, 板を組む(doc, (a) => a.name))
+    : 見出しの板;
+  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 })),
+      };
+    }),
+  };
+}
+
+/**
+ * 順序図の板を 1 枚組む。 面の名前として組み立て器へ渡すものだけを `面の名` で差し替える。
+ *
+ * 組み立て器はこの名前から見出しと「端を引く表」 を作る。 言づての端と帯は書いた名前のまま渡す。
+ */
+function 板を組む(doc: DslDocument, 面の名: (a: DslActor) => string): CdlDiagram {
+  const b = sequence({
+    id: slugify(doc.title),
+    topic: doc.title,
+    actors: doc.actors.map((a) =>
+      a.subtitle ? { name: 面の名(a), subtitle: a.subtitle } : 面の名(a),
+    ),
+    ...(doc.bands && doc.bands.length > 0 ? { bands: doc.bands } : {}),
+    ...(doc.sequenceActorForm !== undefined ? { sequenceActorForm: doc.sequenceActorForm } : {}),
+    ...(doc.sequenceLabelForm !== undefined ? { sequenceLabelForm: doc.sequenceLabelForm } : {}),
+    ...(doc.sequenceReturnHead !== undefined ? { sequenceReturnHead: doc.sequenceReturnHead } : {}),
+    ...(doc.sequenceKindLabels !== undefined ? { sequenceKindLabels: doc.sequenceKindLabels } : {}),
+    ...(doc.sequenceRowGap !== undefined ? { sequenceRowGap: doc.sequenceRowGap } : {}),
+    ...(doc.sequenceGutter !== undefined ? { sequenceGutter: doc.sequenceGutter } : {}),
+    ...(doc.sequenceBandWidth !== undefined ? { sequenceBandWidth: doc.sequenceBandWidth } : {}),
+    ...(doc.sequenceSelfLoop !== undefined ? { sequenceSelfLoop: doc.sequenceSelfLoop } : {}),
+  });
+  for (const s of doc.flow) {
+    b.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 = b.build();
+  if (doc.sequenceGutter === undefined || doc.viewport?.width === undefined) return built;
+  const canvasWidth = doc.viewport.width;
+
+  /*
+   * `sequenceGutter` は見本の canvas 原点から最初の糸を決める。cdl の sequence preset は
+   * 板の左右へさらに lane padding を足すため、そのままでは gutter 610 の糸が 25 右へずれ、
+   * 1800 の canvas も 1948 まで広がる。幅を書いた図では lane の左右 25 ずつを除いた幅を
+   * 板へ渡し、layout 後の lane を canvas 幅に揃える。gutter + 列幅 / 2 は板の原点から測る。
+   * 幅を書かない従来図は cdl の自動幅を保つ。
+   */
+  return {
+    ...built,
+    lanes: built.lanes.map((lane) => lane.id === "seq" ? { ...lane, width: canvasWidth } : lane),
+    nodes: built.nodes.map((node) => node.kind === "sequence-board"
+      ? { ...node, w: Math.max(1, canvasWidth - 50) }
+      : node),
+  };
+}
+
+/**
+ * 見出しで組んだ板へ、 名前で組んだ板の「言づての端」 と「帯」 を写す (#2408)。
+ *
+ * 写すのはこの 2 つだけ。 板の大きさ・見出し・言づての文字は見出しで組んだ板のものを使う。
+ * 帯は書かない時も組み立て器が言づての端から導くため、 端と一緒に写さないと導いた帯がずれる。
+ */
+function 端を写す(見出し: CdlDiagram, 名前: CdlDiagram): CdlDiagram {
+  const 名前の板 = 名前.nodes.find((n) => n.kind === "sequence-board")?.sequenceData;
+  if (!名前の板) return 見出し;
+  return {
+    ...見出し,
+    nodes: 見出し.nodes.map((n) => {
+      if (n.kind !== "sequence-board" || !n.sequenceData) return n;
+      return {
+        ...n,
+        sequenceData: {
+          ...n.sequenceData,
+          messages: n.sequenceData.messages.map((m, i) => {
+            const 正 = 名前の板.messages[i];
+            return 正 ? { ...m, from: 正.from, to: 正.to } : m;
+          }),
+          bands: 名前の板.bands,
+        },
+      };
+    }),
+  };
+}
+
+/** 名前が同じ箱を指すか。 書いた名前のほか、 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,37 @@
+/**
+ * 名前から id を作る (#2030 で `compile.ts` から移した)。
+ *
+ * この repo で最も広く使われる小道具で、組み立ての全域から 37 箇所が呼ぶ。
+ *
+ * **葉に置く** = ここが他の file を 1 つも取り込まないことで、どこから呼んでも取り込みの輪が
+ * できない。 図種ごとの file と `compile.ts` の両方が呼ぶため、どちらかの側に置くと
+ * もう片方から逆向きの取り込みが生まれる。
+ */
+
+/** id の長さの上限。 これを超える名前は切り詰める */
+export const ID_MAX = 64;
+
+/**
+ * 名前を id に直す。
+ *
+ * 英数字と日本語と `-` `_` だけを残し、それ以外は `-` にまとめる。 前後の `-` は落とす。
+ * 何も残らなければ `n` を返す = 空の id は図の参照先にできないため。
+ *
+ * **カタカナは伸ばす音 (`ー`) まで残す** (#2431)。 `ヶ` (U+30F6) で切ると `ー` (U+30FC) が
+ * 範囲の外へ落ち、`フロー` が `フロ-` になる。 読めない字が一覧に出るだけでなく、
+ * `ユーザー` と `ユーザ` が同じ `ユ-ザ` に潰れる (末尾の `-` も落ちるため完全に一致する)。
+ * 矢印は id で端を指すので、潰れると別の箱へ向かう。
+ *
+ * **区切りに使う記号は残さない**。 `・` (U+30FB) と `ヽヾ` (U+30FD-E) は範囲の外に置く =
+ * `東京・大阪` の `・` は名前の区切りで、字として残すと 1 つの名前に見える。
+ */
+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/stages.ts

@@ -0,0 +1,247 @@
+import type { DslActor, DslDocument, DslStep } from "../types";
+import { 縦列ごとの段を決める } from "./lanes";
+import { slugify } from "./slug";
+import { 分かれ道の札, 泳法図で印をどう描く } from "./swimlane-marks";
+
+/**
+ * 段の箱 (`shape: stages`, #2797 / #2831) の配置規則。
+ *
+ * 段階ごとに同じ上端と高さの列を 1 本作り、列の見出しに「段階 N」と段階の名前を出す。
+ * 箱は列の中へ書いた順に積む札にし、担当 (`lane`) は札の右の小さな字として添える。
+ * 列の面・見出し・札の右の字は描く側 (`lane.stage` と `card` の `subtitle`) が描く。
+ */
+
+/**
+ * 段階の列 1 本の幅。描く側は列の面をこの幅から列の間の 48 を引いた幅で描く。
+ * 幅 332 の列の面に対して、札の左右へ内側の余白を 32 ずつ残す。
+ */
+export const STAGE_LANE_WIDTH = 380;
+
+/**
+ * 札の幅。見本は列の面の内側を 24 ずつ空けるが、幅 284 では列の間 (48) に置く
+ * 「いいえ」の札と札の右端が近づき、描く側が衝突を避けて札を列の下端より下へ押し出す。
+ * 幅 270 でも押し出されるため 268 とし、列の間を描く側が広げずに済めば cardene777/cdl#1035 で 24 に寄せる。
+ */
+export const STAGE_CARD_WIDTH = STAGE_LANE_WIDTH - 112;
+
+/** `stageLayout.columnWidths` を書いた列では、見本どおり列面の左右を 24 ずつ空ける。 */
+export const STAGE_CARD_COLUMN_INSET = 48;
+
+/** 札の高さ。名前 1 行と右の担当を同じ行に置く札で、見本の札と同じく 1 行分に収める。 */
+export const STAGE_CARD_HEIGHT = 48;
+
+/** cdl の列面の間 48 に足し、見本の列面の間 64 にする lane の間。 */
+export const STAGE_LANE_GAP = 16;
+
+/** 列の上端 130 から見本の 1 段目の中心 324 までを world 座標に直した値。 */
+export const STAGE_FIRST_CARD_CENTER_Y = 222;
+
+/** 描画側の自動配置と同じ、高さ 48 の札と次の札の間 100。 */
+export const STAGE_CARD_PITCH = 148;
+
+/** cdl の自動 lane と同じ上端。列を固定して先頭の余白を保つため使う。 */
+export const STAGE_LANE_Y = 28;
+
+export type StageColumn = {
+  id: string;
+  /** 見出しの番号。描く側が「段階 N」の形で出す */
+  number: string;
+  name: string;
+};
+
+export type StageCard = {
+  columnId: string;
+  /** 左から数えた列の位置 (0 始まり)。線を曲線にするか戻り線にするかの判定に使う */
+  column: number;
+  stack: number;
+  /** 札の右へ出す字。担当の名前か、分かれ道の札 */
+  subtitle?: string;
+};
+
+export type StagesPlacement = {
+  columns: StageColumn[];
+  /** 箱の名前ごとの札 */
+  cards: ReadonlyMap<string, StageCard>;
+};
+
+/** 段階を書かない箱は、担当、担当も無ければ箱の名前を段階に使う (#2797)。 */
+export function 段階名(actor: Pick<DslActor, "stage" | "lane" | "name">): string {
+  return actor.stage ?? actor.lane ?? actor.name;
+}
+
+/**
+ * 札の右に出す字。分かれ道は「分かれ道」、それ以外は担当の名前を出す。
+ *
+ * 担当の名前が段階の名前と同じ時は出さない。段階を書かない箱は担当を段階に使うため、
+ * 出すと見出しと同じ字が札の右にもう 1 度並ぶ。
+ */
+function 札の右の字(
+  doc: Pick<DslDocument, "type" | "shape" | "lanes">,
+  actor: DslActor,
+  stage: string,
+): string | undefined {
+  if (泳法図で印をどう描く(doc, actor) === "札") return 分かれ道の札;
+  if (actor.lane === undefined) return undefined;
+  const 担当 = doc.lanes?.[actor.lane]?.label ?? actor.lane;
+  return 担当 === stage ? undefined : 担当;
+}
+
+/**
+ * 段を書かない列で、列の札をどの段から積むかを決める。
+ *
+ * 左の列から入る線のうち、札と同じ段から出る線が最も多くなる位置を選ぶ。
+ * 同じ段から入る線は列をまたいでも真横に走るため、見本と同じく曲げずに読める。
+ * 揃う本数が同じなら、図の一番下の段を下げない位置、その中でも上の位置を選ぶ。
+ */
+function 積み始める段(
+  札たち: readonly DslActor[],
+  flow: DslDocument["flow"],
+  左の列の段: ReadonlyMap<string, number>,
+  これまでの最下段: number,
+): number {
+  const 列の中の順 = new Map(札たち.map((actor, index) => [actor.name, index]));
+  const 揃う本数 = new Map<number, number>();
+  for (const step of flow) {
+    const index = 列の中の順.get(step.to);
+    const 出る段 = 左の列の段.get(step.from);
+    if (index === undefined || 出る段 === undefined || 出る段 < index) continue;
+    const 始め = 出る段 - index;
+    揃う本数.set(始め, (揃う本数.get(始め) ?? 0) + 1);
+  }
+  const 最下段 = (始め: number): number => Math.max(これまでの最下段, 始め + 札たち.length - 1);
+  let 選んだ = 0;
+  for (const [始め, 本数] of 揃う本数) {
+    const 今の本数 = 揃う本数.get(選んだ) ?? 0;
+    if (本数 < 今の本数) continue;
+    if (本数 === 今の本数) {
+      if (最下段(始め) > 最下段(選んだ)) continue;
+      if (最下段(始め) === 最下段(選んだ) && 始め >= 選んだ) continue;
+    }
+    選んだ = 始め;
+  }
+  return 選んだ;
+}
+
+/**
+ * 段の箱の列と札を決める。
+ *
+ * 列は段階が箱に最初に現れた順に左から並べる。札は列の中で書いた順に下へ積み、
+ * 段を書いた札がある列だけは書いた段をそのまま使う (空いた段へ書かない札を置く)。
+ * 段を書かない列は、左の列から真横に入れる段から積む (`積み始める段`)。
+ */
+export function placeStages(
+  doc: Pick<DslDocument, "type" | "shape" | "actors" | "flow" | "lanes">,
+): StagesPlacement {
+  const 段階たち: string[] = [];
+  for (const actor of doc.actors) {
+    const stage = 段階名(actor);
+    if (!段階たち.includes(stage)) 段階たち.push(stage);
+  }
+
+  const 使ったid = new Set<string>();
+  const columns = 段階たち.map((stage, index): StageColumn => {
+    const base = `stage-${slugify(stage) || index}`;
+    let id = base;
+    let suffix = 2;
+    while (使ったid.has(id)) id = `${base}-${suffix++}`;
+    使ったid.add(id);
+    return { id, number: String(index + 1), name: stage };
+  });
+
+  const cards = new Map<string, StageCard>();
+  const 置いた段 = new Map<string, number>();
+  let これまでの最下段 = -1;
+  for (const [column, stage] of 段階たち.entries()) {
+    const 札たち = doc.actors.filter((actor) => 段階名(actor) === stage);
+    const 書いた段 = 札たち.some((actor) => actor.stack !== undefined)
+      ? 縦列ごとの段を決める(札たち, () => stage)
+      : undefined;
+    const 始め = 書いた段 === undefined
+      ? 積み始める段(札たち, doc.flow, 置いた段, これまでの最下段)
+      : 0;
+    for (const [index, actor] of 札たち.entries()) {
+      const stack = 書いた段?.get(actor) ?? 始め + index;
+      const subtitle = 札の右の字(doc, actor, stage);
+      cards.set(actor.name, {
+        columnId: columns[column]!.id,
+        column,
+        stack,
+        ...(subtitle === undefined ? {} : { subtitle }),
+      });
+      これまでの最下段 = Math.max(これまでの最下段, stack);
+    }
+    for (const actor of 札たち) 置いた段.set(actor.name, cards.get(actor.name)!.stack);
+  }
+  return { columns, cards };
+}
+
+/**
+ * 段の箱の線の通し方。
+ *
+ * 右の列へ進む線は曲線 (`curve`) で列の間を渡す。左の列や同じ列の上の札へ戻る線は
+ * 列の見出しより上を回る戻り線 (`back-detour`) にする。同じ列で下の札へ進む線は
+ * 描く側の既定 (真下へ下ろす直線) のまま返さない。
+ */
+export function 段の箱の線の通し方(
+  placement: StagesPlacement,
+  from: string,
+  to: string,
+): "curve" | "back-detour" | undefined {
+  const 出る札 = placement.cards.get(from);
+  const 入る札 = placement.cards.get(to);
+  if (出る札 === undefined || 入る札 === undefined) return undefined;
+  if (出る札.column < 入る札.column) return "curve";
+  if (出る札.column > 入る札.column) return "back-detour";
+  return 入る札.stack < 出る札.stack ? "back-detour" : undefined;
+}
+
+/**
+ * 描く側が線の札を描く高さ。字 1 行の札は 36、補足 (`sub`) を持つ札は 68 で描く
+ * (`@cardenelabs/cdl` の `LABEL_PILL_H_MAIN_ONLY` / `LABEL_PILL_H_WITH_SUB`、公開されていない)。
+ * 描く側が値を変えたら、ここも合わせる。
+ */
+const 線の札の高さ = (sub: string | undefined): number => ((sub ?? "") === "" ? 40 : 68);
+
+/**
+ * 真横に渡る線と札の上端の間。見本の「いいえ」は線のすぐ下に札を置く。
+ *
+ * 描く側が線と札の間に求める最小の間 (`LABEL_TO_PATH_CLEARANCE` = 16) と同じにする。
+ * これより詰めると、描く側が札を線から押し出して列の下端より下へ逃がす。
+ */
+const 札を線の下に置く間 = 16;
+
+/**
+ * 段の箱の線に渡す指定。通し方 (`段の箱の線の通し方`) と、札の置き場所を返す。
+ *
+ * 列をまたぐ線と戻り線の札は線の上に重ねる (`overlay`)。見本は「はい」を曲線の上に、
+ * 「翌日もう一度」を戻り線の上に置く。
+ *
+ * 同じ段の札へ真横に渡る線だけは、札を線のすぐ下へずらす (見本の「いいえ」)。描く側は
+ * 札を線から離して置き、同じ分かれ道から出る曲線の札と重ならない側へ逃がすため、
+ * 何もしないと札が列の下端より下へ出る。書いた `overlay` / `labelOffsetY` は後段で上書きされる。
+ */
+export function 段の箱の線の指定(
+  placement: StagesPlacement,
+  step: Pick<DslStep, "from" | "to" | "label" | "sub">,
+): {
+  routing?: "curve" | "back-detour";
+  overlay?: true;
+  labelOffsetY?: number;
+  fromSide?: "right";
+  toSide?: "top";
+} {
+  const routing = 段の箱の線の通し方(placement, step.from, step.to);
+  const 札がある = step.label !== "" || (step.sub ?? "") !== "";
+  if (routing === undefined) return {};
+  const 戻る辺 = routing === "back-detour" ? { fromSide: "right" as const, toSide: "top" as const } : {};
+  if (!札がある) return { routing, ...戻る辺 };
+  const 真横 =
+    routing === "curve" &&
+    placement.cards.get(step.from)?.stack === placement.cards.get(step.to)?.stack;
+  return {
+    routing,
+    ...戻る辺,
+    overlay: true,
+    ...(真横 ? { labelOffsetY: 線の札の高さ(step.sub) / 2 + 札を線の下に置く間 } : {}),
+  };
+}

package/src/compile/subtitle.ts

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