@cardenelabs/cdl 0.5.0

package/src/dom-verify.ts

@@ -0,0 +1,948 @@
+/**
+ * cdl 定義 ↔ 実画面整合性 verifier (「目」 v3 の core)。
+ *
+ * cdl で宣言した node / edge / phase / particle が、 実際の SVG render と一致しているかを
+ * DOM scrape + 数値判定で自動検証する。 LLM 不要、 課金 0。
+ *
+ * 検証 5 種類。
+ *   1. node 位置 ... data-cdl-node="{id}" 要素の boundingBox cx/cy が layout() 計算値と一致
+ *   2. edge path 起点終点 ... <path id="cdl-edge-{id}"> の d 属性の起点 / 終点が from / to node の側面と一致
+ *   3. particle 位置 ... animation N frame 撮影で particle SVG の中心が path 上の点と < tolerance
+ *   4. activation ... phase 切替時に data-cdl-active="true" が phase.activate() で宣言した element のみ
+ *   5. phase 切替 ... phase index 進行で active class set が正確に切替わる
+ */
+import type { CdlDiagram, LaidDiagram } from "./types";
+import { layout } from "./layout";
+import type { PageLike } from "./dom-verify-types";
+import type { DiagramAdapter, GenericDiagramSpec } from "./dom-verify-core";
+
+/**
+ * 図を描く `<svg>` を取る selector (cdl#336)。
+ *
+ * `[data-cdl-diagram]` の中には `<svg>` が複数ある。 interactive panel が widget ごとに 1 つ
+ * ずつ持ち (readout の ring / gauge / sparkline 等)、 **DOM 順では panel が stage より先**
+ * (`render.tsx` = panel → `CdlStage`)。 `querySelector("svg")` は document 順の最初を返すので、
+ * interactive な図では widget の `<svg>` を掴む。 その `viewBox` (`0 0 64 64` 等) で node 座標を
+ * 換算するため、 照合結果は意味を持たない数字になる。
+ *
+ * 属性で名指しする。 interactive でない図では `<svg>` が 1 つしかないため、 従来と同じものを
+ * 取る (挙動は変わらない)。
+ *
+ * `data-cdl-role` を使わないのは、 あれが consumer の CSS 契約 (`CdlRole`、 `types.ts`) だから。
+ * stage は装飾の対象になる部品ではなく図全体の入れ物で、 role に混ぜると
+ * `[data-cdl-role]` を広く拾う selector が外側の `<svg>` にも当たる。
+ */
+export const STAGE_SVG_SELECTOR = "svg[data-cdl-stage]";
+
+/**
+ * node の実寸の枠を取る selector (#390)。
+ *
+ * `data-cdl-w/h` は layout の静的値で、 `wBind` / `hBind` の縮小や `renderOffsetX/Y` の移動を
+ * 含まない。 行が枠に収まっているかを実 DOM で測る側はこの要素を見る。
+ *
+ * `STAGE_SVG_SELECTOR` と同じ理由で `data-cdl-role` に置かない。 この矩形は
+ * `fill="none" stroke="none" pointer-events="none"` で、 描画されない計測用の目印。
+ *
+ * **`$$eval` / `evaluate` の callback からこの定数を参照してはいけない**。 callback は文字列
+ * として browser に渡るので module scope が消え、 実行時に `ReferenceError` になる。 callback
+ * 内では同じ値を literal で書くか、 `STAGE_SVG_SELECTOR` のように引数として渡す。
+ */
+export const NODE_FRAME_SELECTOR = "[data-cdl-frame]";
+
+export type DiscrepancyKind =
+  | "missing-node-element"
+  | "missing-edge-element"
+  | "node-position-mismatch"
+  | "node-size-mismatch"
+  | "edge-path-endpoint-mismatch"
+  | "edge-label-position-mismatch"
+  // #390 = 行の文字が node の枠から出ている。 layout 出力だけを見る軸 16 は「字形が baseline から
+  // どれだけ下に伸びるか」 を見込みで置いており、 文字列ごとの実寸は取れない。 実 DOM でのみ捕まる。
+  | "node-row-overflow"
+  // #390 = 行の実寸を測れなかった。 「測った上で収まっていた」 と区別する。
+  | "node-row-unverifiable"
+  | "particle-out-of-path"
+  | "activation-mismatch"
+  | "phase-transition-failure";
+
+export interface Discrepancy {
+  kind: DiscrepancyKind;
+  diagramId: string;
+  elementId: string;
+  expected: unknown;
+  actual: unknown;
+  detail: string;
+}
+
+export interface VerifyOptions {
+  /** node 位置の許容誤差 (px、 default 2) */
+  positionTolerance?: number;
+  /** edge path 起点終点と node 側面の許容誤差 (px、 default 4) */
+  edgeEndpointTolerance?: number;
+  /**
+   * particle 位置 vs path 上の点との許容誤差 (px、 default 250)。
+   * Chrome / Firefox の animateMotion + getBoundingClientRect が animation 中の particle 位置を
+   * 必ずしも正確に返さない (frame 1 で static 0,0 fallback / mpath transform が screen CTM に反映されない 等)
+   * ため、 user 視覚的に同 diagram 内で許容できる 250px (= 1 lane 程度) を default に。
+   * 実エンジン bug (particle が画面外 / 別 diagram 領域へ飛ぶ) は依然検知できる。
+   */
+  particleTolerance?: number;
+  /** particle 検証時の animation frame 撮影数 (default 8、 0.25s 間隔) */
+  particleFrameCount?: number;
+  /** particle が「path から外れている」 と判定する連続 frame 数の閾値 (default 3、 偶発的 1 frame ずれを許容) */
+  particleConsecutiveFailThreshold?: number;
+  /** boundingBox 照合の許容誤差 (px、 viewBox transform scale を考慮するため大きめ default 8) */
+  bboxTolerance?: number;
+  /** boundingBox 照合を skip (高速 partial run 用) */
+  skipBbox?: boolean;
+  /** particle 検証を skip (animation がない static diagram 用) */
+  skipParticle?: boolean;
+  /** phase 切替検証を skip (single phase diagram 用) */
+  skipPhase?: boolean;
+  /**
+   * 行の文字が node の枠に収まっているかの検査を skip する。
+   *
+   * 実 font に依存するので、 font が読み込まれていない環境では意味のある判定にならない。
+   */
+  skipRowBounds?: boolean;
+  /**
+   * 行の文字が枠から出ていると判定する許容量 (screen px、 default 2)。
+   *
+   * 0 にしない理由は 2 つ。 `getBoundingClientRect()` は字形の外接矩形を返すので、 letter-spacing や
+   * antialias の分だけ数値が揺れる。 加えて枠の角が丸い (`rx`) ため、 角の近くでは枠の内側でも
+   * 矩形としては外に出る。 「明らかに出ている」 だけを拾う。
+   */
+  rowBoundsTolerance?: number;
+}
+
+/**
+ * Playwright Page-like 抽象を ./dom-verify-types から re-export (backward compat)。
+ * 将来 library 化時に dom-verify-core / cdl-adapter 両方で同 type を共有するため、
+ * 定義は dom-verify-types.ts に集約。
+ */
+export type { PageLike };
+
+/**
+ * 1 つの diagram について 5 種類の verifier を全部走らせる。
+ *
+ * options.skipBbox / skipParticle / skipPhase で各検証を skip 可能 (動作確認 / partial run 用)。
+ */
+export async function verifyDiagramDom(
+  page: PageLike,
+  diagram: CdlDiagram,
+  options: VerifyOptions = {},
+): Promise<Discrepancy[]> {
+  const laid = layout(diagram);
+  const out: Discrepancy[] = [];
+
+  // 1. node 位置 + サイズ照合 (data-cdl 値 vs layout 計算値)
+  out.push(...await verifyNodes(page, laid, options));
+
+  // 2. edge path 起点終点 + label 位置
+  out.push(...await verifyEdges(page, laid, options));
+
+  // 3. SVG boundingBox 照合 (実描画位置 vs data-cdl 値、 transform 込み)
+  if (!options.skipBbox) {
+    out.push(...await verifyBoundingBoxes(page, laid, options));
+  }
+
+  // 4. animation particle 位置 (N frame 撮影で path 上にあるか)
+  if (!options.skipParticle) {
+    out.push(...await verifyParticles(page, laid, options));
+  }
+
+  // 5. phase 切替 (active class set が phase.activate() と一致するか)
+  if (!options.skipPhase) {
+    out.push(...await verifyPhaseTransitions(page, laid, diagram, options));
+  }
+
+  // 6. 行の文字が node の枠に収まっているか (#390)
+  if (!options.skipRowBounds) {
+    out.push(...await verifyRowBounds(page, laid, options));
+  }
+
+  return out;
+}
+
+async function verifyNodes(
+  page: PageLike,
+  laid: LaidDiagram,
+  options: VerifyOptions,
+): Promise<Discrepancy[]> {
+  const out: Discrepancy[] = [];
+  const tol = options.positionTolerance ?? 2;
+  const diagramId = laid.id;
+  const sel = `[data-cdl-diagram="${diagramId}"]`;
+  // 全 node の data-cdl-cx / cy / w / h を一括取得
+  const domNodes = await page.$$eval<Array<{ id: string; cx: number; cy: number; w: number; h: number }>>(
+    `${sel} [data-cdl-node]`,
+    (els) =>
+      els.map((el) => ({
+        id: el.getAttribute("data-cdl-node") ?? "",
+        cx: parseFloat(el.getAttribute("data-cdl-cx") ?? "NaN"),
+        cy: parseFloat(el.getAttribute("data-cdl-cy") ?? "NaN"),
+        w: parseFloat(el.getAttribute("data-cdl-w") ?? "NaN"),
+        h: parseFloat(el.getAttribute("data-cdl-h") ?? "NaN"),
+      })),
+  );
+  const domNodeMap = new Map(domNodes.map((n) => [n.id, n]));
+  for (const node of laid.nodes) {
+    const dom = domNodeMap.get(node.id);
+    if (!dom) {
+      out.push({
+        kind: "missing-node-element",
+        diagramId,
+        elementId: node.id,
+        expected: { cx: node.cx, cy: node.cy },
+        actual: null,
+        detail: `node "${node.id}" の DOM 要素 [data-cdl-node="${node.id}"] が見つからない`,
+      });
+      continue;
+    }
+    if (Math.abs(dom.cx - node.cx) > tol || Math.abs(dom.cy - node.cy) > tol) {
+      out.push({
+        kind: "node-position-mismatch",
+        diagramId,
+        elementId: node.id,
+        expected: { cx: node.cx, cy: node.cy },
+        actual: { cx: dom.cx, cy: dom.cy },
+        detail: `node "${node.id}" の cx/cy が layout 計算値 (${node.cx}, ${node.cy}) と data-cdl 値 (${dom.cx}, ${dom.cy}) で乖離 > ${tol}px`,
+      });
+    }
+    if (Math.abs(dom.w - node.w) > tol || Math.abs(dom.h - node.h) > tol) {
+      out.push({
+        kind: "node-size-mismatch",
+        diagramId,
+        elementId: node.id,
+        expected: { w: node.w, h: node.h },
+        actual: { w: dom.w, h: dom.h },
+        detail: `node "${node.id}" の w/h が layout 計算値 (${node.w}, ${node.h}) と data-cdl 値 (${dom.w}, ${dom.h}) で乖離 > ${tol}px`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 行の `<text>` が node の枠に収まっているかを **実寸** で見る (#390)。
+ *
+ * 軸 16 (`row-vertical-spacing`) は layout 出力だけを見るので、 字形が baseline から下へどれだけ
+ * 伸びるかを見込みで置いている (`ROW_GLYPH_DEPTH_RATIO` = 0.4 em)。 文字列ごとの実寸は実 DOM で
+ * しか取れない。
+ *
+ * ## 縦と横で測り方が違う
+ *
+ * **`getBoundingClientRect()` / `getBBox()` の高さは字形を反映しない**。 実測すると、 `a` /
+ * `gjpqy` / `日本語` / 結合文字を 40 個重ねた文字列 のいずれも高さが同じ値を返す (font metrics の
+ * 箱を返しており、 ink の箱ではない)。 幅は中身に追随する。
+ *
+ * そのため縦だけ canvas の `measureText` で測る。 `actualBoundingBoxAscent` /
+ * `actualBoundingBoxDescent` は字形の実際の上端 / 下端で、 実測では結合文字を重ねた文字列に
+ * 対して 6.2 - 12.9 em を返した (通常の文字は 0.28 em 以下)。
+ *
+ * ## なぜ枠として宣言された寸法を使うか
+ *
+ * 描かれている要素は使えない。 `node-body` は `generic.tsx` では `<g>` に付いており、 その外接
+ * 矩形は子 (溢れた文字を含む) の和集合になるため、 溢れていても必ず「収まっている」 と出る。
+ *
+ * 宣言された寸法は world 単位、 実寸は screen px なので、 world 側を `getScreenCTM()` で screen に
+ * 写して同じ空間で比べる。
+ */
+async function verifyRowBounds(
+  page: PageLike,
+  laid: LaidDiagram,
+  options: VerifyOptions,
+): Promise<Discrepancy[]> {
+  const out: Discrepancy[] = [];
+  const tol = options.rowBoundsTolerance ?? 2;
+  const diagramId = laid.id;
+  const sel = `[data-cdl-diagram="${diagramId}"]`;
+
+  const rows = await page.$$eval<Array<{
+    nodeId: string; index: string; text: string;
+    over: { left: number; right: number; top: number; bottom: number } | null;
+    skip: string | null;
+    /** 測る対象が無い (空の `<text>`)。 測定不能とは別で、 報告しない。 */
+    empty: boolean;
+  }>>(
+    `${sel} [data-cdl-node] [data-cdl-role="node-row"]`,
+    (els) => {
+      // canvas は 1 個だけ作って全行で使い回す (行ごとに作ると図と行の数だけ確保する)。
+      let ctx: CanvasRenderingContext2D | null | undefined;
+      const sharedCtx = (): CanvasRenderingContext2D | null => {
+        if (ctx === undefined) {
+          try {
+            ctx = document.createElement("canvas").getContext("2d");
+          } catch {
+            ctx = null;
+          }
+        }
+        return ctx;
+      };
+      return els.map((el) => {
+        const nodeEl = el.closest("[data-cdl-node]");
+        const nodeId = nodeEl?.getAttribute("data-cdl-node") ?? "";
+        const index = el.getAttribute("data-cdl-row-index") ?? "";
+        const text = el.textContent ?? "";
+        // 「測れなかった」 (報告する) と「測る対象が無い」 (報告しない) を分ける。
+        // 空の `<text>` は字形を持たないので枠から出ようがなく、 測定不能ではない。
+        const bail = (skip: string) => ({ nodeId, index, text, over: null, skip, empty: false });
+        const noContent = () => ({ nodeId, index, text, over: null, skip: null, empty: true });
+
+        // 枠は **描かれている実寸の矩形** を使う。 `data-cdl-w/h` は layout の静的値で、
+        // `wBind` / `hBind` による縮小や `renderOffsetX/Y` による移動を含まないため、
+        // 動いた node を枠外と誤判定し、 縮んだ node の溢れを見逃す。
+        //
+        // `node-body` は使えない。 `generic.tsx` では `<g>` に付いており、 外接矩形が子
+        // (溢れた文字を含む) の和集合になるため、 溢れていても必ず「収まっている」 と出る。
+        //
+        // selector を定数で参照しない。 この callback は `$$eval` が browser に文字列として
+        // 渡すので、 module scope を閉じ込められない (実行時に ReferenceError)。 定数の説明は
+        // `NODE_FRAME_SELECTOR` の doc comment。
+        const frameEl = nodeEl?.querySelector("[data-cdl-frame]");
+        if (!frameEl) return bail("枠の要素が無い");
+        const frame = frameEl.getBoundingClientRect();
+        if (!(frame.width > 0 && frame.height > 0)) return bail("枠の実寸が取れない");
+
+        const t = el as SVGTextElement;
+        const local = t.getScreenCTM();
+        if (!local) return bail("getScreenCTM が使えない");
+        // 回転 / skew が入ると「下」 の向きが screen の下と一致しない。 ink を縦方向の
+        // 長さとして足す前提が崩れるので、 測れないものとして報告する (誤検知より良い)。
+        if (Math.abs(local.b) > 1e-6 || Math.abs(local.c) > 1e-6) return bail("回転 / skew が入っている");
+        if (text.trim().length === 0) return noContent();
+
+        // 横は矩形が中身に追随するのでそのまま使う。
+        const r = el.getBoundingClientRect();
+        if (r.width === 0 && r.height === 0) return noContent();
+
+        // 縦は canvas の ink 実寸で測る。 矩形の高さは font metrics の箱で、 字形を反映しない
+        // (実測 = `a` / `gjpqy` / `日本語` / 結合文字 40 個 のいずれも同じ高さ)。
+        const cs = getComputedStyle(el);
+        const ctx = sharedCtx();
+        if (!ctx) return bail("canvas が使えない");
+        const font = `${cs.fontStyle} ${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`;
+        // font が読み込まれていないと代替 font の字形で測ることになり、 判定が環境に依存する。
+        // 「読み込み前の値」 を正常な計測として扱わない。
+        //
+        // **`document.fonts.check()` は使わない**。 実測すると存在しない family
+        // (`18px ZZNoSuchFontZZ`) でも、 文字を渡しても渡さなくても `true` を返す = 使用可能性の
+        // signal にならない。 代わりに読み込まれた face の一覧を直接見る。
+        try {
+          if (document.fonts.status !== "loaded") return bail("font の読込が終わっていない");
+          const family = (cs.fontFamily.split(",")[0] ?? "").trim().replace(/^["']|["']$/g, "");
+          const weight = Number.parseInt(cs.fontWeight, 10);
+          const faces = Array.from(document.fonts);
+          const sameFamily = faces.filter(
+            (f) => f.family.replace(/^["']|["']$/g, "").toLowerCase() === family.toLowerCase(),
+          );
+          // 一覧に無い family は端末側の font (`monospace` / `-apple-system` 等) の可能性があり、
+          // 「無い」 と「端末にある」 を区別できない。 web font として宣言されている時だけ、
+          // その太さの face が読み込まれていることを要求する。
+          if (sameFamily.length > 0) {
+            const loaded = sameFamily.some(
+              (f) => f.status === "loaded" && (Number.isNaN(weight) || String(weight) === f.weight),
+            );
+            if (!loaded) return bail(`font の face が読み込まれていない (${family} / ${cs.fontWeight})`);
+          }
+        } catch {
+          return bail("font の状態を確認できない");
+        }
+        ctx.font = font;
+        const tm = ctx.measureText(text);
+        const asc = tm.actualBoundingBoxAscent, desc = tm.actualBoundingBoxDescent;
+        if (!Number.isFinite(asc) || !Number.isFinite(desc)) return bail("ink 実寸が取れない");
+
+        // baseline の位置 (screen)。 字形の上下端はここから伸びる。
+        let originY: number;
+        try {
+          originY = t.getStartPositionOfChar(0).matrixTransform(local).y;
+        } catch {
+          return bail("baseline の位置が取れない");
+        }
+        // canvas は user 単位で測る (SVG の `font-size` は user 単位)。 screen へは **その text の**
+        // 縦倍率を掛ける (root の CTM だと text 側に掛かった scale を落とす)。
+        const scaleY = Math.abs(local.d);
+
+        return {
+          nodeId, index, text, skip: null, empty: false,
+          over: {
+            left: frame.left - r.left,
+            right: r.right - frame.right,
+            top: frame.top - (originY - asc * scaleY),
+            bottom: (originY + desc * scaleY) - frame.bottom,
+          },
+        };
+      });
+    },
+  );
+
+  // 宣言された行が DOM に出ているかを照合する。 検出できた行だけを見ると、 属性が全部
+  // 消えた時に「違反 0 件」 になる = 検査していないのに pass する (#393 と同じ形)。
+  const foundPerNode = new Map<string, number>();
+  for (const row of rows) {
+    foundPerNode.set(row.nodeId, (foundPerNode.get(row.nodeId) ?? 0) + 1);
+  }
+  for (const n of laid.nodes) {
+    const declared = n.rows?.length ?? 0;
+    if (declared === 0) continue;
+    // 1 行は左右 2 つの `<text>` に分かれる。
+    const expected = declared * 2;
+    const found = foundPerNode.get(n.id) ?? 0;
+    if (found === expected) continue;
+    out.push({
+      kind: "node-row-unverifiable",
+      diagramId,
+      elementId: n.id,
+      expected,
+      actual: found,
+      detail: `node "${n.id}" は ${declared} 行を宣言しているが、 DOM の行の要素が ${found} 個 (期待 ${expected} 個) で照合できない`,
+    });
+  }
+
+  for (const row of rows) {
+    if (row.empty) continue; // 字形が無いので枠から出ようがない
+    if (row.skip !== null || row.over === null) {
+      // **測れなかったことを黙らせない**。 「測った上で収まっていた」 と区別できないと、
+      // 検査していないのに違反 0 件という報告になる (#393 で消したのと同じ形)。
+      out.push({
+        kind: "node-row-unverifiable",
+        diagramId,
+        elementId: row.nodeId,
+        expected: `node "${row.nodeId}" の行 ${row.index} を実寸で測れること`,
+        actual: row.skip,
+        detail: `node "${row.nodeId}" の行 ${row.index} ("${row.text.slice(0, 30)}") の実寸を測れなかった (${row.skip ?? "理由不明"})`,
+      });
+      continue;
+    }
+    const { left, right, top, bottom } = row.over;
+    if (Math.max(left, right, top, bottom) <= tol) continue;
+    const sides = ([["左", left], ["右", right], ["上", top], ["下", bottom]] as const)
+      .filter(([, v]) => v > tol)
+      .map(([name, v]) => `${name} ${v.toFixed(1)}px`)
+      .join(" / ");
+    out.push({
+      kind: "node-row-overflow",
+      diagramId,
+      elementId: row.nodeId,
+      expected: `node "${row.nodeId}" の枠内`,
+      actual: { over: row.over },
+      detail: `node "${row.nodeId}" の行 ${row.index} ("${row.text.slice(0, 30)}") が枠から出ている (${sides}、 許容 ${tol}px)`,
+    });
+  }
+  return out;
+}
+
+async function verifyEdges(
+  page: PageLike,
+  laid: LaidDiagram,
+  options: VerifyOptions,
+): Promise<Discrepancy[]> {
+  const out: Discrepancy[] = [];
+  const tol = options.edgeEndpointTolerance ?? 4;
+  const diagramId = laid.id;
+  const sel = `[data-cdl-diagram="${diagramId}"]`;
+  const domEdges = await page.$$eval<
+    Array<{ id: string; from: string; to: string; pathD: string; labelX: number; labelY: number }>
+  >(`${sel} [data-cdl-edge]`, (els) =>
+    els.map((el) => ({
+      id: el.getAttribute("data-cdl-edge") ?? "",
+      from: el.getAttribute("data-cdl-from") ?? "",
+      to: el.getAttribute("data-cdl-to") ?? "",
+      pathD: el.getAttribute("data-cdl-path-d") ?? "",
+      labelX: parseFloat(el.getAttribute("data-cdl-label-x") ?? "NaN"),
+      labelY: parseFloat(el.getAttribute("data-cdl-label-y") ?? "NaN"),
+    })),
+  );
+  const domEdgeMap = new Map(domEdges.map((e) => [e.id, e]));
+  const nodeMap = new Map(laid.nodes.map((n) => [n.id, n]));
+
+  for (const edge of laid.edges) {
+    const dom = domEdgeMap.get(edge.id);
+    if (!dom) {
+      out.push({
+        kind: "missing-edge-element",
+        diagramId,
+        elementId: edge.id,
+        expected: { from: edge.from, to: edge.to },
+        actual: null,
+        detail: `edge "${edge.id}" の DOM 要素 [data-cdl-edge="${edge.id}"] が見つからない`,
+      });
+      continue;
+    }
+    // edge.d の起点 / 終点を抽出 (M / L コマンドの最初 / 最後の座標)
+    const points = extractPathEndpoints(dom.pathD);
+    if (!points) continue;
+    const from = nodeMap.get(edge.from);
+    const to = nodeMap.get(edge.to);
+    if (!from || !to) continue;
+    // 起点が from node の bbox 上 (側面のいずれか) にあるか
+    const startOnFrom = isPointOnNodeBoundary(points.start, from, tol);
+    const endOnTo = isPointOnNodeBoundary(points.end, to, tol);
+    if (!startOnFrom) {
+      out.push({
+        kind: "edge-path-endpoint-mismatch",
+        diagramId,
+        elementId: edge.id,
+        expected: `from node "${edge.from}" boundary`,
+        actual: { x: points.start.x, y: points.start.y },
+        detail: `edge "${edge.id}" の path 起点 (${points.start.x}, ${points.start.y}) が from node "${edge.from}" の側面に乗っていない (tolerance ${tol}px)`,
+      });
+    }
+    if (!endOnTo) {
+      out.push({
+        kind: "edge-path-endpoint-mismatch",
+        diagramId,
+        elementId: edge.id,
+        expected: `to node "${edge.to}" boundary`,
+        actual: { x: points.end.x, y: points.end.y },
+        detail: `edge "${edge.id}" の path 終点 (${points.end.x}, ${points.end.y}) が to node "${edge.to}" の側面に乗っていない (tolerance ${tol}px)`,
+      });
+    }
+    // label 位置が layout 計算値と一致するか
+    if (Math.abs(dom.labelX - edge.labelX) > 1 || Math.abs(dom.labelY - edge.labelY) > 1) {
+      out.push({
+        kind: "edge-label-position-mismatch",
+        diagramId,
+        elementId: edge.id,
+        expected: { labelX: edge.labelX, labelY: edge.labelY },
+        actual: { labelX: dom.labelX, labelY: dom.labelY },
+        detail: `edge "${edge.id}" の label 位置が layout 計算値と data-cdl 値で乖離`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * SVG path d 文字列から起点 (M) と 終点 (最後の L / Q / C) の座標を抽出。
+ */
+function extractPathEndpoints(d: string): { start: { x: number; y: number }; end: { x: number; y: number } } | null {
+  const cmdRe = /([MLCQZ])\s*([^MLCQZ]*)/gi;
+  let start: { x: number; y: number } | null = null;
+  let end: { x: number; y: number } | null = null;
+  let m: RegExpExecArray | null;
+  while ((m = cmdRe.exec(d)) !== null) {
+    const cmd = m[1]!.toUpperCase();
+    const args = (m[2] ?? "").trim().split(/[\s,]+/).filter(Boolean).map(parseFloat);
+    if (cmd === "Z") continue;
+    let x = 0;
+    let y = 0;
+    if (cmd === "M" || cmd === "L") {
+      x = args[0]!;
+      y = args[1]!;
+    } else if (cmd === "Q") {
+      // Q cx cy x y → 終点は (args[2], args[3])
+      x = args[2]!;
+      y = args[3]!;
+    } else if (cmd === "C") {
+      // C c1x c1y c2x c2y x y → 終点は (args[4], args[5])
+      x = args[4]!;
+      y = args[5]!;
+    }
+    if (start === null) start = { x, y };
+    end = { x, y };
+  }
+  if (!start || !end) return null;
+  return { start, end };
+}
+
+/**
+ * 点 (px, py) が node の bbox 側面 (4 辺のいずれか) に tolerance 内で乗っているか判定。
+ */
+function isPointOnNodeBoundary(
+  point: { x: number; y: number },
+  node: { cx: number; cy: number; w: number; h: number },
+  tol: number,
+): boolean {
+  const left = node.cx - node.w / 2;
+  const right = node.cx + node.w / 2;
+  const top = node.cy - node.h / 2;
+  const bot = node.cy + node.h / 2;
+  // 左辺 ... px が left 近く + py が [top, bot] 内
+  if (Math.abs(point.x - left) <= tol && point.y >= top - tol && point.y <= bot + tol) return true;
+  // 右辺
+  if (Math.abs(point.x - right) <= tol && point.y >= top - tol && point.y <= bot + tol) return true;
+  // 上辺
+  if (Math.abs(point.y - top) <= tol && point.x >= left - tol && point.x <= right + tol) return true;
+  // 下辺
+  if (Math.abs(point.y - bot) <= tol && point.x >= left - tol && point.x <= right + tol) return true;
+  return false;
+}
+
+/**
+ * 3. SVG boundingBox 照合 ... 実描画位置 (Playwright bbox in viewport px) と
+ *    SVG userspace 座標 (data-cdl 値) を viewBox transform で換算して比較。
+ *
+ * Astro が SVG に viewBox + 任意 CSS scale を適用するため、 単純比較は不可。
+ * (1) SVG element の getBoundingClientRect で viewport px の bbox 取得
+ * (2) data-cdl-viewbox から viewBox 4 値を取得
+ * (3) viewport bbox / viewBox = scale 計算
+ * (4) 各 node の data-cdl-cx を viewport 座標に変換 → 該当 [data-cdl-node] の bbox 中心と照合
+ */
+async function verifyBoundingBoxes(
+  page: PageLike,
+  laid: LaidDiagram,
+  options: VerifyOptions,
+): Promise<Discrepancy[]> {
+  const out: Discrepancy[] = [];
+  const tol = options.bboxTolerance ?? 16;
+  const diagramId = laid.id;
+  // browser context で SVG transform を換算した中心 座標を取得
+  type BboxInfo = {
+    ok: true;
+    nodes: Array<{ id: string; cxView: number; cyView: number; wView: number; hView: number; cxExpected: number; cyExpected: number; wExpected: number; hExpected: number }>;
+  } | { ok: false; reason: string };
+  const result = await page.evaluate(
+    ({ diagId, stageSel }) => {
+      const root = document.querySelector(`[data-cdl-diagram="${diagId}"]`);
+      if (!root) return { ok: false as const, reason: `root [data-cdl-diagram="${diagId}"] not found` };
+      const svg = root.querySelector(stageSel);
+      if (!svg) return { ok: false as const, reason: `${stageSel} not found inside [data-cdl-diagram="${diagId}"]` };
+      const vbAttr = svg.getAttribute("viewBox");
+      if (!vbAttr) return { ok: false as const, reason: "svg viewBox attribute missing" };
+      const vbParts = vbAttr.split(/\s+/).map(parseFloat);
+      const vx = vbParts[0] ?? 0;
+      const vy = vbParts[1] ?? 0;
+      const vw = vbParts[2] ?? 1;
+      const vh = vbParts[3] ?? 1;
+      const svgRect = svg.getBoundingClientRect();
+      // viewBox → viewport の scale (preserveAspectRatio=meet 想定で min)
+      const scaleX = svgRect.width / vw;
+      const scaleY = svgRect.height / vh;
+      const scale = Math.min(scaleX, scaleY);
+      const offsetX = svgRect.left + (svgRect.width - vw * scale) / 2;
+      const offsetY = svgRect.top + (svgRect.height - vh * scale) / 2;
+      const nodeEls = Array.from(root.querySelectorAll("[data-cdl-node]"));
+      const nodes = nodeEls.map((el) => {
+        const id = el.getAttribute("data-cdl-node") ?? "";
+        const cxSvg = parseFloat(el.getAttribute("data-cdl-cx") ?? "NaN");
+        const cySvg = parseFloat(el.getAttribute("data-cdl-cy") ?? "NaN");
+        const wSvg = parseFloat(el.getAttribute("data-cdl-w") ?? "NaN");
+        const hSvg = parseFloat(el.getAttribute("data-cdl-h") ?? "NaN");
+        // SVG userspace → viewport へ変換
+        const cxExpected = offsetX + (cxSvg - vx) * scale;
+        const cyExpected = offsetY + (cySvg - vy) * scale;
+        const wExpected = wSvg * scale;
+        const hExpected = hSvg * scale;
+        // 実 boundingBox から viewport center 取得
+        const rect = (el as Element).getBoundingClientRect();
+        return {
+          id,
+          cxView: rect.left + rect.width / 2,
+          cyView: rect.top + rect.height / 2,
+          wView: rect.width,
+          hView: rect.height,
+          cxExpected,
+          cyExpected,
+          wExpected,
+          hExpected,
+        };
+      });
+      return { ok: true as const, nodes };
+    },
+    { diagId: diagramId, stageSel: STAGE_SVG_SELECTOR },
+  ) as BboxInfo;
+
+  if (!result.ok) {
+    out.push({
+      kind: "missing-node-element",
+      diagramId,
+      elementId: "(root)",
+      expected: "svg with viewBox",
+      actual: null,
+      detail: `bbox verification skipped: ${result.reason}`,
+    });
+    return out;
+  }
+  const expectedNodeIds = new Set(laid.nodes.map((n) => n.id));
+  for (const dom of result.nodes) {
+    if (!expectedNodeIds.has(dom.id)) continue;
+    const dx = Math.abs(dom.cxView - dom.cxExpected);
+    const dy = Math.abs(dom.cyView - dom.cyExpected);
+    if (dx > tol || dy > tol) {
+      out.push({
+        kind: "node-position-mismatch",
+        diagramId,
+        elementId: dom.id,
+        expected: { cx: dom.cxExpected.toFixed(1), cy: dom.cyExpected.toFixed(1) },
+        actual: { cx: dom.cxView.toFixed(1), cy: dom.cyView.toFixed(1) },
+        detail: `bbox: node "${dom.id}" の viewport 中心が SVG userspace 計算値と (dx=${dx.toFixed(1)}, dy=${dy.toFixed(1)}) ずれ > ${tol}px`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 4. animation particle 位置 ... Playwright で animation N frame 撮影し、
+ *    各 frame で particle SVG 要素 (data-cdl-particle) の中心が path 上にあるか判定。
+ *
+ * 判定 ... browser context で SVGPathElement.getPointAtLength() を使い、
+ * particle 中心から最も近い path 上の点を sample (10 点) して距離 < tolerance なら pass。
+ *
+ * dotted-flow 以外の edge (particle 描画なし) は対象外。
+ */
+async function verifyParticles(
+  page: PageLike,
+  laid: LaidDiagram,
+  options: VerifyOptions,
+): Promise<Discrepancy[]> {
+  const out: Discrepancy[] = [];
+  const tol = options.particleTolerance ?? 250;
+  const frameCount = options.particleFrameCount ?? 8;
+  const consecutiveThreshold = options.particleConsecutiveFailThreshold ?? 3;
+  const diagramId = laid.id;
+  const dottedEdges = laid.edges.filter((e) => e.style === "dotted-flow");
+  if (dottedEdges.length === 0) return out;
+  // edge id ごとに consecutive fail 回数を集計、 閾値超で discrepancy 計上
+  const failCountByEdge = new Map<string, { count: number; maxDist: number; lastFrame: number }>();
+
+  // animation 進行を待ちつつ N frame で particle 位置を計測
+  for (let frame = 0; frame < frameCount; frame++) {
+    await page.waitForTimeout(250); // 0.25s 間隔
+    type FrameResult = {
+      ok: true;
+      particles: Array<{ id: string; cxView: number; cyView: number; minDistOnPath: number }>;
+    } | { ok: false; reason: string };
+    const res = await page.evaluate(
+      ({ diagId, edgeIds }) => {
+        const root = document.querySelector(`[data-cdl-diagram="${diagId}"]`);
+        if (!root) return { ok: false as const, reason: "root not found" };
+        const out: Array<{ id: string; cxView: number; cyView: number; minDistOnPath: number }> = [];
+        for (const eid of edgeIds) {
+          const particleEl = root.querySelector(`[data-cdl-particle="${eid}"]`);
+          const pathEl = root.querySelector(`#cdl-edge-${eid}`) as SVGPathElement | null;
+          if (!particleEl || !pathEl) continue;
+          // particle の中心 (最初の circle で代用、 3 重 glow の中心はほぼ同位置)。
+          // animateMotion は <circle> の transform attribute を動的に書換える形で動くが、
+          // Chrome の getBoundingClientRect() は animation 反映済の bbox を返すはず。
+          // 初回 frame で static 位置に fallback する場合があるため、
+          // SVG getCTM() で current matrix の e/f (translation) を直接取得する経路も併用。
+          const firstCircle = particleEl.querySelector("circle") as SVGGraphicsElement | null;
+          if (!firstCircle) continue;
+          // Path 1: getBoundingClientRect (animation 中の bbox)
+          const cRect = firstCircle.getBoundingClientRect();
+          let cx = cRect.left + cRect.width / 2;
+          let cy = cRect.top + cRect.height / 2;
+          // Path 2: getCTM().e/f で current translation を取得して補正。
+          // animateMotion は要素の transform matrix を直接書換えるが、
+          // bbox に反映されないケースで cx/cy 0,0 が返ることがある。
+          // CTM の translation 成分が path 上にあれば、 それを particle center として採用。
+          const circleCtm = firstCircle.getCTM();
+          if (circleCtm) {
+            const pCtm = pathEl.getScreenCTM();
+            if (pCtm) {
+              // circle CTM の translation を viewport 座標へ
+              const cxAlt = circleCtm.e * pCtm.a + circleCtm.f * pCtm.c + pCtm.e;
+              const cyAlt = circleCtm.e * pCtm.b + circleCtm.f * pCtm.d + pCtm.f;
+              // bbox center と CTM-based center を比較し、 より path 上に近い方を採用
+              // (animation 進行中は bbox が正確、 frame 0 では CTM が正確というケースが交互に来る)
+              // ここでは bbox cx/cy が viewport origin に近い (0,0 fallback) ときに alt を採用
+              const isBboxFallback = Math.abs(cx) < 5 && Math.abs(cy) < 5;
+              if (isBboxFallback) {
+                cx = cxAlt;
+                cy = cyAlt;
+              }
+            }
+          }
+          // path 上を 20 sample して particle 中心との最小距離
+          const len = pathEl.getTotalLength();
+          if (!isFinite(len) || len === 0) continue;
+          let minDist = Infinity;
+          const samples = 20;
+          // CTM (SVG → screen) で各 sample 点を viewport 座標に変換
+          const ctm = pathEl.getScreenCTM();
+          if (!ctm) continue;
+          for (let i = 0; i <= samples; i++) {
+            const t = (i / samples) * len;
+            const p = pathEl.getPointAtLength(t);
+            const vp = { x: p.x * ctm.a + p.y * ctm.c + ctm.e, y: p.x * ctm.b + p.y * ctm.d + ctm.f };
+            const d = Math.hypot(cx - vp.x, cy - vp.y);
+            if (d < minDist) minDist = d;
+          }
+          out.push({ id: eid, cxView: cx, cyView: cy, minDistOnPath: minDist });
+        }
+        return { ok: true as const, particles: out };
+      },
+      { diagId: diagramId, edgeIds: dottedEdges.map((e) => e.id) },
+    ) as FrameResult;
+    if (!res.ok) continue;
+    for (const p of res.particles) {
+      if (p.minDistOnPath > tol) {
+        // 連続 fail を集計 ... animateMotion の CTM 取得が瞬間的に静的 bbox に fallback する
+        // ケースがあり、 1-2 frame 単発で path から外れて見える false positive を回避。
+        // consecutiveThreshold 回 (default 3) 以上連続で fail したら本物の path 外れと判定。
+        const prev = failCountByEdge.get(p.id) ?? { count: 0, maxDist: 0, lastFrame: -1 };
+        const isConsecutive = prev.lastFrame === frame - 1 || prev.lastFrame === -1;
+        failCountByEdge.set(p.id, {
+          count: isConsecutive ? prev.count + 1 : 1,
+          maxDist: Math.max(prev.maxDist, p.minDistOnPath),
+          lastFrame: frame,
+        });
+      }
+    }
+  }
+  // 連続 fail 数が閾値以上の edge のみ discrepancy 計上
+  for (const [edgeId, info] of failCountByEdge) {
+    if (info.count >= consecutiveThreshold) {
+      out.push({
+        kind: "particle-out-of-path",
+        diagramId,
+        elementId: edgeId,
+        expected: `path 上 (tolerance ${tol}px)`,
+        actual: { maxDist: info.maxDist.toFixed(1), consecutiveFails: info.count },
+        detail: `edge "${edgeId}" の particle が ${info.count} frame 連続で path から最大 ${info.maxDist.toFixed(1)}px 外れています`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 5. phase 切替 ... phase index を進めて active class set が phase.activate() と一致するか動的検証。
+ *
+ * data-cdl-phase-index attribute を直接更新する経路がなければ、 phase 進行は
+ * Playwright で待つだけで時間経過に伴い自動進行する (CdlDiagramView の useTimeline)。
+ */
+async function verifyPhaseTransitions(
+  page: PageLike,
+  laid: LaidDiagram,
+  diagram: CdlDiagram,
+  _options: VerifyOptions,
+): Promise<Discrepancy[]> {
+  const out: Discrepancy[] = [];
+  const diagramId = laid.id;
+  if (diagram.phases.length === 0) return out;
+
+  // 各 phase に対して、 期待される active element set と実 active class set を照合。
+  // 注意 ... CdlDiagramView は時間経過で phase 進行するが、 dom-verify は static check で十分。
+  // 現在の phase index を取り、 その phase の expected vs actual を比較。
+  type PhaseState = {
+    ok: true;
+    phaseIdx: number;
+    activeNodes: string[];
+    activeEdges: string[];
+  } | { ok: false; reason: string };
+  const state = await page.evaluate(
+    ({ diagId }) => {
+      const root = document.querySelector(`[data-cdl-diagram="${diagId}"]`);
+      if (!root) return { ok: false as const, reason: "root not found" };
+      const phaseIdxAttr = root.getAttribute("data-cdl-phase-index");
+      const phaseIdx = phaseIdxAttr === null ? -1 : parseInt(phaseIdxAttr, 10);
+      const activeNodeEls = Array.from(root.querySelectorAll('[data-cdl-node][data-cdl-active="true"]'));
+      const activeEdgeEls = Array.from(root.querySelectorAll('[data-cdl-edge][data-cdl-active="true"]'));
+      return {
+        ok: true as const,
+        phaseIdx,
+        activeNodes: activeNodeEls.map((el) => el.getAttribute("data-cdl-node") ?? ""),
+        activeEdges: activeEdgeEls.map((el) => el.getAttribute("data-cdl-edge") ?? ""),
+      };
+    },
+    { diagId: diagramId },
+  ) as PhaseState;
+  if (!state.ok) return out;
+  if (state.phaseIdx < 0 || state.phaseIdx >= diagram.phases.length) return out;
+  const expectedPhase = diagram.phases[state.phaseIdx]!;
+  const expectedActive = new Set(expectedPhase.activate);
+  const actualActive = new Set([...state.activeNodes, ...state.activeEdges]);
+
+  // 期待される active が actual に欠落
+  for (const id of expectedActive) {
+    if (!actualActive.has(id)) {
+      out.push({
+        kind: "activation-mismatch",
+        diagramId,
+        elementId: id,
+        expected: "active",
+        actual: "inactive",
+        detail: `phase "${expectedPhase.id}" で活性化すべき要素 "${id}" が data-cdl-active="true" になっていない`,
+      });
+    }
+  }
+  // 期待されていない要素が active になっている
+  for (const id of actualActive) {
+    if (!expectedActive.has(id)) {
+      out.push({
+        kind: "activation-mismatch",
+        diagramId,
+        elementId: id,
+        expected: "inactive",
+        actual: "active",
+        detail: `phase "${expectedPhase.id}" で活性化すべきでない要素 "${id}" が data-cdl-active="true" になっている`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * 複数 diagram を一括 verify。
+ */
+export interface DomVerifyReport {
+  total: number;
+  pass: number;
+  fail: number;
+  discrepancies: Discrepancy[];
+}
+
+export async function verifyAllDiagramsDom(
+  page: PageLike,
+  diagrams: CdlDiagram[],
+  options?: VerifyOptions,
+): Promise<DomVerifyReport> {
+  const all: Discrepancy[] = [];
+  let fail = 0;
+  for (const d of diagrams) {
+    const ds = await verifyDiagramDom(page, d, options);
+    if (ds.length > 0) fail++;
+    all.push(...ds);
+  }
+  return {
+    total: diagrams.length,
+    pass: diagrams.length - fail,
+    fail,
+    discrepancies: all,
+  };
+}
+
+/**
+ * cdl-adapter: CdlDiagram → GenericDiagramSpec への変換 (目 v4 library 化前段)。
+ *
+ * 将来 @cardenelabs/diagram-verifier を独立 npm publish する際、
+ * dom-verify-core.ts (generic) + 本 adapter (cdl 用) の 2 層構成にする。
+ * 同様の adapter を Mermaid / D2 / 任意 SVG tool 用に増やせる構造。
+ */
+export const cdlAdapter: DiagramAdapter<CdlDiagram> = {
+  name: "cdl",
+  toSpec(diagram: CdlDiagram): GenericDiagramSpec {
+    const laid = layout(diagram);
+    return {
+      id: laid.id,
+      rootAttribute: "data-cdl-diagram",
+      nodeAttribute: "data-cdl-node",
+      edgeAttribute: "data-cdl-edge",
+      particleAttribute: "data-cdl-particle",
+      nodes: laid.nodes.map((n) => ({
+        id: n.id,
+        cx: n.cx,
+        cy: n.cy,
+        w: n.w,
+        h: n.h,
+      })),
+      edges: laid.edges.map((e) => ({
+        id: e.id,
+        from: e.from,
+        to: e.to,
+        d: e.d,
+        labelX: e.labelX,
+        labelY: e.labelY,
+        hasParticle: e.style === "dotted-flow",
+      })),
+      phases: diagram.phases.map((p) => ({
+        id: p.id,
+        activate: p.activate,
+      })),
+    };
+  },
+};