@cardenelabs/cdl 0.5.0

package/src/layout/footer-shape.ts

@@ -0,0 +1,97 @@
+import type { LaidLane, LaidNode } from "../types";
+
+/**
+ * `shape-` の絵が箱の下端から上へどこまで伸びるか (world unit)。
+ *
+ * これらの種別は中身を **箱の下端から固定の距離** で組み立てる (実測 = `shape-robot-arm` は
+ * base の中心を `cy + h/2 - 60` に置き、 そこから腕を上へ積む)。 箱がこの値より低いと絵が
+ * 箱の上へはみ出す。
+ *
+ * ## 値の出どころ
+ *
+ * 箱 140x72 で描いて絵の外接矩形を測り、 `72 + 上へのはみ出し` を伸びる量とした。 載せるのは
+ * はみ出しが実測で 0 より大きかった種別だけで、 それ以外は箱の中に収まるため不要。
+ */
+export const SHAPE_DRAW_UP_EXTENT: Readonly<Record<string, number>> = {
+  "shape-robot-arm": 201, // 実測 上 129
+  "shape-iot-sensor": 120, // 48
+  "shape-credit-card": 113, // 40.8
+  "shape-exchange": 107, // 35
+  "shape-storefront": 104, // 32
+  "shape-cdn-edge": 103, // 30.8
+  "shape-payment-provider": 101, // 29
+  "shape-gear": 96, // 23.9
+  "shape-rpc-node": 94, // 22
+  "shape-wallet": 84, // 12.1
+};
+
+/**
+ * 縦線を持つ lane の **下端の名札** を集める。
+ *
+ * 順序図は lane ごとに上端と下端へ名札を置く。 node が 1 つ以下の lane は下端の名札を持たない
+ * (上端だけ、 もしくは空) ため対象から外す。
+ *
+ * 縦線の終点 (`CdlStage`) と絵を下げる量 (`footerShapeDrops`) と図の下端 (`computeViewBox`) の
+ * 3 箇所が同じ名札を指す必要があるため、 「どれが下端の名札か」 の判定をここに 1 つだけ置く。
+ */
+export function lifelineFooterNodes(lanes: LaidLane[], nodes: LaidNode[]): LaidNode[] {
+  // lane ごとに node を集める索引を 1 度だけ作る。 lane ごとに全 node を走査すると
+  // lane 数 × node 数に膨らみ、 `CdlStage` は動きの 1 コマごとに描き直すため毎コマ払う
+  const byLane = new Map<string, LaidNode[]>();
+  for (const n of nodes) {
+    const inside = byLane.get(n.lane);
+    if (inside) inside.push(n);
+    else byLane.set(n.lane, [n]);
+  }
+  const footers: LaidNode[] = [];
+  for (const lane of lanes) {
+    if (!lane.lifeline) continue;
+    const inside = byLane.get(lane.id);
+    if (inside === undefined || inside.length < 2) continue;
+    // 一番下 = cy が最大。 並べ替えずに 1 回の走査で選ぶ。 同じ cy が複数ある時は
+    // **後に現れた方** を採る (安定な並べ替えで末尾を取るのと同じ結果にする)
+    let footer = inside[0]!;
+    for (const n of inside) {
+      if (n.cy >= footer.cy) footer = n;
+    }
+    footers.push(footer);
+  }
+  return footers;
+}
+
+/**
+ * 下端の名札で絵を下げる量。 箱に収まる種別と、 収まる高さを持つ箱では 0 を返す。
+ *
+ * 下げた結果、 絵の上端が箱の上端に揃う = 縦線 (箱の上端で止まる) と重ならなくなる。
+ */
+export function footerShapeDropY(kind: string, h: number): number {
+  const extent = SHAPE_DRAW_UP_EXTENT[kind];
+  if (extent === undefined) return 0;
+  if (!Number.isFinite(h) || h <= 0) return 0;
+  return Math.max(0, extent - h);
+}
+
+/**
+ * 下端の名札の id から下げる量を引く表。 下げない名札は載せない。
+ *
+ * **下げるのは下端の名札だけ**。 上端の名札を下げると絵が箱の下端より下に出て、 そこから
+ * 下りる縦線が絵を貫く = 直そうとしている状態を上下逆に作ってしまう。
+ */
+export function footerShapeDrops(lanes: LaidLane[], nodes: LaidNode[]): Map<string, number> {
+  return footerShapeDropsOf(lifelineFooterNodes(lanes, nodes));
+}
+
+/**
+ * 集め終えた下端の名札から、 下げる量の表を作る。
+ *
+ * 呼出側が既に名札を集めている場合はこちらを使う。 `footerShapeDrops` を呼ぶと名札を
+ * もう一度集めることになり、 動きの 1 コマごとに 2 度払う (`CdlStage`)。
+ */
+export function footerShapeDropsOf(footers: LaidNode[]): Map<string, number> {
+  const drops = new Map<string, number>();
+  for (const footer of footers) {
+    const dy = footerShapeDropY(footer.kind, footer.h);
+    if (dy > 0) drops.set(footer.id, dy);
+  }
+  return drops;
+}

package/src/layout/geometry.ts

@@ -0,0 +1,135 @@
+/**
+ * 幾何演算 helper SSOT。
+ *
+ * visual-validate / collisions / dragon test で共通利用する
+ * 2D geometry primitive を 1 箇所に集約。 前 visual-validate.ts 内 local helper と
+ * Playwright test 内 local helper で 2 度書きだったのを engine から export で統一。
+ */
+
+export interface Segment {
+  x1: number;
+  y1: number;
+  x2: number;
+  y2: number;
+}
+
+export interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** 点 (px, py) と矩形の縁 (外周) までの最短距離。 内側なら 0、 外側なら実距離。 */
+export function pointRectEdgeDistance(px: number, py: number, rect: Rect): number {
+  const dx = Math.max(rect.x - px, 0, px - (rect.x + rect.w));
+  const dy = Math.max(rect.y - py, 0, py - (rect.y + rect.h));
+  return Math.hypot(dx, dy);
+}
+
+/** 矩形同士の重なり面積 (world 単位)。 重ならなければ 0。 */
+export function rectRectOverlapArea(a: Rect, b: Rect): number {
+  const dx = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x);
+  const dy = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
+  if (dx <= 0 || dy <= 0) return 0;
+  return dx * dy;
+}
+
+/** 矩形同士の clearance (最短距離)。 重なっていれば 0、 離れていれば実距離。 */
+export function rectRectClearance(a: Rect, b: Rect): number {
+  const dx = Math.max(0, Math.max(a.x - (b.x + b.w), b.x - (a.x + a.w)));
+  const dy = Math.max(0, Math.max(a.y - (b.y + b.h), b.y - (a.y + a.h)));
+  return Math.hypot(dx, dy);
+}
+
+/** 2 線分の交差判定 (端点共有は交差扱いしない)。 */
+export function segmentsIntersect(a: Segment, b: Segment): boolean {
+  const d1 = (b.x2 - b.x1) * (a.y1 - b.y1) - (b.y2 - b.y1) * (a.x1 - b.x1);
+  const d2 = (b.x2 - b.x1) * (a.y2 - b.y1) - (b.y2 - b.y1) * (a.x2 - b.x1);
+  const d3 = (a.x2 - a.x1) * (b.y1 - a.y1) - (a.y2 - a.y1) * (b.x1 - a.x1);
+  const d4 = (a.x2 - a.x1) * (b.y2 - a.y1) - (a.y2 - a.y1) * (b.x2 - a.x1);
+  return ((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0));
+}
+
+/** 線分の交点。 */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/**
+ * 2 線分の交点を返す。 交わらなければ `null`。 **端点での接触も交点として返す**。
+ *
+ * `segmentsIntersect` は端点の接触を交差に数えない。 曲線を折れ線に開いて数える時、 交差が
+ * 分割点にちょうど乗ると隣り合う 2 本の分割片が両方とも端点接触になり、 **交差が消える**
+ * (実測 = `M 0 0 Q 80 80, 160 160` と `y=40` / `y=80` / `y=120` の 3 本で 3 件 → 0 件)。
+ *
+ * 端点を含めて返すので、 呼出側が「元の辺の端点で接しているだけ」 を除く。 同じ節から出る辺
+ * どうしの共有端点を交差として数えないため。
+ *
+ * 平行 / 重なりは `null` を返す。 重なりの交点は 1 点に定まらず、 数えると同じ線を 2 度引いた
+ * 図で件数が跳ねる。
+ */
+export function segmentIntersection(a: Segment, b: Segment): Point | null {
+  const ax = a.x2 - a.x1;
+  const ay = a.y2 - a.y1;
+  const bx = b.x2 - b.x1;
+  const by = b.y2 - b.y1;
+  const denom = ax * by - ay * bx;
+  if (denom === 0) return null;
+  const t = ((b.x1 - a.x1) * by - (b.y1 - a.y1) * bx) / denom;
+  const u = ((b.x1 - a.x1) * ay - (b.y1 - a.y1) * ax) / denom;
+  if (t < 0 || t > 1 || u < 0 || u > 1) return null;
+  return { x: a.x1 + t * ax, y: a.y1 + t * ay };
+}
+
+/** 線分の集まりを覆う矩形。 空なら `null`。 */
+export function segmentsBBox(segs: ReadonlyArray<Segment>): Rect | null {
+  if (segs.length === 0) return null;
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const s of segs) {
+    minX = Math.min(minX, s.x1, s.x2);
+    minY = Math.min(minY, s.y1, s.y2);
+    maxX = Math.max(maxX, s.x1, s.x2);
+    maxY = Math.max(maxY, s.y1, s.y2);
+  }
+  return { x: minX, y: minY, w: maxX - minX, h: maxY - minY };
+}
+
+/**
+ * 矩形どうしが触れているか。 縁の接触も含める。
+ *
+ * 交差の事前除外に使う。 縁で接する形を落とすと、 縁上の交点を見逃す。
+ */
+export function bboxOverlaps(a: Rect | null, b: Rect | null): boolean {
+  if (!a || !b) return false;
+  return a.x <= b.x + b.w && b.x <= a.x + a.w && a.y <= b.y + b.h && b.y <= a.y + a.h;
+}
+
+/** 点が候補のどれかと `tol` 以内で一致するか。 */
+export function isNearAny(p: Point, candidates: ReadonlyArray<Point>, tol: number): boolean {
+  return candidates.some((c) => Math.abs(c.x - p.x) <= tol && Math.abs(c.y - p.y) <= tol);
+}
+
+/** 点 (px, py) と線分 (x1,y1)-(x2,y2) の最短距離。 */
+export function pointToSegmentDistance(
+  px: number,
+  py: number,
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+): number {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const lenSq = dx * dx + dy * dy;
+  if (lenSq === 0) return Math.hypot(px - x1, py - y1);
+  let t = ((px - x1) * dx + (py - y1) * dy) / lenSq;
+  t = Math.max(0, Math.min(1, t));
+  const cx = x1 + t * dx;
+  const cy = y1 + t * dy;
+  return Math.hypot(px - cx, py - cy);
+}

package/src/layout/label-shift.ts

@@ -0,0 +1,28 @@
+import type { LaidEdge, LaidLane, LaidNode } from "../types";
+
+/**
+ * Edge label の post-pass shift 探索は CAR-430 で削除済 (no-op passthrough)。
+ *
+ * 旧実装 (v10 系) は 16 方向 × 26 段階の全探索型 shift + Tier 0-3 fallback +
+ * PROXIMITY_HARD_CAP + computeFanTShift 等の場当たり logic で label 位置を再計算していた。
+ * CAR-426 chain 伝搬 shift の label 層拡張 (CAR-426-A / CAR-428) 完了で
+ * `resolveEdgeLabelOverlapsWithChain` (`layout/collisions.ts`) が label overlap 解消の
+ * 単一 SSOT になったため、 本 file の shift 探索は 二重権限 として削除された。
+ *
+ * label 配置の権限フロー (CAR-430 SSOT)。
+ *   1. `edges.ts routePath()` = 初期 label 位置 (path 中点 ± 30 world 等) を SSOT で決定
+ *   2. `resolveEdgeLabelOverlapsWithChain` (post-pass 2) = overlap 検出時のみ chain 伝搬 shift
+ *   3. 本 function = 通過 no-op (旧 API caller の後方互換のため signature 保持)
+ *
+ * 後方互換のため export は残置、 内部で input を そのまま返す。
+ * caller (`layout.ts` post-pass 1) は CAR-430 同 PR で削除済で、 本 function は
+ * pipeline 経由では呼ばれない。 外部 caller (dragon 等の direct import) がある可能性を
+ * 考慮して signature のみ維持する。
+ */
+export function shiftLabelsAwayFromNodes(
+  edges: LaidEdge[],
+  _nodes: LaidNode[],
+  _lanes: LaidLane[],
+): LaidEdge[] {
+  return edges;
+}

package/src/layout/lanes.ts

@@ -0,0 +1,328 @@
+import type { CdlDiagram, CdlEdge, LaidLane, LaidNode } from "../types";
+import { CLEARANCE_NODE_LABEL } from "./clearance-constants";
+import { computeLabelBoxW, EDGE_STUB_OUT, targetNodeNodeClearance } from "./spec";
+import { CONTAIN_PAD, DEFAULT_LANE_GAP, HEADER_RESERVE, LANE_LABEL_H, LANE_PAD_MIN } from "./tokens";
+
+/**
+ * lane.x を「動いた」 と見なす最小差分 (world unit)。
+ *
+ * pitch 均一化は先頭 lane から targetPitch を累積加算して x を再計算するため、
+ * 小数座標の図では既に均一でも 1e-13 規模の丸め誤差が乗る。 厳密比較だと
+ * この誤差を移動と誤判定し、 描画の変わらない図で lane 配列を再生成してしまう。
+ */
+const LANE_POSITION_EPSILON = 1e-9;
+
+export function layoutLanes(diag: CdlDiagram): LaidLane[] {
+  // contain なし lane = label 高だけ確保、 contain あり lane は後で recompute で高さを node から決める。
+  // lane.x が未指定 (undefined) なら 前 lane の右端 + laneGap で auto 計算 (mermaid 風 auto-layout)。
+  // laneGap = viewport.laneGap → viewport.gap → DEFAULT_LANE_GAP の優先順で解決 (author 細粒度上書き可)。
+  //
+  // 注意 = ここで決めた x / laneGap は最終値ではない。 後段の `expandLaneGapsForEdgeLabels` が
+  // edge label 収納幅から requiredGap を算出し、 gap がそれを下回る場合は lane を右へ shift する。
+  // 結果として lanes 間の実効 gap は `max(laneGap, requiredGap)` になり、
+  // author が明示した `lane.x` も shift 対象になる (CdlViewport.laneGap の doc comment に実測例あり)。
+  //
+  // canvas pivot 新 spec (dragon canvas pivot spec §layout-role-conversion)。
+  // posX / posY / posW / posH が set 済 lane は「user が固定した絶対座標」 = 後続 auto layout の
+  // cursor 進行にも参加しない (座標 skip)。 cursorX 進行と切り離すことで他 lane の位置に副作用を
+  // 与えず、 完全に独立した free-form 座標として扱う。 未指定 lane は従来通り。
+  const laneGap = diag.viewport?.laneGap ?? diag.viewport?.gap ?? DEFAULT_LANE_GAP;
+  let cursorX = 0;
+  return diag.lanes.map((lane) => {
+    if (lane.posX !== undefined && lane.posY !== undefined) {
+      return {
+        ...lane,
+        x: lane.posX,
+        y: lane.posY,
+        width: lane.posW ?? lane.width,
+        height: lane.posH ?? LANE_LABEL_H,
+      };
+    }
+    const resolvedX = lane.x ?? cursorX;
+    cursorX = resolvedX + lane.width + laneGap;
+    return {
+      ...lane,
+      x: resolvedX,
+      y: HEADER_RESERVE,
+      height: LANE_LABEL_H,
+    };
+  });
+}
+
+/**
+ * node が lane.width より広い場合、 lane.width を node 最大幅 + 余裕に自動拡張する。
+ * 拡張後、 後続 lane の x を shift して被りを回避。
+ * 著者が lane.width を node より狭く指定しても engine が自動修正、 label 侵食を防ぐ。
+ */
+export function expandLanesForNodes(lanes: LaidLane[], nodes: LaidNode[]): LaidLane[] {
+  // 隣り合う node の間隔は「著者が空けた lane 間隔 + 左右 lane の余白」 で決まる。
+  //
+  //   node 間隔 = lane 間隔 + (lane 幅 - node 幅) / 2 × 2 本分 = lane 間隔 + PAD × 2
+  //
+  // したがって PAD は「policy が要求する node 間隔を、 著者が詰めて置いた分だけ埋め合わせる」
+  // 値でなければならない。 PAD を定数で持つと、 著者が lane を詰めた図で policy を割る。
+  //
+  // 経緯 = 定数 25 だった頃、 lane 間隔 20 の図でちょうど 70 (policy ぴったり) になり、
+  // 間隔を 10 にした図は 60 で policy 割れを起こしていた (engine は何も補正しなかった)。
+  // 間隔 20 が偶然 policy を満たしていただけで、 policy を守る仕組みは無かった。
+  //
+  // 本 function は policy から必要 PAD を逆算する。 policy 値を変えれば PAD も追従する。
+  //
+  // canvas pivot 新 spec (dragon canvas pivot spec §layout-role-conversion)。
+  // posX / posY set 済 lane は cumulative shift 連鎖から除外、 自身の x / width を固定する。
+  // user drag / resize で明示的に置いた lane が他 lane の auto layout 再計算に副作用を与えない
+  // = 「座標 set 済 skip」 の SSOT。
+  const targetNodeGap = targetNodeNodeClearance();
+
+  // 隣接は「配列の並び」 ではなく x 座標で決める。 著者は lane を x 昇順に宣言するとは限らず、
+  // 配列順で隣を取ると実際には隣り合っていない対を見てしまう。
+  //
+  // 座標を固定した lane (posX / posY) は auto layout の連鎖から外れる既存仕様に合わせ、
+  // ここでも鎖から除く。 固定 lane は幅も位置も engine が動かせないため、 その隣で policy を
+  // 満たせるかは著者の配置次第になる = 本 function の保証の外。 除いた上で「auto lane 同士の
+  // 隣接」 を取り直すので、 固定 lane が間に挟まっても auto lane 同士の関係は切れない。
+  // 重ねることが目的の lane (role: "overlay") も鎖から除く。 単に「その対を見ない」 だけだと、
+  // 帯を挟んだ両隣の column lane 同士が隣接と判定されず調整が効かなくなる。
+  const isAuto = (l: LaidLane): boolean => l.posX === undefined || l.posY === undefined;
+  const isOverlay = (l: LaidLane): boolean => l.role === "overlay";
+  const autoSortedByX = lanes.filter(isAuto).sort((a, b) => a.x - b.x);
+  const columnChain = autoSortedByX.filter((l) => !isOverlay(l));
+
+  // 拡張は lane 間隔を変えない (幅の増分をそのまま後続 lane の x に足すため)。
+  // よって必要な余白は元の lane 配置から先に決められる。
+  //
+  // 重ねることが目的の lane (role: "overlay") が絡む対は対象外。 group を囲む枠や gantt の
+  // timeline 帯がこれにあたり、 引き剥がすのは配置の意図に反する。
+  //
+  // それ以外の対は重なっていても埋め合わせるが、 **重なり幅そのものは埋めない**。
+  // 重なり幅を足し込むと余白が青天井になり lane が異常に太る (実測 = 重なり 460 の対で
+  // 余白 270、 幅 480 の lane が 540)。 role の付け忘れがこの形で図を壊すのを防ぐため、
+  // 重なりは「間隔 0」 として扱い、 余白の上限を「間隔 0 で並べた時に要る値」 で頭打ちにする。
+  const gapById = new Map<string, number>();
+  for (let i = 0; i + 1 < columnChain.length; i++) {
+    const left = columnChain[i]!;
+    const right = columnChain[i + 1]!;
+    const gap = Math.max(0, right.x - (left.x + left.width));
+    // 左右それぞれの lane に対して、 自分が関わる対のうち最も狭い gap を覚える。
+    for (const l of [left, right]) {
+      const prev = gapById.get(l.id);
+      if (prev === undefined || gap < prev) gapById.set(l.id, gap);
+    }
+  }
+
+  const padFor = (lane: LaidLane): number => {
+    const narrowest = gapById.get(lane.id);
+    if (narrowest === undefined) return LANE_PAD_MIN;
+    // node 間隔 = lane 間隔 + PAD * 2 を targetNodeGap 以上にする PAD。
+    // narrowest は 0 以上に丸めてあるので、 上限は ceil(targetNodeGap / 2) で頭打ちになる。
+    return Math.max(LANE_PAD_MIN, Math.ceil((targetNodeGap - narrowest) / 2));
+  };
+
+  // 幅が増えた lane の右側にある lane を、 増えた分だけ右へ動かして間隔を保つ。
+  //
+  // 「右側」 は x 座標で決める。 著者は lane を x 昇順に宣言するとは限らず、 配列順で
+  // 累積すると、 実際には左にある lane まで押してしまい配置が崩れる。
+  const widthOf = new Map<string, number>();
+  const deltaOf = new Map<string, number>();
+  for (const lane of lanes) {
+    if (lane.posX !== undefined && lane.posY !== undefined) continue;
+    const inside = nodes.filter((n) => n.lane === lane.id);
+    const maxNodeW = inside.length > 0 ? Math.max(...inside.map((n) => n.w)) : 0;
+    const newWidth = Math.max(lane.width, maxNodeW + padFor(lane) * 2);
+    widthOf.set(lane.id, newWidth);
+    deltaOf.set(lane.id, newWidth - lane.width);
+  }
+
+  const shiftOf = new Map<string, number>();
+  let cumulativeShift = 0;
+  for (const lane of autoSortedByX) {
+    shiftOf.set(lane.id, cumulativeShift);
+    cumulativeShift += deltaOf.get(lane.id) ?? 0;
+  }
+
+  return lanes.map((lane) => {
+    if (lane.posX !== undefined && lane.posY !== undefined) {
+      return { ...lane };
+    }
+    return {
+      ...lane,
+      x: lane.x + (shiftOf.get(lane.id) ?? 0),
+      width: widthOf.get(lane.id) ?? lane.width,
+    };
+  });
+}
+
+/**
+ * lane 間 gap を edge label 収納幅 + 両側 clearance で先手拡張する (CAR-470 SSOT)。
+ *
+ * 動機 = CAR-468 で routePath init labelY を LABEL_INIT_CLEARANCE (26 world、 CAR-570 で 34 → 26 縮小) に SSOT 準拠したが、
+ * lane 間 gap < label 幅 + 両側 clearance の場合、 edges.ts routePath L 字 分岐で
+ * `labelXOverlapsNode = true` 判定が発火 (edges.ts:354-356) し、 label が node 上端外側
+ * (`A.y - nodeMaxH/2 - CLEARANCE_NODE_LABEL - labelHalfH`) に押し出されて init 位置から乖離する。
+ * 実測 = stateMachine submit / success で label が path から 125 world 離れて配置される。
+ *
+ * 本 function は隣接 lane 対を跨ぐ edge が存在する場合、 label bbox が両 node bbox から
+ * CLEARANCE_NODE_LABEL 分離れて収まる gap を engine 側で確保する。 拡張後、 後続 lane は
+ * cumulative shift で連鎖 shift される (`expandLanesForNodes` と同じ設計)。
+ *
+ * 拡張式 = `labelBoxW + CLEARANCE_NODE_LABEL * 2 + EDGE_STUB_OUT * 2`
+ *   - labelBoxW ... SSOT `computeLabelBoxW(edge.label, edge.sub)` (spec.ts)
+ *   - CLEARANCE_NODE_LABEL ... node × edge-label 誤読下限 32 world (clearance-constants.ts)
+ *   - EDGE_STUB_OUT ... edge 起点から水平直進最小距離 40 world (spec.ts)、 L 字 detour path
+ *     で label が corner Y 上に置かれるため両側 stub 分の余白を確保する
+ *
+ * 結果 = lane 対を跨ぐ全 edge の label が `labelXOverlapsNode = false` 分岐を通り、
+ * routePath init labelY = A.y - LABEL_INIT_CLEARANCE (34、 CAR-630 で 26 → 34 復帰) がそのまま最終 label 位置となる。
+ *
+ * 非隣接 lane を跨ぐ edge の扱い (Issue #202)。
+ * edge は隣接 lane 対だけでなく、 間の lane を横断することがある (例 user(0) → api(2))。
+ * 初版は隣接対しか見ておらず、 横断される中間 lane の gap に label 幅が反映されないため
+ * label が非発着 lane の border を貫通していた。 現在は edge が跨ぐ全ての隣接対に対して
+ * その edge の labelBoxW を要求し、 label が span 内のどの対に置かれても収まるようにする。
+ *
+ * pitch 均一化 (Issue #202)。
+ * 上記の要求 gap を対ごとに個別適用すると lane 中心間距離 (pitch) が不揃いになる。
+ * lane diagram の node.cx は lane 中心に固定されるため、 pitch のばらつきは
+ * そのまま「同 stack 内 node の cx 差のばらつき」 として visualValidate の
+ * Axis 65 (row-gap-uniform) に検出される。 本 function は全対の必要 pitch を求めた上で
+ * その最大値に全対を揃え、 lifeline 間隔を均一にする。
+ *
+ * 実効仕様 = `pitch = max(全対の max(currentGap, requiredGap) + 両 lane の半幅和)`
+ * 先頭 lane の x は固定 (viewBox 原点維持)、 以降の lane が右へ shift される。
+ */
+export function expandLaneGapsForEdgeLabels(
+  lanes: LaidLane[],
+  nodes: LaidNode[],
+  edges: readonly CdlEdge[],
+): LaidLane[] {
+  if (lanes.length < 2) return lanes;
+  // canvas pivot 新 spec (dragon canvas pivot spec §layout-role-conversion)。
+  // posX / posY set 済 lane は pitch uniform 化計算から完全除外し、 座標固定のまま返す。
+  // sortedByX に含めないことで隣接対にも入らず、 他 lane の layout に副作用を与えない。
+  // 未指定 lane のみ従来の pitch 均一化 logic に参加、 catalog 100+ backward compat 保証。
+  const layoutedLanes = lanes.filter((l) => !(l.posX !== undefined && l.posY !== undefined));
+  if (layoutedLanes.length < 2) return lanes;
+  // lane を x 昇順に並べる (author が非順序 index / x 手動指定した場合の safe fallback)。
+  // shifted x を lane.id で lookup、 最後に元 lane 配列の順序で返却する。
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+  const sortedByX = [...layoutedLanes].sort((a, b) => a.x - b.x);
+  const laneIndexById = new Map(sortedByX.map((lane, i) => [lane.id, i]));
+
+  // 各 隣接 lane 対 (i, i+1) が確保すべき labelBoxW の最大値を求める。
+  //
+  // CAR-470 初版は「隣接 lane 対を跨ぐ edge」 だけを見ていた。 しかし edge は
+  // 非隣接 lane を跨ぐことがある (例 jwt-auth の user(0) → api(2))。 この場合
+  // label は中間 lane (login) の領域に描かれうるが、 その lane 対の gap 計算には
+  // 一切反映されていなかった。 結果 label が非発着 lane の border を貫通する
+  // (visualValidate の lane-border-clearance が検出)。
+  //
+  // 修正 = edge が跨ぐ全ての隣接 lane 対に対して、 その edge の labelBoxW を要求する。
+  // label が span 内のどの対に置かれても収まることを保証する (routing 前なので
+  // 実際の label x は未定、 保守的に全対へ課す)。
+  const requiredBoxWByPair = new Array<number>(Math.max(0, sortedByX.length - 1)).fill(0);
+  for (const edge of edges) {
+    const fromLane = nodeById.get(edge.from)?.lane;
+    const toLane = nodeById.get(edge.to)?.lane;
+    if (fromLane === undefined || toLane === undefined) continue;
+    const fi = laneIndexById.get(fromLane);
+    const ti = laneIndexById.get(toLane);
+    if (fi === undefined || ti === undefined || fi === ti) continue;
+    const labelBoxW = computeLabelBoxW(edge.label, edge.sub);
+    if (labelBoxW === 0) continue;
+    const lo = Math.min(fi, ti);
+    const hi = Math.max(fi, ti);
+    for (let pair = lo; pair < hi; pair++) {
+      if (labelBoxW > requiredBoxWByPair[pair]!) requiredBoxWByPair[pair] = labelBoxW;
+    }
+  }
+
+  // 各 隣接対が必要とする pitch (lane 中心間距離) を求め、 その最大値に全対を揃える。
+  //
+  // pitch を対ごとではなく全体で揃える理由 (Issue #202)。
+  // lane diagram の node.cx は lane 中心に固定される。 よって visualValidate の Axis 65
+  // (row-gap-uniform) が見る「同 stack 内 node の cx 差」 は pitch と恒等的に一致する。
+  // 対ごとに requiredGap だけ拡張する初版は pitch を不均一にし、 label 幅の差がそのまま
+  // node 間隔のばらつきとして現れていた (実測 = catalog で min 572 / max 733 world)。
+  //
+  // 代償 = 最も広い対に全対が引き上げられ図幅が増える。 各対の label 収納幅は下限として
+  // 保証し続けるため、 描画の正しさは損なわない。
+  const requiredPitchByPair: number[] = [];
+  for (let i = 0; i < sortedByX.length - 1; i++) {
+    const lane = sortedByX[i]!;
+    const rightLane = sortedByX[i + 1]!;
+    const halfSum = lane.width / 2 + rightLane.width / 2;
+    const currentPitch = rightLane.x + rightLane.width / 2 - (lane.x + lane.width / 2);
+    const maxLabelBoxW = requiredBoxWByPair[i]!;
+    // edge が跨がない対は label 収納の要求がない。 下限を課さず現状の pitch を維持する。
+    // author が意図的に lane を重ねた図 (resolveOverlaps が y 軸 shift で解消する edge case) を
+    // engine が勝手に引き離さないため。
+    if (maxLabelBoxW === 0) {
+      requiredPitchByPair.push(currentPitch);
+      continue;
+    }
+    const requiredGap = maxLabelBoxW + CLEARANCE_NODE_LABEL * 2 + EDGE_STUB_OUT * 2;
+    requiredPitchByPair.push(Math.max(currentPitch, requiredGap + halfSum));
+  }
+  // 整数に切り上げる。 pitch は label 幅から決まり、 label 幅は 1 文字あたりの送り幅
+  // (1.08 em 等) × font size で出すため小数になる。 その小数がそのまま lane の x に乗り、
+  // node 中心 → edge label の x へ順に伝わって、 図全体の座標が非整数になっていた
+  // (実測 = dragon catalog 412 図で subpixel warn 936 件、 うち 9 割超が x 軸)。
+  //
+  // SVG は非整数座標を subpixel で描くため線や文字の輪郭がにじむ。 切り上げなので
+  // label 収納に必要な幅は必ず確保される (切り捨てると label がはみ出す)。
+  const targetPitch = Math.ceil(Math.max(...requiredPitchByPair));
+
+  // 先頭 lane の x を固定し (viewBox 原点維持)、 以降を targetPitch 間隔で再配置する。
+  const shiftedXById = new Map<string, number>();
+  const firstLane = sortedByX[0]!;
+  shiftedXById.set(firstLane.id, firstLane.x);
+  let center = firstLane.x + firstLane.width / 2;
+  for (let i = 1; i < sortedByX.length; i++) {
+    const lane = sortedByX[i]!;
+    center += targetPitch;
+    shiftedXById.set(lane.id, center - lane.width / 2);
+  }
+
+  // targetPitch の累積加算で 1e-13 規模の丸め誤差が乗る。 これを「動いた」 と判定すると
+  // 見た目の変わらない図でも lane を再配置してしまい、 snapshot に無意味な差分が出る。
+  const moved = sortedByX.some(
+    (lane) => Math.abs((shiftedXById.get(lane.id) ?? lane.x) - lane.x) > LANE_POSITION_EPSILON,
+  );
+  if (!moved) return lanes;
+  return lanes.map((lane) => ({ ...lane, x: shiftedXById.get(lane.id) ?? lane.x }));
+}
+
+export function recomputeContainedLanes(lanes: LaidLane[], nodes: LaidNode[]): LaidLane[] {
+  // contain: true な lane は内部 node を囲む height を再計算
+  // lifeline: true な lane は全 node 最下端まで height を拡張 (lifeline が全 box を貫通するよう)
+  // sequence diagram は全 lifeline 同じ長さである必要があるので、 lifeline lane 群の bottom を統一する
+  const lifelineLanes = lanes.filter((l) => l.lifeline);
+  let lifelineBottom = 0;
+  if (lifelineLanes.length > 0) {
+    for (const lane of lifelineLanes) {
+      const inside = nodes.filter((n) => n.lane === lane.id);
+      if (inside.length === 0) continue;
+      const bottom = Math.max(...inside.map((n) => n.cy + n.h / 2));
+      lifelineBottom = Math.max(lifelineBottom, bottom);
+    }
+  }
+
+  return lanes.map((lane) => {
+    if (lane.lifeline) {
+      return {
+        ...lane,
+        height: lifelineBottom - lane.y + CONTAIN_PAD,
+      };
+    }
+    if (!lane.contain) return lane;
+    const inside = nodes.filter((n) => n.lane === lane.id);
+    if (inside.length === 0) return lane;
+    const top = Math.min(...inside.map((n) => n.cy - n.h / 2));
+    const bottom = Math.max(...inside.map((n) => n.cy + n.h / 2));
+    return {
+      ...lane,
+      y: top - CONTAIN_PAD - LANE_LABEL_H,
+      height: bottom - top + CONTAIN_PAD * 2 + LANE_LABEL_H,
+    };
+  });
+}