@cardenelabs/cdl 0.41.0 → 0.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cardenelabs/cdl",
-  "version": "0.41.0",
+  "version": "0.42.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/spec.ts

@@ -581,9 +581,14 @@ export function requiredVerticalLabelGap(pillHs: readonly number[]): number {
  * `computeLabelBBoxWorld` は本 helper を呼出、 layout/edges.ts routePathL は labelX / labelY
  * 未確定の段階で幅だけ必要なので本 helper を単独で呼ぶ。
  *
- * 返す値は **偶数に切り上げる**。 label 位置は `経路の端 + 余白 + 幅 / 2` で決まり、
- * 文字幅の実測値をそのまま使うと半端な小数が乗って輪郭がにじむ (`subpixel-precision` 軸)。
- * 幅を偶数にすると `幅 / 2` が整数になり、 端と余白が整数である限り位置も整数に揃う。
+ * 返す値は **偶数に切り上げる**。 label 位置は `経路の端 + 余白 + 幅 / 2` で決まるので、
+ * 幅を偶数にすると `幅 / 2` が整数になり、 端と余白が整数である限り位置も 0.5 刻みに乗る。
+ *
+ * 元の根拠は「半端な小数が乗ると輪郭がにじむ」 だったが、 にじみは device pixel で起きる
+ * のに世界座標を見ていたため、 それを測っていた軸 33 は `#783` で畳んだ。 丸め自体は残す =
+ * 外すと全ての label が動く一方、 動かして良くなるものが無いため。 固定するのは
+ * 「座標が 0.5 刻みに乗る」 という性質で、 画面上のにじみは主張しない
+ * (`test/label-coord-half-grid.test.ts`)。
  *
  * 切り下げでなく切り上げるのは、 幅を狭める向きの丸めが節や他の label との間隔を
  * 減らすため。 広げる向きなら間隔は増える一方で、 増分は 2 world 未満に収まる

package/src/visual-validate.ts

@@ -316,8 +316,8 @@ export type VisualAxis =
   // CAR-Z5 (PR #84) 追加 = SVG filter / marker / gradient integrity 4 領域。
   | "color-blind-safety"
   | "marker-gradient-def-integrity"
-  // CAR-Z6 (PR #85) 追加 = subpixel / DOM complexity / motion / touch 4 領域。
-  | "subpixel-precision"
+  // CAR-Z6 (PR #85) 追加 = DOM complexity / motion / touch 3 領域
+  // (subpixel は #783 で削除)。
   | "dom-complexity-budget"
   | "reduced-motion-compat"
   | "touch-target-size"
@@ -471,7 +471,6 @@ function emptyCounts(): Record<VisualAxis, number> {
     "print-media-compat": 0,
     "color-blind-safety": 0,
     "marker-gradient-def-integrity": 0,
-    "subpixel-precision": 0,
     "dom-complexity-budget": 0,
     "reduced-motion-compat": 0,
     "touch-target-size": 0,
@@ -1217,8 +1216,11 @@ export function countEdgeCrossings(
    * 分割片どうしの比較回数の上限。
    *
    * 辺の総当たりで、 各対の分割片を全比較する。 曲線 380 本の図では 1850 万回になり 264ms
-   * かかった (実測)。 1 図あたりの予算は `PERF_BUDGET_PER_DIAGRAM_MS` = 100 で、 他の軸が
-   * 150ms 前後使うため本軸に使えるのは僅か。
+   * かかった (実測)。 他の軸が 1 図あたり 150ms 前後を使うため、 本軸に回せるのは僅か。
+   *
+   * **1 図あたりの上限では判定していない** (`#776`)。 壁時計は同じ図を 3 周しても
+   * 53 / 0 / 1 ms と揺れるので、 判定は全図の合計 (`PERF_BUDGET_TOTAL_MS`) だけが持つ。
+   * ここの上限は「1 図が合計を食い潰さない」 ための設計上の目安で、 判定の境ではない。
    *
    * **上限に達したら数えるのをやめる**。 包囲箱で絞れないのは曲線どうしが広く重なる図で、
    * その形は総当たり以外に手が無い。 打ち切ると警告が出ないが、 出ない状態は弦で数えていた
@@ -3046,27 +3048,54 @@ function runAxes(
   }
 
   // ───────────────────────────────────────────────────────────
-  // Axis 23: responsive-viewport (viewBox の過剰扁平回避)
-  //
-  // 判定 = viewBox aspect ratio が RESPONSIVE_MAX_ASPECT (6:1) を超えると横長すぎで
-  // responsive 破綻。 縦 1 段の図に lane を並べ続けると高さが伸びないまま幅だけ増え、
-  // 親幅に収めた時に帯状に潰れて中身が読めなくなる。
+  // Axis 23: responsive-viewport (親幅に収めた時に文字が小さくなりすぎないか)
   //
-  // viewBox width の下限は見ない。 render は `w-full` + `preserveAspectRatio="xMidYMid meet"`
-  // で親要素の幅いっぱいに伸ばすため (`render/stage.tsx`)、 画面上の文字サイズは
+  // render は `w-full` + `preserveAspectRatio="xMidYMid meet"` で親要素の幅いっぱいに伸ばす
+  // (`render/stage.tsx`)。 したがって画面上の文字サイズは
   //
   //   画面上の文字サイズ = 文字の world 寸法 × (親要素の幅 px ÷ viewBox width)
   //
-  // で決まる。 viewBox width が小さいほど倍率が上がって読みやすくなるので、 「幅が小さい =
-  // 識別不能」 は成り立たない。 以前は 400 world 未満を warn にしていたが、 dragon の見本で
+  // で決まる。 **この式に縦横比は出てこない**。 判定は viewBox width の上限で行う。
+  //
+  // 以前は縦横比 6:1 を超えると warn にしていたが、 下流の見本帳 444 枚の実測で順位が
+  // 一致しなかった。 画面上の文字が最も小さい図 (幅 3353 world、 器 1100px で 7.2px) は
+  // 縦横比 1.4 なので 1 度も拾われず、 縦横比が最大の図 (比 8.0、 幅 1535 world) は 15.8px で
+  // 十分読めた。 文字が小さい上位 20 枚のうち縦横比が拾ったのは 5 枚だけ (`#785`)。
+  //
+  // 幅の **下限** は見ない。 viewBox width が小さいほど倍率が上がって読みやすくなるので、
+  // 「幅が小さい = 識別不能」 は成り立たない。 以前 400 world 未満を warn にしていた頃に
   // 発火した 17 件は全て単体部品の図 (271-390 world) で、 幅 375px の携帯では 1.0-1.38 倍に
-  // 拡大される最も読みやすい部類だった。 閾値を下げても判定の向きが誤ったまま残るため、
-  // 判定ごと外している。
+  // 拡大される最も読みやすい部類だった。
   //
-  // 幅の下限を外した分、 描画不能な寸法 (0 / 負値 / 非有限) だけは別に拾う。 縦横比は
-  // 0 幅で NaN、 負値で符号が反転して比較が素通りするため、 比を出す前に弾く。
+  // 描画不能な寸法 (0 / 負値 / 非有限) は別に拾う。 倍率は 0 幅で無限大になり、 負値で
+  // 符号が反転して比較が素通りするため、 割る前に弾く。
   // ───────────────────────────────────────────────────────────
-  const RESPONSIVE_MAX_ASPECT = 6;
+  //
+  /**
+   * 判定に使う親要素の幅 (px)。 書き出しの窓 1600px から左右の余白を引いた実測の見当。
+   *
+   * **実際の親幅は呼び出し側が決める**。 engine はそれを知らないので、 判定の基準として
+   * 1 つ選ぶ。 選んだ値そのものが閾値の意味を決めるため、 定数として出す。
+   */
+  const RESPONSIVE_REF_CONTAINER_PX = 1100;
+  /**
+   * 画面上で読めると見なす文字の下限 (px)。
+   *
+   * 12px は WCAG が数値で定める下限ではない (WCAG は寸法でなく拡大できることを求める)。
+   * 下流の見本帳で実際に読み取れるかを見て決めた運用上の下限で、 これを下回る図は
+   * 器 1100px の画面で拡大しないと読めない。
+   */
+  const RESPONSIVE_MIN_ON_SCREEN_FONT_PX = 12;
+  /**
+   * 判定の基準にする文字の world 寸法。 箱の題の大きさ (`kinds/storage.tsx` の fontSize 22)。
+   *
+   * 図の中には これより小さい文字 (辺の名札等) もあるが、 基準を最小の文字に取ると
+   * ほぼ全ての図が境を割る。 最も多く出る文字で見る。
+   */
+  const RESPONSIVE_BASE_FONT_WORLD = 22;
+  /** 上の 3 つから導く viewBox width の上限。 数を直接書かない。 */
+  const RESPONSIVE_MAX_VIEWBOX_W =
+    (RESPONSIVE_BASE_FONT_WORLD * RESPONSIVE_REF_CONTAINER_PX) / RESPONSIVE_MIN_ON_SCREEN_FONT_PX;
   const vbResp = laid.viewBox;
   if (
     !(vbResp.w > 0) ||
@@ -3079,17 +3108,15 @@ function runAxes(
       `viewBox 寸法 ${vbResp.w}×${vbResp.h} が描画不能 (正の有限値である必要がある)`,
       "warn",
     );
-  } else {
-    // 横長と縦長を同じ尺度で見る。 縦長を aspect のまま報告すると detail が
-    // 「aspect 0.1 が 6:1 超え」 のように読めない値になる。
-    const worstAspect = Math.max(vbResp.w / vbResp.h, vbResp.h / vbResp.w);
-    if (worstAspect > RESPONSIVE_MAX_ASPECT) {
-      push(
-        "responsive-viewport",
-        `viewBox aspect ${worstAspect.toFixed(1)}:1 が RESPONSIVE_MAX_ASPECT ${RESPONSIVE_MAX_ASPECT}:1 超え`,
-        "warn",
-      );
-    }
+  } else if (vbResp.w > RESPONSIVE_MAX_VIEWBOX_W) {
+    const 画面上の字 = (RESPONSIVE_BASE_FONT_WORLD * RESPONSIVE_REF_CONTAINER_PX) / vbResp.w;
+    push(
+      "responsive-viewport",
+      `viewBox width ${vbResp.w} が上限 ${RESPONSIVE_MAX_VIEWBOX_W.toFixed(0)} 超え ` +
+        `(親幅 ${RESPONSIVE_REF_CONTAINER_PX}px で箱の題が ${画面上の字.toFixed(1)}px、 ` +
+        `下限 ${RESPONSIVE_MIN_ON_SCREEN_FONT_PX}px)`,
+      "warn",
+    );
   }
 
   // ───────────────────────────────────────────────────────────
@@ -3364,55 +3391,6 @@ function runAxes(
     }
   }
 
-  // ───────────────────────────────────────────────────────────
-  // Axis 33: subpixel-precision (node / edge label 座標の subpixel drift 検知)
-  //
-  // 判定 = node cx / cy / edge labelX / labelY / lane x / y が SUBPIXEL_TOL (0.5 world) を
-  // 超えて小数点を持つ (e.g. 100.7) と subpixel render 時に SVG 描画が blur を生む。
-  // 整数化 or 0.5 刻みが理想。 label は shift 経路の結果として非整数が出やすい。
-  // ───────────────────────────────────────────────────────────
-  const SUBPIXEL_TOL = 0.5;
-  function isSubpixel(v: number): boolean {
-    // 整数と 0.5 刻みの両方を許容する。
-    //
-    // 0.5 は SVG では「にじむ座標」 ではない。 幅 1 の線は中心を .5 に置くと 1 pixel に
-    // ちょうど収まって輪郭が立つ (逆に整数に置くと 2 pixel に半分ずつ跨いでぼやける)。
-    // 本 axis の説明も「整数化 or 0.5 刻みが理想」 としており、 判定側だけが 0.5 を
-    // 弾いていた。 説明に合わせる。
-    //
-    // 判定は「最も近い 0.5 の倍数からの距離」 で見る。 0.05 以下は float 演算の誤差として許容。
-    const nearestHalf = Math.round(v * 2) / 2;
-    return Math.abs(v - nearestHalf) > SUBPIXEL_TOL / 10;
-  }
-  for (const n of laid.nodes) {
-    if (n.id.endsWith("-spacer") || /^s\d+-/.test(n.id)) continue;
-    if (isSubpixel(n.cx) || isSubpixel(n.cy)) {
-      push(
-        "subpixel-precision",
-        `node "${n.id}" 座標 (${n.cx.toFixed(2)}, ${n.cy.toFixed(2)}) が非整数、 subpixel blur リスク`,
-        "warn",
-      );
-    }
-  }
-  for (const e of laid.edges) {
-    if (isSubpixel(e.labelX) || isSubpixel(e.labelY)) {
-      push(
-        "subpixel-precision",
-        `edge "${e.id}" label 座標 (${e.labelX.toFixed(2)}, ${e.labelY.toFixed(2)}) が非整数、 subpixel blur リスク`,
-        "warn",
-      );
-    }
-  }
-  for (const l of laid.lanes) {
-    if (isSubpixel(l.x) || isSubpixel(l.y)) {
-      push(
-        "subpixel-precision",
-        `lane "${l.id}" 座標 (${l.x.toFixed(2)}, ${l.y.toFixed(2)}) が非整数、 subpixel blur リスク`,
-        "warn",
-      );
-    }
-  }
-
   // ───────────────────────────────────────────────────────────
   // Axis 34: dom-complexity-budget (1 diagram あたりの element 総数)
   //
@@ -4333,6 +4311,76 @@ export function visualValidateAll(diagrams: CdlDiagram[], opts?: ValidateOptions
  *     source を読めない (build 後は minified) ため、 実装は要素数の一致に留まる。
  *     `VisualAxis` / `emptyCounts` / `allAxes` の 3 つが揃っているかは見ない (#381)。
  */
+/** 全 diagram の検査に掛けてよい合計の時間 (ms)。 */
+export const PERF_BUDGET_TOTAL_MS = 5000;
+
+/** 合計が境を超えた時に、内訳として名前を出す図の数。 */
+export const PERF_SLOWEST_SAMPLE = 5;
+
+/**
+ * Axis 52 `validate-performance-budget` の判定 (`#776`)。
+ *
+ * ## 1 枚ごとの壁時計では判定しない
+ *
+ * 同じ図を同じ process で 3 周すると答えが変わる。 実測 (下流の見本帳 444 枚)。
+ *
+ * ```
+ * interactive-social-share-buttons   53ms /   0ms /   1ms
+ * interactive-traffic-sankey         50ms / 159ms / 115ms
+ * ```
+ *
+ * 1 つ目は最初の 1 回だけ掛かる下準備で、2 つ目は機械の混み具合。 どちらも図の性質ではない。
+ * 100ms の境で数えると **入力が同じなのに超過が 0 / 1 / 1 件** と周ごとに変わっていた =
+ * 測れなかったことを「遅い」 に倒していた
+ * (`rules/quality.md § 判定できなかったことを値に潰さない`)。
+ *
+ * 合計は同じ 3 周で 559 / 877 / 858 ms と 1.6 倍の幅に収まり、境の 5000ms から充分離れている
+ * ので判定が安定する。 **合計だけを見る**。
+ *
+ * ## 報告を 1 件に丸めない
+ *
+ * 合計だけを見ると「どの図が重いか」 が落ちるので、超過した時に重い順の内訳を文面へ載せる。
+ * 出し切れない分は件数で残す = 黙って捨てない。
+ *
+ * 旧実装は `findIndex` で最初に当たった 1 枚しか出しておらず、20 枚が超過した周でも報告は
+ * 1 枚だった。 残り 19 枚は数にも文面にも出ない。
+ *
+ * ## なぜ関数に切り出すか
+ *
+ * 合計が 5000ms を超える状況を実際に作ると、確かめる検査そのものが 5 秒以上掛かる。
+ * 時間の配列を直接渡せる形にして、両向きを実時間なしで固定する。
+ *
+ * @param durations 図ごとの実行時間 (ms)。 `diagrams` と同じ並び
+ * @param diagrams 図。 名前を内訳に出すためだけに使う
+ */
+export function perfBudgetViolations(
+  durations: readonly number[],
+  diagrams: readonly { id: string }[] = [],
+): Violation[] {
+  const total = durations.reduce((s, d) => s + d, 0);
+  if (total <= PERF_BUDGET_TOTAL_MS) return [];
+
+  const 重い順 = durations
+    .map((ms, i) => ({ id: diagrams[i]?.id ?? "?", ms }))
+    .sort((a, b) => b.ms - a.ms);
+  const 抜粋 = 重い順.slice(0, PERF_SLOWEST_SAMPLE);
+  const 残り = 重い順.length - 抜粋.length;
+  const 内訳 =
+    抜粋.map((d) => `"${d.id}" ${d.ms}ms`).join(" / ") +
+    (残り > 0 ? `、 残り ${残り} 図は出していない` : "");
+
+  return [
+    {
+      axis: "validate-performance-budget",
+      diagramId: "__meta__",
+      detail:
+        `visualValidateAll 全 ${durations.length} 図の累計 ${total}ms > ` +
+        `${PERF_BUDGET_TOTAL_MS}ms budget (重い順 ${内訳})`,
+      severity: "warn",
+    },
+  ];
+}
+
 function validateMetaAxes(
   totalCounts: Record<VisualAxis, number>,
   diagrams: CdlDiagram[] = [],
@@ -4364,27 +4412,7 @@ function validateMetaAxes(
   // 本 axis は 空 (engine 単体で判定材料なし)、 発火経路として先取り。
 
   // ─── Axis 52: validate-performance-budget (validate 実行時間) ───
-  const PERF_BUDGET_PER_DIAGRAM_MS = 100;
-  const PERF_BUDGET_TOTAL_MS = 5000;
-  const overBudgetIdx = durations.findIndex((d) => d > PERF_BUDGET_PER_DIAGRAM_MS);
-  if (overBudgetIdx >= 0) {
-    const did = diagrams[overBudgetIdx]?.id ?? "?";
-    out.push({
-      axis: "validate-performance-budget",
-      diagramId: did,
-      detail: `diagram "${did}" validate ${durations[overBudgetIdx]}ms > ${PERF_BUDGET_PER_DIAGRAM_MS}ms budget`,
-      severity: "warn",
-    });
-  }
-  const totalDur = durations.reduce((s, d) => s + d, 0);
-  if (totalDur > PERF_BUDGET_TOTAL_MS) {
-    out.push({
-      axis: "validate-performance-budget",
-      diagramId: "__meta__",
-      detail: `visualValidateAll 全 diagram 累計 ${totalDur}ms > ${PERF_BUDGET_TOTAL_MS}ms budget`,
-      severity: "warn",
-    });
-  }
+  out.push(...perfBudgetViolations(durations, diagrams));
 
   // Axis 47: dead axis 検知
   // security / migration 系は自然発火なしを許容 (実データに XSS / migration 混入は稀)
@@ -4428,7 +4456,6 @@ function validateMetaAxes(
     "print-media-compat",
     "color-blind-safety",
     "marker-gradient-def-integrity",
-    "subpixel-precision",
     "dom-complexity-budget",
     "reduced-motion-compat",
     "touch-target-size",
@@ -4497,7 +4524,6 @@ function validateMetaAxes(
     "print-media-compat",
     "color-blind-safety",
     "marker-gradient-def-integrity",
-    "subpixel-precision",
     "dom-complexity-budget",
     "reduced-motion-compat",
     "touch-target-size",
@@ -4554,8 +4580,9 @@ function validateMetaAxes(
   //
   // 削除済 = engine-meta 51 (mermaid-parity、 #366) / 軸 29 (svg-filter-integrity) /
   // 軸 30 (neumorphism-shadow-budget、 どちらも #426 で主題の廃止に伴い削除) /
-  // 軸 40 (memory-budget、 #775 で軸 34 に一本化)。
-  const EXPECTED_AXIS_COUNT = 67;
+  // 軸 40 (memory-budget、 #775 で軸 34 に一本化) /
+  // 軸 33 (subpixel-precision、 #783 で削除)。
+  const EXPECTED_AXIS_COUNT = 66;
   if (allAxes.length !== EXPECTED_AXIS_COUNT) {
     out.push({
       axis: "axis-documentation-completeness",