@pygmalionjs/pygmalion 0.2.10 → 0.2.12

package/node/storyboard-capture-runtime.mjs

@@ -0,0 +1,1165 @@
+import { createHash } from 'node:crypto';
+
+const DEFAULT_VIEWPORT = Object.freeze({ width: 1280, height: 800 });
+const QA_FAILURE_STAGES = new Set(['interaction', 'assertion']);
+const STORYBOARD_ENVIRONMENT_QUERY = '__pygmalion_environment';
+const FROZEN_STYLE =
+  '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}';
+const DOM_STABLE_ATTRIBUTES = new Set([
+  'type',
+  'name',
+  'role',
+  'class',
+  'href',
+  'src',
+  'alt',
+  'title',
+  'aria-label',
+  'aria-expanded',
+  'aria-hidden',
+  'aria-pressed',
+  'aria-selected',
+  'aria-checked',
+  'aria-disabled',
+  'disabled',
+  'checked',
+  'selected',
+  'open',
+  'data-testid',
+  'data-state',
+  'data-scenario',
+  'data-kind',
+  'data-card-key',
+]);
+
+export const STORYBOARD_CAPTURE_STATUSES = Object.freeze({
+  ready: 'ready',
+  qaFailure: 'rendered-with-qa-failure',
+  captureError: 'capture-error',
+});
+
+export class StoryboardCaptureStageError extends Error {
+  constructor(stage, error, details = {}) {
+    const message = error instanceof Error ? error.message : String(error);
+    super(message, { cause: error });
+    this.name = 'StoryboardCaptureStageError';
+    this.stage = stage;
+    this.details = details;
+  }
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function boundedDiagnosticText(value, maximumLength) {
+  if (typeof value !== 'string') return undefined;
+  const normalized = value
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, ' ')
+    .trim();
+  if (!normalized) return undefined;
+  return normalized.length <= maximumLength
+    ? normalized
+    : `${normalized.slice(0, Math.max(0, maximumLength - 1))}…`;
+}
+
+function asPositiveInteger(value, fallback) {
+  return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function captureViewport(screenCase) {
+  return {
+    width: asPositiveInteger(screenCase?.width, DEFAULT_VIEWPORT.width),
+    height: asPositiveInteger(screenCase?.height, DEFAULT_VIEWPORT.height),
+  };
+}
+
+function throwIfAborted(signal) {
+  signal?.throwIfAborted?.();
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error
+      ? signal.reason
+      : new Error('Storyboard capture was aborted.');
+  }
+}
+
+async function atCaptureStage(stage, task, details = {}) {
+  try {
+    return await task();
+  } catch (error) {
+    if (error instanceof StoryboardCaptureStageError) throw error;
+    throw new StoryboardCaptureStageError(stage, error, details);
+  }
+}
+
+export function resolveStoryboardCaptureRoute(screenCase) {
+  return (
+    screenCase?.route ??
+    screenCase?.coverageRoutes?.[0] ??
+    screenCase?.path ??
+    null
+  );
+}
+
+/**
+ * Resolves an application route without dropping a proxy prefix in the base URL.
+ */
+export function resolveStoryboardCaptureUrl(baseUrl, route, environment) {
+  const base = new URL(baseUrl);
+  const routeUrl = new URL(String(route ?? ''), 'http://pygmalion-route.local');
+  const prefix = base.pathname.endsWith('/')
+    ? base.pathname
+    : `${base.pathname}/`;
+  base.pathname = `${prefix}${routeUrl.pathname.replace(/^\/+/, '')}`.replace(
+    /\/{2,}/g,
+    '/',
+  );
+  base.search = routeUrl.search;
+  base.hash = routeUrl.hash;
+  if (
+    environment &&
+    typeof environment === 'object' &&
+    !Array.isArray(environment) &&
+    Object.keys(environment).length > 0
+  ) {
+    base.searchParams.set(
+      STORYBOARD_ENVIRONMENT_QUERY,
+      Buffer.from(JSON.stringify(environment), 'utf8').toString('base64url'),
+    );
+  }
+  return base.href;
+}
+
+export function resolveStoryboardFixedTime(preset) {
+  if (preset?.timers?.mode !== 'fixed') return null;
+  const value = preset.timers.now;
+  const time =
+    typeof value === 'string' || typeof value === 'number'
+      ? new Date(value)
+      : null;
+  if (!time || Number.isNaN(time.getTime())) {
+    throw new Error(
+      'A valid timers.now value is required when timers.mode is fixed.',
+    );
+  }
+  return time.toISOString();
+}
+
+export function hashStoryboardCapture(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function normalizeCapturedClass(value) {
+  return value
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((name) =>
+      name
+        .replace(/__[A-Za-z0-9_-]+_[A-Za-z0-9]{5,}$/g, '__{hash}')
+        .replace(/_[A-Za-z0-9]{6,}$/g, '_{hash}'),
+    )
+    .sort()
+    .join(' ');
+}
+
+function normalizeCapturedUrl(value) {
+  if (/^(?:blob:|data:)/.test(value)) {
+    return `{${value.split(':', 1)[0]}}`;
+  }
+  return value
+    .replace(/[?#].*$/, '')
+    .replace(/\/[a-f0-9]{16,}(?=\/|$)/gi, '/{id}');
+}
+
+function normalizeCapturedAttribute(name, value) {
+  if (name === 'class') return normalizeCapturedClass(value);
+  if (name === 'href' || name === 'src') return normalizeCapturedUrl(value);
+  if (name === 'style') {
+    return value
+      .split(';')
+      .map((declaration) => declaration.split(':', 1)[0]?.trim())
+      .filter(Boolean)
+      .sort()
+      .join(';');
+  }
+  if (!DOM_STABLE_ATTRIBUTES.has(name)) return '{value}';
+  return value
+    .replace(/\b[0-9a-f]{8}-[0-9a-f-]{27,}\b/gi, '{uuid}')
+    .replace(/\b\d{10,}\b/g, '{number}')
+    .replace(/\b[a-f0-9]{20,}\b/gi, '{hash}');
+}
+
+function normalizedCapturedNode(node) {
+  if (!node) return '';
+  if (node.type === 'text') return '#text';
+  const attributes = [...(node.attributes ?? [])]
+    .map(([name, value]) => [
+      name.toLowerCase(),
+      normalizeCapturedAttribute(name.toLowerCase(), value),
+    ])
+    .sort(([left], [right]) => left.localeCompare(right));
+  const children = (node.children ?? [])
+    .map(normalizedCapturedNode)
+    .filter(Boolean);
+  return {
+    tag: String(node.tag ?? '').toLowerCase(),
+    attributes,
+    children,
+  };
+}
+
+/**
+ * Produces a stable structural DOM identity without volatile text, IDs, or
+ * generated class suffixes.
+ */
+export function normalizeStoryboardDomStructure(node) {
+  return JSON.stringify(normalizedCapturedNode(node));
+}
+
+export function createStoryboardArtifactRecord({
+  screenCase,
+  domTree,
+  screenshot,
+  route,
+}) {
+  return {
+    id: screenCase.id,
+    scenarioIds: [...(screenCase.scenarioIds ?? [])],
+    route,
+    viewport: {
+      width: screenCase.width ?? DEFAULT_VIEWPORT.width,
+      height: screenCase.height ?? DEFAULT_VIEWPORT.height,
+    },
+    domStructureHash: hashStoryboardCapture(
+      normalizeStoryboardDomStructure(domTree),
+    ),
+    screenshotHash: hashStoryboardCapture(screenshot),
+  };
+}
+
+function normalizeText(value) {
+  return String(value ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Returns every user-facing label that can identify an interactive element.
+ *
+ * This function is self-contained because Playwright serializes it into the page.
+ */
+export function storyboardCaptureCandidateTexts(element) {
+  const valueControl =
+    element instanceof HTMLInputElement ||
+    element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement;
+  return [
+    ...new Set(
+      [
+        element.getAttribute('aria-label') ?? '',
+        element.getAttribute('title') ?? '',
+        valueControl ? element.value : '',
+        element.textContent ?? '',
+      ]
+        .map((value) => String(value).trim())
+        .filter(Boolean),
+    ),
+  ];
+}
+
+async function candidateLocator(page, item) {
+  const selector =
+    item.selector ??
+    'button,a,input,textarea,select,[role="button"],[role="tab"],[role="menuitem"],[role="option"]';
+  const candidates = page.locator(selector);
+  if (!item.text) return candidates.nth(item.index ?? 0);
+  const expected = normalizeText(item.text);
+  const count = await candidates.count();
+  const matches = [];
+  for (let index = 0; index < count; index += 1) {
+    const candidate = candidates.nth(index);
+    const actual = await candidate.evaluate(storyboardCaptureCandidateTexts);
+    const normalized = actual.map(normalizeText);
+    if (
+      normalized.some((value) =>
+        item.exact ? value === expected : value.includes(expected),
+      )
+    ) {
+      matches.push(candidate);
+    }
+  }
+  return (
+    matches[item.index ?? 0] ?? page.locator('__pygmalion_missing_target__')
+  );
+}
+
+async function targetExists(locator, timeoutMs, state = 'attached') {
+  try {
+    await locator.waitFor({ state, timeout: timeoutMs });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForCandidateLocator(page, item, timeoutMs) {
+  const startedAt = Date.now();
+  do {
+    const target = await candidateLocator(page, item);
+    if ((await target.count()) > 0) return target;
+    if (Date.now() - startedAt >= timeoutMs) return target;
+    await page.waitForTimeout(100);
+  } while (true);
+}
+
+export async function runStoryboardInteraction(page, interaction) {
+  const settleMs =
+    interaction.settleMs ?? (interaction.action === 'storage' ? 50 : 600);
+  if (interaction.action === 'wait') {
+    if (interaction.selector || interaction.text) {
+      const timeoutMs = interaction.timeoutMs ?? 5_000;
+      const waitState = interaction.waitState ?? 'visible';
+      if (!['attached', 'visible'].includes(waitState)) {
+        throw new Error(
+          `"${interaction.label}" waitState must be attached or visible.`,
+        );
+      }
+      const target = await waitForCandidateLocator(
+        page,
+        interaction,
+        timeoutMs,
+      );
+      if (!(await targetExists(target, timeoutMs, waitState))) {
+        throw new Error(
+          `"${interaction.label}" did not reach the expected screen state.`,
+        );
+      }
+    }
+    await page.waitForTimeout(
+      interaction.settleMs ?? Number(interaction.value ?? 500),
+    );
+    return;
+  }
+
+  if (interaction.action === 'storage') {
+    await page.evaluate(
+      ({ storageType, key, value }) => {
+        const target =
+          storageType === 'session'
+            ? window.sessionStorage
+            : window.localStorage;
+        if (!key) throw new Error('Storage key is missing.');
+        if (value == null) target.removeItem(key);
+        else target.setItem(key, value);
+      },
+      {
+        storageType: interaction.storage,
+        key: interaction.key,
+        value: interaction.value,
+      },
+    );
+    await page.waitForTimeout(settleMs);
+    return;
+  }
+
+  const timeoutMs = interaction.timeoutMs ?? 5_000;
+  const target = await waitForCandidateLocator(page, interaction, timeoutMs);
+  if (!(await targetExists(target, Math.min(timeoutMs, 500)))) {
+    throw new Error(`"${interaction.label}" target was not found.`);
+  }
+  try {
+    if (interaction.action === 'click') {
+      await target.click({ timeout: timeoutMs });
+    } else if (interaction.action === 'focus') {
+      await target.focus({ timeout: timeoutMs });
+    } else if (interaction.action === 'fill') {
+      await target.fill(interaction.value ?? '', { timeout: timeoutMs });
+    } else if (interaction.action === 'check') {
+      await target.check({ timeout: timeoutMs });
+    } else if (interaction.action === 'press') {
+      await target.press(interaction.key ?? interaction.value ?? 'Enter', {
+        timeout: timeoutMs,
+      });
+    } else {
+      throw new Error(`Unsupported interaction action: ${interaction.action}`);
+    }
+  } catch (error) {
+    throw new Error(
+      `"${interaction.label}" interaction failed: ${messageOf(error)}`,
+    );
+  }
+  await page.waitForTimeout(settleMs);
+}
+
+async function assertionFailure(page, assertion) {
+  let target;
+  try {
+    target = page.locator(assertion.selector).nth(assertion.index ?? 0);
+  } catch {
+    return 'The selector is invalid.';
+  }
+  const count = await page
+    .locator(assertion.selector)
+    .count()
+    .catch(() => 0);
+  const exists = count > (assertion.index ?? 0);
+  const expectedExists = assertion.exists !== false;
+  if (exists !== expectedExists) {
+    return `Existence mismatch (${exists} !== ${expectedExists}).`;
+  }
+  if (!exists) return null;
+  if (assertion.text != null) {
+    const actual = normalizeText(
+      await target.evaluate((element) =>
+        'value' in element
+          ? String(element.value ?? '')
+          : (element.textContent ?? ''),
+      ),
+    );
+    const expected = normalizeText(assertion.text);
+    if (assertion.exact ? actual !== expected : !actual.includes(expected)) {
+      return `Text mismatch ("${actual}" / "${expected}").`;
+    }
+  }
+  if (assertion.attribute) {
+    const actual = await target.getAttribute(assertion.attribute.name);
+    const present = actual != null;
+    const expectedPresent = assertion.attribute.present !== false;
+    const matchesValue =
+      assertion.attribute.value == null ||
+      (assertion.attribute.match === 'contains'
+        ? (actual ?? '').includes(assertion.attribute.value)
+        : actual === assertion.attribute.value);
+    if (present !== expectedPresent || (expectedPresent && !matchesValue)) {
+      return `Attribute mismatch (${assertion.attribute.name}).`;
+    }
+  }
+  if (assertion.visibility) {
+    const visible = await target.evaluate((element) => {
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return (
+        style.display !== 'none' &&
+        style.visibility !== 'hidden' &&
+        Number(style.opacity) !== 0 &&
+        rect.width > 0 &&
+        rect.height > 0
+      );
+    });
+    if ((assertion.visibility === 'visible') !== visible) {
+      return 'Visibility mismatch.';
+    }
+  }
+  return null;
+}
+
+export async function runStoryboardAssertion(page, assertion) {
+  const timeoutMs = assertion.timeoutMs ?? 2_000;
+  const startedAt = Date.now();
+  let failure = null;
+  do {
+    failure = await assertionFailure(page, assertion);
+    if (!failure || Date.now() - startedAt >= timeoutMs) break;
+    await page.waitForTimeout(100);
+  } while (true);
+  if (failure) {
+    throw new StoryboardCaptureStageError(
+      'assertion',
+      new Error(`"${assertion.label}" assertion failed: ${failure}`),
+      {
+        label: assertion.label,
+        selector: assertion.selector,
+      },
+    );
+  }
+}
+
+/**
+ * Finds a visible modal that is not explicitly authorized by a positive assertion.
+ *
+ * This function is self-contained because Playwright serializes it into the page.
+ */
+export function findUnassertedStoryboardModal(assertions = []) {
+  const modalSelector =
+    'dialog[open],[role="dialog"],[role="alertdialog"],[aria-modal="true"]';
+  const visibleModals = [...document.querySelectorAll(modalSelector)].filter(
+    (element) => {
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      const intersectsViewport =
+        !Number.isFinite(rect.top) ||
+        !Number.isFinite(rect.left) ||
+        (rect.bottom > 0 &&
+          rect.right > 0 &&
+          rect.top < window.innerHeight &&
+          rect.left < window.innerWidth);
+      return (
+        !element.hasAttribute('hidden') &&
+        element.getAttribute('aria-hidden') !== 'true' &&
+        style.display !== 'none' &&
+        style.visibility !== 'hidden' &&
+        Number.parseFloat(style.opacity || '1') !== 0 &&
+        rect.width > 0 &&
+        rect.height > 0 &&
+        intersectsViewport
+      );
+    },
+  );
+
+  for (const modal of visibleModals) {
+    const asserted = assertions.some((assertion) => {
+      if (
+        assertion?.optional ||
+        assertion?.exists === false ||
+        typeof assertion?.selector !== 'string'
+      ) {
+        return false;
+      }
+      try {
+        const matches = document.querySelectorAll(assertion.selector);
+        const index = Number.isInteger(assertion.index) ? assertion.index : 0;
+        const target = matches[index];
+        return Boolean(target && (target === modal || modal.contains(target)));
+      } catch {
+        return false;
+      }
+    });
+    if (asserted) continue;
+
+    const labelledBy = modal.getAttribute('aria-labelledby');
+    const labelledText = labelledBy
+      ? document.getElementById(labelledBy)?.textContent
+      : '';
+    const label = (
+      modal.getAttribute('aria-label') ||
+      labelledText ||
+      modal.textContent ||
+      ''
+    )
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, 120);
+    return {
+      role: modal.getAttribute('role') || modal.tagName.toLowerCase(),
+      label,
+    };
+  }
+  return null;
+}
+
+export async function assertFinalStoryboardState(page, assertions) {
+  for (const assertion of assertions) {
+    await runStoryboardAssertion(page, assertion);
+  }
+  const unassertedModal = await page.evaluate(
+    findUnassertedStoryboardModal,
+    assertions,
+  );
+  if (!unassertedModal) return;
+  throw new StoryboardCaptureStageError(
+    'assertion',
+    new Error(
+      `A visible ${unassertedModal.role} has no final assertion` +
+        `${unassertedModal.label ? `: ${unassertedModal.label}` : ''}`,
+    ),
+    {
+      label: unassertedModal.label,
+      selector:
+        'dialog[open],[role="dialog"],[role="alertdialog"],[aria-modal="true"]',
+    },
+  );
+}
+
+async function installStoryboardPreset(context, page, preset) {
+  if (!preset) return;
+  await context.addInitScript((value) => {
+    window.__PYGMALION_SCREEN_PRESET__ = value;
+    const local = value.localStorage ?? value.storage?.local;
+    const session = value.sessionStorage ?? value.storage?.session;
+    try {
+      for (const [key, item] of Object.entries(local ?? {})) {
+        if (item == null) window.localStorage.removeItem(key);
+        else window.localStorage.setItem(key, String(item));
+      }
+      for (const [key, item] of Object.entries(session ?? {})) {
+        if (item == null) window.sessionStorage.removeItem(key);
+        else window.sessionStorage.setItem(key, String(item));
+      }
+    } catch {
+      // The script runs again after an opaque initial page reaches the app origin.
+    }
+  }, preset);
+  const media = preset.media ?? preset;
+  if (media.colorScheme || media.reducedMotion) {
+    await page.emulateMedia({
+      colorScheme: media.colorScheme,
+      reducedMotion: media.reducedMotion,
+    });
+  }
+}
+
+async function executeStoryboardPreset(page, screenCase, route) {
+  if (!screenCase.preset) return;
+  const request = {
+    pageId: screenCase.id,
+    route,
+    preset: screenCase.preset,
+  };
+  await page.evaluate(async (payload) => {
+    const runtime = window;
+    runtime.sessionStorage.setItem(
+      'pygmalion:screen-capture-preset',
+      JSON.stringify(payload.preset),
+    );
+    await runtime.__PYGMALION_APPLY_SCREEN_PRESET__?.(payload);
+    runtime.dispatchEvent(
+      new CustomEvent('pygmalion:screen-capture-preset', {
+        detail: payload,
+      }),
+    );
+  }, request);
+}
+
+export function collectStoryboardDomTree() {
+  const visit = (node) => {
+    if (node.nodeType === Node.TEXT_NODE) {
+      return node.textContent?.trim() ? { type: 'text' } : null;
+    }
+    if (!(node instanceof Element)) return null;
+    if (['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'].includes(node.tagName)) {
+      return null;
+    }
+    return {
+      type: 'element',
+      tag: node.tagName.toLowerCase(),
+      attributes: [...node.attributes].map((attribute) => [
+        attribute.name,
+        attribute.value,
+      ]),
+      children: [...node.childNodes].map(visit).filter(Boolean),
+    };
+  };
+  return visit(document.body);
+}
+
+/**
+ * Returns a compact stability signature for the rendered document.
+ *
+ * The mutation revision observes the entire document element, which includes
+ * React portals mounted beside the application root. Layout and visible
+ * overlay details cover changes that can occur without changing DOM length.
+ * This function is self-contained because Playwright serializes it into the
+ * page.
+ */
+export function storyboardDocumentStabilitySignature() {
+  const runtime = window;
+  const trackerKey = '__PYGMALION_STORYBOARD_STABILITY__';
+  let tracker = runtime[trackerKey];
+  if (!tracker || tracker.document !== document) {
+    tracker?.observer?.disconnect?.();
+    tracker = {
+      document,
+      observer: null,
+      revision: 0,
+    };
+    if (
+      document.documentElement &&
+      typeof runtime.MutationObserver === 'function'
+    ) {
+      tracker.observer = new runtime.MutationObserver(() => {
+        tracker.revision += 1;
+      });
+      tracker.observer.observe(document.documentElement, {
+        attributes: true,
+        characterData: true,
+        childList: true,
+        subtree: true,
+      });
+    }
+    runtime[trackerKey] = tracker;
+  }
+
+  const root = document.documentElement;
+  const body = document.body;
+  const modalSelector =
+    'dialog[open],[role="dialog"],[role="alertdialog"],[aria-modal="true"]';
+  const overlays = [...document.querySelectorAll(modalSelector)]
+    .filter((element) => {
+      const style = getComputedStyle(element);
+      const rect = element.getBoundingClientRect();
+      return (
+        !element.hasAttribute('hidden') &&
+        element.getAttribute('aria-hidden') !== 'true' &&
+        style.display !== 'none' &&
+        style.visibility !== 'hidden' &&
+        Number.parseFloat(style.opacity || '1') !== 0 &&
+        rect.width > 0 &&
+        rect.height > 0
+      );
+    })
+    .map((element) => {
+      const rect = element.getBoundingClientRect();
+      return [
+        element.tagName,
+        element.getAttribute('role') ?? '',
+        element.getAttribute('aria-modal') ?? '',
+        Math.round(rect.left),
+        Math.round(rect.top),
+        Math.round(rect.width),
+        Math.round(rect.height),
+        (element.textContent ?? '').replace(/\s+/g, ' ').trim().slice(0, 160),
+      ];
+    });
+
+  return JSON.stringify({
+    readyState: document.readyState,
+    revision: tracker.revision,
+    elementCount: body?.querySelectorAll('*').length ?? 0,
+    scrollWidth: Math.max(root?.scrollWidth ?? 0, body?.scrollWidth ?? 0),
+    scrollHeight: Math.max(root?.scrollHeight ?? 0, body?.scrollHeight ?? 0),
+    overlays,
+  });
+}
+
+export async function waitForStableStoryboardDocument(
+  page,
+  {
+    attempts = 20,
+    requiredStableSamples = 3,
+    intervalMs = 100,
+    minimumWaitMs = 400,
+  } = {},
+) {
+  await page.evaluate(async () => {
+    await document.fonts?.ready;
+  });
+  let previous = '';
+  let stable = 0;
+  let elapsedMs = 0;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const current = await page.evaluate(storyboardDocumentStabilitySignature);
+    if (current === previous) stable += 1;
+    else stable = 0;
+    previous = current;
+    if (stable >= requiredStableSamples && elapsedMs >= minimumWaitMs) {
+      return true;
+    }
+    await page.waitForTimeout(intervalMs);
+    elapsedMs += intervalMs;
+  }
+  return stable >= requiredStableSamples && elapsedMs >= minimumWaitMs;
+}
+
+/**
+ * Serializes the current document into an inert, standalone DOM preview.
+ *
+ * This function is self-contained because Playwright serializes it into the page.
+ */
+export function serializeStoryboardPreviewDocument(
+  baseHref = '__PYGMALION_PREVIEW_BASE__',
+) {
+  const clone = document.documentElement.cloneNode(true);
+  if (!(clone instanceof HTMLElement)) return null;
+
+  const sourceInputs = [...document.querySelectorAll('input')];
+  const cloneInputs = [...clone.querySelectorAll('input')];
+  sourceInputs.forEach((source, index) => {
+    const target = cloneInputs[index];
+    if (!target) return;
+    target.setAttribute('value', source.value);
+    if (source.checked) target.setAttribute('checked', '');
+    else target.removeAttribute('checked');
+  });
+
+  const sourceTextareas = [...document.querySelectorAll('textarea')];
+  const cloneTextareas = [...clone.querySelectorAll('textarea')];
+  sourceTextareas.forEach((source, index) => {
+    const target = cloneTextareas[index];
+    if (target) target.textContent = source.value;
+  });
+
+  const sourceSelects = [...document.querySelectorAll('select')];
+  const cloneSelects = [...clone.querySelectorAll('select')];
+  sourceSelects.forEach((source, index) => {
+    const target = cloneSelects[index];
+    if (!target) return;
+    [...target.options].forEach((option, optionIndex) => {
+      if (source.options[optionIndex]?.selected) {
+        option.setAttribute('selected', '');
+      } else {
+        option.removeAttribute('selected');
+      }
+    });
+  });
+
+  const sourceCanvases = [...document.querySelectorAll('canvas')];
+  const cloneCanvases = [...clone.querySelectorAll('canvas')];
+  sourceCanvases.forEach((source, index) => {
+    const target = cloneCanvases[index];
+    if (!target) return;
+    const image = document.createElement('img');
+    for (const attribute of [...target.attributes]) {
+      image.setAttribute(attribute.name, attribute.value);
+    }
+    image.width = source.width;
+    image.height = source.height;
+    image.alt ||= 'canvas snapshot';
+    try {
+      image.src = source.toDataURL();
+    } catch {
+      image.src =
+        'data:image/svg+xml;charset=utf-8,' +
+        encodeURIComponent(
+          `<svg xmlns="http://www.w3.org/2000/svg" width="${source.width}" height="${source.height}"/>`,
+        );
+    }
+    target.replaceWith(image);
+  });
+
+  clone
+    .querySelectorAll(
+      'script,noscript,iframe,object,embed,link[rel="modulepreload"],link[rel="preload"][as="script"]',
+    )
+    .forEach((element) => element.remove());
+  for (const element of [clone, ...clone.querySelectorAll('*')]) {
+    for (const attribute of [...element.attributes]) {
+      const name = attribute.name.toLowerCase();
+      if (name.startsWith('on')) element.removeAttribute(attribute.name);
+      if (
+        (name === 'href' ||
+          name === 'src' ||
+          name === 'action' ||
+          name === 'formaction') &&
+        /^\s*javascript\s*:/i.test(attribute.value)
+      ) {
+        element.removeAttribute(attribute.name);
+      }
+    }
+  }
+
+  let head = clone.querySelector('head');
+  if (!head) {
+    head = document.createElement('head');
+    clone.prepend(head);
+  }
+  head.querySelectorAll('base').forEach((element) => element.remove());
+  const base = document.createElement('base');
+  base.setAttribute('href', baseHref);
+  head.prepend(base);
+
+  const csp = document.createElement('meta');
+  csp.setAttribute('http-equiv', 'Content-Security-Policy');
+  csp.setAttribute('content', "script-src 'none'; object-src 'none'");
+  head.prepend(csp);
+
+  const frozenStyle = document.createElement('style');
+  frozenStyle.setAttribute('data-pygmalion-preview', 'frozen');
+  frozenStyle.textContent =
+    '*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}html,body{pointer-events:none!important}';
+  head.append(frozenStyle);
+
+  return `<!doctype html>${clone.outerHTML}`;
+}
+
+function captureDiagnostic(error, viewport) {
+  const stage =
+    error instanceof StoryboardCaptureStageError ? error.stage : 'unknown';
+  const details =
+    error instanceof StoryboardCaptureStageError ? error.details : {};
+  const selector = boundedDiagnosticText(details.selector, 4_096);
+  const label = boundedDiagnosticText(details.label, 1_024);
+  const message =
+    boundedDiagnosticText(messageOf(error), 4_096) ?? 'Capture failed.';
+  return {
+    stage,
+    code: QA_FAILURE_STAGES.has(stage)
+      ? `${stage}-failed`
+      : 'capture-stage-failed',
+    ...(selector ? { selector } : {}),
+    ...(label ? { label } : {}),
+    message,
+    viewport,
+  };
+}
+
+async function collectStableEvidence(
+  page,
+  viewport,
+  {
+    includeDomTree,
+    includePreviewSnapshot,
+    previewBaseToken,
+    screenshotOptions,
+  },
+) {
+  const evidence = {};
+  const errors = [];
+  try {
+    await page.addStyleTag({ content: FROZEN_STYLE });
+    const stable = await waitForStableStoryboardDocument(page);
+    if (!stable) {
+      throw new Error(
+        'The rendered document did not reach a stable DOM and overlay state.',
+      );
+    }
+  } catch (error) {
+    errors.push(new StoryboardCaptureStageError('stabilize', error));
+  }
+  if (includeDomTree) {
+    try {
+      evidence.domTree = await page.evaluate(collectStoryboardDomTree);
+    } catch (error) {
+      errors.push(new StoryboardCaptureStageError('serialize', error));
+    }
+  }
+  if (includePreviewSnapshot) {
+    try {
+      const snapshot = await page.evaluate(
+        serializeStoryboardPreviewDocument,
+        previewBaseToken,
+      );
+      if (
+        typeof snapshot !== 'string' ||
+        !snapshot.includes(previewBaseToken)
+      ) {
+        throw new Error('The inert DOM snapshot is invalid.');
+      }
+      evidence.snapshot = snapshot;
+    } catch (error) {
+      errors.push(new StoryboardCaptureStageError('serialize', error));
+    }
+  }
+  try {
+    evidence.screenshot = {
+      mediaType: 'image/png',
+      width: viewport.width,
+      height: viewport.height,
+      bytes: await page.screenshot({
+        type: 'png',
+        fullPage: false,
+        animations: 'disabled',
+        caret: 'hide',
+        ...screenshotOptions,
+      }),
+    };
+  } catch (error) {
+    errors.push(new StoryboardCaptureStageError('screenshot', error));
+  }
+  return { evidence, errors };
+}
+
+function captureResult({
+  screenCase,
+  route,
+  viewport,
+  status,
+  evidence,
+  diagnostics,
+}) {
+  return {
+    id: screenCase.id,
+    route,
+    status,
+    viewport,
+    ...(evidence.snapshot == null ? {} : { snapshot: evidence.snapshot }),
+    ...(evidence.screenshot == null ? {} : { screenshot: evidence.screenshot }),
+    ...(evidence.domTree == null ? {} : { domTree: evidence.domTree }),
+    diagnostics,
+  };
+}
+
+/**
+ * Captures one storyboard case with a Playwright-compatible browser.
+ *
+ * Pygmalion owns the deterministic browser lifecycle and QA status model. The
+ * host application owns only domain setup through hooks.
+ */
+export async function captureStoryboardCase({
+  browser,
+  baseUrl,
+  screenCase,
+  signal,
+  hooks = {},
+  includeDomTree = true,
+  includePreviewSnapshot = true,
+  previewBaseToken = '__PYGMALION_PREVIEW_BASE__',
+  contextOptions = {},
+  navigationOptions = {},
+  screenshotOptions = {},
+} = {}) {
+  if (!browser || typeof browser.newContext !== 'function') {
+    throw new TypeError(
+      'captureStoryboardCase requires a Playwright-compatible browser.',
+    );
+  }
+  if (!screenCase || typeof screenCase !== 'object') {
+    throw new TypeError('captureStoryboardCase requires a screen case.');
+  }
+  const viewport = captureViewport(screenCase);
+  const route = resolveStoryboardCaptureRoute(screenCase);
+  if (route == null || route === '') {
+    const error = new StoryboardCaptureStageError(
+      'recipe',
+      'The screen case has no route, coverage route, or path.',
+    );
+    return captureResult({
+      screenCase,
+      route: null,
+      viewport,
+      status: STORYBOARD_CAPTURE_STATUSES.captureError,
+      evidence: {},
+      diagnostics: [captureDiagnostic(error, viewport)],
+    });
+  }
+
+  let context = null;
+  let page = null;
+  let primaryError = null;
+  let evidence = {};
+  const evidenceErrors = [];
+  try {
+    throwIfAborted(signal);
+    context = await atCaptureStage('setup', () =>
+      browser.newContext({
+        viewport,
+        colorScheme: 'light',
+        reducedMotion: 'reduce',
+        locale: 'en-US',
+        timezoneId: 'UTC',
+        ...contextOptions,
+        viewport,
+      }),
+    );
+    await atCaptureStage('setup', () =>
+      context.addInitScript(() => {
+        let seed = 0x5f3759df;
+        Math.random = () => {
+          seed = (seed * 1664525 + 1013904223) >>> 0;
+          return seed / 0x100000000;
+        };
+      }),
+    );
+    page = await atCaptureStage('setup', () => context.newPage());
+
+    await atCaptureStage('preset', async () => {
+      throwIfAborted(signal);
+      const fixedTime = resolveStoryboardFixedTime(screenCase.preset);
+      if (fixedTime) await page.clock.setFixedTime(fixedTime);
+      await hooks.beforePreset?.({ context, page, screenCase, route, signal });
+      await installStoryboardPreset(context, page, screenCase.preset);
+    });
+    await atCaptureStage('navigation', () =>
+      page.goto(
+        resolveStoryboardCaptureUrl(baseUrl, route, screenCase.environment),
+        {
+          waitUntil: 'domcontentloaded',
+          timeout: 30_000,
+          ...navigationOptions,
+        },
+      ),
+    );
+    await atCaptureStage('preset', async () => {
+      await executeStoryboardPreset(page, screenCase, route);
+      await hooks.afterPreset?.({
+        context,
+        page,
+        screenCase,
+        route,
+        signal,
+      });
+    });
+    for (const interaction of screenCase.interactions ?? []) {
+      throwIfAborted(signal);
+      await atCaptureStage(
+        'interaction',
+        () => runStoryboardInteraction(page, interaction),
+        {
+          label: interaction.label,
+          selector: interaction.selector,
+        },
+      );
+    }
+    await atCaptureStage('stabilize', async () => {
+      await page.addStyleTag({ content: FROZEN_STYLE });
+      const stable = await waitForStableStoryboardDocument(page);
+      if (!stable) {
+        throw new Error(
+          'The rendered document did not reach a stable DOM and overlay state.',
+        );
+      }
+    });
+    await atCaptureStage('assertion', async () => {
+      await assertFinalStoryboardState(page, screenCase.assertions ?? []);
+    });
+  } catch (error) {
+    primaryError =
+      error instanceof StoryboardCaptureStageError
+        ? error
+        : new StoryboardCaptureStageError('unknown', error);
+  }
+
+  if (page) {
+    const collected = await collectStableEvidence(page, viewport, {
+      includeDomTree,
+      includePreviewSnapshot,
+      previewBaseToken,
+      screenshotOptions,
+    });
+    evidence = collected.evidence;
+    evidenceErrors.push(...collected.errors);
+    if (!primaryError) {
+      try {
+        await atCaptureStage('assertion', () =>
+          assertFinalStoryboardState(page, screenCase.assertions ?? []),
+        );
+      } catch (error) {
+        primaryError = error;
+      }
+    }
+  }
+
+  try {
+    await context?.close();
+  } catch (error) {
+    evidenceErrors.push(new StoryboardCaptureStageError('teardown', error));
+  }
+
+  if (!primaryError && evidenceErrors.length === 0) {
+    return captureResult({
+      screenCase,
+      route,
+      viewport,
+      status: STORYBOARD_CAPTURE_STATUSES.ready,
+      evidence,
+      diagnostics: [],
+    });
+  }
+
+  const error =
+    primaryError ??
+    evidenceErrors[0] ??
+    new StoryboardCaptureStageError('unknown', 'Capture failed.');
+  const preservesStableOutput = Boolean(
+    evidence.snapshot && evidence.screenshot,
+  );
+  const isQaFailure =
+    error instanceof StoryboardCaptureStageError &&
+    QA_FAILURE_STAGES.has(error.stage) &&
+    preservesStableOutput;
+  const diagnostics = [
+    captureDiagnostic(error, viewport),
+    ...evidenceErrors
+      .filter((item) => item !== error)
+      .map((item) => captureDiagnostic(item, viewport)),
+  ];
+  return captureResult({
+    screenCase,
+    route,
+    viewport,
+    status: isQaFailure
+      ? STORYBOARD_CAPTURE_STATUSES.qaFailure
+      : STORYBOARD_CAPTURE_STATUSES.captureError,
+    evidence,
+    diagnostics,
+  });
+}