@pygmalionjs/pygmalion 0.2.11 → 0.2.12

package/node/qa-capture-plugin.mjs

@@ -0,0 +1,1226 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import pixelmatch from 'pixelmatch';
+import pngjs from 'pngjs';
+
+export const PYGMALION_QA_CAPTURE_ENDPOINT = '/__pygmalion-qa/capture';
+export const PYGMALION_QA_ARTIFACT_PREFIX = '/__pygmalion-qa/artifacts/';
+export const DEFAULT_QA_CAPTURE_MAX_FRAMES = 128;
+
+const DEFAULT_TIMEOUT_MS = 180_000;
+const DEFAULT_MAX_BASELINES = 8;
+const DEFAULT_BASELINE_TTL_MS = 15 * 60_000;
+const DEFAULT_MAX_BASELINE_BYTES = 128 * 1024 * 1024;
+const DEFAULT_MAX_ARTIFACTS = 384;
+const DEFAULT_MAX_ARTIFACT_BYTES = 128 * 1024 * 1024;
+const DEFAULT_ARTIFACT_TTL_MS = 15 * 60_000;
+const DEFAULT_MAX_PNG_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAX_PNG_PIXELS = 16_777_216;
+const DEFAULT_PIXEL_THRESHOLD = 0.1;
+const MAX_BODY_BYTES = 32 * 1024;
+const FRAME_ID_RE = /^[A-Za-z0-9][A-Za-z0-9:_-]{0,119}$/;
+const BASELINE_ID_RE = /^[A-Za-z0-9_-]{8,80}$/;
+const ARTIFACT_ID_RE = /^[A-Za-z0-9_-]{8,80}$/;
+const SCREENSHOT_FILE_RE = /^[0-9a-f]{64}\.png$/;
+const HASH_RE = /^[0-9a-f]{64}$/;
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+const { PNG } = pngjs;
+const DEFAULT_ROOT = process.cwd();
+
+export class QaCaptureError extends Error {
+  constructor(statusCode, code, message, failures) {
+    super(message);
+    this.name = 'QaCaptureError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.failures = failures;
+  }
+}
+
+function requestHost(value) {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (typeof raw !== 'string' || !raw.trim()) return null;
+  try {
+    return new URL(`http://${raw.trim()}`).host.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+function isLocalRequestHost(value) {
+  const host = requestHost(value);
+  if (!host) return false;
+  try {
+    return ['localhost', '127.0.0.1', '[::1]', '::1'].includes(
+      new URL(`http://${host}`).hostname.toLowerCase(),
+    );
+  } catch {
+    return false;
+  }
+}
+
+function artifactUrl(id) {
+  return `${PYGMALION_QA_ARTIFACT_PREFIX}${id}.png`;
+}
+
+export function normalizeLocalCaptureBasePath(value, allowedHost) {
+  if (
+    typeof value !== 'string' ||
+    value.trim() !== value ||
+    value.length < 1 ||
+    value.length > 2_048
+  ) {
+    throw new QaCaptureError(400, 'invalid_base_path', 'basePath is invalid.');
+  }
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new QaCaptureError(
+      400,
+      'invalid_base_path',
+      'basePath must be an absolute local URL.',
+    );
+  }
+  const hostname = url.hostname.toLowerCase();
+  if (
+    !['http:', 'https:'].includes(url.protocol) ||
+    !['localhost', '127.0.0.1', '[::1]', '::1'].includes(hostname) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new QaCaptureError(
+      400,
+      'invalid_base_path',
+      'basePath must be a local Vite URL without a query or hash.',
+    );
+  }
+  const expectedHost = requestHost(allowedHost);
+  if (expectedHost && url.host.toLowerCase() !== expectedHost) {
+    throw new QaCaptureError(
+      400,
+      'invalid_base_path',
+      'basePath must use the same host as the current Vite server.',
+    );
+  }
+
+  const authorityStart = value.indexOf('//') + 2;
+  const rawPathStart = value.indexOf('/', authorityStart);
+  const rawPath = rawPathStart >= 0 ? value.slice(rawPathStart) : '/';
+  let decodedPath;
+  try {
+    decodedPath = decodeURIComponent(rawPath);
+  } catch {
+    throw new QaCaptureError(
+      400,
+      'invalid_base_path',
+      'basePath encoding is invalid.',
+    );
+  }
+  if (
+    decodedPath.includes('\0') ||
+    decodedPath.includes('\\') ||
+    decodedPath.split('/').some((segment) => segment === '.' || segment === '..')
+  ) {
+    throw new QaCaptureError(
+      400,
+      'invalid_base_path',
+      'basePath contains an unsafe path.',
+    );
+  }
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/`;
+  return url.href;
+}
+
+export function validateQaCaptureRequest(
+  value,
+  { allowedHost, maxFrameIds = DEFAULT_QA_CAPTURE_MAX_FRAMES } = {},
+) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new QaCaptureError(
+      400,
+      'invalid_request',
+      'A JSON object request is required.',
+    );
+  }
+  if (!['baseline', 'changed'].includes(value.phase)) {
+    throw new QaCaptureError(
+      400,
+      'invalid_phase',
+      'phase must be baseline or changed.',
+    );
+  }
+  if (!Number.isInteger(maxFrameIds) || maxFrameIds < 1) {
+    throw new Error('maxFrameIds must be a positive integer');
+  }
+  if (
+    !Array.isArray(value.frameIds) ||
+    value.frameIds.length < 1 ||
+    value.frameIds.length > maxFrameIds ||
+    value.frameIds.some((id) => typeof id !== 'string' || !FRAME_ID_RE.test(id)) ||
+    new Set(value.frameIds).size !== value.frameIds.length
+  ) {
+    throw new QaCaptureError(
+      400,
+      'invalid_frame_ids',
+      `frameIds must contain at most ${maxFrameIds} unique valid IDs.`,
+    );
+  }
+  if (value.phase === 'baseline' && value.baselineId != null) {
+    throw new QaCaptureError(
+      400,
+      'invalid_baseline_id',
+      'The baseline phase must not include baselineId.',
+    );
+  }
+  if (
+    value.phase === 'changed' &&
+    (typeof value.baselineId !== 'string' || !BASELINE_ID_RE.test(value.baselineId))
+  ) {
+    throw new QaCaptureError(
+      400,
+      'invalid_baseline_id',
+      'The changed phase requires a valid baselineId.',
+    );
+  }
+  return {
+    phase: value.phase,
+    basePath: normalizeLocalCaptureBasePath(value.basePath, allowedHost),
+    frameIds: [...value.frameIds],
+    ...(value.phase === 'changed' ? { baselineId: value.baselineId } : {}),
+  };
+}
+
+async function readManifest(file) {
+  try {
+    return JSON.parse(await fs.readFile(file, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function terminateChild(child) {
+  if (!child || child.exitCode != null || child.signalCode != null) return;
+  child.kill('SIGTERM');
+  const force = setTimeout(() => {
+    if (child.exitCode == null && child.signalCode == null) child.kill('SIGKILL');
+  }, 2_000);
+  force.unref?.();
+}
+
+export async function runCaptureScript({
+  root = DEFAULT_ROOT,
+  scriptPath,
+  basePath,
+  frameIds,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxPngBytes = DEFAULT_MAX_PNG_BYTES,
+  maxTotalPngBytes = DEFAULT_MAX_BASELINE_BYTES,
+  signal,
+}) {
+  if (typeof scriptPath !== 'string' || scriptPath.trim() === '') {
+    throw new Error('QA capture scriptPath is required.');
+  }
+  const validated = validateQaCaptureRequest({
+    phase: 'baseline',
+    basePath,
+    frameIds,
+  });
+  if (
+    !Number.isInteger(timeoutMs) ||
+    timeoutMs < 1 ||
+    !Number.isInteger(maxPngBytes) ||
+    maxPngBytes < 1 ||
+    !Number.isInteger(maxTotalPngBytes) ||
+    maxTotalPngBytes < 1
+  ) {
+    throw new Error('Invalid capture process limits');
+  }
+  if (signal?.aborted) {
+    throw new QaCaptureError(499, 'capture_aborted', 'QA capture was aborted.');
+  }
+  const temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'pygmalion-qa-capture-'));
+  const output = path.join(temporaryRoot, 'capture.json');
+  const failedOutput = `${output}.failed.json`;
+  const screenshotDirectory = path.join(temporaryRoot, 'screenshots');
+  let child = null;
+  let timer = null;
+  let aborted = false;
+  let timedOut = false;
+  let tail = '';
+  const onAbort = () => {
+    aborted = true;
+    terminateChild(child);
+  };
+
+  try {
+    const args = [
+      scriptPath,
+      '--base-url',
+      validated.basePath,
+      '--no-start',
+      '--out',
+      output,
+      '--screenshot-dir',
+      screenshotDirectory,
+    ];
+    for (const id of validated.frameIds) args.push('--case', id);
+    child = spawn(process.execPath, args, {
+      cwd: root,
+      env: { ...process.env, BROWSER: 'none' },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    for (const stream of [child.stdout, child.stderr]) {
+      stream?.on('data', (chunk) => {
+        tail = `${tail}${String(chunk)}`.slice(-16_000);
+      });
+    }
+    signal?.addEventListener('abort', onAbort, { once: true });
+    timer = setTimeout(() => {
+      timedOut = true;
+      terminateChild(child);
+    }, timeoutMs);
+    timer.unref?.();
+
+    const exit = await new Promise((resolvePromise) => {
+      let settled = false;
+      const settle = (value) => {
+        if (settled) return;
+        settled = true;
+        resolvePromise(value);
+      };
+      child.once('error', (error) => settle({ code: null, error }));
+      child.once('exit', (code, exitSignal) => settle({ code, signal: exitSignal }));
+    });
+    if (timedOut) {
+      throw new QaCaptureError(
+        504,
+        'capture_timeout',
+        `QA capture did not finish within ${timeoutMs}ms.`,
+      );
+    }
+    if (aborted || signal?.aborted) {
+      throw new QaCaptureError(499, 'capture_aborted', 'QA capture was aborted.');
+    }
+
+    const manifest = (await readManifest(output)) ?? (await readManifest(failedOutput));
+    if (!manifest) {
+      const detail = exit.error?.message ?? tail.trim() ?? `exit ${exit.code ?? exit.signal ?? 'unknown'}`;
+      throw new QaCaptureError(
+        502,
+        'capture_process_failed',
+        `QA capture process failed: ${detail.slice(-1_000)}`,
+      );
+    }
+    const screens = [];
+    let totalPngBytes = 0;
+    for (const screen of Array.isArray(manifest.screens) ? manifest.screens : []) {
+      if (screen?.screenshotFile == null) {
+        screens.push(screen);
+        continue;
+      }
+      if (
+        typeof screen.screenshotFile !== 'string' ||
+        !SCREENSHOT_FILE_RE.test(screen.screenshotFile)
+      ) {
+        throw new QaCaptureError(
+          502,
+          'invalid_capture_output',
+          'The QA capture PNG path is invalid.',
+        );
+      }
+      const screenshotPath = path.resolve(screenshotDirectory, screen.screenshotFile);
+      if (path.dirname(screenshotPath) !== path.resolve(screenshotDirectory)) {
+        throw new QaCaptureError(
+          502,
+          'invalid_capture_output',
+          'The QA capture PNG path escapes its temporary directory.',
+        );
+      }
+      const screenshotStat = await fs.lstat(screenshotPath);
+      if (!screenshotStat.isFile() || screenshotStat.isSymbolicLink()) {
+        throw new QaCaptureError(
+          502,
+          'invalid_capture_output',
+          'A QA capture PNG must be a regular file in its temporary directory.',
+        );
+      }
+      totalPngBytes += screenshotStat.size;
+      if (
+        screenshotStat.size > maxPngBytes ||
+        totalPngBytes > maxTotalPngBytes
+      ) {
+        throw new QaCaptureError(
+          502,
+          'capture_png_too_large',
+          'QA capture PNG bytes exceed the individual or process limit.',
+        );
+      }
+      screens.push({
+        ...screen,
+        screenshotBytes: await fs.readFile(screenshotPath),
+      });
+    }
+    return {
+      screens,
+      failures: Array.isArray(manifest.failures) ? manifest.failures : [],
+    };
+  } finally {
+    if (timer) clearTimeout(timer);
+    signal?.removeEventListener('abort', onAbort);
+    terminateChild(child);
+    await fs.rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+class BaselineLru {
+  constructor({ maxEntries, maxBytes, ttlMs, now }) {
+    this.maxEntries = maxEntries;
+    this.maxBytes = maxBytes;
+    this.ttlMs = ttlMs;
+    this.now = now;
+    this.entries = new Map();
+    this.totalBytes = 0;
+  }
+
+  remove(id) {
+    const entry = this.entries.get(id);
+    if (!entry) return;
+    this.totalBytes -= entry.byteSize ?? 0;
+    this.entries.delete(id);
+  }
+
+  prune() {
+    const current = this.now();
+    for (const [id, entry] of this.entries) {
+      if (entry.expiresAt <= current) this.remove(id);
+    }
+  }
+
+  set(id, value) {
+    this.prune();
+    this.remove(id);
+    this.entries.set(id, { ...value, expiresAt: this.now() + this.ttlMs });
+    this.totalBytes += value.byteSize ?? 0;
+    while (this.entries.size > this.maxEntries || this.totalBytes > this.maxBytes) {
+      this.remove(this.entries.keys().next().value);
+    }
+  }
+
+  get(id) {
+    this.prune();
+    const entry = this.entries.get(id);
+    if (!entry) return null;
+    this.entries.delete(id);
+    const touched = { ...entry, expiresAt: this.now() + this.ttlMs };
+    this.entries.set(id, touched);
+    return touched;
+  }
+
+  getArtifact(id) {
+    this.prune();
+    for (const [baselineId, entry] of this.entries) {
+      for (const frame of entry.frames.values()) {
+        if (frame.screenshotArtifactId === id && frame.screenshotBytes) {
+          this.entries.delete(baselineId);
+          this.entries.set(baselineId, {
+            ...entry,
+            expiresAt: this.now() + this.ttlMs,
+          });
+          return frame.screenshotBytes;
+        }
+      }
+    }
+    return null;
+  }
+
+  hasArtifact(id) {
+    this.prune();
+    for (const entry of this.entries.values()) {
+      for (const frame of entry.frames.values()) {
+        if (frame.screenshotArtifactId === id) return true;
+      }
+    }
+    return false;
+  }
+
+  get size() {
+    this.prune();
+    return this.entries.size;
+  }
+}
+
+class ArtifactLru {
+  constructor({ maxEntries, maxBytes, ttlMs, now }) {
+    this.maxEntries = maxEntries;
+    this.maxBytes = maxBytes;
+    this.ttlMs = ttlMs;
+    this.now = now;
+    this.entries = new Map();
+    this.totalBytes = 0;
+  }
+
+  remove(id) {
+    const entry = this.entries.get(id);
+    if (!entry) return;
+    this.totalBytes -= entry.bytes.length;
+    this.entries.delete(id);
+  }
+
+  prune() {
+    const current = this.now();
+    for (const [id, entry] of this.entries) {
+      if (entry.expiresAt <= current) this.remove(id);
+    }
+  }
+
+  setBatch(artifacts) {
+    this.prune();
+    const ids = new Set();
+    let bytes = 0;
+    for (const artifact of artifacts) {
+      if (
+        !artifact ||
+        typeof artifact.id !== 'string' ||
+        !ARTIFACT_ID_RE.test(artifact.id) ||
+        !Buffer.isBuffer(artifact.bytes) ||
+        ids.has(artifact.id)
+      ) {
+        throw new Error('Invalid QA review artifact');
+      }
+      ids.add(artifact.id);
+      bytes += artifact.bytes.length;
+    }
+    if (artifacts.length > this.maxEntries || bytes > this.maxBytes) return false;
+    for (const id of ids) this.remove(id);
+    while (
+      this.entries.size + artifacts.length > this.maxEntries ||
+      this.totalBytes + bytes > this.maxBytes
+    ) {
+      this.remove(this.entries.keys().next().value);
+    }
+    const expiresAt = this.now() + this.ttlMs;
+    for (const artifact of artifacts) {
+      this.entries.set(artifact.id, {
+        bytes: artifact.bytes,
+        expiresAt,
+      });
+      this.totalBytes += artifact.bytes.length;
+    }
+    return true;
+  }
+
+  get(id) {
+    this.prune();
+    const entry = this.entries.get(id);
+    if (!entry) return null;
+    this.entries.delete(id);
+    const touched = { ...entry, expiresAt: this.now() + this.ttlMs };
+    this.entries.set(id, touched);
+    return touched.bytes;
+  }
+
+  has(id) {
+    this.prune();
+    return this.entries.has(id);
+  }
+
+  get size() {
+    this.prune();
+    return this.entries.size;
+  }
+}
+
+function inspectPng(bytes, { maxPngBytes, maxPngPixels }) {
+  const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  if (
+    buffer.length < 24 ||
+    buffer.length > maxPngBytes ||
+    !buffer.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE)
+  ) {
+    throw new Error(`PNG bytes are invalid or exceed the ${maxPngBytes} byte limit.`);
+  }
+  const width = buffer.readUInt32BE(16);
+  const height = buffer.readUInt32BE(20);
+  if (
+    width < 1 ||
+    height < 1 ||
+    width * height > maxPngPixels
+  ) {
+    throw new Error(`PNG dimensions exceed the ${maxPngPixels} pixel limit.`);
+  }
+  return { buffer, width, height };
+}
+
+function decodePng(bytes, limits) {
+  const inspected = inspectPng(bytes, limits);
+  const decoded = PNG.sync.read(inspected.buffer, { checkCRC: true });
+  if (
+    decoded.width !== inspected.width ||
+    decoded.height !== inspected.height ||
+    decoded.data.length !== decoded.width * decoded.height * 4
+  ) {
+    throw new Error('Decoded PNG dimensions are invalid.');
+  }
+  return decoded;
+}
+
+export function comparePngScreenshots(
+  beforeBytes,
+  afterBytes,
+  {
+    maxPngBytes = DEFAULT_MAX_PNG_BYTES,
+    maxPngPixels = DEFAULT_MAX_PNG_PIXELS,
+    threshold = DEFAULT_PIXEL_THRESHOLD,
+  } = {},
+) {
+  if (
+    !Number.isInteger(maxPngBytes) ||
+    maxPngBytes < 1 ||
+    !Number.isInteger(maxPngPixels) ||
+    maxPngPixels < 1 ||
+    typeof threshold !== 'number' ||
+    !Number.isFinite(threshold) ||
+    threshold < 0 ||
+    threshold > 1
+  ) {
+    throw new Error('Invalid PNG comparison limits');
+  }
+  const before = decodePng(beforeBytes, { maxPngBytes, maxPngPixels });
+  const after = decodePng(afterBytes, { maxPngBytes, maxPngPixels });
+  const overlapWidth = Math.min(before.width, after.width);
+  const overlapHeight = Math.min(before.height, after.height);
+  const overlapBefore = Buffer.alloc(overlapWidth * overlapHeight * 4);
+  const overlapAfter = Buffer.alloc(overlapWidth * overlapHeight * 4);
+  for (let y = 0; y < overlapHeight; y += 1) {
+    const beforeStart = y * before.width * 4;
+    const afterStart = y * after.width * 4;
+    const targetStart = y * overlapWidth * 4;
+    before.data.copy(
+      overlapBefore,
+      targetStart,
+      beforeStart,
+      beforeStart + overlapWidth * 4,
+    );
+    after.data.copy(
+      overlapAfter,
+      targetStart,
+      afterStart,
+      afterStart + overlapWidth * 4,
+    );
+  }
+
+  const overlapDiff = Buffer.alloc(overlapWidth * overlapHeight * 4);
+  const overlapChanged = pixelmatch(
+    overlapBefore,
+    overlapAfter,
+    overlapDiff,
+    overlapWidth,
+    overlapHeight,
+    {
+      threshold,
+      includeAA: true,
+      alpha: 0.25,
+      diffColor: [255, 0, 96],
+      diffColorAlt: [128, 0, 255],
+    },
+  );
+  const width = Math.max(before.width, after.width);
+  const height = Math.max(before.height, after.height);
+  const heatmap = new PNG({ width, height });
+  heatmap.data.fill(0);
+  for (let y = 0; y < overlapHeight; y += 1) {
+    const sourceStart = y * overlapWidth * 4;
+    overlapDiff.copy(
+      heatmap.data,
+      y * width * 4,
+      sourceStart,
+      sourceStart + overlapWidth * 4,
+    );
+  }
+
+  const overlapPixels = overlapWidth * overlapHeight;
+  const outsidePixels =
+    before.width * before.height + after.width * after.height - 2 * overlapPixels;
+  for (let y = 0; y < height; y += 1) {
+    for (let x = 0; x < width; x += 1) {
+      const inBefore = x < before.width && y < before.height;
+      const inAfter = x < after.width && y < after.height;
+      if (inBefore === inAfter) continue;
+      const offset = (y * width + x) * 4;
+      heatmap.data[offset] = 255;
+      heatmap.data[offset + 1] = 0;
+      heatmap.data[offset + 2] = 96;
+      heatmap.data[offset + 3] = 255;
+    }
+  }
+  const totalPixels =
+    before.width * before.height + after.width * after.height - overlapPixels;
+  const changedPixels = overlapChanged + outsidePixels;
+  return {
+    before: { width: before.width, height: before.height },
+    after: { width: after.width, height: after.height },
+    dimensionsMatch: before.width === after.width && before.height === after.height,
+    changedPixels,
+    totalPixels,
+    diffRatio: totalPixels === 0 ? 0 : changedPixels / totalPixels,
+    threshold,
+    heatmapBytes: PNG.sync.write(heatmap, { colorType: 6 }),
+  };
+}
+
+function normalizeCaptureResult(
+  frameIds,
+  result,
+  { maxPngBytes, maxPngPixels },
+) {
+  const requested = new Set(frameIds);
+  const frames = new Map();
+  for (const screen of result?.screens ?? []) {
+    if (
+      !screen ||
+      typeof screen.id !== 'string' ||
+      !requested.has(screen.id) ||
+      !HASH_RE.test(screen.domStructureHash) ||
+      !HASH_RE.test(screen.screenshotHash) ||
+      (screen.screenshotBytes != null &&
+        !Buffer.isBuffer(screen.screenshotBytes) &&
+        !(screen.screenshotBytes instanceof Uint8Array)) ||
+      frames.has(screen.id)
+    ) {
+      throw new QaCaptureError(
+        502,
+        'invalid_capture_output',
+        'The QA capture result is invalid.',
+      );
+    }
+    let screenshotBytes;
+    let screenshotSize;
+    if (screen.screenshotBytes != null) {
+      try {
+        const inspected = inspectPng(screen.screenshotBytes, {
+          maxPngBytes,
+          maxPngPixels,
+        });
+        screenshotBytes = inspected.buffer;
+        screenshotSize = { width: inspected.width, height: inspected.height };
+      } catch (error) {
+        throw new QaCaptureError(
+          502,
+          'invalid_capture_png',
+          `The QA capture PNG is invalid: ${error instanceof Error ? error.message : error}`,
+        );
+      }
+    }
+    frames.set(screen.id, {
+      id: screen.id,
+      domStructureHash: screen.domStructureHash,
+      screenshotHash: screen.screenshotHash,
+      ...(screenshotBytes ? { screenshotBytes, screenshotSize } : {}),
+    });
+  }
+  const failures = [];
+  const failedIds = new Set();
+  for (const failure of result?.failures ?? []) {
+    if (
+      !failure ||
+      typeof failure.id !== 'string' ||
+      !requested.has(failure.id) ||
+      failedIds.has(failure.id)
+    ) {
+      throw new QaCaptureError(
+        502,
+        'invalid_capture_output',
+        'The QA capture failure result is invalid.',
+      );
+    }
+    failedIds.add(failure.id);
+    failures.push({
+      id: failure.id,
+      error: String(failure.error ?? 'Screen capture failed.').slice(0, 1_000),
+    });
+  }
+  for (const id of frameIds) {
+    if (!frames.has(id) && !failedIds.has(id)) {
+      failedIds.add(id);
+      failures.push({ id, error: 'No screen capture result was returned.' });
+    }
+  }
+  return {
+    frames,
+    failures,
+    complete: failures.length === 0 && frames.size === frameIds.length,
+  };
+}
+
+async function withTimeout(captureRunner, input, timeoutMs) {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(
+        new QaCaptureError(
+          504,
+          'capture_timeout',
+          `QA capture did not finish within ${timeoutMs}ms.`,
+        ),
+      );
+    }, timeoutMs);
+    timer.unref?.();
+  });
+  const capture = Promise.resolve().then(() =>
+    captureRunner({ ...input, timeoutMs, signal: controller.signal }),
+  );
+  capture.catch(() => undefined);
+  try {
+    return await Promise.race([capture, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function publicHashes(frame, screenshotUrl) {
+  return {
+    domStructureHash: frame.domStructureHash,
+    screenshotHash: frame.screenshotHash,
+    ...(screenshotUrl ? { screenshotUrl } : {}),
+  };
+}
+
+function publicFrame(frame) {
+  return {
+    id: frame.id,
+    ...publicHashes(
+      frame,
+      frame.screenshotArtifactId ? artifactUrl(frame.screenshotArtifactId) : null,
+    ),
+  };
+}
+
+export function createQaCaptureService({
+  root = DEFAULT_ROOT,
+  scriptPath,
+  captureRunner = runCaptureScript,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  maxFrameIds = DEFAULT_QA_CAPTURE_MAX_FRAMES,
+  maxBaselines = DEFAULT_MAX_BASELINES,
+  baselineTtlMs = DEFAULT_BASELINE_TTL_MS,
+  maxBaselineBytes = DEFAULT_MAX_BASELINE_BYTES,
+  maxArtifacts = DEFAULT_MAX_ARTIFACTS,
+  maxArtifactBytes = DEFAULT_MAX_ARTIFACT_BYTES,
+  artifactTtlMs = DEFAULT_ARTIFACT_TTL_MS,
+  maxPngBytes = DEFAULT_MAX_PNG_BYTES,
+  maxPngPixels = DEFAULT_MAX_PNG_PIXELS,
+  pixelThreshold = DEFAULT_PIXEL_THRESHOLD,
+  now = () => Date.now(),
+  createBaselineId = () => randomUUID(),
+  createArtifactId = () => randomUUID(),
+} = {}) {
+  if (
+    !Number.isInteger(timeoutMs) ||
+    timeoutMs < 1 ||
+    !Number.isInteger(maxFrameIds) ||
+    maxFrameIds < 1 ||
+    !Number.isInteger(maxBaselines) ||
+    maxBaselines < 1 ||
+    !Number.isInteger(baselineTtlMs) ||
+    baselineTtlMs < 1 ||
+    !Number.isInteger(maxBaselineBytes) ||
+    maxBaselineBytes < 1 ||
+    !Number.isInteger(maxArtifacts) ||
+    maxArtifacts < 1 ||
+    !Number.isInteger(maxArtifactBytes) ||
+    maxArtifactBytes < 1 ||
+    !Number.isInteger(artifactTtlMs) ||
+    artifactTtlMs < 1 ||
+    !Number.isInteger(maxPngBytes) ||
+    maxPngBytes < 1 ||
+    !Number.isInteger(maxPngPixels) ||
+    maxPngPixels < 1 ||
+    typeof pixelThreshold !== 'number' ||
+    !Number.isFinite(pixelThreshold) ||
+    pixelThreshold < 0 ||
+    pixelThreshold > 1
+  ) {
+    throw new Error('Invalid QA capture service limits');
+  }
+  const baselines = new BaselineLru({
+    maxEntries: maxBaselines,
+    maxBytes: maxBaselineBytes,
+    ttlMs: baselineTtlMs,
+    now,
+  });
+  const artifacts = new ArtifactLru({
+    maxEntries: maxArtifacts,
+    maxBytes: maxArtifactBytes,
+    ttlMs: artifactTtlMs,
+    now,
+  });
+  const nextArtifactId = (reserved = new Set()) => {
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      const id = createArtifactId();
+      if (
+        typeof id === 'string' &&
+        ARTIFACT_ID_RE.test(id) &&
+        !reserved.has(id) &&
+        !baselines.hasArtifact(id) &&
+        !artifacts.has(id)
+      ) {
+        reserved.add(id);
+        return id;
+      }
+    }
+    throw new Error('createArtifactId returned an invalid or duplicate ID');
+  };
+  let active = false;
+
+  const capture = async (rawRequest, { allowedHost } = {}) => {
+    const request = validateQaCaptureRequest(rawRequest, { allowedHost, maxFrameIds });
+    if (active) {
+      throw new QaCaptureError(
+        409,
+        'capture_in_progress',
+        'Another QA capture is already running.',
+      );
+    }
+
+    let baseline = null;
+    if (request.phase === 'changed') {
+      baseline = baselines.get(request.baselineId);
+      if (!baseline) {
+        throw new QaCaptureError(
+          404,
+          'baseline_not_found',
+          'The baseline does not exist or has expired.',
+        );
+      }
+      if (
+        baseline.frameIds.length !== request.frameIds.length ||
+        baseline.frameIds.some((id, index) => id !== request.frameIds[index])
+      ) {
+        throw new QaCaptureError(
+          409,
+          'baseline_mismatch',
+          'The baseline frameIds do not match the current request.',
+        );
+      }
+    }
+
+    active = true;
+    try {
+      const runnerInput = {
+        root,
+        scriptPath,
+        basePath: request.basePath,
+        frameIds: request.frameIds,
+      };
+      const rawResult =
+        captureRunner === runCaptureScript
+          ? await captureRunner({
+              ...runnerInput,
+              timeoutMs,
+              maxPngBytes,
+              maxTotalPngBytes: maxBaselineBytes,
+            })
+          : await withTimeout(
+              captureRunner,
+              runnerInput,
+              timeoutMs,
+            );
+      const result = normalizeCaptureResult(request.frameIds, rawResult, {
+        maxPngBytes,
+        maxPngPixels,
+      });
+      if (request.phase === 'baseline') {
+        if (!result.complete) {
+          throw new QaCaptureError(
+            422,
+            'baseline_capture_failed',
+            'Not all baseline screens could be captured.',
+            result.failures,
+          );
+        }
+        const baselineId = createBaselineId();
+        if (typeof baselineId !== 'string' || !BASELINE_ID_RE.test(baselineId)) {
+          throw new Error('createBaselineId returned an invalid ID');
+        }
+        const reservedArtifactIds = new Set();
+        const frames = request.frameIds.map((id) => {
+          const frame = result.frames.get(id);
+          return {
+            ...frame,
+            ...(frame.screenshotBytes
+              ? { screenshotArtifactId: nextArtifactId(reservedArtifactIds) }
+              : {}),
+          };
+        });
+        const byteSize = frames.reduce(
+          (total, frame) => total + (frame.screenshotBytes?.length ?? 0),
+          0,
+        );
+        if (byteSize > maxBaselineBytes) {
+          throw new QaCaptureError(
+            422,
+            'baseline_artifacts_too_large',
+            `Baseline PNG bytes exceed the ${maxBaselineBytes} byte storage limit.`,
+            frames
+              .filter((frame) => frame.screenshotBytes)
+              .map((frame) => ({
+                id: frame.id,
+                error: 'Baseline PNG bytes exceed the storage limit.',
+              })),
+          );
+        }
+        baselines.set(baselineId, {
+          basePath: request.basePath,
+          frameIds: [...request.frameIds],
+          frames: new Map(frames.map((frame) => [frame.id, frame])),
+          byteSize,
+        });
+        return {
+          ok: true,
+          baselineId,
+          frames: frames.map(publicFrame),
+        };
+      }
+
+      const diffFailures = [];
+      const reviewArtifacts = [];
+      const reservedArtifactIds = new Set();
+      const reviewGroups = [];
+      const frames = request.frameIds.map((id) => {
+        const before = baseline.frames.get(id);
+        const after = result.frames.get(id) ?? null;
+        const frame = {
+          id,
+          before: publicHashes(
+            before,
+            before.screenshotArtifactId
+              ? artifactUrl(before.screenshotArtifactId)
+              : null,
+          ),
+          after: after
+            ? publicHashes(after)
+            : null,
+          domChanged: after ? before.domStructureHash !== after.domStructureHash : null,
+          screenshotChanged: after ? before.screenshotHash !== after.screenshotHash : null,
+        };
+        if (!after?.screenshotBytes || !before.screenshotBytes) return frame;
+
+        try {
+          const comparison = comparePngScreenshots(
+            before.screenshotBytes,
+            after.screenshotBytes,
+            {
+              maxPngBytes,
+              maxPngPixels,
+              threshold: pixelThreshold,
+            },
+          );
+          const afterArtifactId = nextArtifactId(reservedArtifactIds);
+          const heatmapArtifactId = nextArtifactId(reservedArtifactIds);
+          const group = {
+            id,
+            frame,
+            afterArtifactId,
+            heatmapArtifactId,
+            artifacts: [
+              { id: afterArtifactId, bytes: after.screenshotBytes },
+              { id: heatmapArtifactId, bytes: comparison.heatmapBytes },
+            ],
+          };
+          reviewGroups.push(group);
+          reviewArtifacts.push(...group.artifacts);
+          frame.pixelDiff = {
+            before: comparison.before,
+            after: comparison.after,
+            dimensionsMatch: comparison.dimensionsMatch,
+            changedPixels: comparison.changedPixels,
+            totalPixels: comparison.totalPixels,
+            diffRatio: comparison.diffRatio,
+            threshold: comparison.threshold,
+            heatmapUrl: artifactUrl(heatmapArtifactId),
+          };
+        } catch (error) {
+          diffFailures.push({
+            id,
+            error: `Pixel diff failed: ${String(error instanceof Error ? error.message : error).slice(0, 900)}`,
+          });
+        }
+        return frame;
+      });
+      if (reviewArtifacts.length && artifacts.setBatch(reviewArtifacts)) {
+        for (const group of reviewGroups) {
+          group.frame.after.screenshotUrl = artifactUrl(group.afterArtifactId);
+        }
+      } else if (reviewArtifacts.length) {
+        for (const group of reviewGroups) {
+          group.frame.pixelDiff.heatmapUrl = null;
+          diffFailures.push({
+            id: group.id,
+            error: 'Review PNGs exceed the artifact count or byte limit.',
+          });
+        }
+      }
+      return {
+        ok: true,
+        baselineId: request.baselineId,
+        beforeBasePath: baseline.basePath,
+        afterBasePath: request.basePath,
+        frames,
+        complete: result.complete && diffFailures.length === 0,
+        failures: [...result.failures, ...diffFailures],
+      };
+    } finally {
+      active = false;
+    }
+  };
+
+  return {
+    capture,
+    getArtifact(id) {
+      if (typeof id !== 'string' || !ARTIFACT_ID_RE.test(id)) return null;
+      const bytes = baselines.getArtifact(id) ?? artifacts.get(id);
+      return bytes ? { bytes, contentType: 'image/png' } : null;
+    },
+    get baselineCount() {
+      return baselines.size;
+    },
+    get artifactCount() {
+      return artifacts.size;
+    },
+    get busy() {
+      return active;
+    },
+  };
+}
+
+async function readJson(req) {
+  const chunks = [];
+  let size = 0;
+  let tooLarge = false;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > MAX_BODY_BYTES) {
+      tooLarge = true;
+      continue;
+    }
+    chunks.push(chunk);
+  }
+  if (tooLarge) {
+    throw new QaCaptureError(413, 'request_too_large', 'The QA capture request is too large.');
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  } catch {
+    throw new QaCaptureError(400, 'invalid_json', 'A valid JSON request is required.');
+  }
+}
+
+function sendJson(res, statusCode, body) {
+  res.statusCode = statusCode;
+  res.setHeader('content-type', 'application/json; charset=utf-8');
+  res.setHeader('cache-control', 'no-store');
+  res.end(JSON.stringify(body));
+}
+
+function sendPng(res, artifact) {
+  res.statusCode = 200;
+  res.setHeader('content-type', artifact.contentType);
+  res.setHeader('content-length', String(artifact.bytes.length));
+  res.setHeader('cache-control', 'no-store');
+  res.setHeader('x-content-type-options', 'nosniff');
+  res.end(artifact.bytes);
+}
+
+export function pygmalionQaCapturePlugin(options = {}) {
+  const service = createQaCaptureService(options);
+  return {
+    name: 'pygmalion-qa-capture',
+    apply: 'serve',
+    configureServer(server) {
+      if (process.env.PYGMALION_PREVIEW_MODE === '1') return;
+      server.middlewares.use(async (req, res, next) => {
+        const rawTarget = req.url ?? '/';
+        const rawPath = rawTarget.split(/[?#]/, 1)[0];
+        if (rawPath.startsWith(PYGMALION_QA_ARTIFACT_PREFIX.replace(/\/$/, ''))) {
+          if (req.method !== 'GET') {
+            res.setHeader('allow', 'GET');
+            sendJson(res, 405, {
+              ok: false,
+              error: 'method_not_allowed',
+              message: 'Only GET requests are supported.',
+            });
+            return;
+          }
+          if (!isLocalRequestHost(req.headers.host)) {
+            sendJson(res, 403, {
+              ok: false,
+              error: 'artifact_host_forbidden',
+              message: 'QA artifacts are available only from a local Vite host.',
+            });
+            return;
+          }
+          const match =
+            rawTarget === rawPath
+              ? /^\/__pygmalion-qa\/artifacts\/([A-Za-z0-9_-]{8,80})\.png$/.exec(rawPath)
+              : null;
+          if (!match) {
+            sendJson(res, 400, {
+              ok: false,
+              error: 'invalid_artifact_path',
+              message: 'The QA artifact path is invalid.',
+            });
+            return;
+          }
+          const artifact = service.getArtifact(match[1]);
+          if (!artifact) {
+            sendJson(res, 404, {
+              ok: false,
+              error: 'artifact_not_found',
+              message: 'The QA artifact does not exist or has expired.',
+            });
+            return;
+          }
+          sendPng(res, artifact);
+          return;
+        }
+        const url = new URL(rawTarget, 'http://localhost');
+        if (url.pathname !== PYGMALION_QA_CAPTURE_ENDPOINT) {
+          next();
+          return;
+        }
+        if (req.method !== 'POST') {
+          res.setHeader('allow', 'POST');
+          sendJson(res, 405, {
+            ok: false,
+            error: 'method_not_allowed',
+            message: 'Only POST requests are supported.',
+          });
+          return;
+        }
+        try {
+          const result = await service.capture(await readJson(req), {
+            allowedHost: req.headers.host,
+          });
+          sendJson(res, 200, result);
+        } catch (error) {
+          const known = error instanceof QaCaptureError;
+          sendJson(res, known ? error.statusCode : 500, {
+            ok: false,
+            error: known ? error.code : 'internal_error',
+            message: error instanceof Error ? error.message : String(error),
+            ...(known && error.failures ? { failures: error.failures } : {}),
+          });
+        }
+      });
+    },
+  };
+}