@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-headless-replatform/scripts/verify-interactions.mjs

@@ -0,0 +1,669 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { docsDir, parseArgs, readJson, writeJson } from "./lib/common.mjs";
+import { loadPlaywrightFromContext, resolveBrowserToolingContext } from "./lib/browser-tooling.mjs";
+
+/**
+ * The viewport this file verified at when it only ever checked one.
+ * Still the default and still the *primary* viewport in the report, so a caller
+ * that passes nothing gets byte-identical top-level fields to schemaVersion 2.
+ */
+export const DEFAULT_VIEWPORT = { width: 1440, height: 1200 };
+
+/** A width with no height gets a plausible one — a phone is not 1200px tall. */
+export function viewportHeightForWidth(width) {
+  if (width < 500) return 800;
+  if (width < 1024) return 1024;
+  return 1200;
+}
+
+/**
+ * `--viewports 375,768,1440` or `--viewports 375x800,1440x1200`.
+ * Returns the default viewport when nothing parses, never an empty list — a
+ * typo must not silently verify zero viewports and report `pass: true`.
+ */
+export function parseViewports(spec) {
+  if (!spec) return [DEFAULT_VIEWPORT];
+  const parsed = String(spec)
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [rawWidth, rawHeight] = entry.split(/[x×]/i);
+      const width = Number.parseInt(rawWidth, 10);
+      if (!Number.isFinite(width) || width <= 0) return null;
+      const height = Number.parseInt(rawHeight, 10);
+      return { width, height: Number.isFinite(height) && height > 0 ? height : viewportHeightForWidth(width) };
+    })
+    .filter(Boolean);
+  if (!parsed.length) throw new Error(`No usable viewport in --viewports "${spec}" (expected e.g. 375,768,1440).`);
+  // Widest first: it becomes the primary viewport, matching the historical single-viewport report.
+  return parsed.sort((a, b) => b.width - a.width);
+}
+
+async function main() {
+  const args = parseArgs();
+  const cloneUrl = args["clone-url"] || args.url || args._[0];
+  const outputDir = path.resolve(args.out || args.output || "");
+  if (!cloneUrl) throw new Error("Missing --clone-url for the running clone.");
+  if (!args.out && !args.output) throw new Error("Missing --out for the generated project directory.");
+  const browserTooling = await resolveBrowserToolingContext({ startDir: path.resolve(args["project-root"] || process.cwd()) });
+  const viewports = parseViewports(args.viewports || args.viewport);
+  const report = await verifyInteractionRuntime({ outputDir, cloneUrl, browserTooling, viewports });
+  await writeJson(path.join(docsDir(outputDir), "interaction-qa.json"), report);
+  if (args.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else console.log(`Interaction QA: ${report.viewports.map((v) => `${v.width}px ${v.passedScenes}/${v.sceneCount}`).join(" · ")}`);
+  if (!report.pass) process.exitCode = 1;
+}
+
+/**
+ * Replay the scene contract against a running clone, once per viewport.
+ *
+ * A layout correct at 1440 and broken at 375 is the ordinary case, and a
+ * single-viewport run reports it as passing. `pass` is therefore
+ * true only when EVERY viewport passes — that widening is the point of the
+ * change, and it is the one field whose meaning differs from schemaVersion 2.
+ * The other top-level fields keep describing the primary (widest) viewport, so
+ * existing readers of `scenes` / `sceneCount` / `normalization` are unaffected.
+ */
+export async function verifyInteractionRuntime({ outputDir, cloneUrl, browserTooling, viewports } = {}) {
+  const contract = await readJson(path.join(docsDir(outputDir), "scene-contract.json"));
+  let uiNormalization = null;
+  try {
+    uiNormalization = await readJson(path.join(docsDir(outputDir), "ui-normalization.json"));
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const targets = Array.isArray(viewports) && viewports.length ? viewports : [DEFAULT_VIEWPORT];
+  const toolingContext = browserTooling || await resolveBrowserToolingContext({ startDir: process.cwd() });
+  const playwright = await loadPlaywrightFromContext(toolingContext);
+  const browser = await playwright.chromium.launch({ headless: true });
+  try {
+    const results = [];
+    for (const viewport of targets) {
+      const page = await browser.newPage({ viewport });
+      try {
+        await page.goto(cloneUrl, { waitUntil: "domcontentloaded", timeout: 45000 });
+        await page.waitForTimeout(800);
+        const scenes = [];
+        for (const scene of contract.scenes || []) scenes.push(await verifyScene(page, scene));
+        const passedScenes = scenes.filter((scene) => scene.pass).length;
+        const normalization = uiNormalization ? await verifyUiNormalization(page, uiNormalization) : null;
+        const scenePass = scenes.length > 0 && passedScenes === scenes.length;
+        results.push({
+          width: viewport.width,
+          height: viewport.height,
+          sceneCount: scenes.length,
+          passedScenes,
+          failedScenes: scenes.length - passedScenes,
+          pass: scenePass && (!normalization || normalization.pass),
+          scenes,
+          ...(normalization ? { normalization } : {}),
+        });
+      } finally {
+        await page.close();
+      }
+    }
+    const primary = results[0];
+    return {
+      schemaVersion: 3,
+      generatedAt: new Date().toISOString(),
+      cloneUrl,
+      primaryViewport: { width: primary.width, height: primary.height },
+      sceneCount: primary.sceneCount,
+      passedScenes: primary.passedScenes,
+      failedScenes: primary.failedScenes,
+      pass: results.every((result) => result.pass),
+      scenes: primary.scenes,
+      ...(primary.normalization ? { normalization: primary.normalization } : {}),
+      viewports: results,
+      failingViewports: results.filter((result) => !result.pass).map((result) => result.width),
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+async function verifyUiNormalization(page, contract) {
+  const globalChecks = [];
+  for (const assertion of contract.globalAssertions || []) {
+    if (assertion.kind === "no-page-horizontal-overflow") {
+      const pixels = await page.evaluate(() => Math.max(0, document.documentElement.scrollWidth - document.documentElement.clientWidth));
+      globalChecks.push(pixels <= assertion.maximumPixels
+        ? { ...assertion, pass: true, actualPixels: pixels }
+        : { ...assertion, pass: false, message: `Document overflows horizontally by ${pixels}px.` });
+    } else if (assertion.kind === "reduced-motion-available") {
+      const present = await page.evaluate(() => Array.from(document.styleSheets).some((sheet) => {
+        try {
+          return Array.from(sheet.cssRules || []).some((rule) => String(rule.cssText || "").includes("prefers-reduced-motion"));
+        } catch {
+          return false;
+        }
+      }));
+      globalChecks.push(present
+        ? { ...assertion, pass: true }
+        : { ...assertion, pass: false, message: "No same-origin prefers-reduced-motion rule was found." });
+    }
+  }
+  const sections = [];
+  for (const section of contract.sections || []) sections.push(await verifyNormalizedSection(page, section));
+  return {
+    sectionCount: sections.length,
+    passedSections: sections.filter((section) => section.pass).length,
+    pass: globalChecks.every((check) => check.pass) && sections.every((section) => section.pass),
+    globalChecks,
+    sections,
+  };
+}
+
+async function verifyNormalizedSection(page, section) {
+  const selector = `[data-rp-section="${escapeAttribute(section.sectionId)}"]`;
+  const root = page.locator(selector).first();
+  if (!await root.count()) {
+    return {
+      sectionId: section.sectionId,
+      pass: false,
+      checks: [{ kind: "section-present", pass: false, message: `Missing ${selector}.` }],
+    };
+  }
+  const checks = [];
+  for (const assertion of section.assertions || []) {
+    if (assertion.kind === "section-present") {
+      checks.push({ ...assertion, pass: true });
+      continue;
+    }
+    if (assertion.kind === "repeated-item-height-spread") {
+      const heights = await itemHeights(root);
+      const ratio = heightSpreadRatio(heights);
+      checks.push(ratio <= assertion.maximumRatio
+        ? { ...assertion, pass: true, actualRatio: round(ratio), heights }
+        : { ...assertion, pass: false, message: `Repeated item height spread ${round(ratio)} exceeds ${assertion.maximumRatio}.`, heights });
+      continue;
+    }
+    if (assertion.kind === "activation-preserves-item-height") {
+      const before = await itemHeights(root);
+      let after = before;
+      const activators = root.locator("[data-rp-activate]");
+      if (await activators.count() > 1) {
+        await activators.nth(1).click({ force: true });
+        await page.waitForTimeout(650);
+        after = await itemHeights(root);
+      }
+      const ratio = maximumPairedHeightDelta(before, after);
+      checks.push(ratio <= assertion.maximumRatio
+        ? { ...assertion, pass: true, actualRatio: round(ratio) }
+        : { ...assertion, pass: false, message: `Activation changed item block size by ${round(ratio)}; maximum is ${assertion.maximumRatio}.` });
+      continue;
+    }
+    if (assertion.kind === "hover-preserves-item-layout") {
+      const before = await itemRects(root);
+      const targets = root.locator("[data-rp-hover-target],[data-rp-item]");
+      const count = await targets.count();
+      if (!count) {
+        checks.push({ ...assertion, pass: false, message: "No marked hover target exists." });
+        continue;
+      }
+      let targetIndex = Math.max(0, count - 1);
+      for (let index = 0; index < count; index += 1) {
+        const active = await targets.nth(index).getAttribute("data-rp-active");
+        if (active !== "true") {
+          targetIndex = index;
+          break;
+        }
+      }
+      await targets.nth(targetIndex).hover({ force: true });
+      await page.waitForTimeout(280);
+      const after = await itemRects(root);
+      const inlineRatio = maximumPairedRectDelta(before, after, "width");
+      const blockRatio = maximumPairedRectDelta(before, after, "height");
+      checks.push(inlineRatio <= assertion.maximumInlineRatio && blockRatio <= assertion.maximumBlockRatio
+        ? { ...assertion, pass: true, actualInlineRatio: round(inlineRatio), actualBlockRatio: round(blockRatio) }
+        : { ...assertion, pass: false, message: `Hover changed peer layout by inline=${round(inlineRatio)}, block=${round(blockRatio)}.` });
+      continue;
+    }
+    if (assertion.kind === "eased-motion-present") {
+      const motion = await root.locator("[data-rp-motion]").evaluateAll((nodes) => nodes.map((node) => {
+        const style = getComputedStyle(node);
+        return { duration: style.transitionDuration, easing: style.transitionTimingFunction };
+      }));
+      const eased = motion.some((item) => item.duration.split(",").some((value) => Number.parseFloat(value) > 0)
+        && item.easing.split(",").some((value) => !/^\s*(?:linear|steps\()/i.test(value)));
+      checks.push(eased
+        ? { ...assertion, pass: true, motion }
+        : { ...assertion, pass: false, message: "No marked motion target has a non-zero eased transition." });
+      continue;
+    }
+    checks.push({ ...assertion, pass: false, message: `Unsupported UI normalization assertion: ${assertion.kind}.` });
+  }
+  return { sectionId: section.sectionId, pass: checks.every((check) => check.pass), checks };
+}
+
+async function itemHeights(root) {
+  return root.locator("[data-rp-item]").evaluateAll((items) => items
+    .filter((item) => {
+      const style = getComputedStyle(item);
+      const rect = item.getBoundingClientRect();
+      return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden";
+    })
+    .map((item) => Math.round(item.getBoundingClientRect().height)));
+}
+
+async function itemRects(root) {
+  return root.locator("[data-rp-item]").evaluateAll((items) => items.map((item) => {
+    const rect = item.getBoundingClientRect();
+    return { width: rect.width, height: rect.height };
+  }));
+}
+
+function heightSpreadRatio(heights) {
+  if (heights.length < 2) return 0;
+  const sorted = [...heights].sort((left, right) => left - right);
+  const median = sorted[Math.floor(sorted.length / 2)] || 1;
+  return (Math.max(...heights) - Math.min(...heights)) / median;
+}
+
+function maximumPairedHeightDelta(before, after) {
+  const length = Math.min(before.length, after.length);
+  let maximum = 0;
+  for (let index = 0; index < length; index += 1) maximum = Math.max(maximum, Math.abs(after[index] - before[index]) / Math.max(1, before[index]));
+  return maximum;
+}
+
+function maximumPairedRectDelta(before, after, key) {
+  const length = Math.min(before.length, after.length);
+  let maximum = 0;
+  for (let index = 0; index < length; index += 1) maximum = Math.max(maximum, Math.abs(after[index][key] - before[index][key]) / Math.max(1, before[index][key]));
+  return maximum;
+}
+
+async function verifyScene(page, scene) {
+  const selector = `[data-rp-scene="${escapeAttribute(scene.id)}"]`;
+  const root = page.locator(selector).first();
+  const present = await root.count() > 0;
+  if (!present) {
+    return {
+      id: scene.id,
+      primitive: scene.implementation?.primitive || scene.implementation?.model || "unknown",
+      pass: false,
+      checks: [{ kind: "scene-present", pass: false, message: `Missing ${selector}.` }],
+    };
+  }
+
+  await root.scrollIntoViewIfNeeded();
+  await page.waitForTimeout(120);
+  const before = await readSceneState(root);
+  const assertions = scene.implementation?.assertions || [];
+  const needsActivation = assertions.some((item) => [
+    "activation-changes-state",
+    "activation-changes-content",
+    "active-item-width-ratio",
+    "single-active-item",
+    "transition-settles",
+  ].includes(item.kind));
+  let after = before;
+  let settleMs = 0;
+  let activationError = null;
+  if (needsActivation) {
+    try {
+      const result = await activateAlternateState(page, root, assertions);
+      after = result.after;
+      settleMs = result.settleMs;
+    } catch (error) {
+      activationError = error.message;
+    }
+  }
+  let scrollFrames = [];
+  if (assertions.some((item) => item.kind.startsWith("scroll-") || item.kind === "visual-pins-during-scroll")) {
+    scrollFrames = await sampleScrollScene(page, root);
+  }
+  let hoverBefore = null;
+  let hoverAfter = null;
+  let hoverError = null;
+  if (assertions.some((item) => item.kind === "hover-changes-visual-state")) {
+    try {
+      const hover = await probeHoverState(page, root);
+      hoverBefore = hover.before;
+      hoverAfter = hover.after;
+    } catch (error) {
+      hoverError = error.message;
+    }
+  }
+
+  const checks = assertions.map((assertion) => evaluateAssertion(assertion, {
+    before,
+    after,
+    settleMs,
+    scrollFrames,
+    activationError,
+    hoverBefore,
+    hoverAfter,
+    hoverError,
+  }));
+  if (!assertions.some((item) => item.kind === "scene-present")) {
+    checks.unshift({ kind: "scene-present", pass: true });
+  }
+  return {
+    id: scene.id,
+    primitive: scene.implementation?.primitive || scene.implementation?.model || "unknown",
+    pass: checks.every((check) => check.pass),
+    settleMs,
+    checks,
+  };
+}
+
+async function readSceneState(root) {
+  return root.evaluate((scene) => {
+    const visible = (node) => {
+      const rect = node.getBoundingClientRect();
+      const style = getComputedStyle(node);
+      return rect.width > 0 && rect.height > 0 && style.display !== "none" && style.visibility !== "hidden" && style.opacity !== "0";
+    };
+    const clean = (value) => String(value || "").replace(/\s+/g, " ").trim();
+    const items = Array.from(scene.querySelectorAll("[data-rp-item]")).map((node, index) => {
+      const rect = node.getBoundingClientRect();
+      const style = getComputedStyle(node);
+      return {
+        index,
+        active: node.getAttribute("data-rp-active") === "true",
+        text: clean(node.textContent).slice(0, 160),
+        rect: { left: Math.round(rect.left), top: Math.round(rect.top), width: Math.round(rect.width), height: Math.round(rect.height) },
+        spacing: {
+          marginLeft: parseFloat(style.marginLeft) || 0,
+          marginRight: parseFloat(style.marginRight) || 0,
+          paddingLeft: parseFloat(style.paddingLeft) || 0,
+          paddingRight: parseFloat(style.paddingRight) || 0,
+          borderLeftWidth: parseFloat(style.borderLeftWidth) || 0,
+          borderRightWidth: parseFloat(style.borderRightWidth) || 0,
+        },
+      };
+    });
+    const track = scene.querySelector("[data-rp-track]");
+    const viewport = scene.querySelector("[data-rp-viewport]") || track?.parentElement;
+    const panels = Array.from(scene.querySelectorAll("[data-rp-panel]")).filter(visible).map((node) => clean(node.textContent).slice(0, 600));
+    const mediaNodes = Array.from(scene.querySelectorAll("iframe,video"));
+    const media = mediaNodes.map((node) => {
+      const rect = node.getBoundingClientRect();
+      return {
+        tag: node.tagName.toLowerCase(),
+        src: node.currentSrc || node.getAttribute("src") || "",
+        autoplay: node.autoplay || /(?:^|[?&])autoplay=1(?:&|$)/.test(node.getAttribute("src") || ""),
+        loop: node.loop || /(?:^|[?&])loop=1(?:&|$)/.test(node.getAttribute("src") || ""),
+        muted: node.muted || /(?:^|[?&])muted=1(?:&|$)/.test(node.getAttribute("src") || ""),
+        background: /(?:^|[?&])background=1(?:&|$)/.test(node.getAttribute("src") || ""),
+        rect: { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom, width: rect.width, height: rect.height },
+      };
+    });
+    const fallbackLayers = Array.from(scene.querySelectorAll("*")).slice(0, 500).filter(visible).flatMap((node) => {
+      const sources = [];
+      if (node.tagName === "IMG") sources.push(node.currentSrc || node.getAttribute("src") || "");
+      const background = getComputedStyle(node).backgroundImage || "";
+      for (const match of background.matchAll(/url\(["']?([^"')]+)["']?\)/g)) sources.push(match[1]);
+      return sources.filter(Boolean).map((source) => ({ source, rect: node.getBoundingClientRect() }));
+    });
+    const overlappingFallbackSources = fallbackLayers
+      .filter((layer) => mediaNodes.some((mediaNode) => overlapRatio(layer.rect, mediaNode.getBoundingClientRect()) >= 0.8))
+      .map((layer) => layer.source);
+    return {
+      items,
+      activeIndexes: items.filter((item) => item.active).map((item) => item.index),
+      initialized: String(scene.getAttribute("data-rp-initialized") || "").split(/\s+/).filter(Boolean),
+      track: track ? {
+        clientWidth: viewport?.clientWidth || track.clientWidth,
+        scrollWidth: Math.max(track.scrollWidth, Math.round(track.getBoundingClientRect().width), viewport?.scrollWidth || 0),
+        gap: parseFloat(getComputedStyle(track).columnGap || getComputedStyle(track).gap) || 0,
+      } : null,
+      panelText: panels.join(" | "),
+      phase: scene.getAttribute("data-rp-phase") || "",
+      media,
+      overlappingFallbackSources,
+    };
+
+    function overlapRatio(left, right) {
+      const width = Math.max(0, Math.min(left.right, right.right) - Math.max(left.left, right.left));
+      const height = Math.max(0, Math.min(left.bottom, right.bottom) - Math.max(left.top, right.top));
+      const overlap = width * height;
+      const smaller = Math.min(left.width * left.height, right.width * right.height);
+      return smaller > 0 ? overlap / smaller : 0;
+    }
+  });
+}
+
+async function probeHoverState(page, root) {
+  const targets = root.locator("[data-rp-hover-target],[data-rp-item],[data-rp-direction],[data-rp-activate]");
+  if (!await targets.count()) throw new Error("No hoverable data-rp control exists in the scene.");
+  const target = targets.first();
+  const before = await readHoverSnapshot(target);
+  await target.hover({ force: true });
+  await page.waitForTimeout(220);
+  const after = await readHoverSnapshot(target);
+  return { before, after };
+}
+
+async function readHoverSnapshot(target) {
+  return target.evaluate((node) => [node, ...Array.from(node.querySelectorAll("*")).slice(0, 16)].map((part) => {
+    const style = getComputedStyle(part);
+    const rect = part.getBoundingClientRect();
+    return {
+      tag: part.tagName.toLowerCase(),
+      rect: { width: Math.round(rect.width), height: Math.round(rect.height) },
+      backgroundColor: style.backgroundColor,
+      color: style.color,
+      opacity: style.opacity,
+      transform: style.transform,
+      filter: style.filter,
+      boxShadow: style.boxShadow,
+      borderColor: style.borderColor,
+    };
+  }));
+}
+
+async function activateAlternateState(page, root, assertions) {
+  const activators = root.locator("[data-rp-activate]");
+  const count = await activators.count();
+  if (!count) throw new Error("No data-rp-activate target exists in the scene.");
+  const before = await readSceneState(root);
+  let targetIndex = count > 1 ? 1 : 0;
+  for (let index = 0; index < count; index += 1) {
+    const active = await activators.nth(index).evaluate((node) => node.closest("[data-rp-item]")?.getAttribute("data-rp-active") === "true");
+    if (!active) {
+      targetIndex = index;
+      break;
+    }
+  }
+  await activators.nth(targetIndex).click({ force: true });
+  const maximumMs = Math.min(3000, Math.max(500, Number(assertions.find((item) => item.kind === "transition-settles")?.maximumMs) || 1800));
+  const startedAt = Date.now();
+  let lastSignature = "";
+  let stableCount = 0;
+  let after = before;
+  while (Date.now() - startedAt < maximumMs) {
+    await page.waitForTimeout(80);
+    after = await readSceneState(root);
+    const signature = JSON.stringify({ activeIndexes: after.activeIndexes, items: after.items.map((item) => item.rect), panelText: after.panelText });
+    if (signature === lastSignature) stableCount += 1;
+    else stableCount = 0;
+    lastSignature = signature;
+    if (stableCount >= 2) break;
+  }
+  return { before, after, settleMs: Date.now() - startedAt };
+}
+
+async function sampleScrollScene(page, root) {
+  return root.evaluate(async (scene) => {
+    const frames = [];
+    const start = window.scrollY + scene.getBoundingClientRect().top;
+    const travel = Math.max(0, scene.getBoundingClientRect().height - window.innerHeight);
+    const samples = [
+      { progress: -2, scrollY: Math.max(0, start - window.innerHeight * 2) },
+      { progress: -1, scrollY: Math.max(0, start - window.innerHeight) },
+      { progress: -0.5, scrollY: Math.max(0, start - window.innerHeight * 0.5) },
+      { progress: 0, scrollY: start },
+      { progress: 0.5, scrollY: start + travel * 0.5 },
+      { progress: 1, scrollY: start + travel },
+    ];
+    for (const sample of samples) {
+      window.scrollTo(0, Math.round(sample.scrollY));
+      await new Promise((resolve) => setTimeout(resolve, 180));
+      const visual = scene.querySelector("[data-rp-visual]");
+      const content = scene.querySelector("[data-rp-content]");
+      const style = visual ? getComputedStyle(visual) : null;
+      const rect = visual?.getBoundingClientRect();
+      const contentStyle = content ? getComputedStyle(content) : null;
+      const contentRect = content?.getBoundingClientRect();
+      const curtainWidths = Array.from(scene.querySelectorAll("[data-rp-curtain]")).map((curtain) => Math.round(curtain.getBoundingClientRect().width));
+      frames.push({
+        progress: sample.progress,
+        phase: scene.getAttribute("data-rp-phase") || "",
+        entryProgress: scene.style.getPropertyValue("--rp-entry-progress") || "",
+        scrollProgress: scene.style.getPropertyValue("--rp-scroll-progress") || "",
+        visual: visual ? { position: style.position, top: Math.round(rect.top), width: Math.round(rect.width), height: Math.round(rect.height), transform: style.transform } : null,
+        content: content ? { width: Math.round(contentRect.width), height: Math.round(contentRect.height), transform: contentStyle.transform } : null,
+        curtainWidths,
+      });
+    }
+    return frames;
+  });
+}
+
+function evaluateAssertion(assertion, state) {
+  const fail = (message) => ({ ...assertion, pass: false, message });
+  const pass = (details) => ({ ...assertion, pass: true, ...(details ? { details } : {}) });
+  if (assertion.kind === "scene-present") return pass();
+  if (assertion.kind === "runtime-initialized") {
+    return state.after.initialized.includes(assertion.primitive)
+      ? pass({ initialized: state.after.initialized })
+      : fail(`Runtime primitive ${assertion.primitive} did not initialize; found ${state.after.initialized.join(", ") || "none"}.`);
+  }
+  if (state.activationError && ["activation-changes-state", "activation-changes-content", "active-item-width-ratio", "transition-settles"].includes(assertion.kind)) {
+    return fail(state.activationError);
+  }
+  if (assertion.kind === "minimum-item-count") {
+    return state.after.items.length >= assertion.value ? pass({ actual: state.after.items.length }) : fail(`Expected at least ${assertion.value} items; found ${state.after.items.length}.`);
+  }
+  if (assertion.kind === "horizontal-overflow") {
+    const ratio = state.after.track?.clientWidth ? state.after.track.scrollWidth / state.after.track.clientWidth : 0;
+    return ratio >= assertion.minimumRatio ? pass({ actualRatio: round(ratio) }) : fail(`Expected overflow ratio >= ${assertion.minimumRatio}; got ${round(ratio)}.`);
+  }
+  if (assertion.kind === "single-active-item") {
+    return state.after.activeIndexes.length === assertion.value ? pass({ activeIndexes: state.after.activeIndexes }) : fail(`Expected ${assertion.value} active item; found ${state.after.activeIndexes.length}.`);
+  }
+  if (assertion.kind === "initial-active-item-count") {
+    return state.before.activeIndexes.length === assertion.value ? pass({ activeIndexes: state.before.activeIndexes }) : fail(`Expected ${assertion.value} initially active item(s); found ${state.before.activeIndexes.length}.`);
+  }
+  if (assertion.kind === "item-separation") {
+    const gaps = state.before.items.slice(1).map((item, index) => item.rect.left - (state.before.items[index].rect.left + state.before.items[index].rect.width));
+    const expected = assertion.observed || {};
+    const median = (values) => values.length ? values.sort((left, right) => left - right)[Math.floor(values.length / 2)] : 0;
+    let observed = Number(expected.geometricGap) || 0;
+    let actual = median(gaps);
+    let metric = "geometric gap";
+    if (expected.mechanism === "track-gap") {
+      observed = Number(expected.trackGap) || 0;
+      actual = state.before.track?.gap || 0;
+      metric = "track gap";
+    } else if (expected.mechanism === "item-margin") {
+      observed = Number(expected.itemMargin) || 0;
+      actual = median(state.before.items.flatMap((item) => [item.spacing.marginLeft, item.spacing.marginRight]).filter((value) => value > 0));
+      metric = "item margin";
+    } else if (expected.mechanism === "divider") {
+      observed = Number(expected.dividerWidth) || 0;
+      actual = median(state.before.items.flatMap((item) => [item.spacing.borderLeftWidth, item.spacing.borderRightWidth]).filter((value) => value > 0));
+      metric = "divider";
+    } else if (Number(expected.contentInset) > 0) {
+      observed = Number(expected.contentInset);
+      actual = median(state.before.items.flatMap((item) => [item.spacing.paddingLeft, item.spacing.paddingRight]).filter((value) => value > 0));
+      metric = "content inset";
+    }
+    return Math.abs(actual - observed) <= Math.max(2, Math.abs(observed) * 0.2) ? pass({ metric, actual: round(actual) }) : fail(`Expected ${metric} near ${observed}px; got ${round(actual)}px.`);
+  }
+  if (assertion.kind === "activation-changes-state") {
+    return JSON.stringify(state.before.activeIndexes) !== JSON.stringify(state.after.activeIndexes) ? pass() : fail("Activation did not change data-rp-active state.");
+  }
+  if (assertion.kind === "activation-changes-content") {
+    return state.before.panelText !== state.after.panelText ? pass() : fail("Activation did not change visible data-rp-panel content.");
+  }
+  if (assertion.kind === "active-item-width-ratio") {
+    const active = state.after.items.find((item) => item.active);
+    const inactiveWidths = state.after.items.filter((item) => !item.active).map((item) => item.rect.width).filter(Boolean).sort((left, right) => left - right);
+    const collapsed = inactiveWidths[Math.floor(inactiveWidths.length / 2)] || 0;
+    const ratio = collapsed ? active?.rect.width / collapsed : 0;
+    return ratio >= assertion.minimumRatio ? pass({ actualRatio: round(ratio) }) : fail(`Expected active width ratio >= ${assertion.minimumRatio}; got ${round(ratio)}.`);
+  }
+  if (assertion.kind === "transition-settles") {
+    return state.settleMs <= assertion.maximumMs ? pass({ actualMs: state.settleMs }) : fail(`Transition did not settle within ${assertion.maximumMs}ms.`);
+  }
+  if (assertion.kind === "scroll-produces-distinct-phases") {
+    const signatures = new Set(state.scrollFrames.map((frame) => JSON.stringify({ phase: frame.phase, entryProgress: frame.entryProgress, scrollProgress: frame.scrollProgress, visual: frame.visual })));
+    return signatures.size >= assertion.minimumPhaseCount ? pass({ actualPhaseCount: signatures.size }) : fail(`Expected ${assertion.minimumPhaseCount} scroll phases; found ${signatures.size}.`);
+  }
+  if (assertion.kind === "visual-pins-during-scroll") {
+    return state.scrollFrames.some((frame) => frame.visual?.position === "sticky" || frame.visual?.position === "fixed") ? pass() : fail("No sticky/fixed data-rp-visual phase was observed.");
+  }
+  if (assertion.kind === "scroll-visual-expansion") {
+    const widths = state.scrollFrames.map((frame) => frame.visual?.width || 0).filter((width) => width > 0);
+    const widthRatio = widths.length ? Math.max(...widths) / Math.min(...widths) : 0;
+    const curtainTotals = state.scrollFrames.map((frame) => (frame.curtainWidths || []).reduce((total, width) => total + width, 0));
+    const curtainRatio = curtainTotals.length && widths.length
+      ? 1 + (Math.max(...curtainTotals) - Math.min(...curtainTotals)) / Math.max(...widths)
+      : 1;
+    const ratio = Math.max(widthRatio, curtainRatio);
+    return ratio >= assertion.minimumRatio ? pass({ actualRatio: round(ratio) }) : fail(`Expected scroll visual expansion ratio >= ${assertion.minimumRatio}; got ${round(ratio)}.`);
+  }
+  if (assertion.kind === "scroll-content-scale-bound") {
+    const widths = state.scrollFrames.map((frame) => frame.content?.width || 0).filter((width) => width > 0);
+    const heights = state.scrollFrames.map((frame) => frame.content?.height || 0).filter((height) => height > 0);
+    const ratio = Math.max(
+      widths.length ? Math.max(...widths) / Math.min(...widths) : 1,
+      heights.length ? Math.max(...heights) / Math.min(...heights) : 1,
+    );
+    return ratio <= assertion.maximumRatio ? pass({ actualRatio: round(ratio) }) : fail(`Expected content scale ratio <= ${assertion.maximumRatio}; got ${round(ratio)}.`);
+  }
+  if (assertion.kind === "exclusive-media-layer") {
+    const fallback = canonicalUrl(assertion.fallbackSource);
+    const overlaps = state.after.overlappingFallbackSources.filter((source) => canonicalUrl(source) === fallback);
+    return overlaps.length === 0
+      ? pass()
+      : fail(`Fallback layer overlaps active media: ${overlaps.join(", ")}.`);
+  }
+  if (assertion.kind === "hover-changes-visual-state") {
+    if (state.hoverError) return fail(state.hoverError);
+    return JSON.stringify(state.hoverBefore || []) !== JSON.stringify(state.hoverAfter || [])
+      ? pass()
+      : fail("Hover did not change any marked control's visual state.");
+  }
+  if (assertion.kind === "media-source-present") {
+    const canonical = canonicalUrl(assertion.source);
+    const matched = state.after.media.find((item) => canonicalUrl(item.src) === canonical || item.src.includes(assertion.source));
+    if (!matched) return fail(`Missing required media source ${assertion.source}.`);
+    const mismatches = Object.entries(assertion.playback || {}).filter(([key, value]) => typeof value === "boolean" && Boolean(matched[key]) !== value);
+    return mismatches.length
+      ? fail(`Media playback flags differ: ${mismatches.map(([key, value]) => `${key}=${value}`).join(", ")}.`)
+      : pass({ source: matched.src });
+  }
+  return fail(`Unsupported interaction assertion: ${assertion.kind}`);
+}
+
+function canonicalUrl(value) {
+  try {
+    const url = new URL(value);
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return String(value || "");
+  }
+}
+
+function escapeAttribute(value) {
+  return String(value || "").replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
+function round(value) {
+  return Math.round((Number(value) || 0) * 1000) / 1000;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error.stack || error.message);
+    process.exit(1);
+  });
+}