@cardenelabs/cdl 0.5.0

package/src/layout/spec.ts

@@ -0,0 +1,872 @@
+/**
+ * Layout spec SSOT (world unit)。
+ *
+ * CAR-421 (PR 1 / CAR-418 chain 伝搬 shift + spec 固定化) で新設した固定値 SSOT。
+ * 既存 `clearance-constants.ts` は clearance (near collision 距離下限) の SSOT だが、
+ * 本 file は「positive spec」 = engine が満たすべき正しい配置目標値 の SSOT。
+ *
+ * clearance-constants.ts と役割分担。
+ *   - clearance-constants.ts ... 「これ以下は誤読」 の下限 (near collision detection)
+ *   - spec.ts (本 file)       ... 「これを満たすと正しい」 の目標値 (positive-check axis)
+ *
+ * downstream (layout / edges / collisions / visual-validate) は本 module を import して同一値を
+ * 使うことで、 magic number の散在を防ぐ。 dragon 側 pixel-perfect gate も同 SSOT を参照する。
+ *
+ * world unit = SVG viewBox 内の座標系単位 (clearance-constants.ts と同定義)。
+ */
+
+import { CLEARANCE_LABEL_LABEL, CLEARANCE_NODE_LABEL } from "./clearance-constants";
+import { measureTextWidth } from "./text-width";
+import { EDGE_LABEL_TEXT } from "../label-text";
+import type { CdlEdge, LaidEdge } from "../types";
+
+// ─── edge label pill bbox SSOT (CAR-431 で 3 定義箇所を集約) ──
+
+/**
+ * edge label pill 高さ (sub あり時、 world unit)。
+ *
+ * `render/edges.tsx` の `<rect height={boxH}>` 属性値と一致する SSOT。 sub あり = main + sub の
+ * 2 行 label で 68 world (main line 22px + sub line 19px + 上下 padding + 行間)。 render / layout /
+ * predict-bbox 3 箇所で個別定義していた drift (64 vs 68) を CAR-431 で本定数に集約。
+ */
+export const LABEL_PILL_H_WITH_SUB = 68;
+
+/**
+ * edge label pill 高さ (main のみ、 world unit)。
+ *
+ * sub なし = 1 行 label で 36 world (main line 22px + 上下 padding)。 render 側 rect height と一致。
+ */
+export const LABEL_PILL_H_MAIN_ONLY = 36;
+
+/**
+ * edge label pill 水平 padding (左右対称、 world unit)。
+ *
+ * `boxW = measureTextWidth(label) + LABEL_PILL_PAD_X * 2` の左右 padding。 render / layout /
+ * predict-bbox 全てで 18 world 固定。
+ */
+export const LABEL_PILL_PAD_X = 18;
+
+/**
+ * edge label の pill が実際に描かれるか (SSOT)。
+ *
+ * `label` が空でも `sub` があれば描かれ、 空白のみの `label` は描かれない。 render / bbox 収集 /
+ * 検査 / stack gap の先手拡張 が同じ判定を共有する。
+ *
+ * `!e.label` だけで判定すると `sub` のみの pill が漏れる。 実際に `layoutEdges` の label 逃がし
+ * (Issue #211) と `layoutNodes` の stack gap 拡張 (Issue #224) の 2 箇所で欠陥を生んだ。
+ */
+export function hasRenderedLabel(e: { label?: string; sub?: string }): boolean {
+  return Boolean(e.label?.trim() || e.sub?.trim());
+}
+
+/**
+ * `title` を文字として描かない node の種別。
+ *
+ * 2 群ある。 形だけを描く `dyn-*` 5 種は `DynShapeNode` に回り、 `node.title` を一度も参照しない
+ * (描くのは形と数値の小さな label だけ)。 payload を自前 layout する chart / timeline / analytic
+ * 11 種は、 描くのが payload 側の label で `title` は使わない。
+ *
+ * 一覧は手で持つと描画側とずれるため、 `test/node-title-render.test.tsx` が `NODE_KINDS` を
+ * **全件 render** して「title の文字が出るか」 と本述語の返り値の一致を検査する。 新しい種別を
+ * 足すと `NODE_KINDS` に載った時点で検査対象に入るので、 追記を忘れれば必ず落ちる。
+ */
+const KINDS_WITHOUT_TITLE_TEXT: ReadonlySet<string> = new Set([
+  // 形だけを描く (DynShapeNode)
+  "dyn-rect",
+  "dyn-circle",
+  "dyn-arc",
+  "dyn-wave",
+  "dyn-polygon",
+  // payload を自前 layout して描く (label は payload 側が持つ)
+  "chart-pie",
+  "chart-line",
+  "chart-bar",
+  "gantt-timeline",
+  "mind-map",
+  "mind-radial",
+  "funnel-stages",
+  "quadrant-matrix",
+  "tree-hierarchy",
+  "journey-map",
+  // 形の中に自前の文字を置く (title は使わない)
+  "shape-blockchain-block",
+]);
+
+/**
+ * その node が `title` を文字として描くか (SSOT)。
+ *
+ * 描かない種別に対して「文字が幅を超えて切れる」 (`text-readability`) や「文字が無い」
+ * (`i18n-cjk-detection` / `bidi-hyphenation`) を判定しても、 前提が成り立たない。
+ *
+ * `accessibility-basics` (軸 24) は #363 で「図全体の代替説明が組み立つか」 に変わったため、
+ * 本述語は使わない (節の文字は絵の中の点でしかなく、 読み上げる名前の置き場所にならない)。
+ */
+export function rendersTitleText(kind: string | undefined): boolean {
+  return !KINDS_WITHOUT_TITLE_TEXT.has(kind ?? "");
+}
+
+/**
+ * `rows` を文字として描く node の種別。
+ *
+ * 2 群ある。 `storage` は `StorageNode` が専用の表組みで描き、 残る 21 種は `GenericNode` の
+ * 汎用描画が描く。 行の縦位置が群ごとに違うので、 `rowBaselineY` で分けている。
+ *
+ * 除外側 (`KINDS_WITHOUT_TITLE_TEXT`) ではなく採用側を列挙するのは、 描く種別が少数で、
+ * 新しい種別が増えた時に既定で「描かない」 側に入るのが正しいため。 描くようにしたら明示的に
+ * ここへ足す。
+ *
+ * 一覧は手で持つと描画側とずれるため、 `test/node-rows-render.test.tsx` が `NODE_KINDS` を
+ * **全件 render** して「行の文字が出るか」 と本述語の返り値の一致を検査する。 新しい種別を足すと
+ * `NODE_KINDS` に載った時点で検査対象に入るので、 追記を忘れれば必ず落ちる。
+ */
+const KINDS_WITH_ROW_TEXT: ReadonlySet<string> = new Set([
+  // 専用の表組み (StorageNode)
+  "storage",
+  // 汎用描画 (GenericNode)
+  "person",
+  "user-group",
+  "admin",
+  "developer",
+  "external-user",
+  "database",
+  "cache",
+  "queue",
+  "message-bus",
+  "cloud",
+  "cdn",
+  "service",
+  "api",
+  "frontend",
+  "backend",
+  "webhook",
+  "microservice",
+  "signer",
+  "oracle",
+  "merkle-tree",
+  "decision",
+]);
+
+/**
+ * その node が `rows` を文字として描くか (SSOT)。
+ *
+ * 描かない種別に対して「行が `key: value` 形式か」 (`row-format`) や「行が枠内に収まるか」
+ * (`row-vertical-spacing`) を判定しても、 前提が成り立たない。 逆に、 描かない種別に `rows` が
+ * 書かれていること自体は「書いた内容が消える」 という別の破綻で、 `rows-not-rendered` が見る。
+ */
+export function rendersRows(kind: string | undefined): boolean {
+  return KINDS_WITH_ROW_TEXT.has(kind ?? "");
+}
+
+/**
+ * `rows[i]` の baseline が node 上端から何 world 下に来るか (SSOT)。
+ *
+ * `storage` は `kinds/storage.tsx` が `130 + i * 56`、 残りは `kinds/generic.tsx` が
+ * `100 + i * 28` に置く。 行を描かない種別は `null`。
+ *
+ * `layout/nodes.ts` の `autoStorageHeight` は storage 側の式から必要 h を出しており、
+ * `row-vertical-spacing` (軸 16) は本関数から最終行の位置を得て枠内に収まるかを見る。 どちらも
+ * 描画側の式を 1 箇所から引くことで、 render を変えた時に両方が同時にずれるのを防ぐ。
+ */
+export function rowBaselineY(kind: string | undefined, index: number): number | null {
+  if (!rendersRows(kind)) return null;
+  return kind === "storage"
+    ? ROW_TOP_STORAGE + index * ROW_PITCH_STORAGE
+    : ROW_TOP_GENERIC + index * ROW_PITCH_GENERIC;
+}
+
+/** `kinds/storage.tsx` の 1 行目 baseline と行送り。 */
+export const ROW_TOP_STORAGE = 130;
+export const ROW_PITCH_STORAGE = 56;
+
+/** `kinds/generic.tsx` の 1 行目 baseline と行送り。 */
+export const ROW_TOP_GENERIC = 100;
+export const ROW_PITCH_GENERIC = 28;
+
+/**
+ * 行の文字寸法。 `kinds/storage.tsx` は 26px、 `kinds/generic.tsx` は左 18px / 右 21px。
+ * descender の見積もりには大きい方を使う。
+ */
+export const ROW_FONT_STORAGE = 26;
+export const ROW_FONT_GENERIC = 21;
+
+/** `kinds/storage.tsx` の名前 (title) の baseline。 */
+export const STORAGE_TITLE_BASELINE = 78;
+
+/**
+ * `storage` の名前と列の間に引く区切り線の Y。
+ *
+ * 名前の baseline と 1 行目の字形の上端の中間に置く。 どちらかに寄せると片側だけ詰まって見える。
+ * 変更前は 100 の固定値で、 実測すると名前の下端から 15 / 1 行目の上端から 5 と偏っていた
+ * (`#419`)。
+ *
+ * 1 行目の字形の上端は baseline から font size の 0.72 倍だけ上と見込む (cap 高さの目安)。
+ */
+export const STORAGE_ROW_DIVIDER_Y = Math.round(
+  (STORAGE_TITLE_BASELINE + (ROW_TOP_STORAGE - ROW_FONT_STORAGE * 0.72)) / 2,
+);
+
+/**
+ * baseline から下へ字形が伸びる量を、 font size の何割と **見込むか**。
+ *
+ * 実測値ではなく仮定である。 任意の Unicode 文字列に対する上限は存在しない (結合文字を
+ * 下方向に重ねればいくらでも深くなり、 fallback font の字形も予測できない)。 本定数が
+ * 押さえるのは **preset が行に出す文字の範囲** で、 その中で最も深い字形に合わせてある。
+ *
+ * - 欧文の descender (`g` / `y` / `p`) ... em の 0.20-0.22
+ * - `classDiagram` preset が区切りに入れる `───` (`presets.ts`) の box-drawing 字形 ...
+ *   JetBrains Mono の `┃` で 0.40em
+ * - 丸囲み数字 (`①` 等) ... Inter で約 0.32em
+ *
+ * 著者が結合文字などを直接書いた場合は仮定の外に出る。 その場合の枠外描画は **どこでも
+ * 捕まえていない**。 文字列ごとの実寸には実 DOM が要り、 layout 出力だけを見る本軸では
+ * 原理的に扱えない。 `dom-verify.ts` は実 DOM を読むが、 現状は node の枠の位置と大きさを
+ * 比べるだけで、 行の文字が枠に収まっているかは見ていない (#390)。
+ */
+export const ROW_GLYPH_DEPTH_RATIO = 0.4;
+
+/**
+ * 最終行の baseline から下に、 字形が枠に触れないために要ると **見込む** 量。
+ *
+ * baseline は文字の下端ではない。 字形はここからさらに下へ出る。 行を描かない種別は `null`。
+ *
+ * `row-vertical-spacing` (軸 16) が「文字が枠外に出ている」 と言うための閾値。
+ * `ROW_LAYOUT_BOTTOM_PAD` (レイアウトが確保する余白) とは別物で、 こちらの方が小さい。
+ * レイアウトの余白を検査の閾値に使うと、 実際には文字が収まっている高さまで警告する。
+ *
+ * 仮定の範囲は `ROW_GLYPH_DEPTH_RATIO` の説明を参照。 preset が出す文字の範囲を押さえる。
+ */
+export function rowGlyphDepth(kind: string | undefined): number | null {
+  if (!rendersRows(kind)) return null;
+  const font = kind === "storage" ? ROW_FONT_STORAGE : ROW_FONT_GENERIC;
+  return Math.ceil(font * ROW_GLYPH_DEPTH_RATIO);
+}
+
+/**
+ * レイアウトが最終行の下に確保する余白。
+ *
+ * 文字が触れないための最小量 (`rowGlyphDepth`) より広く取って、 枠と文字の間に見た目の
+ * 間隔を作る。 検査の閾値ではない。
+ */
+export const ROW_LAYOUT_BOTTOM_PAD = 20;
+
+/**
+ * `rows` を持つ node に必要な高さ (SSOT)。
+ *
+ * 最終行の baseline から 1 行送りぶんとレイアウト余白を確保する。 行を描かない種別は `null`。
+ *
+ * `layout/nodes.ts` の `autoStorageHeight` と、 下流 (dragon の sequence header 等) が
+ * 同じ値を使う。 各所で式を写すと、 描画を変えた時に一部だけ古くなる。
+ *
+ * これは「そう置くとよい高さ」 で、 「これを下回ると破綻する高さ」 ではない。 後者は
+ * `rowBaselineY` + `rowGlyphDepth` で、 軸 16 はそちらを見る。
+ */
+export function requiredRowsHeight(kind: string | undefined, rowCount: number): number | null {
+  if (rowCount <= 0) return null;
+  const lastBaseline = rowBaselineY(kind, rowCount - 1);
+  if (lastBaseline === null) return null;
+  const pitch = kind === "storage" ? ROW_PITCH_STORAGE : ROW_PITCH_GENERIC;
+  return lastBaseline + pitch + ROW_LAYOUT_BOTTOM_PAD;
+}
+
+/**
+ * その node が画面に出るか (SSOT)。
+ *
+ * `visibleIf` が **固定の偽** (`"0"` / `"false"` / `"null"` / `"undefined"` / `"nan"`) の node は
+ * 常に非表示。 判定文字列は `render/nodes.tsx` の falsy 判定と同じ。
+ *
+ * 空文字は **出る側** に倒す。 render は `if (node.visibleIf)` で分岐に入るため、 空文字は
+ * JavaScript の falsy として分岐自体を素通りし、 node は描画される。 述語だけ非表示と判定すると
+ * 実際には出ている node の検査が外れる。
+ *
+ * `{signal}` を含む場合は状態しだいで表示されるので、 これも出る側に倒す。
+ *
+ * 寸法は見ない。 実効寸法は `posW` / `posH` が上書きするうえ、 小さい node を非表示扱いにするのは
+ * 軸 1 (`node-visibility`) の担当で、 そちらは幅だけを見る規則を持っている。 二重に別基準を
+ * 持つと食い違う。
+ */
+export function isRenderedNode(n: { visibleIf?: string }): boolean {
+  if (n.visibleIf === undefined || n.visibleIf === "") return true;
+  if (n.visibleIf.includes("{")) return true;
+  const v = n.visibleIf.trim().toLowerCase();
+  return !(v === "" || v === "0" || v === "false" || v === "null" || v === "undefined" || v === "nan");
+}
+
+/** edge label pill の高さ (world unit)。 sub の有無で 2 値。 */
+export function labelPillH(sub: string | undefined): number {
+  return sub ? LABEL_PILL_H_WITH_SUB : LABEL_PILL_H_MAIN_ONLY;
+}
+
+/**
+ * 重なりを解くために、 1 直線上の要素を最小の移動量でずらす (#372)。
+ *
+ * 各要素は「そこに居たい位置」 (`want`) と大きさ (`size`) を持つ。 隣り合う 2 つの中心は
+ * `(size_i + size_{i+1}) / 2 + gap` 以上離す。 その制約の下で、 移動量の 2 乗和を最小にする
+ * 配置を返す。
+ *
+ * label を並べる用途では `want` に「自分の線の上の位置」 を渡す。 動かす量が最小になるので、
+ * 重ならない範囲で全ての label が自分の線の近くに残る。
+ *
+ * 手順は 2 段。 まず制約を「単調増加」 に読み替える。 i 番目までに必要な最小の間隔を累積した
+ * 値を引くと、 制約は「引いた後の列が単調増加」 と同値になる。 次に単調な列への最小 2 乗
+ * 当てはめを解く (隣り合う塊が順序を破る間、 塊を併合して平均を取る)。
+ *
+ * 併合を使うのは、 前から順に押し出すだけでは移動量が最小にならないため。 前から押すと後ろの
+ * 要素だけが動いて群れ全体が一方向に流れる。 併合すると群れが両側に均等に開く。
+ *
+ * @param items 順不同でよい。 `want` 昇順に並べ替えてから解く
+ * @param gap 隣り合う要素の縁どうしに残す最小の隙間
+ * @returns 入力と同じ並びの、 移動後の中心位置
+ */
+export function spreadWithMinimalShift(
+  items: ReadonlyArray<{ want: number; size: number }>,
+  gap: number,
+): number[] {
+  if (items.length === 0) return [];
+  if (items.length === 1) return [items[0]!.want];
+
+  const order = items.map((_, i) => i).sort((a, b) => items[a]!.want - items[b]!.want);
+  const sorted = order.map((i) => items[i]!);
+
+  // cum[i] = i 番目を最小間隔で詰めた時の、 先頭からの累積距離。
+  const cum: number[] = [0];
+  for (let i = 1; i < sorted.length; i++) {
+    cum.push(cum[i - 1]! + (sorted[i - 1]!.size + sorted[i]!.size) / 2 + gap);
+  }
+
+  // 単調増加列への最小 2 乗当てはめ。 塊 = 平均でまとめて置く、 連続した要素の集まり。
+  const blocks: Array<{ sum: number; count: number }> = [];
+  for (let i = 0; i < sorted.length; i++) {
+    blocks.push({ sum: sorted[i]!.want - cum[i]!, count: 1 });
+    while (blocks.length >= 2) {
+      const last = blocks[blocks.length - 1]!;
+      const prev = blocks[blocks.length - 2]!;
+      if (prev.sum / prev.count <= last.sum / last.count) break;
+      blocks.pop();
+      prev.sum += last.sum;
+      prev.count += last.count;
+    }
+  }
+
+  const out = new Array<number>(items.length);
+  let idx = 0;
+  for (const b of blocks) {
+    const mean = b.sum / b.count;
+    for (let k = 0; k < b.count; k++, idx++) {
+      out[order[idx]!] = mean + cum[idx]!;
+    }
+  }
+  return out;
+}
+
+/**
+ * 同じ位置に重なる parallel edge の label を縦に分散する時の中心間 step (world unit、 Issue #202)。
+ *
+ * pill が縦に並ぶので、 中心間距離は「最も高い pill の高さ + label 間の要求 clearance」。
+ * 旧実装は `pill 36 + minClearance 16 = 52` の固定値で、 label 同士の実 gap は 16 しか残らず
+ * `CLEARANCE_LABEL_LABEL` (36) を満たさなかった (catalog 実測 = read ↔ write gap 16、 need 36)。
+ *
+ * @param pillHs 同 group の pill 高さ
+ */
+export function parallelLabelStepY(pillHs: readonly number[]): number {
+  return Math.max(...pillHs) + CLEARANCE_LABEL_LABEL;
+}
+
+/**
+ * 縦 edge の label 群が上下 node の間に収まるために必要な隙間 (world unit、 Issue #202)。
+ *
+ * label 群の中心は隙間の中点に置かれる (`centeredOffset` が 0 を中心に対称分散する)。
+ * よって中点から上下に伸びる距離は
+ * `(本数 - 1) / 2 * step + 端 pill の半分` で、 大きい方が隙間の半分を決める。
+ *
+ * 端 pill の半分ずつを足す (= 帯の実高) と、 高さが非対称な group で片側の余白が不足する
+ * (Codex review 実測 = pill [68, 36] で狭い側が 24、 要求 32)。 そこで端 pill の大きい方を採る。
+ *
+ * 横方向の `expandLaneGapsForEdgeLabels` (CAR-470) と対称だが、 縦 edge は曲がる前の
+ * 水平直進を挟まないので `EDGE_STUB_OUT` は加算しない。
+ */
+export function requiredVerticalLabelGap(pillHs: readonly number[]): number {
+  if (pillHs.length === 0) return 0;
+  const first = pillHs[0]!;
+  const last = pillHs[pillHs.length - 1]!;
+  const step = parallelLabelStepY(pillHs);
+  return (pillHs.length - 1) * step + Math.max(first, last) + CLEARANCE_NODE_LABEL * 2;
+}
+
+/**
+ * edge label pill の world 幅計算 (SSOT)。 main / sub text の実測 advance + padding。
+ *
+ * label / sub の (undefined 含む) 両方から SSOT font 設定で measureTextWidth を呼び、
+ * max(main, sub) + LABEL_PILL_PAD_X * 2 を返す。 CAR-431 で render / layout (collisions +
+ * edges routePathL) / predict-bbox 4 箇所で個別実装されていた同一計算を本 helper に集約。
+ *
+ * `computeLabelBBoxWorld` は本 helper を呼出、 layout/edges.ts routePathL は labelX / labelY
+ * 未確定の段階で幅だけ必要なので本 helper を単独で呼ぶ。
+ *
+ * 返す値は **偶数に切り上げる**。 label 位置は `経路の端 + 余白 + 幅 / 2` で決まり、
+ * 文字幅の実測値をそのまま使うと半端な小数が乗って輪郭がにじむ (`subpixel-precision` 軸)。
+ * 幅を偶数にすると `幅 / 2` が整数になり、 端と余白が整数である限り位置も整数に揃う。
+ *
+ * 切り下げでなく切り上げるのは、 幅を狭める向きの丸めが節や他の label との間隔を
+ * 減らすため。 広げる向きなら間隔は増える一方で、 増分は 2 world 未満に収まる
+ * (clearance の下限は 8 world 以上なので判定を跨がない)。
+ *
+ * @param label main text (undefined / 空文字は最低幅 clamp)
+ * @param sub sub text (undefined なら 0)
+ * @returns pill 全体の world 幅 (偶数)
+ */
+export function computeLabelBoxW(label: string | undefined, sub: string | undefined): number {
+  const mainW = measureTextWidth(label ?? "", { fontSize: EDGE_LABEL_TEXT.main.fontSize });
+  const subW = sub
+    ? measureTextWidth(sub, { fontSize: EDGE_LABEL_TEXT.sub.fontSize, fontFamily: "mono" })
+    : 0;
+  const raw = Math.max(mainW, subW) + LABEL_PILL_PAD_X * 2;
+  // 切り上げる前に浮動小数の誤差を落とす。 文字幅は係数の掛け算と足し算を重ねるので、
+  // 数学的にちょうど偶数になる値が 102.00000000000001 のように出る。 そのまま切り上げると
+  // 既に偶数の幅を余計に 2 広げてしまい、 帯の間隔が図ごとに 2 world ずれる。
+  const EPSILON = 1e-6;
+  return Math.ceil((raw - EPSILON) / 2) * 2;
+}
+
+/**
+ * edge label pill の bbox 予測 (world unit)。 SSOT = render/edges.tsx の rect 描画位置。
+ *
+ * render (packages/cdl/src/render/edges.tsx) / layout (packages/cdl/src/layout/collisions.ts) /
+ * predict-bbox (packages/cdl/src/layout/predict-bbox.ts) の 3 箇所で個別実装されていた bbox 計算を
+ * CAR-431 で本 function に集約。 downstream は本 helper 経由で bbox を取得する事で drift 再発防止。
+ *
+ * 計算経路 (CAR-581 で sub 有無に関わらず pill 中心 = labelY の対称配置に統一):
+ *   1. boxW = computeLabelBoxW(label, sub) (= max(mainW, subW) + LABEL_PILL_PAD_X * 2)
+ *   2. boxH = edge.sub ? LABEL_PILL_H_WITH_SUB : LABEL_PILL_H_MAIN_ONLY
+ *   3. boxLeftX = anchor==="start" ? 0 : anchor==="end" ? -boxW : -boxW/2
+ *   4. boxTopY = -boxH / 2 (sub 有無に関わらず pill 中心 = labelY で対称配置)
+ *
+ * 対称化の背景 (CAR-581): 旧実装は sub あり時のみ `boxTopY = -boxH - LABEL_PILL_SUB_Y_OFFSET_ADJ`
+ * で pill 全体を labelY より上に押上げていた (非対称)。 routePath の `labelY = A.y - labelInit`
+ * は pill 中心 = labelY を前提とする式なので、 sub あり時に二重補正で水平 edge の pill 下端 → path
+ * gap が 44 world (期待 8) に膨らむ regression が発生。 対称化で解消。
+ *
+ * @param edge LaidEdge (labelX / labelY / labelAnchor / label / sub 既確定)
+ * @returns { x, y, w, h } の world 座標 bbox (render 実 rect 位置と一致)
+ */
+export function computeLabelBBoxWorld(edge: LaidEdge): { x: number; y: number; w: number; h: number } {
+  const boxW = computeLabelBoxW(edge.label, edge.sub);
+  const boxH = edge.sub ? LABEL_PILL_H_WITH_SUB : LABEL_PILL_H_MAIN_ONLY;
+  const anchor = edge.labelAnchor;
+  const boxLeftX = anchor === "start" ? 0 : anchor === "end" ? -boxW : -boxW / 2;
+  const boxTopY = -boxH / 2;
+  return {
+    x: edge.labelX + boxLeftX,
+    y: edge.labelY + boxTopY,
+    w: boxW,
+    h: boxH,
+  };
+}
+
+// ─── path geometry SSOT ────────────────────────────────────────
+
+/**
+ * label pill 端 と path segment 距離 (world unit)。
+ *
+ * **engine が label を離して置く時の目標値**。 検証器の軸 59 `edge-label-clearance` が
+ * 「この値未満なら貼り付いている」 と判定していたが、 #386 で畳んだ = 中置き label (線の上に
+ * 載せて pill で線を隠す配置) が正常なので、 距離の下限を一律に課せない。
+ *
+ * 下限の契約は layout の test が持つ (`test/car202-edge-label-clearance.test.ts` が、 離して
+ * 置いた辺について実際に描かれる線との隙間を測る)。 検証器はこの値を見ない。
+ *
+ * clearance-constants.ts の `CLEARANCE_PATH_LABEL` (14) より大きい ... 本値は
+ * 「positive spec」 = 目標値、 CLEARANCE_PATH_LABEL は「これ以下は誤読」 の下限。
+ * 16 world unit = 大 diagram で ~4 px。 経緯 = CAR-483 で 8 → 16 拡大 → CAR-570 で
+ * 16 → 8 縮小 (「16 は離れすぎ」 判定) → CAR-630 で 8 → 16 に戻す (実描画で 8 world
+ * ~2 px は近すぎ、 user 目視判定「4px が最適」 で 16 world 復帰)。
+ */
+export const LABEL_TO_PATH_CLEARANCE = 16;
+
+/**
+ * edge label center と path center の初期距離 (world unit)。
+ *
+ * routePath() が返す init labelY は path 中央から本値だけ離れた位置に配置する。
+ * pill 端 と path 実距離 = 本値 - LABEL_PILL_H_MAIN_ONLY / 2 = LABEL_TO_PATH_CLEARANCE。
+ *
+ * 計算式 = LABEL_TO_PATH_CLEARANCE (16) + LABEL_PILL_H_MAIN_ONLY (36) / 2 = 34 world。
+ * CAR-468 で 5 箇所 (旧 30 / 30 / 32 / 50 / 30 magic number) を本 SSOT に集約、 CAR-482 で
+ * LABEL_TO_PATH_CLEARANCE 4 → 8 拡大に伴い derived value 22 → 26、 CAR-483 で
+ * 8 → 16 拡大に伴い derived value 26 → 34、 CAR-570 で 16 → 8 縮小に伴い derived
+ * value 34 → 26 に戻す、 CAR-630 で 8 → 16 に戻し derived value 26 → 34 に復帰
+ * (user 目視判定 「4px が最適」)。
+ * spec.ts の 2 定数を組み合わせた derived value のため、 downstream から本定数を import する。
+ */
+export const LABEL_INIT_CLEARANCE = LABEL_TO_PATH_CLEARANCE + LABEL_PILL_H_MAIN_ONLY / 2;
+
+/**
+ * dotted-flow style edge の marker glow 最外周 radius (world unit)。
+ *
+ * `render/edges.tsx` の EdgeGlowCircles で描画する 3 重 glow 円 (r=28/18/11 world) のうち最外周値。
+ * 動く marker が path 両側に広がる範囲 = 本値、 dotted-flow の label 距離拡張基準として使う。
+ * render 側 hard-code 値と一致必須、 render 側 radius 変更時は本値も同期。
+ */
+export const MARKER_GLOW_RADIUS = 28;
+
+/**
+ * dotted-flow style edge の label center と path center の初期距離 (world unit)。
+ *
+ * CAR-518 で追加。 dotted-flow edge (Fan-out / Fan-in / Rollback / flow preset 等) は
+ * 動く marker glow (r=28 world) が path 両側に広がるため、 通常 LABEL_INIT_CLEARANCE (34) では
+ * pill 端 と marker 外周の実距離 = 16 - 28 = -12 world (marker が pill 内部に食い込む)。
+ *
+ * 計算式 = LABEL_INIT_CLEARANCE (34) + MARKER_GLOW_RADIUS (28) = 62 world。
+ * pill 端 と marker 外周実距離 = 62 - 18 - 28 = LABEL_TO_PATH_CLEARANCE (16) と等しくなり、
+ * solid edge と同じ視覚的 clearance を marker 通過帯を挟んで確保する。 CAR-570 で
+ * LABEL_TO_PATH_CLEARANCE 16 → 8 縮小に伴い derived value 62 → 54、 CAR-630 で
+ * 8 → 16 に戻し derived value 54 → 62 に復帰。
+ * routePath 内は `labelInitClearance(edge)` helper 経由でのみ本値を参照する (SSOT 単一経路)。
+ */
+export const LABEL_INIT_CLEARANCE_DOTTED_FLOW = LABEL_INIT_CLEARANCE + MARKER_GLOW_RADIUS;
+
+/**
+ * edge style に応じた label init clearance (world unit) を返す。
+ *
+ * routePath 内 labelY 計算 8 箇所の SSOT helper。 solid = 34 (LABEL_INIT_CLEARANCE)、
+ * dotted-flow = 62 (LABEL_INIT_CLEARANCE_DOTTED_FLOW)。 edge 未指定 (routePath 単体 test 経路) は
+ * solid 扱い。
+ *
+ * 分岐を 8 箇所に散らさず helper 化することで、 (a) 将来の新 style 追加時に 1 箇所修正で済む
+ * (b) test で helper を直叩きして分岐を全 style pattern で cover 可能、 という 2 利点を得る。
+ */
+export function labelInitClearance(edge?: Pick<CdlEdge, "style" | "sub"> | null): number {
+  const pillHalfH = edge?.sub ? LABEL_PILL_H_WITH_SUB / 2 : LABEL_PILL_H_MAIN_ONLY / 2;
+  const base = LABEL_TO_PATH_CLEARANCE + pillHalfH;
+  return edge?.style === "dotted-flow" ? base + MARKER_GLOW_RADIUS : base;
+}
+
+/**
+ * pill 端 → path の水平方向距離 (world unit)。
+ *
+ * 垂直 edge が pill を左右にオフセットする際の基準値。 dotted-flow は marker glow radius 分拡張。
+ *
+ * 計算式 = LABEL_TO_PATH_CLEARANCE (16) + (dotted-flow ? MARKER_GLOW_RADIUS (28) : 0)
+ *   = solid: 16 world (pill 左端 → path X)
+ *   = dotted-flow: 44 world (pill 左端 → path X、 glow radius=28 分拡張)
+ *
+ * `labelInitClearance` が水平 edge で label CENTER (Y) の距離を扱うのに対し、 本 helper は
+ * 垂直 edge が pill 端 (X) の距離を扱う SSOT。 対称的な 2 helper で全方向 SSOT 統一。
+ *
+ * CAR-601 で新設。 CAR-573 で垂直 edge labelX を `labelInit + labelHalfW` →
+ * `LABEL_TO_PATH_CLEARANCE + labelHalfW` に変更した際、 dotted-flow の MARKER_GLOW_RADIUS
+ * (28) 加算が漏れた regression を解消。 dotted-flow 垂直 edge の pill 左端が marker glow
+ * 通過帯 (r=28 world) に食い込む症状 (gap=8 実測、 期待=36) を修正。 CAR-630 で
+ * LABEL_TO_PATH_CLEARANCE 8 → 16 に戻し、 solid 8 → 16、 dotted-flow 36 → 44 に復帰。
+ */
+export function labelPathClearanceHorizontal(edge?: Pick<CdlEdge, "style"> | null): number {
+  const base = LABEL_TO_PATH_CLEARANCE;
+  return edge?.style === "dotted-flow" ? base + MARKER_GLOW_RADIUS : base;
+}
+
+/**
+ * edge 起点から水平方向に直進する最小距離 (world unit)。
+ *
+ * L 字 edge が起点即折れすると (起点直後で垂直方向 に turn すると) 「起点がどの
+ * node 由来か視覚判別困難」 になる。 EDGE_STUB_OUT world 以上直進すると起点が
+ * node bbox 縁から明確に離れる → 起点認識容易。
+ *
+ * 40 world = 通常 node w (200-400) の 10-20%、 detour 発火閾値と分離、 label pill
+ * 標準 h (36 world) より大きく起点 stub が label 位置と干渉しない値。
+ */
+export const EDGE_STUB_OUT = 40;
+
+/**
+ * 同 node の対称対 edge (out + in が同 side) の下側 (lower) edge の平行 shift 距離 (world unit)。
+ *
+ * CAR-541 で SYMMETRIC_ENDPOINT_OFFSET (±16 両側 endpoint 単独 shift) から本 SSOT に置換。
+ * 対称対のうち upper (相手 node の Y / X が小さい側) は shift 0 で不変、 lower (相手 node
+ * の Y / X が大きい側) は edge 全体 (両 endpoint 同時) を perpendicular 軸で +本値 shift。
+ *
+ * 両 endpoint を同量 shift する事で、 直線 edge (A.y = B.y) の直進性 SSOT = 「path = M A L B の
+ * 1 直線」 を保存する (旧 CAR-532 は endpoint 単独 shift で A.y != B.y を生み S 字風 corner 挿入
+ * bug (Issue CAR-541 fc-0 submit-review) を発生させていた)。 lower 側は shift 後も A.y = B.y の
+ * 平行移動なので corner 挿入されない。
+ *
+ * 32 world = 旧 SYMMETRIC_ENDPOINT_OFFSET (16) × 2 = 対称対 2 edge 間の視覚的 gap を維持
+ * (旧: 中央 ±16 で 32 gap、 新: 上側 0 + 下側 32 で同じく 32 gap)。 node bbox 半 h (100+ world)
+ * 内に収まって node 縁を逸脱しない。 CAR-489 の endpoint 保持 chain shift とは加算方式で共存可能。
+ *
+ * 判定 (どちらが lower か) ...
+ *   - 各 edge の distant endpoint 座標 (out edge = target node、 in edge = source node)
+ *     の perpendicular 軸 (horizontal side → Y、 vertical side → X) 値の min を direction 別 (out / in) に集計
+ *   - min が小さい direction = upper (shift 0)、 大きい direction = lower (+32 shift)
+ *   - tie の場合 = in edge を lower とする (CAR-532 test の out=Y-16, in=Y+16 挙動を
+ *     out=Y, in=Y+32 に翻訳、 tie-break で 決定論的挙動維持)
+ */
+export const SYMMETRIC_PAIR_SHIFT = 32;
+
+/**
+ * 同じ 2 点を同じ向きに結ぶ edge が複数ある時、 弓なりに離す間隔 (world unit)。
+ *
+ * 端点は動かせない = 同じ node の同じ辺から出る edge は起点を 1 点に集める規約があり
+ * (`fan-origin-single-point` 軸)、 矢頭は辺の中央に着地する規約もある
+ * (`arrow-endpoint-center` 軸)。 そのため途中だけを膨らませて分ける。
+ *
+ * 32 world = `SYMMETRIC_PAIR_SHIFT` と同じ値。 向きが逆の 2 本を離す間隔と揃えることで、
+ * 「同じ 2 点を結ぶ 2 本」 の見え方が向きに依らず同じになる。 中点での 2 本の間隔がこの値、
+ * 各 path は中心線から半分ずつ膨らむ。
+ */
+export const PARALLEL_EDGE_BOW = 32;
+
+/**
+ * 同一 obstacle を迂回する複数 detour path の Y 分離距離 (world unit)。
+ *
+ * 例 = A → C と B → C の 2 edge が同 obstacle X を上方 detour するとき、 detour
+ * top Y が近すぎると 2 path が視覚的に重なる。 DETOUR_SLOT_GAP world 以上離すと
+ * どちらがどの edge か視認可能。
+ *
+ * 30 world = 通常 edge label h (36) より少し小さく、 detour 群が縦に密集しても label
+ * 表示スペースを圧迫しない値。 単一 obstacle の detour 3-4 本まで実用的に分離可能。
+ */
+export const DETOUR_SLOT_GAP = 30;
+
+/**
+ * 同 Y の detour crest (迂回の水平区間) が X 方向に重なってよい長さ (world unit)。
+ *
+ * peak 点 1 個の比較では、 peak X を離すだけで水平区間が同 Y で完全に重なっていても
+ * 検知できない (dragon #890)。 crest を区間として扱い、 重なり長がこの値を超えたら
+ * 「後から描いた線が前の線を覆っている」 症状と判定する。
+ *
+ * 8 world = edge の線幅 (active 5 / 非 active 2.5) より広く、 角の丸め (Q command を
+ * 弦に落とした時に生じる数 world の食い違い) では超えない値。
+ */
+export const DETOUR_CREST_OVERLAP_MIN = 8;
+
+/**
+ * 同 row 内 node の cy 差分許容 (world unit)。
+ *
+ * 同 row 概念 = 同 stack index を持つ横並び node 群。 各 node の cy が完全一致
+ * (差 0) が理想だが、 subpixel 丸め誤差で 1 world 未満の差が発生し得る。 この値
+ * 未満は許容、 超過は positive-check axis `row-alignment` で fail 判定。
+ *
+ * 1 world = 大 diagram で subpixel 相当、 実測差 = 0 の場合のみ pass する厳格判定。
+ */
+export const MIN_ROW_ALIGNMENT_TOLERANCE = 1;
+
+/**
+ * 同 column 内 node の cx 差分許容 (world unit)。
+ *
+ * 同 column 概念 = 同 lane 内で縦積みされた node 群。 cx は lane center に engine が
+ * 揃える設計、 差 0 が理想だが `MIN_ROW_ALIGNMENT_TOLERANCE` と同 tolerance を採用。
+ */
+export const MIN_COLUMN_ALIGNMENT_TOLERANCE = 1;
+
+// ─── clearance policy 拡張 (kind pair 別) ──────────────────────
+
+/**
+ * kind pair 別 clearance policy (world unit)。
+ *
+ * `collisions.ts` の CLEARANCE_POLICY (near collision 下限) と分離、 本 policy は
+ * 目標値を満たすかを見る軸 (`row-alignment` / `column-alignment` 等) が使う。
+ * `edge-label-clearance` は #386 で畳んだ。
+ *
+ * pair key format = `${kindA}|${kindB}` (アルファベット順)、 `requiredSpecClearance()` で
+ * 双方向 lookup。 未登録 pair は 0 = 判定対象外。
+ */
+export const SPEC_CLEARANCE_POLICY: Record<string, number> = {
+  "edge-label|edge-path": LABEL_TO_PATH_CLEARANCE,
+  "edge-path|edge-label": LABEL_TO_PATH_CLEARANCE,
+};
+
+/**
+ * kind pair 別 spec clearance を返す。 未登録 pair は 0 (判定対象外)。
+ */
+export function requiredSpecClearance(kindA: string, kindB: string): number {
+  const keys = [`${kindA}|${kindB}`, `${kindB}|${kindA}`];
+  for (const k of keys) {
+    if (SPEC_CLEARANCE_POLICY[k] !== undefined) return SPEC_CLEARANCE_POLICY[k]!;
+  }
+  return 0;
+}
+
+// ─── chain 伝搬 shift SSOT ─────────────────────────────────────
+
+/**
+ * chain 伝搬 shift resolver の最大 iter 数。
+ *
+ * resolveOverlapsWithChain() で shift → 再検出 → 再 shift を loop するが、
+ * 発散防止のため N iter で強制収束。 通常 diagram は 3-5 iter で収束、 20 iter は
+ * 極端に密な layout でも十分な余裕。
+ */
+export const CHAIN_SHIFT_MAX_ITER = 20;
+
+/**
+ * chain 伝搬 shift の最小 clearance (world unit)。
+ *
+ * overlap 検出時に shift する距離 = overlap 実測 + `CHAIN_MIN_CLEARANCE`。
+ * shift 後の gap が最低この値になる保証。 16 world = 通常 node gap の 20% 相当、
+ * shift 後に「くっつきすぎ」 を視覚防止する余裕距離。
+ */
+export const CHAIN_MIN_CLEARANCE = 16;
+
+/**
+ * chain 伝搬 shift の 1 要素あたり累積 shift 上限 (world unit)。
+ *
+ * CAR-508 SSOT。 chain 伝搬 loop 内で label / edge-path が各軸方向にこの値以上
+ * 移動することを禁止し、 発散を止める。 Fan-out / Fan-in topology で label が互いに
+ * shift 連鎖して viewBox 外に飛ぶ regression の防止 guard。
+ *
+ * 100 world = label pill 高 (36) + label-label clearance (36) + 予備 (28) を目安、
+ * 通常の shift ケース (fail label ↔ retry path で 30-50 world 程度) には影響しない。
+ */
+export const CHAIN_SHIFT_MAX_ACCUMULATED = 100;
+
+// ─── CAR-422 (PR 2) positive-spec 追加値 ───────────────────────
+
+/**
+ * arrow 終点と終点 node の辺中央との距離許容 (world unit)。
+ *
+ * 終点 node の toSide (top/right/bottom/left) の辺中央 と、 arrow 実際の
+ * 終点座標との距離が本値以下なら「中央着地」 と判定。 超過は 4 隅当て症状。
+ *
+ * 8 world = 通常 node 短辺 (h=100 前後) の 8% 相当、 実描画上「辺の真ん中」
+ * と視覚判別できる余裕距離。 axis 8 (arrow-endpoint-anchoring) が「側 or 内側」
+ * を判定するのに対し、 本値は「側の中央 or 端」 を判定する棲み分け。
+ */
+export const ARROW_ENDPOINT_CENTER_TOL = 8;
+
+/**
+ * 同 row 内 node 間の gap variance 許容 (world unit)。
+ *
+ * 同 stack index を持つ node 群を cx 昇順で並べ、 隣接 node cx 差 = gap を求める。
+ * gap の max - min が本値以下なら「均一」 判定。 超過は「片寄っている」 症状で
+ * axis `row-gap-uniform` で fail 判定。
+ *
+ * 40 world = 通常 node 間 gap (100-300) の 15-40% 相当、 layout engine が
+ * 均等配置に努めた結果として許容される subpixel 誤差 + 意図的 offset 余裕。
+ */
+export const ROW_GAP_VARIANCE_TOL = 40;
+
+/**
+ * 同 column 内 node 間の端間 gap variance 許容 (world unit)。
+ *
+ * 同 lane 内 node 群を cy 昇順で並べ、 隣接 node の端間 gap
+ * (下の node の上端 - 上の node の下端) を求める。
+ * gap の max - min が本値以下なら「均一」 判定。 縦積み layout の gap uniform 判定。
+ * 40 world = row 側と同 tolerance で対称、 vertical stacking の意図的 offset 余裕を含む。
+ *
+ * 中心間距離 (cy 差) ではなく端間 gap を測る (Issue #202)。 node 高さは kind ごとに
+ * 異なるため、 中心間距離は端間 gap が完全に均一でも node 高さ差の分だけばらつく。
+ * engine が制御しているのは端間 gap であり、 検査もそれに合わせる。
+ */
+export const COLUMN_GAP_VARIANCE_TOL = 40;
+
+/**
+ * edge-label bbox と lane border 貫通の判定 gap (world unit)。
+ *
+ * edge-label pill が lane 縁 (lane.x / lane.x+width) を貫通すると、 label の一部が
+ * 「別 lane に侵入」 したように見える。 label bbox 端が lane border から本値以下の
+ * 距離にあれば「貫通疑い」 として警告。
+ *
+ * 2 world = lane border の描画線幅 (通常 1-2 px) と bbox pill 端の許容誤差。
+ * 0 = 完全接触は許容、 内側に食い込むと fail。
+ */
+export const LANE_BORDER_CLEARANCE_TOL = 2;
+
+// ─── near-collision policy SSOT (CAR-424 で collisions.ts から集約) ──
+
+/**
+ * near-collision 検出用 kind pair 別 clearance policy (world unit)。
+ *
+ * `SPEC_CLEARANCE_POLICY` (positive spec、 目標値) と分離、 本 policy は
+ * `detectNearCollisions()` (`collisions.ts`) が「これ以下は誤読」 の下限判定で使う。
+ *
+ * SSOT 集約 (CAR-424) — 旧実装は `collisions.ts` 内 module-local const `CLEARANCE_POLICY`
+ * として定義されていたが、 CAR-421 の `spec.ts` 追加後に「positive spec は spec.ts、
+ * near-collision は collisions.ts」 の分散所有になっていた。 本 file に集約する事で
+ * layout SSOT が 1 module に集中する (`clearance-constants.ts` の primitive 定数と
+ * 2 SSOT policy dict は組み合わせて downstream が使う)。
+ *
+ * default 未登録 pair は `NEAR_COLLISION_DEFAULT_MIN` (16 world unit)。
+ */
+export const NEAR_COLLISION_POLICY: Record<string, number> = {
+  "node|node": 70,
+  "node|edge-label": 32,
+  "edge-label|edge-label": 36,
+  "edge-label|edge-path": 14,
+  "node|lane-label": 0,
+  "lane-label|edge-label": 24,
+  "lane-label|lane-label": 0,
+  "lane-label|edge-path": 0,
+  "edge-path|node": 0,
+  "edge-path|edge-path": 0,
+};
+
+/**
+ * `NEAR_COLLISION_POLICY` に登録なし pair の default 下限 (world unit)。
+ */
+export const NEAR_COLLISION_DEFAULT_MIN = 16;
+
+/**
+ * layout が node 同士に確保する間隔を、 policy ちょうどではなくこの分だけ広く取る (world unit)。
+ *
+ * policy は「これを割ったら誤読する」 下限で、 判定は `gap < required` の strict 比較。
+ * 下限ぴったりに置くと「通るだけ」 の状態になり、 lane 配置が 1 world 動いただけで割れる。
+ * 実際 dragon catalog では 68 対が下限ちょうど (余裕 0) に張り付いていた。
+ */
+export const NODE_GAP_MARGIN = 10;
+
+/**
+ * layout が node 同士に確保する目標間隔 (world unit)。
+ *
+ * 検査側の下限 (`NEAR_COLLISION_POLICY["node|node"]`) に余裕を足した値。 layout 側はこの値を
+ * 目標に lane 幅を決め、 検査側は下限で判定する = 目標を下げても即座に error にはならない。
+ */
+export function targetNodeNodeClearance(): number {
+  return requiredNearClearance("node", "node") + NODE_GAP_MARGIN;
+}
+
+/**
+ * near-collision 用 kind pair 別 clearance を返す。 未登録 pair は
+ * `NEAR_COLLISION_DEFAULT_MIN` を返す (旧 collisions.ts `requiredClearance` 挙動保持)。
+ */
+export function requiredNearClearance(kindA: string, kindB: string): number {
+  const keys = [`${kindA}|${kindB}`, `${kindB}|${kindA}`];
+  for (const k of keys) {
+    if (NEAR_COLLISION_POLICY[k] !== undefined) return NEAR_COLLISION_POLICY[k]!;
+  }
+  return NEAR_COLLISION_DEFAULT_MIN;
+}
+
+/**
+ * 図を読み上げる時の代替説明 (#363)。
+ *
+ * cdl の図は `<svg role="img">` で描く = 支援技術には **1 枚の絵** として渡り、 中の節や辺は
+ * 個別に公開されない (WAI-ARIA の `img` role は子孫を公開しない)。 そのため読み上げの質は
+ * この 1 文で決まる。
+ *
+ * 操作できる部品 (スライダー等) は `<svg>` の外の HTML なので、 絵として扱っても隠れない。
+ *
+ * 組み立ては 3 つを繋ぐ。
+ *
+ * | 部分 | 出どころ | 無い時 |
+ * |---|---|---|
+ * | 図が何を示すか | `topic` | 落とす |
+ * | 今どの段か | 段の `title` | 落とす |
+ * | 段が何を説明するか | 段の `body` | 落とす |
+ *
+ * 元は「題名 + 段の **id**」 を出していた (`"OAuth 認可コードの往復を追う p"`)。 段の id は
+ * 著者が付ける短い記号 (`"p"` 等) で、 読み上げても意味を持たない。
+ *
+ * @param topic 図が何を示すか
+ * @param phase 現在の段 (無ければ省略)
+ * @returns 読み上げる 1 文。 全て空なら空文字
+ */
+export function buildDiagramAltText(
+  topic: string | undefined,
+  phase: { title?: string; body?: string } | undefined,
+): string {
+  const parts: string[] = [];
+  const topicText = topic?.trim() ?? "";
+  if (topicText) parts.push(topicText.endsWith("。") ? topicText : `${topicText}。`);
+  const title = phase?.title?.trim() ?? "";
+  const body = phase?.body?.trim() ?? "";
+  if (title && body) parts.push(`${title} — ${body}`);
+  else if (title) parts.push(title);
+  else if (body) parts.push(body);
+  return parts.join(" ");
+}