@cardenelabs/cdl 0.48.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "description": "CDL (Chainome Diagram Language). Mermaid-like declarative DSL that compiles to animated SVG diagrams. Built for blockchain / Solidity flows, generic enough for sequence / flow / state / ER / topology diagrams.",
   "license": "MIT",
   "author": "cardene777",

package/src/layout/collisions.ts

@@ -2212,57 +2212,17 @@ export function resolveEdgeLabelOverlapsWithChainAndPropagate(
   };
 }
 
+/** 札の逃がし先を測るのに使う、 線の区間と外接矩形。 同じ図の中で使い回す (#810)。 */
+interface 線の測り方 {
+  readonly 区間: (id: string, d: string) => Seg[];
+  readonly 遠い: (box: BBox, edgeId: string, d: string, 余裕: number) => boolean;
+}
+
 /**
- * 経路を動かす pass の **後** に、 札だけを箱 ・ 札 ・ 線から離す (#659)。
- *
- * ## なぜ最終 pass が要るか
- *
- * `resolveEdgeLabelOverlapsWithChainAndPropagate` は経路を動かす 4 つの pass
- * (`bowSharedStraightPaths` / `pullOutgoingFirstCorner` / `fanIncomingEndpoints` /
- * `separateSharedStraightRuns`) の **前** に走る。 札の初期位置は経路から決まるため、
- * 後の pass が経路を動かすと札も一緒に動く。 動いた後を見る者が誰も居なかった。
- *
- * 0.30.0 で `pullOutgoingFirstCorner` (#651) と `fanIncomingEndpoints` (#649) が経路を
- * 大きく動かすようになり、 消費側の見本帳で札が 11 件動いた (実測 = 最大 217 world)。
- * 動いた先が箱の近くだと `clearance` 軸の要求 (箱と札で 32) を割ったまま残る。
- * 実測 = 0.29.0 で 0 件だった違反が 0.30.1 で 9 件。
- *
- * ## 何を動かすか
- *
- * **札だけを動かす**。 箱と経路は動かさない = ここで経路を動かすと、 直前の 4 pass が
- * 確定させた形 (根元の重なり分け / 起点の直進) を崩すことになる。
- *
- * 判定は門 (`detectNearCollisions`) と同じ `requiredNearClearance` ・ `computeGap` ・
- * `measurePathLabelGapSegs` を引く。 別の式で近似すると、 門は落ちるのに押し出しは動かない
- * 状態に戻る。
- *
- * ## 行き先を確かめてから動かす
- *
- * 一番安く済む軸へ出すだけだと、 上下や左右の箱に挟まれた札が往復して収束しない
- * (実測 = 箱 2 つの間で 16 下げて 4 上げるのを繰り返す)。
- * 軸ごとに行き先を作り、 **他のどの箱 ・ 札 ・ 線とも今より近づかない** 向きだけを採る。
- * どの向きも安全でなければ動かさない = 直せなかったことは門が引き続き報告する。
- *
- * ## 動かしすぎない
- *
- * 累積は `CHAIN_SHIFT_MAX_ACCUMULATED` で頭を打つ。 札は自分の線の近くに居ることが
- * 読みの前提で、 離しすぎるとどの線の札か判らなくなる。
+ * 線の測り方を作る。 逃がし pass と、 門が「なぜ動かせなかったか」 を説明する側
+ * (`札が動けない理由`) の両方が使う = 2 箇所で別に書くと、 片方だけ直してずれる。
  */
-export function resolveLabelClearanceAfterPathPasses(
-  edges: LaidEdge[],
-  obstacles: BBox[],
-  maxIter = 8,
-): LaidEdge[] {
-  if (edges.length === 0) return edges;
-
-  const labeledIds = new Set(
-    edges.filter((e) => e.label?.trim() || e.sub?.trim()).map((e) => e.id),
-  );
-  if (labeledIds.size === 0) return edges;
-
-  const 箱たち = obstacles.filter((o) => o.kind === "node" || o.kind === "lane-label");
-  const edgeById = new Map<string, LaidEdge>();
-  for (const e of edges) edgeById.set(e.id, e);
+function 線の測り方を作る(): 線の測り方 {
   /*
    * 線の区間は **曲線を開いた形** で持つ (`detectCollisions` の札 branch と同じ)。
    *
@@ -2313,12 +2273,287 @@ export function resolveLabelClearanceAfterPathPasses(
     return Math.hypot(dx, dy) >= 余裕;
   };
 
+  return { 区間, 遠い };
+}
+
+/*
+ * 動かす量の頭。 読みの上限は「自分の線から離れすぎない」 ことで、 それは `安全か` が
+ * 距離そのもので見る。 ここは念のための頭で、 chain 伝搬の頭 (`CHAIN_SHIFT_MAX_ACCUMULATED`)
+ * より緩くしてよい = この pass は札しか動かさず、 箱や経路を引きずらない。
+ */
+const 札の最大移動 = CHAIN_SHIFT_MAX_ACCUMULATED * 2;
+
+/** 軸ごとの離れ量。 重なっている時は負になる */
+const 離れ量 = (a: BBox, b: BBox): { x: number; y: number } => ({
+  x: Math.max(a.x - (b.x + b.w), b.x - (a.x + a.w)),
+  y: Math.max(a.y - (b.y + b.h), b.y - (a.y + a.h)),
+});
+
+const 動かした箱 = (box: BBox, axis: "x" | "y", sign: 1 | -1, amount: number): BBox => ({
+  ...box,
+  x: box.x + (axis === "x" ? sign * amount : 0),
+  y: box.y + (axis === "y" ? sign * amount : 0),
+});
+
+/** 札の逃がし候補。 軸 ・ 向き ・ 量 */
+type 逃がし候補 = { axis: "x" | "y"; sign: 1 | -1; amount: number };
+
+/** 札を 1 つ動かした先で、 いまより近づいてしまう相手 (#810)。 */
+export interface 札の移動を塞ぐ相手 {
+  /** `種類:id`。 自分の線から離れすぎる時は `自分の線` */
+  readonly 相手: string;
+  /** 動かす前の隙間 */
+  readonly 前: number;
+  /** 動かした後の隙間 */
+  readonly 後: number;
+}
+
+/** 札を動かす判定に使う、 図の中の相手 */
+interface 札の周り {
+  readonly 箱たち: readonly BBox[];
+  readonly labels: readonly BBox[];
+  readonly edges: readonly LaidEdge[];
+  readonly edgeById: ReadonlyMap<string, LaidEdge>;
+  readonly 測り方: 線の測り方;
+}
+
+/**
+ * 札 1 つを動かした先が、 いまより近づく相手を作らないか。 作るなら最初の 1 つを返す。
+ *
+ * 逃がし pass の `安全か` と、 門の説明 (`札が動けない理由`) が同じものを引く (#810)。
+ * 2 箇所で別に書くと、 「pass は動かせないのに説明は動かせると言う」 ずれが生まれる。
+ */
+function 札の移動を塞ぐ相手を探す(
+  周り: 札の周り,
+  label: BBox,
+  行き先: BBox,
+): 札の移動を塞ぐ相手 | null {
+  const { 箱たち, labels, edges, edgeById, 測り方 } = 周り;
+  for (const obs of 箱たち) {
+    const 前 = computeGap(label, obs);
+    const 後 = computeGap(行き先, obs);
+    if (後 < Math.min(前, requiredNearClearance("edge-label", obs.kind))) return { 相手: `${obs.kind}:${obs.id}`, 前, 後 };
+  }
+  const 札の要求 = requiredNearClearance("edge-label", "edge-label");
+  for (const 他 of labels) {
+    if (他.id === label.id) continue;
+    const 前 = computeGap(label, 他);
+    const 後 = computeGap(行き先, 他);
+    if (後 < Math.min(前, 札の要求)) return { 相手: `edge-label:${他.id}`, 前, 後 };
+  }
+  // 線との距離は重いので最後に見る。 ここまでで落ちる候補が大半。
+  const 自分 = edgeById.get(label.id);
+  const 自分の区間 = 自分 ? 測り方.区間(自分.id, 自分.d) : [];
   /*
-   * 動かす量の頭。 読みの上限は「自分の線から離れすぎない」 ことで、 それは `安全か` が
-   * 距離そのもので見る。 ここは念のための頭で、 chain 伝搬の頭 (`CHAIN_SHIFT_MAX_ACCUMULATED`)
-   * より緩くしてよい = この pass は札しか動かさず、 箱や経路を引きずらない。
+   * **自分の線から離れすぎない**。 札は自分の線の近くに在ることが読みの前提で、
+   * 離すと どの線の説明なのかが判らなくなる。 いま既に離れている札はそれ以上離さない。
    */
-  const 最大移動 = CHAIN_SHIFT_MAX_ACCUMULATED * 2;
+  if (自分の区間.length > 0) {
+    const 前 = measurePathLabelGapSegs(自分の区間, label);
+    const 後 = measurePathLabelGapSegs(自分の区間, 行き先);
+    if (後 > Math.max(前, DIST_LABEL_PATH_MAX)) return { 相手: "自分の線", 前, 後 };
+  }
+  for (const 相手 of edges) {
+    if (相手.id === label.id) continue;
+    // 動かす前も後も要求ぶん離れている線は、 測らずに落とす。
+    if (測り方.遠い(label, 相手.id, 相手.d, LABEL_TO_PATH_CLEARANCE) && 測り方.遠い(行き先, 相手.id, 相手.d, LABEL_TO_PATH_CLEARANCE)) continue;
+    const segs = segmentsExcludingOwnPath(測り方.区間(相手.id, 相手.d), 自分の区間);
+    if (segs.length === 0) continue;
+    const 前 = measurePathLabelGapSegs(segs, label);
+    const 後 = measurePathLabelGapSegs(segs, 行き先);
+    if (後 < Math.min(前, LABEL_TO_PATH_CLEARANCE)) return { 相手: `edge-path:${相手.id}`, 前, 後 };
+  }
+  return null;
+}
+
+/** 矩形どうしが要求を満たしていない時の、 軸ごとの逃がし候補 */
+function 矩形の候補(
+  label: BBox,
+  static箱: BBox,
+  required: number,
+): 逃がし候補[] {
+  const sep = 離れ量(label, static箱);
+  const 向き = (axis: "x" | "y"): 1 | -1 => {
+    const a = axis === "x" ? label.x + label.w / 2 : label.y + label.h / 2;
+    const b = axis === "x" ? static箱.x + static箱.w / 2 : static箱.y + static箱.h / 2;
+    return a >= b ? 1 : -1;
+  };
+  return [
+    { axis: "x" as const, sign: 向き("x"), amount: required - sep.x + NEAR_MISS_MARGIN },
+    { axis: "y" as const, sign: 向き("y"), amount: required - sep.y + NEAR_MISS_MARGIN },
+  ];
+}
+
+/**
+ * 札を軸の向きへ動かして、 線から `LABEL_TO_PATH_CLEARANCE` 離れるのに要る量。
+ * 上限 (`札の最大移動`) まで伸ばしても満たせない向きは `null`。
+ */
+function 線から離れる量(
+  segs: Seg[],
+  label: BBox,
+  gap: number,
+  axis: "x" | "y",
+  sign: 1 | -1,
+): number | null {
+  const 最大移動 = 札の最大移動;
+  const 満たす = (量: number): boolean =>
+    measurePathLabelGapSegs(segs, 動かした箱(label, axis, sign, 量)) >= LABEL_TO_PATH_CLEARANCE;
+  let lo = 0;
+  let hi = Math.max(4, LABEL_TO_PATH_CLEARANCE - gap);
+  // **上限そのものを試してから諦める**。 2 倍で伸ばした値が上限を跨いだ所で打ち切ると、
+  // 上限内に満たす量があっても見つけられない (実測 = 83 で足りるのに 128 で諦めていた)。
+  while (!満たす(hi)) {
+    if (hi >= 最大移動) return null;
+    lo = hi;
+    hi = Math.min(hi * 2, 最大移動);
+  }
+  for (let k = 0; k < 12; k += 1) {
+    const mid = (lo + hi) / 2;
+    if (満たす(mid)) hi = mid;
+    else lo = mid;
+  }
+  return hi + NEAR_MISS_MARGIN;
+}
+
+/** 報告に出す向きの呼び名。 並べる順もこの順にする */
+const 向きの順: ReadonlyArray<{ axis: "x" | "y"; sign: 1 | -1; 名前: string }> = [
+  { axis: "y", sign: -1, 名前: "上" },
+  { axis: "y", sign: 1, 名前: "下" },
+  { axis: "x", sign: -1, 名前: "左" },
+  { axis: "x", sign: 1, 名前: "右" },
+];
+
+/**
+ * 門が `clearance` の違反を報告する時に、 札が **なぜ動けなかったか** を 1 行で返す (#810)。
+ *
+ * 違反の報告は「どの 2 つが何 px で、 要求が何 px か」 しか持たない。 読んだ人が次に知りたいのは
+ * 「なぜ engine はこれを直せなかったのか」 で、 それを探すのに層を 3 つ読む必要があった。
+ * 理由は逃がし pass の中で分かっている = 向きごとに行き先を作り、 塞ぐ相手が居る向きを捨てている。
+ *
+ * **最終の位置から測り直す**。 layout の途中の記録を運ぶと、 途中で逃がせたが別の pass で押し戻された
+ * 形や、 走査を打ち切った形で、 古い理由が残る。 逃がし pass と同じ候補 ・ 同じ判定
+ * (`札の移動を塞ぐ相手を探す`) を最終の位置で試せば、 報告と実物がずれない。
+ *
+ * どれか 1 つの向きでも安全なら `null` を返す = 動けるのに動いていない形について、
+ * 「塞がれている」 と言うのは誤り。
+ *
+ * @param labelId 動かせなかった札の辺 id
+ * @param 相手 違反の相手 (箱 / 縦列の題 / 別の札 / 別の線)
+ * @param edges 図の全ての辺 (最終の位置)
+ * @param obstacles 箱と縦列の題の矩形
+ */
+export function 札が動けない理由(
+  labelId: string,
+  相手: BBox,
+  edges: readonly LaidEdge[],
+  obstacles: readonly BBox[],
+): string | null {
+  const edgeById = new Map(edges.map((e) => [e.id, e] as const));
+  const 自分 = edgeById.get(labelId);
+  if (!自分) return null;
+  const labels: BBox[] = edges
+    .filter((e) => e.label?.trim() || e.sub?.trim())
+    .map((e) => ({ kind: "edge-label" as const, id: e.id, ...computeLabelBBoxWorld(e) }));
+  const label = labels.find((l) => l.id === labelId);
+  if (!label) return null;
+  const 測り方 = 線の測り方を作る();
+  const 周り: 札の周り = {
+    箱たち: obstacles.filter((o) => o.kind === "node" || o.kind === "lane-label"),
+    labels,
+    edges,
+    edgeById,
+    測り方,
+  };
+
+  // 逃がし pass と同じ候補を作る。 線が相手なら 4 つの向き、 矩形が相手なら離れる側の 2 つ。
+  const 候補: Array<{ axis: "x" | "y"; sign: 1 | -1; amount: number | null }> = [];
+  if (相手.kind === "edge-path") {
+    const 線 = edgeById.get(相手.id);
+    if (!線) return null;
+    const segs = segmentsExcludingOwnPath(測り方.区間(線.id, 線.d), 測り方.区間(自分.id, 自分.d));
+    if (segs.length === 0) return null;
+    const gap = measurePathLabelGapSegs(segs, label);
+    for (const 向き of 向きの順) {
+      候補.push({ axis: 向き.axis, sign: 向き.sign, amount: 線から離れる量(segs, label, gap, 向き.axis, 向き.sign) });
+    }
+  } else {
+    const required = requiredNearClearance("edge-label", 相手.kind);
+    for (const c of 矩形の候補(label, 相手, required)) {
+      // 既に離れている軸は候補にしない (逃がし pass も量 0 以下を飛ばす)
+      if (c.amount > 0) 候補.push(c);
+    }
+  }
+  if (候補.length === 0) return null;
+
+  const 理由: Array<{ 順: number; 文: string }> = [];
+  for (const c of 候補) {
+    const 順 = 向きの順.findIndex((v) => v.axis === c.axis && v.sign === c.sign);
+    const 名前 = 向きの順[順]!.名前;
+    if (c.amount === null || c.amount > 札の最大移動) {
+      理由.push({ 順, 文: `${名前}=上限 ${札の最大移動} を越える` });
+      continue;
+    }
+    const 塞ぐ = 札の移動を塞ぐ相手を探す(周り, label, 動かした箱(label, c.axis, c.sign, c.amount));
+    if (!塞ぐ) return null;
+    理由.push({ 順, 文: `${名前}=${塞ぐ.相手} (${塞ぐ.前.toFixed(0)}→${塞ぐ.後.toFixed(0)})` });
+  }
+  return `逃げ場なし: ${理由.sort((a, b) => a.順 - b.順).map((r) => r.文).join(" / ")}`;
+}
+
+/**
+ * 経路を動かす pass の **後** に、 札だけを箱 ・ 札 ・ 線から離す (#659)。
+ *
+ * ## なぜ最終 pass が要るか
+ *
+ * `resolveEdgeLabelOverlapsWithChainAndPropagate` は経路を動かす 4 つの pass
+ * (`bowSharedStraightPaths` / `pullOutgoingFirstCorner` / `fanIncomingEndpoints` /
+ * `separateSharedStraightRuns`) の **前** に走る。 札の初期位置は経路から決まるため、
+ * 後の pass が経路を動かすと札も一緒に動く。 動いた後を見る者が誰も居なかった。
+ *
+ * 0.30.0 で `pullOutgoingFirstCorner` (#651) と `fanIncomingEndpoints` (#649) が経路を
+ * 大きく動かすようになり、 消費側の見本帳で札が 11 件動いた (実測 = 最大 217 world)。
+ * 動いた先が箱の近くだと `clearance` 軸の要求 (箱と札で 32) を割ったまま残る。
+ * 実測 = 0.29.0 で 0 件だった違反が 0.30.1 で 9 件。
+ *
+ * ## 何を動かすか
+ *
+ * **札だけを動かす**。 箱と経路は動かさない = ここで経路を動かすと、 直前の 4 pass が
+ * 確定させた形 (根元の重なり分け / 起点の直進) を崩すことになる。
+ *
+ * 判定は門 (`detectNearCollisions`) と同じ `requiredNearClearance` ・ `computeGap` ・
+ * `measurePathLabelGapSegs` を引く。 別の式で近似すると、 門は落ちるのに押し出しは動かない
+ * 状態に戻る。
+ *
+ * ## 行き先を確かめてから動かす
+ *
+ * 一番安く済む軸へ出すだけだと、 上下や左右の箱に挟まれた札が往復して収束しない
+ * (実測 = 箱 2 つの間で 16 下げて 4 上げるのを繰り返す)。
+ * 軸ごとに行き先を作り、 **他のどの箱 ・ 札 ・ 線とも今より近づかない** 向きだけを採る。
+ * どの向きも安全でなければ動かさない = 直せなかったことは門が引き続き報告する。
+ *
+ * ## 動かしすぎない
+ *
+ * 累積は `CHAIN_SHIFT_MAX_ACCUMULATED` で頭を打つ。 札は自分の線の近くに居ることが
+ * 読みの前提で、 離しすぎるとどの線の札か判らなくなる。
+ */
+export function resolveLabelClearanceAfterPathPasses(
+  edges: LaidEdge[],
+  obstacles: BBox[],
+  maxIter = 8,
+): LaidEdge[] {
+  if (edges.length === 0) return edges;
+
+  const labeledIds = new Set(
+    edges.filter((e) => e.label?.trim() || e.sub?.trim()).map((e) => e.id),
+  );
+  if (labeledIds.size === 0) return edges;
+
+  const 箱たち = obstacles.filter((o) => o.kind === "node" || o.kind === "lane-label");
+  const edgeById = new Map<string, LaidEdge>();
+  for (const e of edges) edgeById.set(e.id, e);
+  const 測り方 = 線の測り方を作る();
+  const { 区間, 遠い } = 測り方;
+  const 最大移動 = 札の最大移動;
 
   const shiftMap = new Map<string, { dx: number; dy: number }>();
   const getShift = (id: string): { dx: number; dy: number } =>
@@ -2335,18 +2570,6 @@ export function resolveLabelClearanceAfterPathPasses(
     return out;
   };
 
-  /** 軸ごとの離れ量。 重なっている時は負になる */
-  const 離れ量 = (a: BBox, b: BBox): { x: number; y: number } => ({
-    x: Math.max(a.x - (b.x + b.w), b.x - (a.x + a.w)),
-    y: Math.max(a.y - (b.y + b.h), b.y - (a.y + a.h)),
-  });
-
-  const 動かした箱 = (box: BBox, axis: "x" | "y", sign: 1 | -1, amount: number): BBox => ({
-    ...box,
-    x: box.x + (axis === "x" ? sign * amount : 0),
-    y: box.y + (axis === "y" ? sign * amount : 0),
-  });
-
   for (let iter = 0; iter < maxIter; iter += 1) {
     const labels = labelBBoxes();
     const 札の要求 = requiredNearClearance("edge-label", "edge-label");
@@ -2360,47 +2583,13 @@ export function resolveLabelClearanceAfterPathPasses(
     const 今回動かした = new Set<string>();
 
     /** 札 1 つを動かした先が、 いまより近づく相手を作らないか */
-    const 安全か = (label: BBox, 行き先: BBox): boolean => {
-      for (const obs of 箱たち) {
-        const 前 = computeGap(label, obs);
-        const 後 = computeGap(行き先, obs);
-        if (後 < Math.min(前, requiredNearClearance("edge-label", obs.kind))) return false;
-      }
-      for (const 他 of labels) {
-        if (他.id === label.id) continue;
-        const 前 = computeGap(label, 他);
-        const 後 = computeGap(行き先, 他);
-        if (後 < Math.min(前, 札の要求)) return false;
-      }
-      // 線との距離は重いので最後に見る。 ここまでで落ちる候補が大半。
-      const 自分 = edgeById.get(label.id);
-      const 自分の区間 = 自分 ? 区間(自分.id, 自分.d) : [];
-      /*
-       * **自分の線から離れすぎない**。 札は自分の線の近くに在ることが読みの前提で、
-       * 離すと どの線の説明なのかが判らなくなる。 いま既に離れている札はそれ以上離さない。
-       */
-      if (自分の区間.length > 0) {
-        const 前 = measurePathLabelGapSegs(自分の区間, label);
-        const 後 = measurePathLabelGapSegs(自分の区間, 行き先);
-        if (後 > Math.max(前, DIST_LABEL_PATH_MAX)) return false;
-      }
-      for (const 相手 of edges) {
-        if (相手.id === label.id) continue;
-        // 動かす前も後も要求ぶん離れている線は、 測らずに落とす。
-        if (遠い(label, 相手.id, 相手.d, LABEL_TO_PATH_CLEARANCE) && 遠い(行き先, 相手.id, 相手.d, LABEL_TO_PATH_CLEARANCE)) continue;
-        const segs = segmentsExcludingOwnPath(区間(相手.id, 相手.d), 自分の区間);
-        if (segs.length === 0) continue;
-        const 前 = measurePathLabelGapSegs(segs, label);
-        const 後 = measurePathLabelGapSegs(segs, 行き先);
-        if (後 < Math.min(前, LABEL_TO_PATH_CLEARANCE)) return false;
-      }
-      return true;
-    };
+    const 安全か = (label: BBox, 行き先: BBox): boolean =>
+      札の移動を塞ぐ相手を探す({ 箱たち, labels, edges, edgeById, 測り方 }, label, 行き先) === null;
 
     /** 候補を安い順に試し、 行き先が安全な最初の 1 つを積む */
     const 逃がす = (
       label: BBox,
-      候補: Array<{ axis: "x" | "y"; sign: 1 | -1; amount: number }>,
+      候補: 逃がし候補[],
     ): boolean => {
       for (const c of 候補.slice().sort((a, b) => a.amount - b.amount)) {
         if (c.amount <= 0) continue;
@@ -2417,24 +2606,6 @@ export function resolveLabelClearanceAfterPathPasses(
       return false;
     };
 
-    /** 矩形どうしが要求を満たしていない時の、 軸ごとの逃がし候補 */
-    const 矩形の候補 = (
-      label: BBox,
-      static箱: BBox,
-      required: number,
-    ): Array<{ axis: "x" | "y"; sign: 1 | -1; amount: number }> => {
-      const sep = 離れ量(label, static箱);
-      const 向き = (axis: "x" | "y"): 1 | -1 => {
-        const a = axis === "x" ? label.x + label.w / 2 : label.y + label.h / 2;
-        const b = axis === "x" ? static箱.x + static箱.w / 2 : static箱.y + static箱.h / 2;
-        return a >= b ? 1 : -1;
-      };
-      return [
-        { axis: "x" as const, sign: 向き("x"), amount: required - sep.x + NEAR_MISS_MARGIN },
-        { axis: "y" as const, sign: 向き("y"), amount: required - sep.y + NEAR_MISS_MARGIN },
-      ];
-    };
-
     // 札 ↔ 箱 / 縦列の題。 障害物は動かさないので札だけを逃がす。
     for (const label of labels) {
       if (今回動かした.has(label.id)) continue;
@@ -2506,25 +2677,8 @@ export function resolveLabelClearanceAfterPathPasses(
          * 動かす量を 2 倍ずつ伸ばして満たす所を見つけ、 二分で詰める。 測り方は門と同じ
          * `measurePathLabelGapSegs` を使う。 上限まで伸ばしても満たせない向きは候補にしない。
          */
-        const 必要量 = (axis: "x" | "y", sign: 1 | -1): number | null => {
-          const 満たす = (量: number): boolean =>
-            measurePathLabelGapSegs(segs, 動かした箱(label, axis, sign, 量)) >= LABEL_TO_PATH_CLEARANCE;
-          let lo = 0;
-          let hi = Math.max(4, LABEL_TO_PATH_CLEARANCE - gap);
-          // **上限そのものを試してから諦める**。 2 倍で伸ばした値が上限を跨いだ所で打ち切ると、
-          // 上限内に満たす量があっても見つけられない (実測 = 83 で足りるのに 128 で諦めていた)。
-          while (!満たす(hi)) {
-            if (hi >= 最大移動) return null;
-            lo = hi;
-            hi = Math.min(hi * 2, 最大移動);
-          }
-          for (let k = 0; k < 12; k += 1) {
-            const mid = (lo + hi) / 2;
-            if (満たす(mid)) hi = mid;
-            else lo = mid;
-          }
-          return hi + NEAR_MISS_MARGIN;
-        };
+        const 必要量 = (axis: "x" | "y", sign: 1 | -1): number | null =>
+          線から離れる量(segs, label, gap, axis, sign);
         const dx = 芯.x - 近い点.x;
         const dy = 芯.y - 近い点.y;
         const 候補: Array<{ axis: "x" | "y"; sign: 1 | -1; amount: number }> = [];

package/src/layout-with-validation.ts

@@ -62,10 +62,12 @@ export function layoutWithValidation(
 
   if (opts.emitConsole) {
     for (const v of report.violations) {
+      // 理由は末尾に足す = `(diagram=...)` までの形を読む側を崩さない (#810)
+      const 理由 = v.reason !== undefined ? ` ${v.reason}` : "";
       if (v.severity === "error") {
-        console.error(`[cdl geometry ${v.axis}] ${v.detail} (diagram=${v.diagramId})`);
+        console.error(`[cdl geometry ${v.axis}] ${v.detail} (diagram=${v.diagramId})${理由}`);
       } else {
-        console.warn(`[cdl geometry ${v.axis}] ${v.detail} (diagram=${v.diagramId})`);
+        console.warn(`[cdl geometry ${v.axis}] ${v.detail} (diagram=${v.diagramId})${理由}`);
       }
     }
   }

package/src/visual-validate.ts

@@ -88,6 +88,7 @@ import {
   flattenPathSegments,
   measurePathLabelGapSegs,
   segmentsCrossRect,
+  札が動けない理由,
 } from "./layout/collisions";
 import { measureTextWidth } from "./layout/text-width";
 import { droppedLineIsHidden, labelPlan } from "./kinds/shape-region";
@@ -276,6 +277,14 @@ export interface Violation {
   diagramId: string;
   detail: string;
   severity: "error" | "warn";
+  /**
+   * engine がなぜ直せなかったか (#810)。 分かる時だけ付く。
+   *
+   * `detail` とは別の欄に置く = `detail` は「どの 2 つが何 px か」 を固定の形で持ち、
+   * 消費側がそこから id を読み取っている。 理由を `detail` に足すと、 理由の中の id まで
+   * 違反の対象として拾われる。
+   */
+  reason?: string;
 }
 
 export type VisualAxis =
@@ -1447,12 +1456,23 @@ export function visualValidateLaid(
   const counts = emptyCounts();
   const profile = opts?.profile ?? "production";
   const skipped = SKIPPED_AXES[profile];
-  const push = (axis: VisualAxis, detail: string, severity: "error" | "warn" = "error") => {
+  const push = (
+    axis: VisualAxis,
+    detail: string,
+    severity: "error" | "warn" = "error",
+    reason?: string,
+  ) => {
     // 用途に合わない軸は数えない。
     if (skipped.has(axis)) return;
     // `diag` は壊れた形でも渡りうる (`#393`)。 報告そのものが例外になると、 壊れている
     // ことを伝える手段が無くなる。
-    violations.push({ axis, diagramId: safeDiagramId(diag), detail, severity });
+    violations.push({
+      axis,
+      diagramId: safeDiagramId(diag),
+      detail,
+      severity,
+      ...(reason !== undefined ? { reason } : {}),
+    });
     counts[axis]++;
   };
 
@@ -1479,10 +1499,21 @@ export function visualValidate(diag: CdlDiagram, opts?: ValidateOptions): Visual
   const counts = emptyCounts();
   const profile = opts?.profile ?? "production";
   const skipped = SKIPPED_AXES[profile];
-  const push = (axis: VisualAxis, detail: string, severity: "error" | "warn" = "error") => {
+  const push = (
+    axis: VisualAxis,
+    detail: string,
+    severity: "error" | "warn" = "error",
+    reason?: string,
+  ) => {
     // 用途に合わない軸は数えない。 見なかった軸は report の `skippedAxes` に載せる。
     if (skipped.has(axis)) return;
-    violations.push({ axis, diagramId: safeDiagramId(diag), detail, severity });
+    violations.push({
+      axis,
+      diagramId: safeDiagramId(diag),
+      detail,
+      severity,
+      ...(reason !== undefined ? { reason } : {}),
+    });
     counts[axis]++;
   };
 
@@ -1852,7 +1883,7 @@ function visualValidateInner(
   diag: CdlDiagram,
   violations: Violation[],
   counts: Record<VisualAxis, number>,
-  push: (axis: VisualAxis, detail: string, severity?: "error" | "warn") => void,
+  push: (axis: VisualAxis, detail: string, severity?: "error" | "warn", reason?: string) => void,
   profile: ValidationProfile,
   skippedAxes: VisualAxis[],
   /** 軸 23 が基準にする器。 入口で確かめ済 (`器を確かめる`)。 高さ `undefined` は上限なし。 */
@@ -1909,7 +1940,7 @@ function runAxes(
   diag: CdlDiagram,
   violations: Violation[],
   counts: Record<VisualAxis, number>,
-  push: (axis: VisualAxis, detail: string, severity?: "error" | "warn") => void,
+  push: (axis: VisualAxis, detail: string, severity?: "error" | "warn", reason?: string) => void,
   profile: ValidationProfile,
   skippedAxes: VisualAxis[],
   /** 軸 23 が基準にする器。 入口で確かめ済 (`器を確かめる`)。 高さ `undefined` は上限なし。 */
@@ -2046,10 +2077,35 @@ function runAxes(
   // Axis 6: clearance (near collision 0 件、 CLEARANCE_POLICY 違反)
   // ───────────────────────────────────────────────────────────
   const nears = detectNearCollisions(bboxes, laid.edges);
+  /*
+   * 札が絡む違反には、 engine がなぜ動かせなかったかを添える (#810)。
+   *
+   * 動かす側は逃がし pass と同じ = 札どうしなら後に書いた方 (`resolveLabelClearanceAfterPathPasses`
+   * が後の方を動かす)、 札と別の物なら札。 札の絡まない違反 (箱どうし等) には添えない。
+   */
+  const 札の障害物 = bboxes.filter((b) => b.kind === "node" || b.kind === "lane-label");
+  const 辺の順 = new Map(laid.edges.map((e, i) => [e.id, i] as const));
   for (const n of nears) {
+    const aは札 = n.a.kind === "edge-label";
+    const bは札 = n.b.kind === "edge-label";
+    const 動かす =
+      aは札 && bは札
+        ? (辺の順.get(n.a.id) ?? 0) > (辺の順.get(n.b.id) ?? 0)
+          ? n.a
+          : n.b
+        : aは札
+          ? n.a
+          : bは札
+            ? n.b
+            : null;
+    const 相手 = 動かす === n.a ? n.b : n.a;
+    const reason =
+      動かす !== null ? (札が動けない理由(動かす.id, 相手, laid.edges, 札の障害物) ?? undefined) : undefined;
     push(
       "clearance",
       `${n.a.kind}:${n.a.id} ↔ ${n.b.kind}:${n.b.id} gap=${n.gap.toFixed(1)}px (need ${n.required}px)`,
+      "error",
+      reason,
     );
   }