@cardenelabs/cdl 0.5.0

package/src/layout/text-width.ts

@@ -0,0 +1,133 @@
+/**
+ * 文字列の pixel 幅を字種別に精度計算する engine SSOT。
+ *
+ * label / lane-label / node title 等の bbox 計算に使用。 SVG 実 render (Inter Bold / JetBrains Mono
+ * @ Chrome + macOS) の実測 advance width と ±5-10% 精度で一致する char-class × per-char 係数化。
+ *
+ * 過去の一律 `text.length * 18` は 30-40% 過小評価で G5 (predicted-vs-actual) warn 84 件の
+ * 主因だった。 実測係数化で warn を大幅削減する。
+ *
+ * 係数 SSOT の設計。
+ * - 全て `advance / em` (fontSize=1 相当) で保持、 実 fontSize は乗算して算出する
+ * - fontFamily は "sans" (Inter Bold @ fontWeight 700) と "mono" (JetBrains Mono) の 2 系統
+ * - letterSpacing は char 間 tracking (SVG letter-spacing 属性の world 単位) を charCount 倍で加算
+ * - 記号 / 括弧 は char class 別、 特に `(` `)` `:` `.` `,` の実測は naive 平均より狭い / 広い
+ * - CJK / 全角 は Inter fallback を経て CJK font (macOS "Hiragino Sans" / "Yu Gothic") で描画、
+ *   fontSize と等幅 (1.0 em)、 kerning なし
+ *
+ * Inter Bold @ Chrome 実測 advance width (em 単位)。 主要 char のみ、 未定義は class default に fallback。
+ * Bold は Regular に対し英字で +8-15%、 CJK は同じ、 記号は char により大差 (bold ならではの pen 太り)。
+ */
+
+type FontFamily = "sans" | "mono";
+
+interface MeasureOptions {
+  fontSize?: number;
+  fontWeight?: number;
+  letterSpacing?: number;
+  fontFamily?: FontFamily;
+}
+
+/**
+ * Inter Bold 700 @ Chrome + macOS の SVG 実 render 実測 advance width (em 単位)。
+ *
+ * G5 gate (predicted-vs-actual) 実測で英字 lowercase 平均が Inter Bold 仕様値 0.55 em ではなく
+ * 実測 0.68 em (+25%) だと判明したため、 実測係数化して +20-25% 補正した table を採用する。
+ * 原因は Chrome の `text-rendering: optimizeLegibility` + subpixel positioning + macOS 側の
+ * font fallback (Inter → SF Pro Text 部分置換) 込みで advance width が Inter Regular 仕様より
+ * 広く描画されるため。 数値は cookbook / presets / flow-demo の dw 実測から逆算した mean。
+ */
+const INTER_BOLD_ADVANCE_EM: Record<string, number> = {
+  // uppercase (実測係数化、 Inter Bold 仕様 × 1.20)
+  A: 0.86, B: 0.86, C: 0.88, D: 0.93, E: 0.82, F: 0.79, G: 0.94, H: 0.92, I: 0.44,
+  J: 0.66, K: 0.86, L: 0.74, M: 1.12, N: 0.94, O: 0.94, P: 0.85, Q: 0.94, R: 0.87,
+  S: 0.79, T: 0.82, U: 0.91, V: 0.85, W: 1.22, X: 0.85, Y: 0.82, Z: 0.82,
+  // lowercase (実測係数化、 Inter Bold 仕様 × 1.22)
+  a: 0.73, b: 0.77, c: 0.68, d: 0.77, e: 0.73, f: 0.51, g: 0.76, h: 0.77, i: 0.39,
+  j: 0.41, k: 0.73, l: 0.39, m: 1.15, n: 0.77, o: 0.76, p: 0.77, q: 0.77, r: 0.54,
+  s: 0.65, t: 0.54, u: 0.77, v: 0.71, w: 1.05, x: 0.71, y: 0.71, z: 0.66,
+  // digits (Inter Bold tabular-nums、 実測係数化 × 1.20)
+  "0": 0.72, "1": 0.72, "2": 0.72, "3": 0.72, "4": 0.72, "5": 0.72,
+  "6": 0.72, "7": 0.72, "8": 0.72, "9": 0.72,
+  // ascii symbols (実測係数化 × 1.15、 punct 系は kerning が広く効くため 1.20)
+  " ": 0.35, "!": 0.44, "\"": 0.59, "#": 0.78, "$": 0.72, "%": 1.00, "&": 0.86,
+  "'": 0.32, "(": 0.46, ")": 0.46, "*": 0.63, "+": 0.78, ",": 0.36, "-": 0.50,
+  ".": 0.36, "/": 0.51, ":": 0.36, ";": 0.36, "<": 0.78, "=": 0.78, ">": 0.78,
+  "?": 0.63, "@": 1.17, "[": 0.48, "\\": 0.51, "]": 0.48, "^": 0.63, "_": 0.63,
+  "`": 0.48, "{": 0.52, "|": 0.37, "}": 0.52, "~": 0.78,
+};
+
+/**
+ * JetBrains Mono 実測 advance width (em)。 mono は全 char 等幅の仕様値 0.60 em だが、
+ * Chrome 実測 (fontSize 19 の sub label) では 0.63 em (+5%) で描画される。
+ */
+const JETBRAINS_MONO_ADVANCE_EM = 0.63;
+
+function isCJK(code: number): boolean {
+  return (
+    (code >= 0x3000 && code <= 0x30ff) || // CJK symbols / hiragana / katakana
+    (code >= 0x3400 && code <= 0x9fff) || // CJK ideographs
+    (code >= 0xf900 && code <= 0xfaff) || // CJK compat ideographs
+    (code >= 0xff01 && code <= 0xff60) || // fullwidth ASCII
+    (code >= 0xffe0 && code <= 0xffe6) // fullwidth signs
+  );
+}
+
+function isHalfwidthKana(code: number): boolean {
+  return code >= 0xff61 && code <= 0xffdc;
+}
+
+/**
+ * char class 別 default advance (em)。 char 表に個別値が無い場合の fallback。
+ * Inter Bold で ASCII 平均 = 0.58、 記号平均 = 0.42、 CJK = 1.05 (font-fallback overhang 込)、 半角カナ = 0.60。
+ */
+function defaultAdvanceEm(ch: string, code: number): number {
+  if (isCJK(code)) return 1.08;
+  if (isHalfwidthKana(code)) return 0.72;
+  if (ch >= "a" && ch <= "z") return 0.73;
+  if (ch >= "A" && ch <= "Z") return 0.86;
+  if (ch >= "0" && ch <= "9") return 0.72;
+  return 0.65;
+}
+
+/**
+ * 文字列の SVG render pixel 幅を実測係数で算出する。
+ *
+ * @param text 対象文字列 (空文字は最低幅にクランプされる)
+ * @param opts fontSize / fontWeight / letterSpacing / fontFamily の描画 context
+ *
+ * default = fontSize 22, fontWeight 700, letterSpacing 0, fontFamily "sans" (Inter Bold)。
+ * edge label main text の caller (collisions / predict-bbox / edges) と一致する。
+ * sub text (fontSize 19, fontFamily "mono") / lane label (fontSize 20, letterSpacing 2) は
+ * opts で明示的に渡す。
+ *
+ * 最低幅 = fontSize × 1.2 (超短 label で bbox が細くなり shift 判定不安定になる問題を防ぐ)。
+ */
+export function measureTextWidth(text: string, opts: MeasureOptions = {}): number {
+  const fontSize = opts.fontSize ?? 22;
+  const letterSpacing = opts.letterSpacing ?? 0;
+  const fontFamily = opts.fontFamily ?? "sans";
+  let advanceEmSum = 0;
+  let charCount = 0;
+  for (const ch of text) {
+    charCount++;
+    if (fontFamily === "mono") {
+      const code = ch.codePointAt(0) ?? 0;
+      advanceEmSum += isCJK(code) ? 1.08 : JETBRAINS_MONO_ADVANCE_EM;
+      continue;
+    }
+    const code = ch.codePointAt(0) ?? 0;
+    if (isCJK(code)) {
+      // CJK 実測 = Chrome + macOS system CJK font (Hiragino Sans / Yu Gothic) で
+      // Inter fontSize 22 baseline に対し 1.08 em 前後で描画される (実測係数化)。
+      // 1.08 が cookbook / presets / text-dsl の合計 G5 warn 最小 (10 件)、
+      // 1.15 以上に上げると flow-demo が過大化して +2-6 件増える tradeoff。
+      advanceEmSum += 1.08;
+      continue;
+    }
+    const table = INTER_BOLD_ADVANCE_EM[ch];
+    advanceEmSum += table !== undefined ? table : defaultAdvanceEm(ch, code);
+  }
+  const w = advanceEmSum * fontSize + letterSpacing * charCount;
+  return Math.max(w, fontSize * 1.2);
+}

package/src/layout/tokens.ts

@@ -0,0 +1,181 @@
+import type { NodeKind } from "../types";
+
+/**
+ * DESIGN TOKENS (全 layout 寸法の SSOT)
+ *
+ * 全要素は token を参照、 magic number は書かない。
+ * label と node の clearance も、 並走 path 同士の gap も、
+ * 全部この 1 ブロックで管理することで「キャンバス全体を engine が把握」 する状態を保つ。
+ */
+export const TOKENS = {
+  // viewBox / lane margins
+  header_reserve: 28,
+  view_pad: 60,
+  lane_label_h: 40,
+  lane_top_pad: 100,
+  contain_pad: 28,
+
+  // node sizes (kind ごと、 unified row h は engine が max() で算出)
+  node: {
+    actor: { w: 340, h: 200 },
+    function: { w: 380, h: 170 },
+    storage: { w: 400, h: 240 },
+    event: { w: 360, h: 200 },
+    card: { w: 320, h: 150 },
+    // 人系
+    person: { w: 280, h: 180 },
+    "user-group": { w: 320, h: 180 },
+    admin: { w: 280, h: 180 },
+    developer: { w: 280, h: 180 },
+    "external-user": { w: 300, h: 180 },
+    // インフラ
+    database: { w: 320, h: 200 },
+    cache: { w: 280, h: 160 },
+    queue: { w: 340, h: 140 },
+    "message-bus": { w: 380, h: 140 },
+    cloud: { w: 320, h: 180 },
+    cdn: { w: 320, h: 160 },
+    // アプリ系
+    service: { w: 320, h: 180 },
+    api: { w: 320, h: 160 },
+    frontend: { w: 320, h: 180 },
+    backend: { w: 320, h: 180 },
+    webhook: { w: 320, h: 160 },
+    microservice: { w: 320, h: 180 },
+    // データ / 判定
+    signer: { w: 300, h: 180 },
+    oracle: { w: 320, h: 180 },
+    "merkle-tree": { w: 340, h: 220 },
+    decision: { w: 300, h: 180 },
+    // Chart 系 (CAR-994 Phase A) ... 1 node に datum 配列を持ち、 kind 内で SVG geometry 描画。
+    // 実際の w/h は preset chart() が w/h override で指定 (default fallback は preset 未指定時のみ)。
+    "chart-line": { w: 640, h: 360 },
+    "chart-pie": { w: 640, h: 320 },
+    "chart-bar": { w: 640, h: 360 },
+    // Timeline / Radial 系 (CAR-994 Phase B)
+    "gantt-timeline": { w: 720, h: 360 },
+    "mind-map": { w: 720, h: 480 },
+    "mind-radial": { w: 640, h: 640 },
+    // Analytic 系 (CAR-994 Phase C)
+    "funnel-stages": { w: 560, h: 480 },
+    "quadrant-matrix": { w: 640, h: 480 },
+    "tree-hierarchy": { w: 720, h: 480 },
+    "journey-map": { w: 720, h: 480 },
+    // Shape-driven basement 8 (CAR-1099)
+    "shape-file": { w: 260, h: 200 },
+    "shape-folder": { w: 260, h: 200 },
+    "shape-cloud": { w: 320, h: 200 },
+    "shape-cylinder": { w: 260, h: 220 },
+    "shape-hexagon": { w: 280, h: 200 },
+    "shape-diamond": { w: 260, h: 200 },
+    "shape-stack": { w: 260, h: 220 },
+    "shape-person": { w: 220, h: 240 },
+    // Shape-driven software 6 (CAR-1111 Phase 2-B)
+    "shape-window": { w: 320, h: 200 },
+    "shape-terminal": { w: 340, h: 240 },
+    "shape-code-block": { w: 340, h: 220 },
+    "shape-kanban-card": { w: 300, h: 200 },
+    "shape-message-bubble": { w: 300, h: 200 },
+    "shape-gear": { w: 320, h: 320 },
+    // Shape-driven hardware 6 (CAR-1111 Phase 2-C)
+    "shape-server-rack": { w: 260, h: 260 },
+    "shape-network-node": { w: 300, h: 260 },
+    "shape-mobile-device": { w: 200, h: 260 },
+    "shape-iot-sensor": { w: 260, h: 240 },
+    "shape-robot-arm": { w: 260, h: 280 },
+    "shape-satellite": { w: 340, h: 260 },
+    // Shape-driven blockchain / web3 10 (CAR-1111 Phase 2-D)
+    "shape-smart-contract": { w: 300, h: 280 },
+    "shape-blockchain-block": { w: 280, h: 280 },
+    "shape-rpc-node": { w: 320, h: 260 },
+    "shape-wallet": { w: 300, h: 220 },
+    "shape-nft": { w: 260, h: 320 },
+    "shape-token": { w: 300, h: 320 },
+    "shape-blockchain": { w: 380, h: 220 },
+    "shape-bitcoin-chain": { w: 380, h: 220 },
+    "shape-ethereum-chain": { w: 380, h: 220 },
+    "shape-blockchain-node": { w: 300, h: 260 },
+    // Shape-driven finance 7 (CAR-1111 Phase 2-D)
+    "shape-bank": { w: 340, h: 260 },
+    "shape-trust-bank": { w: 340, h: 280 },
+    "shape-payment-provider": { w: 300, h: 260 },
+    "shape-credit-card": { w: 300, h: 220 },
+    "shape-brokerage": { w: 300, h: 300 },
+    "shape-exchange": { w: 380, h: 260 },
+    "shape-atm": { w: 260, h: 300 },
+    // Shape-driven commerce / web 6 (CAR-1111 Phase 2-D)
+    "shape-website": { w: 340, h: 280 },
+    "shape-storefront": { w: 340, h: 300 },
+    "shape-warehouse": { w: 340, h: 280 },
+    "shape-online-shop": { w: 260, h: 320 },
+    "shape-cdn-edge": { w: 320, h: 300 },
+    "shape-api-gateway": { w: 340, h: 280 },
+    // dynamic shape 5 (CAR: shape primitive) ... 汎用 container、
+    // author が w/h override 前提だがデフォルト固有値を持つ
+    "dyn-rect": { w: 120, h: 200 },
+    "dyn-circle": { w: 160, h: 160 },
+    "dyn-arc": { w: 180, h: 180 },
+    "dyn-wave": { w: 140, h: 180 },
+    "dyn-polygon": { w: 160, h: 160 },
+    // Shape-driven people 6 (CAR-1111 Phase 2-D)
+    "shape-auditor": { w: 280, h: 300 },
+    "shape-regulator": { w: 280, h: 320 },
+    "shape-notary": { w: 280, h: 320 },
+    "shape-lawyer": { w: 280, h: 300 },
+    "shape-trader": { w: 300, h: 300 },
+    "shape-customer-service": { w: 320, h: 300 },
+  } as Record<NodeKind, { w: number; h: number }>,
+
+  // row gap (stack 間の vertical gap、 lane 内 / 跨ぎ共通)
+  // edge label が node の上 36 px に配置されるため、 boxH 68 + 36 + 余裕 = 100 必要。
+  // pill h / w / padding SSOT は `spec.ts` の LABEL_PILL_H_WITH_SUB / LABEL_PILL_H_MAIN_ONLY /
+  // LABEL_PILL_PAD_X (CAR-431 で 3 定義箇所を集約)。
+  row_gap: 100,
+
+  // edge label parallel routing offset (SSOT はここで独立、 pill 高 / padding は spec.ts SSOT)
+  label: {
+    parallel_x_offset: 140,
+    parallel_y_offset: 50,
+    clearance_to_path: 18,
+    clearance_to_node: 16,
+  },
+
+  // edge stroke
+  edge: {
+    active_w: 3.5,
+    inactive_w: 2,
+    glow_w: 14,
+    inactive_dash: "4 5",
+  },
+} as const;
+
+// 互換 alias (既存 layout 関数が参照)
+export const LANE_LABEL_H = TOKENS.lane_label_h;
+export const LANE_TOP_PAD = TOKENS.lane_top_pad;
+export const STACK_GAP = TOKENS.row_gap;
+export const NODE_SIZE = TOKENS.node;
+export const CONTAIN_PAD = TOKENS.contain_pad;
+export const VIEW_PAD = TOKENS.view_pad;
+export const HEADER_RESERVE = TOKENS.header_reserve;
+export const LANE_AUTO_GAP = 80;
+
+/**
+ * viewport.laneGap / nodeGap / labelMargin の default (CdlViewport で author 上書き可)。
+ *
+ * - DEFAULT_LANE_GAP=80 ... lanes 間 horizontal gap (LANE_AUTO_GAP と同値、 lane 自動配置で使用)
+ * - DEFAULT_NODE_GAP=24 ... nodes 間 vertical gap、 row_gap=100 の base に追加する増分として扱う
+ *   (row_gap は edge label + node 余白を含む total なので、 nodeGap は author 追加 padding として加算)
+ * - DEFAULT_LABEL_MARGIN=8 ... edge label 周辺余白、 author offset として label x/y 計算に加算
+ */
+export const DEFAULT_LANE_GAP = 80;
+export const DEFAULT_NODE_GAP = 24;
+export const DEFAULT_LABEL_MARGIN = 8;
+
+/**
+ * lane を node 幅に合わせて広げる時の左右余白の下限 (world unit)。
+ *
+ * 著者が lane を十分に離して置いている図では、 policy を満たすための埋め合わせが要らない。
+ * その場合に lane が node に張り付かないよう、 見た目の余白としてこの値を下限に使う。
+ * 実際の余白は `expandLanesForNodes` が policy から逆算した値と本値の大きい方になる。
+ */
+export const LANE_PAD_MIN = 25;

package/src/layout/viewbox.ts

@@ -0,0 +1,47 @@
+import type { BBox, CdlViewport, LaidEdge, LaidLane, LaidNode } from "../types";
+import { footerShapeDrops } from "./footer-shape";
+import { VIEW_PAD } from "./tokens";
+
+export function computeViewBox(
+  lanes: LaidLane[],
+  nodes: LaidNode[],
+  edges: LaidEdge[],
+  bboxes: BBox[],
+  viewport?: CdlViewport,
+): { x: number; y: number; w: number; h: number } {
+  let maxX = 0;
+  let maxY = 0;
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  for (const bbox of bboxes) {
+    maxX = Math.max(maxX, bbox.x + bbox.w);
+    maxY = Math.max(maxY, bbox.y + bbox.h);
+    minX = Math.min(minX, bbox.x);
+    minY = Math.min(minY, bbox.y);
+  }
+  for (const lane of lanes) {
+    maxX = Math.max(maxX, lane.x + lane.width);
+    maxY = Math.max(maxY, lane.y + lane.height);
+  }
+  for (const n of nodes) {
+    maxX = Math.max(maxX, n.cx + n.w / 2);
+    maxY = Math.max(maxY, n.cy + n.h / 2);
+  }
+  // 下端の名札で下げた絵は箱より下に出る (`footerShapeDrops`)。 その分を図の下端に含めないと
+  // 絵と名前が viewBox の外に落ちて切れる = `<svg>` は既定で外側を描かない。
+  const footerDrops = footerShapeDrops(lanes, nodes);
+  for (const n of nodes) {
+    const dy = footerDrops.get(n.id);
+    if (dy !== undefined) maxY = Math.max(maxY, n.cy + n.h / 2 + dy);
+  }
+  if (!Number.isFinite(minX)) minX = 0;
+  if (!Number.isFinite(minY)) minY = 0;
+  const x = minX - VIEW_PAD;
+  const y = minY - VIEW_PAD;
+  let w = maxX - x + VIEW_PAD;
+  let h = maxY - y + VIEW_PAD;
+  // viewport で author が明示宣言した場合は最低 size として強制 (auto 計算結果が小さければそれを優先)
+  if (viewport?.width !== undefined && viewport.width > w) w = viewport.width;
+  if (viewport?.height !== undefined && viewport.height > h) h = viewport.height;
+  return { x, y, w, h };
+}

package/src/layout-with-validation.ts

@@ -0,0 +1,175 @@
+/**
+ * layout + visualValidate を 1 回 loop 化して自動修復する SSOT 経路。
+ *
+ * `layout()` は 1 pass の layout 計算、 17 軸 visualValidate の warn / error は fixWithRetry で
+ * 3 loop まで自動修復を試みる。 修復不能な error は throw 前に戻り値の `report.violations` に集約。
+ *
+ * 呼出しモデル。
+ *  - CI / test = `layoutWithValidation(diag, { fix: false })` で diagnose のみ
+ *  - dragon build = `layoutWithValidation(diag)` (fix default true) で修復 pass
+ *  - 開発中 = `layoutWithValidation(diag, { emitConsole: true })` で warn を console に流す
+ *
+ * 修復 heuristics (順次適用、 1 loop で全 heuristic を試行 → 再 validate)。
+ *  - h1 label-offset-reset ... label-char-range / label-inside-viewbox / edge-label-overlap を
+ *      持つ edge の labelOffsetX/Y を 0 にリセット (作者の手動 offset で bbox 範囲外に押し出された
+ *      label を default 位置に戻す)
+ *  - h2 node-shift-down ... node-overlap error node pair の下 node の stack を +1
+ *  - h3 edge-back-detour ... edge-node-cross error edge の routing を "back-detour" に切替
+ */
+import type { CdlDiagram, CdlEdge, LaidDiagram } from "./types";
+import { layout } from "./layout";
+import { visualValidate, type Violation, type VisualValidationReport } from "./visual-validate";
+
+export interface LayoutWithValidationOptions {
+  /** 修復 loop の最大回数 (default 3)。 0 で修復 skip。 */
+  maxFixLoops?: number;
+  /** true なら warn / error を console.warn / console.error に流す (dev のみ推奨)。 */
+  emitConsole?: boolean;
+  /** true なら修復 heuristics 適用、 false なら diagnose のみ (default true)。 */
+  fix?: boolean;
+}
+
+export interface LayoutWithValidationResult {
+  laid: LaidDiagram;
+  report: VisualValidationReport;
+  /** 実際に走った修復 loop 数 (0 = 修復不要 or fix:false or maxFixLoops:0) */
+  fixLoops: number;
+  /** loop ごとに適用された heuristic 名の履歴 */
+  appliedHeuristics: string[];
+}
+
+export function layoutWithValidation(
+  diag: CdlDiagram,
+  opts: LayoutWithValidationOptions = {},
+): LayoutWithValidationResult {
+  const maxLoops = opts.maxFixLoops ?? 3;
+  const doFix = opts.fix ?? true;
+
+  let currentDiag: CdlDiagram = diag;
+  let laid: LaidDiagram = layout(currentDiag);
+  let report: VisualValidationReport = visualValidate(currentDiag);
+  const appliedHeuristics: string[] = [];
+  let fixLoops = 0;
+
+  while (doFix && fixLoops < maxLoops && needsRetry(report.violations)) {
+    const nextDiag = applyHeuristics(currentDiag, laid, report.violations, appliedHeuristics);
+    if (nextDiag === currentDiag) break;
+    currentDiag = nextDiag;
+    laid = layout(currentDiag);
+    report = visualValidate(currentDiag);
+    fixLoops++;
+  }
+
+  if (opts.emitConsole) {
+    for (const v of report.violations) {
+      if (v.severity === "error") {
+        console.error(`[cdl geometry ${v.axis}] ${v.detail} (diagram=${v.diagramId})`);
+      } else {
+        console.warn(`[cdl geometry ${v.axis}] ${v.detail} (diagram=${v.diagramId})`);
+      }
+    }
+  }
+
+  return { laid, report, fixLoops, appliedHeuristics };
+}
+
+const RETRY_AXES = new Set([
+  "edge-label-overlap",
+  "edge-label-proximity",
+  "arrow-endpoint-anchoring",
+  "label-char-range",
+  "node-overlap",
+  "edge-crossing",
+  "edge-node-cross",
+  "label-inside-viewbox",
+]);
+
+function needsRetry(violations: Violation[]): boolean {
+  return violations.some((v) => RETRY_AXES.has(v.axis));
+}
+
+function applyHeuristics(
+  diag: CdlDiagram,
+  laid: LaidDiagram,
+  violations: Violation[],
+  applied: string[],
+): CdlDiagram {
+  let mutated = false;
+  let edges = diag.edges;
+  let nodes = diag.nodes;
+
+  const h1Edges = new Set(
+    violations
+      .filter(
+        (v) =>
+          v.axis === "label-char-range" ||
+          v.axis === "label-inside-viewbox" ||
+          v.axis === "edge-label-overlap",
+      )
+      .map((v) => extractEdgeId(v.detail))
+      .filter((id): id is string => id !== null),
+  );
+  if (h1Edges.size > 0) {
+    const originalEdges = edges;
+    edges = edges.map((e) =>
+      h1Edges.has(e.id) && (e.labelOffsetX || e.labelOffsetY)
+        ? { ...e, labelOffsetX: 0, labelOffsetY: 0 }
+        : e,
+    );
+    if (edges !== originalEdges) {
+      applied.push("h1-label-offset-reset");
+      mutated = true;
+    }
+  }
+
+  const h2NodeIds = new Set<string>();
+  for (const v of violations) {
+    if (v.axis !== "node-overlap") continue;
+    const pair = extractNodePair(v.detail);
+    if (pair) {
+      const a = laid.nodes.find((n) => n.id === pair.a);
+      const b = laid.nodes.find((n) => n.id === pair.b);
+      if (a && b) {
+        h2NodeIds.add(a.cy > b.cy ? pair.a : pair.b);
+      }
+    }
+  }
+  if (h2NodeIds.size > 0) {
+    const originalNodes = nodes;
+    nodes = nodes.map((n) => (h2NodeIds.has(n.id) ? { ...n, stack: n.stack + 1 } : n));
+    if (nodes !== originalNodes) {
+      applied.push("h2-node-shift-down");
+      mutated = true;
+    }
+  }
+
+  const h3Edges = new Set(
+    violations
+      .filter((v) => v.axis === "edge-node-cross")
+      .map((v) => extractEdgeId(v.detail))
+      .filter((id): id is string => id !== null),
+  );
+  if (h3Edges.size > 0) {
+    const originalEdges = edges;
+    edges = edges.map((e): CdlEdge =>
+      h3Edges.has(e.id) && e.routing !== "back-detour" ? { ...e, routing: "back-detour" } : e,
+    );
+    if (edges !== originalEdges) {
+      applied.push("h3-edge-back-detour");
+      mutated = true;
+    }
+  }
+
+  if (!mutated) return diag;
+  return { ...diag, edges, nodes };
+}
+
+function extractEdgeId(detail: string): string | null {
+  const m = detail.match(/edge "([^"]+)"/) ?? detail.match(/edge-label "([^"]+)"/);
+  return m ? m[1]! : null;
+}
+
+function extractNodePair(detail: string): { a: string; b: string } | null {
+  const m = detail.match(/node "([^"]+)" ↔ "([^"]+)"/);
+  return m ? { a: m[1]!, b: m[2]! } : null;
+}