@wix/agent-skills 1.36.0 → 1.36.1

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

@@ -1,669 +0,0 @@
-#!/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);
-  });
-}