inspectra-engine 0.0.0-stage → 1.0.2

package/node/runner.mjs

@@ -0,0 +1,135 @@
+import { createServer } from 'node:http';
+import { sendEvent } from './event-stream.mjs';
+import { timingSafeEqual } from 'node:crypto';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { ScanJobs, secret, integer, terminal } from './job-manager.mjs';
+
+function authorized(header, token) {
+  const value = typeof header === 'string' ? header : '';
+  const expected = `Bearer ${token}`;
+  const received = Buffer.from(value), wanted = Buffer.from(expected);
+  return received.length === wanted.length && timingSafeEqual(received, wanted);
+}
+function json(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(data));
+}
+async function body(req) {
+  if (req.headers['content-type']?.split(';')[0] !== 'application/json') throw new TypeError('Content-Type must be application/json');
+  let size = 0; const chunks = [];
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 6 * 1024 * 1024) throw Object.assign(new Error('Request body too large'), { status: 413 });
+    chunks.push(chunk);
+  }
+  const input = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (size > 65536 && input?.baseline?.type !== 'png') throw Object.assign(new Error('Non-PNG request body too large'), { status: 413 });
+  return input;
+}
+
+/** Local-only HTTP adapter; tokens never appear in URLs or scan artifacts. */
+export async function startLocalRunner({ port = 4317, allowedOrigins = [], bootstrapTTL = 900000, signal, ...jobOptions } = {}) {
+  integer(port, 'port', 0, 65535); integer(bootstrapTTL, 'bootstrapTTL', 100, 900000);
+  if (!Array.isArray(allowedOrigins)) throw new TypeError('allowedOrigins must be an array');
+  const origins = new Set(allowedOrigins.map(origin => {
+    const url = new URL(origin);
+    if (!['http:', 'https:'].includes(url.protocol) || url.origin !== origin) throw new TypeError('Allowed origins must be exact HTTP(S) origins');
+    return origin;
+  }));
+  signal?.throwIfAborted();
+  const root = await mkdtemp(path.join(os.tmpdir(), 'inspectra-runner-'));
+  let jobs;
+  try { jobs = new ScanJobs({ ...jobOptions, root }); }
+  catch (error) { await rm(root, { recursive: true, force: true }); throw error; }
+  const token = secret(), expiresAt = Date.now() + bootstrapTTL;
+  let origin, closing;
+  const server = createServer(async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store'); res.setHeader('X-Content-Type-Options', 'nosniff');
+    try {
+      if (req.headers.host !== new URL(origin).host) return json(res, 403, { error: 'Invalid Host' });
+      const frontend = req.headers.origin;
+      if (frontend && !origins.has(frontend)) return json(res, 403, { error: 'Origin not allowed' });
+      if (!frontend && req.headers['sec-fetch-site'] && req.headers['sec-fetch-site'] !== 'none') return json(res, 403, { error: 'Explicit Origin required' });
+      if (frontend) {
+        res.setHeader('Access-Control-Allow-Origin', frontend); res.setHeader('Vary', 'Origin');
+        res.setHeader('Access-Control-Expose-Headers', 'X-Preview-Side, X-Preview-Timestamp');
+        res.setHeader('Access-Control-Allow-Headers', 'Authorization, Content-Type, Last-Event-ID');
+        res.setHeader('Access-Control-Allow-Methods', 'POST, GET, DELETE, OPTIONS');
+      }
+      if (req.method === 'OPTIONS') { res.writeHead(204); return res.end(); }
+      const url = new URL(req.url, origin);
+      if (url.search) return json(res, 400, { error: 'Query parameters are not accepted; use Authorization headers' });
+      if (req.method === 'POST' && url.pathname === '/sessions') {
+        if (Date.now() >= expiresAt || !authorized(req.headers.authorization, token)) return json(res, 401, { error: 'Invalid or expired runner token' });
+        const input = await body(req);
+        if (Date.now() >= expiresAt) return json(res, 401, { error: 'Runner token expired' });
+        const job = jobs.create(input);
+        return json(res, 202, { ...jobs.status(job), token: job.token });
+      }
+      const match = /^\/sessions\/([a-f0-9-]+)(?:\/(events|preview|issues|report|baseline\.png|target\.png|baseline\.matches\.svg|target\.matches\.svg))?$/.exec(url.pathname);
+      const job = match && jobs.jobs.get(match[1]);
+      if (!job || Date.now() >= job.expiresAt || !authorized(req.headers.authorization, job.token)) return json(res, 401, { error: 'Invalid or expired scan token' });
+      const action = match[2];
+      if (req.method === 'GET' && !action) return json(res, 200, jobs.status(job));
+      if (req.method === 'DELETE' && !action) { jobs.cancel(job); return json(res, 202, jobs.status(job)); }
+      if (req.method !== 'GET') return json(res, 405, { error: 'Method not allowed' });
+      if (action === 'events') {
+        if (job.listeners.size >= 4) return json(res, 429, { error: 'Event subscriber limit reached' });
+        const cursor = Number(req.headers['last-event-id'] ?? 0);
+        if (!Number.isSafeInteger(cursor) || cursor < 0 || cursor > job.sequence) throw new TypeError('Invalid Last-Event-ID');
+        res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Connection': 'keep-alive', 'X-Accel-Buffering': 'no' });
+        res.flushHeaders();
+        const send = (data, end) => sendEvent(res, data, end);
+        if (cursor < (job.events[0]?.id ?? job.sequence + 1) - 1) send(`event: replay-gap\ndata: ${JSON.stringify(jobs.status(job))}\n\n`);
+        for (const event of job.events) if (event.id > cursor) send(event.data);
+        if (terminal(job.state)) return res.end();
+        job.listeners.add(send);
+        const heartbeat = setInterval(() => send(': keepalive\n\n'), 15000);
+        const expiry = setTimeout(() => res.end(), Math.max(0, job.expiresAt - Date.now()));
+        res.on('close', () => { clearInterval(heartbeat); clearTimeout(expiry); job.listeners.delete(send); });
+        return;
+      }
+      if (action === 'preview') {
+        if (!job.frame) { res.writeHead(204); return res.end(); }
+        res.writeHead(200, { 'Content-Type': job.frame.contentType, 'X-Preview-Side': job.frame.side, 'X-Preview-Timestamp': job.frame.timestamp });
+        return res.end(job.frame.data);
+      }
+      if (job.state !== 'completed') return json(res, 409, { error: 'Scan has no completed report', state: job.state });
+      if (action === 'issues') return json(res, 200, { issues: job.result.issues, diagnostics: job.result.analysis.diagnostics });
+      if (action === 'report') return json(res, 200, job.result);
+      if (action === 'baseline.matches.svg' || action === 'target.matches.svg') {
+        const artifact = job.result.artifacts[action === 'baseline.matches.svg' ? 'baselineHighlights' : 'targetHighlights'];
+        if (!artifact) return json(res, 404, { error: 'No matched-region highlight artifact for this source' });
+        const data = await readFile(artifact);
+        res.writeHead(200, { 'Content-Type': 'image/svg+xml', 'Content-Security-Policy': "default-src 'none'; img-src data:; style-src 'none'" }); return res.end(data);
+      }
+      if (action === 'baseline.png' || action === 'target.png') {
+        const data = await readFile(job.result.artifacts[action === 'baseline.png' ? 'baselineScreenshot' : 'targetScreenshot']);
+        res.writeHead(200, { 'Content-Type': 'image/png' }); return res.end(data);
+      }
+      json(res, 404, { error: 'Endpoint not found' });
+    } catch (error) {
+      if (!res.headersSent) json(res, error.status ?? (error instanceof TypeError || error instanceof SyntaxError ? 400 : 500), { error: error.message });
+      else res.destroy();
+    }
+  });
+  server.requestTimeout = 10000; server.headersTimeout = 10000; server.maxConnections = 64;
+  const close = () => {
+    if (!closing) closing = (async () => {
+      signal?.removeEventListener('abort', abort);
+      const stopped = new Promise(resolve => server.close(resolve));
+      await jobs.close(); server.closeAllConnections(); await stopped;
+      await rm(root, { recursive: true, force: true });
+    })();
+    return closing;
+  };
+  const abort = () => { void close(); };
+  try {
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); });
+    origin = `http://127.0.0.1:${server.address().port}`;
+    signal?.addEventListener('abort', abort, { once: true });
+    if (signal?.aborted) { await close(); signal.throwIfAborted(); }
+    return { origin, token, expiresAt, close };
+  } catch (error) { await close(); throw error; }
+}

package/package.json

@@ -1,6 +1,138 @@
 {
   "name": "inspectra-engine",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.2",
+  "description": "Playwright UI testing and accessibility toolkit for Node.js. Compare URL, Figma and PNG baselines using Shivax, with DOM snapshots, layout measurements and JSON reports.",
+  "homepage": "https://gitlab.com/urveshgohil.developer/inspectra",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/urveshgohil.developer/inspectra.git"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/urveshgohil.developer/inspectra/-/issues"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "cspell": "^10.3.6",
+    "lighthouse": "^13.5.0",
+    "playwright": "^1.64.0",
+    "shivax": "^0.1.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.0"
+  },
+  "scripts": {
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "report": "playwright show-report",
+    "scan": "node scan.js",
+    "ui": "node --watch server.js",
+    "test:ui-check": "node --test --test-concurrency=1 tests/ui-check/regression.mjs tests/ui-check/dynamic-content.mjs",
+    "test:dynamic-content": "node --test --test-concurrency=1 tests/ui-check/dynamic-content.mjs",
+    "test:extraction": "node --test --test-concurrency=1 tests/extraction/snapshot.mjs",
+    "build": "node scripts/check-build.mjs",
+    "test:integration": "node --test --test-concurrency=1 tests/integration/*.mjs",
+    "prepack": "npm run build",
+    "test:runner": "node --test --test-concurrency=1 tests/integration/runner.mjs",
+    "test:figma": "node --test --test-concurrency=1 tests/integration/figma.mjs",
+    "test:png": "node --test --test-concurrency=1 tests/integration/png.mjs"
+  },
+  "main": "./node/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./node/index.d.mts",
+      "import": "./node/index.mjs"
+    },
+    "./node": {
+      "types": "./node/index.d.mts",
+      "import": "./node/index.mjs"
+    },
+    "./client": {
+      "types": "./client/index.d.mts",
+      "import": "./client/index.mjs"
+    },
+    "./ui-check.js": "./ui-check.js",
+    "./compare.js": "./compare.js",
+    "./dom-compare.js": "./dom-compare.js",
+    "./scanner/browser-snapshot.js": "./scanner/browser-snapshot.js"
+  },
+  "bin": {
+    "inspectra": "./bin/inspectra.mjs"
+  },
+  "files": [
+    "node/",
+    "client/",
+    "bin/",
+    "scanner/",
+    "ui-check.js",
+    "compare.js",
+    "dom-compare.js",
+    "scan.js",
+    "server.js",
+    "ui/",
+    "pages.json",
+    "scripts/check-build.mjs",
+    "examples/",
+    "CHANGELOG.md",
+    "NOTICE"
+  ],
+  "keywords": [
+    "inspectra",
+    "visynq",
+    "shivax",
+    "playwright",
+    "nodejs",
+    "javascript",
+    "typescript",
+    "qa",
+    "quality-assurance",
+    "test-automation",
+    "browser-automation",
+    "web-automation",
+    "web-testing",
+    "frontend-testing",
+    "ui-testing",
+    "ui-inspection",
+    "ui-audit",
+    "ui-comparison",
+    "visual-testing",
+    "visual-regression",
+    "visual-regression-testing",
+    "design-qa",
+    "design-validation",
+    "design-comparison",
+    "figma",
+    "figma-comparison",
+    "figma-to-web",
+    "screenshot-testing",
+    "screenshot-comparison",
+    "screenshot-capture",
+    "dom-extraction",
+    "dom-snapshot",
+    "ui-snapshot",
+    "semantic-comparison",
+    "layout-testing",
+    "typography",
+    "spacing",
+    "responsive-testing",
+    "viewport-testing",
+    "accessibility",
+    "a11y",
+    "accessibility-testing",
+    "wcag",
+    "axe-core",
+    "spelling",
+    "spell-check",
+    "cspell",
+    "png",
+    "ocr",
+    "tesseract",
+    "json-report",
+    "local-scanner",
+    "developer-tools"
+  ],
+  "author": "Urvesh Gohil",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.15"
+  }
+}

package/pages.json

@@ -0,0 +1,8 @@
+{
+  "baseURL": "http://localhost:4015",
+  "pages": [
+    { "name": "home", "path": "/" },
+    { "name": "about", "path": "/about" },
+    { "name": "contact", "path": "/contact" }
+  ]
+}

package/scan.js

@@ -0,0 +1,27 @@
+// Usage: node scan.js <url>
+// Runs the locally built axe.js (repo root) against a page using Playwright.
+const fs = require('fs');
+const path = require('path');
+const { chromium } = require('playwright');
+
+const url = process.argv[2];
+if (!url) {
+  console.error('Usage: node scan.js <url>');
+  process.exit(1);
+}
+
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  await page.goto(url, { waitUntil: 'load' });
+  await page.addScriptTag({ path: process.env.AXE_PATH || path.join(__dirname, '..', 'axe-core', 'axe.js') });
+  const results = await page.evaluate(() => window.axe.run());
+  console.log(`Scanned: ${results.url}`);
+  console.log(`Violations: ${results.violations.length}, Incomplete: ${results.incomplete.length}, Passes: ${results.passes.length}\n`);
+  for (const v of results.violations) {
+    console.log(`[${v.impact}] ${v.id} - ${v.help} (${v.nodes.length} nodes)`);
+    console.log(`  ${v.helpUrl}`);
+    v.nodes.slice(0, 3).forEach(n => console.log(`  - ${n.target.join(' ')}`));
+  }
+  await browser.close();
+})().catch(e => { console.error(e); process.exit(1); });

package/scanner/README.md

@@ -0,0 +1,70 @@
+# Playwright UI extraction (Phase 2)
+
+Use this adapter from a local Node.js runner. It reuses `inspectPage`, `settlePage`,
+`VIEWPORTS`, page creation and full-page screenshots from `ui-check.js`.
+Existing scanner endpoints and comparison results retain their existing format.
+
+```js
+import { captureUISnapshot, captureUIPage, captureUISnapshotPair } from './browser-snapshot.js';
+
+const scope = { kind: 'company', id: 'your-workspace-id' };
+const snapshot = await captureUISnapshot(page, { scope });
+const capture = await captureUIPage(page, { scope, screenshotPath: './target.png' });
+const pair = await captureUISnapshotPair({
+  baselineUrl: 'http://localhost:3000/baseline',
+  targetUrl: 'http://localhost:3000/target',
+  scope,
+  viewport: { width: 1440, height: 900 },
+  deviceScaleFactor: 1,
+  screenshots: { baseline: './baseline.png', target: './target.png' },
+});
+// pair.baseline.snapshot and pair.target.snapshot are Shivax UISnapshot v1.
+```
+
+`captureUISnapshot` returns only the strict Shivax contract. `captureUIPage` also
+returns a separate `metadata` object containing DOM tags/paths, approximate
+accessible names, sibling order/links, text glyph bounds, flex/grid properties,
+signed sibling edge distances, media dimensions/readiness and scroll metrics.
+These fields cannot be added to Shivax v1, whose validator rejects extra keys.
+Node IDs are capture-local; DOM paths use child indices and never CSS classes.
+Wrapper changes are retained in the hierarchy; this adapter does no matching.
+
+All geometry uses unrounded CSS pixels in document coordinates. DPR is metadata,
+not a geometry multiplier. Bounds are axis-aligned rendered boxes, including
+transforms; computed padding/margins describe CSS lengths. Unresolved values
+such as `line-height: normal` stay unknown. Measurements include provenance and
+confidence. Accessible names use a partial DOM-based algorithm and are marked
+estimated (quality annotation 0.8, not a calibrated probability). Roles use
+explicit ARIA roles and common native HTML semantics, not a full accessibility tree.
+Sibling edge distances can be negative for overlap or different layout rows.
+
+Captures disable animations and scroll to the top after the existing lazy-load
+scroll pass. Snapshot mode disables legacy opacity-forcing fallbacks so hidden
+content stays hidden. Offscreen document nodes are retained; hidden and fully
+overflow-clipped elements are omitted. Partial clipping retains the full rendered
+box. Pseudo-elements, shadow DOM, iframe contents and arbitrary clip-path masks
+are not extracted. Both URLs use the same Chromium instance, viewport and DPR,
+with separate contexts (cookies/storage are not shared). An existing page uses
+the browser settings supplied by its caller.
+
+Options shared by all capture APIs:
+
+- `scope` is required: `{ kind: 'company' | 'personal', id: string }`. No captures
+  are cached, merged or persisted automatically. Never reuse scope IDs across owners.
+- `includeText: false` omits text, accessible names and glyph bounds. Input values
+  are never read; visible page text can still contain personal information.
+- `ignoreSelectors: string[]` excludes selected subtrees.
+- `maxNodes` defaults to 10,000; overflow throws instead of silently truncating.
+- `timeout` defaults to 15,000 ms per readiness/navigation operation, not a total
+  scan deadline. Existing settling also has bounded network/image waits.
+- All document images and loaded fonts must finish successfully. `requiredAssets`
+  is an array of CSS selectors for additional required assets: selectors must
+  resolve, media must have current frame data, and CSS background URLs must load.
+  Broken/missing assets produce errors. Dynamic sites must expose an appropriate
+  ready state before capture; stabilization does not freeze application data.
+
+Run `npm run test:extraction` and `npm run test:ui-check`. Extraction tests validate
+against the built sibling Shivax package without editing it. Set `SHIVAX_ENTRY`
+to an alternative built module path/URL when testing outside this workspace.
+This JavaScript package has no configured build step; use `node --check` for the
+changed modules. No dependencies or comparison algorithms were added.

package/scanner/accessibility.mjs

@@ -0,0 +1,10 @@
+import AxeBuilder from '@axe-core/playwright';
+
+export const WCAG_TAGS = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'];
+
+/** The same WCAG A/AA scan used by the existing accessibility workflow. */
+export async function scanAccessibility(page, { exclude = [], bestPractice = false } = {}) {
+  const builder = new AxeBuilder({ page }).withTags(bestPractice ? [...WCAG_TAGS, 'best-practice'] : WCAG_TAGS);
+  for (const selector of exclude) builder.exclude(selector);
+  return builder.analyze();
+}

package/scanner/browser-snapshot.js

@@ -0,0 +1,128 @@
+// Local Node.js adapter. Do not bundle this module into application/browser code.
+import { chromium } from "playwright";
+import { inspectPage, settlePage, VIEWPORTS, createInspectionPage, capturePageScreenshot } from "../ui-check.js";
+
+function captureOptions(options) {
+  const { scope, maxNodes = 10000, includeText = true, timeout = 15000, ignoreSelectors = [], requiredAssets = [] } = options;
+  if (!scope || !["company", "personal"].includes(scope.kind) || typeof scope.id !== "string" || !scope.id.trim() || scope.id.length > 256) {
+    throw new TypeError("An explicit company/personal scope and id are required");
+  }
+  if (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > 10000) throw new TypeError("maxNodes must be between 1 and 10000");
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new TypeError("timeout must be positive");
+  if (typeof includeText !== "boolean") throw new TypeError("includeText must be boolean");
+  for (const list of [ignoreSelectors, requiredAssets]) {
+    if (!Array.isArray(list) || list.some((s) => typeof s !== "string" || !s.trim())) throw new TypeError("Asset/ignore selectors must be nonempty strings");
+  }
+  return { scope: { kind: scope.kind, id: scope.id }, maxNodes, includeText, timeout, ignoreSelectors, requiredAssets };
+}
+
+async function prepare(page, options) {
+  await settlePage(page, true, options.timeout, false);
+  // Legacy settling is best effort. Snapshot capture requires fonts and images to
+  // succeed and exposes failures, instead of returning apparently complete data.
+  await page.waitForFunction(({ requiredAssets }) => {
+    const required = requiredAssets.flatMap((selector) => [...document.querySelectorAll(selector)]);
+    if (requiredAssets.some((selector) => !document.querySelector(selector))) return false;
+    return document.fonts.status === "loaded" && [...document.images, ...required].every((el) => {
+      if (el instanceof HTMLImageElement) return el.complete && (!el.currentSrc || el.naturalWidth > 0);
+      if (el instanceof HTMLMediaElement) return el.readyState >= 2;
+      return true;
+    });
+  }, { requiredAssets: options.requiredAssets }, { timeout: options.timeout });
+  const failures = await page.evaluate(async ({ requiredAssets, timeout }) => {
+    await document.fonts.ready;
+    const failed = [...document.fonts].filter((f) => f.status === "error").map((f) => `font: ${f.family}`);
+    const images = requiredAssets.flatMap((s) => [...document.querySelectorAll(s)])
+      .flatMap((el) => [...getComputedStyle(el).backgroundImage.matchAll(/url\(["']?(.*?)["']?\)/g)].map((m) => m[1]));
+    await Promise.all(images.map((url) => new Promise((resolve) => {
+      const img = new Image();
+      const timer = setTimeout(() => { failed.push("Required background image timed out"); resolve(); }, timeout);
+      img.onload = img.onerror = (event) => { clearTimeout(timer); if (event.type === "error") failed.push("Required background image failed"); resolve(); };
+      img.src = url;
+    })));
+    window.scrollTo({ left: 0, top: 0, behavior: "instant" });
+    await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+    return failed;
+  }, { requiredAssets: options.requiredAssets, timeout: options.timeout });
+  if (failures.length) throw new Error(`Snapshot assets failed: ${failures.join(", ")}`);
+}
+
+async function extract(page, options) {
+  return page.evaluate(inspectPage, { ignore: options.ignoreSelectors.join(","), snapshot: options });
+}
+
+/** Returns only the strict Shivax UISnapshot v1 contract. No persistence or comparison. */
+export async function captureUISnapshot(page, options = {}) {
+  const config = captureOptions(options);
+  await prepare(page, config);
+  return (await extract(page, config)).snapshot;
+}
+
+/** Metadata is separate because Shivax v1 rejects fields outside its contract. */
+export async function captureUIPage(page, options = {}) {
+  const config = captureOptions(options);
+  await prepare(page, config);
+  const capture = await extract(page, config);
+  if (options.uiChecks) {
+    const { inspectUICheckPage } = await import('../ui-check.js');
+    capture.uiInspection = await inspectUICheckPage(page, config.ignoreSelectors);
+  }
+  if (options.screenshotPath) {
+    const size = await capturePageScreenshot(page, options.screenshotPath);
+    capture.screenshot = { path: options.screenshotPath, ...size };
+  }
+  return capture;
+}
+
+/** Validate runner settings without launching Chromium. */
+export function validateCaptureOptions({ viewport = VIEWPORTS.desktop, deviceScaleFactor = 1, ...options } = {}) {
+  captureOptions(options);
+  if (!viewport || !Number.isInteger(viewport.width) || !Number.isInteger(viewport.height) || viewport.width <= 0 || viewport.height <= 0) throw new TypeError("A positive integer viewport is required");
+  if (!Number.isFinite(deviceScaleFactor) || deviceScaleFactor < 0.01 || deviceScaleFactor > 100) throw new TypeError("Invalid deviceScaleFactor");
+}
+
+/** Same Chromium instance/settings; independent fresh contexts for the two URLs. */
+export async function captureUISnapshotPair({ baselineUrl, targetUrl, viewport = VIEWPORTS.desktop, deviceScaleFactor = 1, signal, accessibility = false, onEvent, onPage, baselineCapture, ...options } = {}) {
+  validateCaptureOptions({ ...options, viewport, deviceScaleFactor });
+  if ((!baselineUrl && !baselineCapture) || !targetUrl) throw new TypeError("baselineUrl and targetUrl are required");
+  signal?.throwIfAborted();
+  onEvent?.({ type: "state", state: "loading", side: baselineCapture ? "target" : "baseline" });
+  const browser = await chromium.launch({ headless: true });
+  const abort = () => { void browser.close().catch(() => {}); };
+  signal?.addEventListener("abort", abort, { once: true });
+  try {
+    signal?.throwIfAborted();
+    const captures = {};
+    for (const [kind, url] of [["baseline", baselineUrl], ["target", targetUrl]]) {
+      signal?.throwIfAborted();
+      if (kind === "baseline" && baselineCapture) { captures.baseline = baselineCapture; continue; }
+      const page = await createInspectionPage(browser, viewport, deviceScaleFactor);
+      let stopPreview;
+      try {
+        stopPreview = await onPage?.(page, kind);
+        onEvent?.({ type: "state", state: "loading", side: kind });
+        page.on("domcontentloaded", () => onEvent?.({ type: "page", name: "domcontentloaded", side: kind }));
+        page.on("requestfailed", request => onEvent?.({ type: "page", name: "requestfailed", side: kind, error: request.failure()?.errorText }));
+        await page.goto(url, { waitUntil: "load", timeout: options.timeout ?? 15000 });
+        onEvent?.({ type: "state", state: "extracting", side: kind });
+        captures[kind] = await captureUIPage(page, { ...options, screenshotPath: options.screenshots?.[kind] });
+        onEvent?.({ type: "snapshot", side: kind, nodes: captures[kind].snapshot.nodes.length });
+        if (accessibility) {
+          const { scanAccessibility } = await import("./accessibility.mjs");
+          captures[kind].accessibility = await scanAccessibility(page, { exclude: options.ignoreSelectors });
+        }
+      } finally {
+        await stopPreview?.();
+        await page.context().close().catch(() => {});
+      }
+    }
+    signal?.throwIfAborted();
+    return captures;
+  } catch (error) {
+    signal?.throwIfAborted();
+    throw error;
+  } finally {
+    signal?.removeEventListener("abort", abort);
+    await browser.close();
+  }
+}