@cardenelabs/cdl 0.5.0

package/src/layout/nodes.ts

@@ -0,0 +1,190 @@
+import { requiredRowsWidth } from "../kinds/row-align";
+import type { CdlDiagram, LaidLane, LaidNode } from "../types";
+import {
+  hasRenderedLabel,
+  labelPillH,
+  requiredVerticalLabelGap,
+  requiredRowsHeight,
+} from "./spec";
+import { DEFAULT_NODE_GAP, HEADER_RESERVE, LANE_TOP_PAD, NODE_SIZE, STACK_GAP } from "./tokens";
+
+/**
+ * kind=storage で rows[] を持つ node の自動 h を計算する。
+ *
+ * rows 数に応じて h が足りないと最後の rows が node 枠外にはみ出す (ER preset User entity 等)。
+ * 最終行の baseline (`rowBaselineY`、 描画側の式の SSOT) に下余白を足した値を default h と
+ * max() して必要 h を確保する。
+ *
+ * 本関数が扱うのは `storage` だけ。 `GenericNode` 側の 21 種も rows を描くが、 そちらは
+ * 自動で h を伸ばさない (著者が指定した h をそのまま使う)。 行が枠外に出ていないかは
+ * `row-vertical-spacing` (軸 16) が同じ `rowBaselineY` を見て検査する。
+ */
+function autoStorageHeight(n: { kind: string; rows?: string[]; h?: number }, defaultH: number): number {
+  if (n.kind !== "storage") return n.h ?? defaultH;
+  if (n.h != null) return n.h;
+  // rows なし storage は title + divider のみで render されるため、 default h=240 では空白過大。
+  // title block (130px) + bottom padding (20px) = 150px に縮める。
+  if (!n.rows || n.rows.length === 0) return 150;
+  // 元の式 `130 + rows * 56 + 20` と同値。 式の SSOT は `requiredRowsHeight` (spec.ts)。
+  return Math.max(defaultH, requiredRowsHeight("storage", n.rows.length) ?? defaultH);
+}
+
+/**
+ * rows[] を持つ node (kind=storage 主、 generic 系も同 logic) の必要 width を rows 内容から算出。
+ *
+ * 旧実装は w 固定 (token NODE_SIZE.storage.w=400) で、 長い row (例 "charlie: 999999")
+ * が node 枠右端を割って詰まって見える問題があった。 rows の左 / 右 列 max 幅を char width 換算で
+ * 合計し、 default w と max() で確保する。 結果として lane 側 expandLanesForNodes も連動拡張、
+ * label 侵食を防ぐ。
+ *
+ * 著者が n.w を明示している場合は尊重 (snapshot 互換 / catalog thumbnail 縮小指定を壊さない)。
+ */
+function autoRowsWidth(n: { kind: string; rows?: string[]; w?: number }, defaultW: number): number {
+  if (n.w != null) return n.w;
+  if (!n.rows || n.rows.length === 0) return defaultW;
+  const required = requiredRowsWidth(n.rows, n.kind);
+  return Math.max(defaultW, required);
+}
+
+/**
+ * 同 lane 内で隣り合う row を繋ぐ edge の label が収まる stack gap を求める (Issue #202)。
+ *
+ * 横方向は `expandLaneGapsForEdgeLabels` (CAR-470) が lane 間隔を
+ * `labelBoxW + CLEARANCE_NODE_LABEL * 2 + EDGE_STUB_OUT * 2` で先手拡張する。
+ * 縦方向にはこれに対応する経路が無く、 STACK_GAP の固定値しか無かった。
+ *
+ * 必要な隙間は `requiredVerticalLabelGap` (spec.ts SSOT)。 同じ隙間を複数の edge が通る場合
+ * (parallel edge) は label が縦に積まれるので、 その帯の高さを使う。
+ *
+ * 実測。
+ *   - sub 付き label (pill 高 68) は 132 を要するが STACK_GAP は 100 (topology の TCP 5432)
+ *   - parallel 2 本 (pill 高 36 x 2) は 172 を要する (pattern-call-rw の read / write)
+ *
+ * 「隣り合う row」 の判定は stack 番号の差ではなく、 diagram 全体で実在する stack 列
+ * (`allStacks`) 上の隣接で行う。 stack 0 と 2 しか存在しない lane では両者の間に row が無く、
+ * その隙間に label が置かれるため (Codex review 指摘、 stack 番号の差で判定すると見落とす)。
+ *
+ * 全 stack gap を同じ値に揃える。 lane 内の縦間隔が不揃いになると visualValidate の
+ * column-gap-uniform が発火するため (lane pitch を全対で揃えるのと同じ理由)。
+ *
+ * @param diag layout 前の diagram
+ * @param allStacks diagram 全体で実在する stack 番号の昇順列
+ * @returns 要求 stack gap (world unit)。 縦 edge に label が無ければ 0
+ */
+function requiredStackGapForEdgeLabels(diag: CdlDiagram, allStacks: readonly number[]): number {
+  const byId = new Map(diag.nodes.map((n) => [n.id, n]));
+  const rankOf = new Map(allStacks.map((stack, i) => [stack, i]));
+
+  // 同じ隙間 (lane + 上側 row の rank) を通る label の pill 高を集める。
+  const pillHsByGap = new Map<string, number[]>();
+  for (const e of diag.edges) {
+    // `label` が空でも `sub` があれば pill は描かれ、 その高さ (68) の分だけ隙間が要る (Issue #224)。
+    if (!hasRenderedLabel(e)) continue;
+    const from = byId.get(e.from);
+    const to = byId.get(e.to);
+    if (!from || !to) continue;
+    if (from.lane !== to.lane) continue;
+    const fromRank = rankOf.get(from.stack);
+    const toRank = rankOf.get(to.stack);
+    if (fromRank === undefined || toRank === undefined) continue;
+    if (Math.abs(fromRank - toRank) !== 1) continue;
+    const key = `${from.lane}::${Math.min(fromRank, toRank)}`;
+    pillHsByGap.set(key, [...(pillHsByGap.get(key) ?? []), labelPillH(e.sub)]);
+  }
+
+  let required = 0;
+  for (const pillHs of pillHsByGap.values()) {
+    required = Math.max(required, requiredVerticalLabelGap(pillHs));
+  }
+  return required;
+}
+
+export function layoutNodes(diag: CdlDiagram, lanes: LaidLane[]): LaidNode[] {
+  const laneMap = new Map(lanes.map((l) => [l.id, l]));
+
+  // 全 lane を跨いで stack 番号で row を共有する。
+  // 同 stack 番号の node は全 lane で同じ y 中心になり、 lane 間 edge が水平で揃う。
+  // 各 row の h は、 その row に存在する全 lane の node h の最大値。
+  const allStacks = Array.from(new Set(diag.nodes.map((n) => n.stack))).sort((a, b) => a - b);
+  const rowH = new Map<number, number>();
+  for (const stack of allStacks) {
+    const nodesAtStack = diag.nodes.filter((n) => n.stack === stack);
+    const h = Math.max(...nodesAtStack.map((n) => autoStorageHeight(n, NODE_SIZE[n.kind].h)));
+    rowH.set(stack, h);
+  }
+  const rowCy = new Map<number, number>();
+  // nodeGap = author 追加 padding (DEFAULT_NODE_GAP=24)、 STACK_GAP=100 (edge label + 余白の base) に加算。
+  // viewport.nodeGap 明示時はその差分を加算、 未指定なら viewport.gap → DEFAULT_NODE_GAP の順で fallback。
+  const nodeGapExtra =
+    (diag.viewport?.nodeGap ?? diag.viewport?.gap ?? DEFAULT_NODE_GAP) - DEFAULT_NODE_GAP;
+  const stackGap = Math.max(STACK_GAP + nodeGapExtra, requiredStackGapForEdgeLabels(diag, allStacks));
+  let cursor = (lanes[0]?.y ?? HEADER_RESERVE) + LANE_TOP_PAD;
+  for (const stack of allStacks) {
+    const h = rowH.get(stack)!;
+    const cy = cursor + h / 2;
+    rowCy.set(stack, cy);
+    cursor = cy + h / 2 + stackGap;
+  }
+
+  // 各 lane 内で stack 番号重複チェック
+  const byLane = new Map<string, typeof diag.nodes>();
+  for (const n of diag.nodes) {
+    const list = byLane.get(n.lane) ?? [];
+    list.push(n);
+    byLane.set(n.lane, list);
+  }
+  for (const [laneId, list] of byLane) {
+    const seen = new Set<number>();
+    for (const n of list) {
+      if (seen.has(n.stack)) {
+        throw new Error(
+          `cdl layout: lane "${laneId}" の stack=${n.stack} に node が重複 (node "${n.id}")`,
+        );
+      }
+      seen.add(n.stack);
+    }
+  }
+
+  // node を出力 (各 node は所属 lane の x 中央 + 所属 stack の cy)
+  //
+  // canvas pivot 新 spec (dragon canvas pivot spec §layout-role-conversion)。
+  // posX / posY set 済 node は「user が固定した絶対座標」 = auto layout の stack / lane 中央
+  // 計算を skip し、 posX / posY をそのまま cx / cy として採用。 posW / posH set 済なら
+  // 該当値を w / h に採用、 未指定なら NODE_SIZE default + rows/kind 依存の auto 拡張を継承。
+  // free-form Miro 相当 UX の SSOT。
+  const out: LaidNode[] = [];
+  for (const n of diag.nodes) {
+    const lane = laneMap.get(n.lane);
+    if (!lane) {
+      throw new Error(`cdl layout: node "${n.id}" の lane "${n.lane}" が定義されていない`);
+    }
+    const size = NODE_SIZE[n.kind];
+    if (n.posX !== undefined && n.posY !== undefined) {
+      const w = n.posW ?? n.w ?? autoRowsWidth(n, size.w);
+      const h = n.posH ?? n.h ?? rowH.get(n.stack) ?? size.h;
+      out.push({
+        ...n,
+        cx: n.posX,
+        cy: n.posY,
+        w,
+        h,
+        insideContainedLane: !!lane.contain,
+      });
+      continue;
+    }
+    const cx = lane.x + lane.width / 2;
+    const cy = rowCy.get(n.stack)!;
+    const h = n.h ?? rowH.get(n.stack)!;
+    // n.w 明示時は尊重、 未指定で rows[] を持つ node は内容長に合わせて auto 拡張。
+    const w = autoRowsWidth(n, size.w);
+    out.push({
+      ...n,
+      cx,
+      cy,
+      w,
+      h,
+      insideContainedLane: !!lane.contain,
+    });
+  }
+  return out;
+}

package/src/layout/predict-bbox.ts

@@ -0,0 +1,76 @@
+/**
+ * Engine が予測する label / node bbox の world 単位 public API。
+ *
+ * CAR-430 で label-shift.ts の shift 探索は削除、 label 位置 SSOT は edges.ts routePath() +
+ * collisions.ts resolveEdgeLabelOverlapsWithChain に移管。 CAR-431 で pill h/w/padding SSOT は
+ * spec.ts に集約 (render / layout / predict-bbox 3 箇所の drift 解消)、 本 file は spec.ts の
+ * `computeLabelBBoxWorld` を re-export する public API 層として engine 予測値と DOM 実測値を
+ * diff で assert する用途に特化した stable interface を提供する。
+ */
+
+import { computeLabelBBoxWorld } from "./spec";
+import type { LaidEdge, LaidNode } from "../types";
+
+/**
+ * Edge label の world 単位 bbox 予測 (spec.ts SSOT の re-export)。
+ *
+ * SSOT は `spec.ts` の `computeLabelBBoxWorld` に集約 (CAR-431)、 本 function は名前互換のため
+ * delegate wrapper。 render (render/edges.tsx) / layout (layout/collisions.ts) / predict-bbox (本 file)
+ * の 3 箇所で個別実装されていた bbox 計算の drift (boxH 64 vs 68、 labelY 位置の centered vs shifted)
+ * を解消。
+ *
+ * @param edge LaidEdge (labelX, labelY, labelAnchor, label, sub 既確定)
+ * @returns { x, y, w, h } の world 座標 bbox (render 実 rect 位置と一致)
+ */
+export function predictLabelBBoxWorld(edge: LaidEdge): { x: number; y: number; w: number; h: number } {
+  return computeLabelBBoxWorld(edge);
+}
+
+/**
+ * Node の world 単位 bbox 予測。
+ */
+export function predictNodeBBoxWorld(n: LaidNode): { x: number; y: number; w: number; h: number } {
+  return {
+    x: n.cx - n.w / 2,
+    y: n.cy - n.h / 2,
+    w: n.w,
+    h: n.h,
+  };
+}
+
+/**
+ * SVG font rendering の実測誤差 tolerance (world unit)。
+ *
+ * 用途別 2 種類。
+ * - `FONT_RENDER_TOLERANCE_WORLD` = 一般 bbox 予測との tolerance (label position / node size)、
+ *   80 world (実 DOM 約 22 px @ scale 3.7)
+ * - `LABEL_SIZE_TOLERANCE_WORLD` = **label bbox size 専用**、 150 world (約 40 px @ scale 3.7)
+ *
+ * label bbox tolerance を大きく取る理由 = getBoundingClientRect() は SVG `<g>` の外接矩形を
+ * 返し、 内部 `<text>` の glyph render (kerning / overhang / letter-spacing) が `<rect>` の
+ * pad から数-十 world 単位はみ出す。 measureTextWidth (advance width 集計) と DOM 実測
+ * (外接矩形) は本質的に別測定なので、 label size は 150 world で妥当な近似。
+ *
+ * engine measureTextWidth と SVG 実 render の乖離 breakdown:
+ *   - Inter font の hinting 差 ≈ ±0.5 px / char
+ *   - subpixel rendering の rounding ≈ ±1 px / bbox
+ *   - Playwright DOM 実測 と engine world 座標系の scale 差 ≈ ±10-15 world
+ *   - text glyph の rect padding 外 overhang ≈ ±20-40 world (label のみ)
+ */
+export const FONT_RENDER_TOLERANCE_WORLD = 80;
+export const LABEL_SIZE_TOLERANCE_WORLD = 150;
+
+/**
+ * bbox diff 計算 (world 単位)。 各辺の差の Math.abs の Math.max を返す。
+ * tolerance 内なら「engine 予測と実測が一致」 と判定。
+ */
+export function bboxDiffWorld(
+  predicted: { x: number; y: number; w: number; h: number },
+  actual: { x: number; y: number; w: number; h: number },
+): { dx: number; dy: number; dw: number; dh: number; max: number } {
+  const dx = Math.abs(predicted.x - actual.x);
+  const dy = Math.abs(predicted.y - actual.y);
+  const dw = Math.abs(predicted.w - actual.w);
+  const dh = Math.abs(predicted.h - actual.h);
+  return { dx, dy, dw, dh, max: Math.max(dx, dy, dw, dh) };
+}

package/src/layout/px-projection.ts

@@ -0,0 +1,176 @@
+/**
+ * World 座標系 (engine viewBox 内) と DOM 実測 px の相互変換を提供する pixel-perfect projection layer。
+ *
+ * 背景 ...
+ *   engine は viewBox world 単位で全 layout (node.cx / cy / w / h、 edge.d、 label.x / y) を確定する。
+ *   実 DOM 描画は SVG viewBox → CSS width の scale で 縮小 / 拡大され、 world 単位と DOM px は
+ *   一致しない (dragon 実測 scale = displayWidth 490 / viewBox 幅 1820 ≒ 0.269)。
+ *
+ *   従来 routing v8 / v10.1 では WORLD_SCALE = 4.0 の経験係数で world 座標の
+ *   label 幅 / clearance を 「DOM px 相当」 に補正していたが、 実は viewBox 幅 / displayWidth の
+ *   比率で数式的に算出可能。 本 module で計算を SSOT 化し、 全 downstream (edges routing / gate 判定 /
+ *   visual regression) が正確な変換を使う。
+ *
+ * 提供する変換 ...
+ *   1. worldToPx(worldValue, scale) ... 単一値 world → px
+ *   2. pxToWorld(pxValue, scale) ... 単一値 px → world (WORLD_SCALE 逆算)
+ *   3. computeViewportScale(viewBoxWidth, displayWidth) ... scale factor = viewBoxWidth / displayWidth
+ *   4. projectNode / projectEdgeLabel / projectPathSegment ... 各要素の px 予測 bbox / point
+ *
+ * SSOT ...
+ *   本 module の変換式は SVG viewBox の projection と完全に一致する (SVG spec `preserveAspectRatio`
+ *   default = xMidYMid meet で uniform scale)。 fontSize は viewBox 単位で描画時に scale される
+ *   ため、 world font 幅 × scale = DOM 実測 幅。
+ */
+
+import type { LaidEdge, LaidNode } from "../types";
+
+/**
+ * viewBox width と CSS display width から scale factor を計算する。
+ *
+ * scale factor = viewBoxWidth / displayWidth
+ *   例 = dragon CdlDiagramThumbnail は viewBox width 1820 world unit、 display width 490 CSS px
+ *        → scale = 1820 / 490 ≒ 3.714
+ *   world 座標を DOM px に落とす場合は `world / scale`、
+ *   DOM px を world に戻す場合は `px * scale`。
+ *
+ * @param viewBoxWidth SVG viewBox の width 属性値 (world 単位)
+ * @param displayWidth CSS 描画時の width (px)
+ * @returns world unit per DOM px (常に > 0)
+ */
+export function computeViewportScale(viewBoxWidth: number, displayWidth: number): number {
+  if (!Number.isFinite(viewBoxWidth) || viewBoxWidth <= 0) {
+    throw new Error(`computeViewportScale: viewBoxWidth must be > 0 (got ${viewBoxWidth})`);
+  }
+  if (!Number.isFinite(displayWidth) || displayWidth <= 0) {
+    throw new Error(`computeViewportScale: displayWidth must be > 0 (got ${displayWidth})`);
+  }
+  return viewBoxWidth / displayWidth;
+}
+
+/**
+ * world 座標値を DOM px に変換する。 scale = viewBoxWidth / displayWidth。
+ */
+export function worldToPx(worldValue: number, scale: number): number {
+  return worldValue / scale;
+}
+
+/**
+ * DOM px を world 座標に変換する。 scale = viewBoxWidth / displayWidth。
+ */
+export function pxToWorld(pxValue: number, scale: number): number {
+  return pxValue * scale;
+}
+
+/**
+ * Node の px 予測 bbox。 world 座標 (cx, cy, w, h) を DOM px 実測相当に変換する。
+ *
+ * SVG viewBox は uniform scale (preserveAspectRatio xMidYMid meet)、 x / y 両軸同一 scale。
+ * node cx / cy / w / h は viewBox 内 world 座標そのまま、 SVG viewBox → CSS 描画時に scale で
+ * 縮小される。 実 DOM getBoundingClientRect().width == worldW / scale。
+ *
+ * @param n LaidNode (engine 計算後の world 座標)
+ * @param scale viewBox width / display width (world unit per DOM px)
+ * @param svgOffsetPx SVG 要素の CSS 位置 offset (通常 svgClientRect.left / top、 省略時 0)
+ * @returns 予測 DOM px bbox { x, y, w, h }
+ */
+export function projectNode(
+  n: LaidNode,
+  scale: number,
+  svgOffsetPx: { x: number; y: number } = { x: 0, y: 0 },
+  viewBoxOrigin: { x: number; y: number } = { x: 0, y: 0 },
+): { x: number; y: number; w: number; h: number } {
+  const worldLeft = n.cx - n.w / 2 - viewBoxOrigin.x;
+  const worldTop = n.cy - n.h / 2 - viewBoxOrigin.y;
+  return {
+    x: svgOffsetPx.x + worldToPx(worldLeft, scale),
+    y: svgOffsetPx.y + worldToPx(worldTop, scale),
+    w: worldToPx(n.w, scale),
+    h: worldToPx(n.h, scale),
+  };
+}
+
+/**
+ * Edge label の px 予測 bbox。 label.x / y は world 座標での中心 (anchor middle 時) or
+ * 起点 / 終点 (anchor start / end 時)、 labelBoxW を world 単位で受け取り px 換算する。
+ *
+ * @param edge LaidEdge (labelX, labelY, labelAnchor 既確定)
+ * @param labelBoxWorldW world 単位での label bbox 幅 (measureTextWidth + padding)
+ * @param labelBoxWorldH world 単位での label bbox 高 (36 default、 sub あり時 64)
+ * @param scale viewBox width / display width
+ * @param svgOffsetPx SVG 要素の CSS 位置 offset
+ * @param viewBoxOrigin viewBox の (x_min, y_min)、 auto viewBox で 0 でない
+ */
+export function projectEdgeLabel(
+  edge: LaidEdge,
+  labelBoxWorldW: number,
+  labelBoxWorldH: number,
+  scale: number,
+  svgOffsetPx: { x: number; y: number } = { x: 0, y: 0 },
+  viewBoxOrigin: { x: number; y: number } = { x: 0, y: 0 },
+): { x: number; y: number; w: number; h: number } {
+  const anchor = edge.labelAnchor;
+  const boxLeftOffset = anchor === "start" ? 0 : anchor === "end" ? -labelBoxWorldW : -labelBoxWorldW / 2;
+  const worldLeft = edge.labelX + boxLeftOffset - viewBoxOrigin.x;
+  const worldTop = edge.labelY - labelBoxWorldH / 2 - viewBoxOrigin.y;
+  return {
+    x: svgOffsetPx.x + worldToPx(worldLeft, scale),
+    y: svgOffsetPx.y + worldToPx(worldTop, scale),
+    w: worldToPx(labelBoxWorldW, scale),
+    h: worldToPx(labelBoxWorldH, scale),
+  };
+}
+
+/**
+ * Path segment (start point → end point) を DOM px に投影する。
+ *
+ * @param seg { x1, y1, x2, y2 } の world 座標 segment
+ * @param scale viewBox width / display width
+ * @param svgOffsetPx SVG 要素の CSS 位置 offset
+ * @param viewBoxOrigin viewBox の (x_min, y_min)
+ */
+export function projectPathSegment(
+  seg: { x1: number; y1: number; x2: number; y2: number },
+  scale: number,
+  svgOffsetPx: { x: number; y: number } = { x: 0, y: 0 },
+  viewBoxOrigin: { x: number; y: number } = { x: 0, y: 0 },
+): { x1: number; y1: number; x2: number; y2: number } {
+  return {
+    x1: svgOffsetPx.x + worldToPx(seg.x1 - viewBoxOrigin.x, scale),
+    y1: svgOffsetPx.y + worldToPx(seg.y1 - viewBoxOrigin.y, scale),
+    x2: svgOffsetPx.x + worldToPx(seg.x2 - viewBoxOrigin.x, scale),
+    y2: svgOffsetPx.y + worldToPx(seg.y2 - viewBoxOrigin.y, scale),
+  };
+}
+
+/**
+ * 2 bbox の距離 (rectangular gap、 交差時 0)。 px 単位で受け取り px 単位で返す。
+ * label と node の clearance 判定に使う。
+ */
+export function bboxClearance(
+  a: { x: number; y: number; w: number; h: number },
+  b: { x: number; y: number; w: number; h: number },
+): 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);
+}
+
+/**
+ * 点と segment の最短距離 (px 単位)。 label center → path segment 判定に使う。
+ */
+export function pointToSegmentDistance(
+  px: number,
+  py: number,
+  seg: { x1: number; y1: number; x2: number; y2: number },
+): number {
+  const dx = seg.x2 - seg.x1;
+  const dy = seg.y2 - seg.y1;
+  const lenSq = dx * dx + dy * dy;
+  if (lenSq === 0) return Math.hypot(px - seg.x1, py - seg.y1);
+  let t = ((px - seg.x1) * dx + (py - seg.y1) * dy) / lenSq;
+  t = Math.max(0, Math.min(1, t));
+  const cx = seg.x1 + t * dx;
+  const cy = seg.y1 + t * dy;
+  return Math.hypot(px - cx, py - cy);
+}