inspectra-engine 0.0.0-stage → 1.0.2

package/examples/README.md

@@ -0,0 +1,105 @@
+# Local runner example
+
+1. Copy `.env.example` to `.env` if you do not already have a `.env` file.
+2. Set `INSPECTRA_ALLOWED_ORIGINS` to your Visynq frontend's exact origin.
+   `http://localhost:5173` is the example frontend origin; this package does not
+   start that frontend. Leave the value empty for curl-only usage.
+3. Start your baseline and target websites, then edit `runner-scan.json` to use
+   their real URLs and an explicit personal or company scope. Ports 3000 and 3001
+   are examples; Inspectra does not start those websites.
+4. From the Inspectra directory, start the runner:
+
+```sh
+node bin/inspectra.mjs dev
+# Or load a different configuration file:
+node bin/inspectra.mjs dev --env .env.local
+# After installing this version of the package:
+npx inspectra dev
+```
+
+Startup prints the runner URL, a generated token and its expiry. Leave that
+terminal running. In a second terminal, set the values printed at startup:
+
+```sh
+export RUNNER_URL='http://127.0.0.1:4317'
+export RUNNER_TOKEN='paste-the-startup-token-here'
+
+curl --fail-with-body -X POST "$RUNNER_URL/sessions" \
+  -H "Authorization: Bearer $RUNNER_TOKEN" \
+  -H 'Content-Type: application/json' \
+  --data-binary @examples/runner-scan.json
+```
+
+The response contains a scan `id` and a new scan-specific `token`. Use those for
+all scan endpoints. The startup token only creates sessions.
+
+```sh
+export SCAN_ID='paste-the-session-id-here'
+export SCAN_TOKEN='paste-the-session-token-here'
+
+# Watch real scan events and issues until the scan finishes.
+curl --no-buffer "$RUNNER_URL/sessions/$SCAN_ID/events" \
+  -H "Authorization: Bearer $SCAN_TOKEN"
+
+# Check status.
+curl "$RUNNER_URL/sessions/$SCAN_ID" \
+  -H "Authorization: Bearer $SCAN_TOKEN"
+
+# Save the completed JSON report (409 if not completed yet).
+curl --fail-with-body "$RUNNER_URL/sessions/$SCAN_ID/report" \
+  -H "Authorization: Bearer $SCAN_TOKEN" --output report.json
+
+# Save the latest preview (204 means no frame yet).
+curl "$RUNNER_URL/sessions/$SCAN_ID/preview" \
+  -H "Authorization: Bearer $SCAN_TOKEN" --output preview.jpg
+
+# Cancel a running or queued scan; poll status until cancelled.
+curl -X DELETE "$RUNNER_URL/sessions/$SCAN_ID" \
+  -H "Authorization: Bearer $SCAN_TOKEN"
+```
+
+`INSPECTRA_PORT` is the runner port; `INSPECTRA_ALLOWED_ORIGINS` describes the
+frontend allowed to call it. Baseline and target URLs describe the websites
+being scanned. These are three separate settings.
+
+Shell variables override `.env`; `--port` and repeated `--origin` flags override
+both. Invalid values fail at startup. An absent default `.env` is allowed; an
+explicit `--env` must exist. The Node API does not automatically read `.env`.
+
+Use Ctrl+C in the runner terminal to cancel work and clean up temporary reports.
+Download results before expiry or shutdown. `.env` is ignored by Git and excluded
+from npm packages. Do not save runtime tokens in configuration files.
+
+## Figma baseline
+
+Use `examples/figma-scan.json` as the session request instead of
+`examples/runner-scan.json`. Replace the file URL and selected node ID with real
+values and set the actual website URL. Set `FIGMA_TOKEN` in the local Node runner
+before starting `dev`; React requests contain no Figma token. The token needs
+`file_content:read` and access to that file. The baseline PNG is Figma's rendering;
+issues come from the existing Shivax snapshot comparator. See the Phase 10 section
+in the root README for scaling, role mappings, font and unsupported-property
+limitations. No original image assets or fonts are installed into your website.
+
+## PNG baseline
+
+Record the viewport and DPR **when taking the screenshot**. Edit
+`examples/png-metadata.json` to match those values, then run:
+
+```sh
+node bin/inspectra.mjs compare --baseline /absolute/path/reference.png \
+  --png-metadata examples/png-metadata.json --target http://localhost:3000 \
+  --output ./new-png-report --scope-kind personal --scope-id png-demo
+```
+
+The target uses that viewport by default. The output includes the original
+baseline, a real target screenshot, a JSON report, and `baseline.matches.svg` /
+`target.matches.svg` with corresponding matched regions highlighted. Open these
+SVGs locally; matches and differences from PNGs require human review.
+
+OCR runs locally through macOS Vision and Swift command-line tools on macOS, or
+an installed Tesseract executable with English data on other systems. There is
+no hosted OCR requirement and no silent placeholder output if OCR is unavailable.
+Node callers can supply `pngOcr` for another OCR implementation. See the Phase 11
+section in the root README for inline HTTP uploads, confidence, limitations and
+unknown CSS properties.

package/examples/figma-scan.json

@@ -0,0 +1,12 @@
+{
+  "baseline": {
+    "type": "figma",
+    "url": "https://www.figma.com/design/REPLACE_FILE_KEY/Design",
+    "nodeId": "123:456",
+    "unitsPerCssPixel": 1
+  },
+  "target": "http://localhost:3000",
+  "scope": { "kind": "personal", "id": "figma-demo" },
+  "viewport": { "width": 1440, "height": 900 },
+  "accessibility": true
+}

package/examples/png-metadata.json

@@ -0,0 +1,5 @@
+{
+  "viewport": { "width": 1440, "height": 900, "devicePixelRatio": 1 },
+  "fullPage": false,
+  "scroll": { "x": 0, "y": 0 }
+}

package/examples/runner-scan.json

@@ -0,0 +1,7 @@
+{
+  "baseline": "http://localhost:3000",
+  "target": "http://localhost:3001",
+  "scope": { "kind": "personal", "id": "local-demo" },
+  "viewport": { "width": 1440, "height": 900 },
+  "accessibility": true
+}

package/node/analysis-worker.mjs

@@ -0,0 +1,33 @@
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
+import { analyzeUI } from 'shivax';
+
+if (!isMainThread) {
+  try {
+    const result = analyzeUI(...workerData, state => parentPort.postMessage({ type: 'state', state }));
+    parentPort.postMessage({ type: 'result', result });
+  } catch (error) { parentPort.postMessage({ type: 'error', message: error.message }); }
+}
+
+export async function analyzeInWorker(baseline, target, options, signal, onEvent) {
+  signal?.throwIfAborted();
+  const worker = new Worker(new URL(import.meta.url), { workerData: [baseline, target, options] });
+  let abort;
+  try {
+    return await new Promise((resolve, reject) => {
+      abort = () => reject(signal.reason);
+      signal?.addEventListener('abort', abort, { once: true });
+      if (signal?.aborted) return abort();
+      worker.on('message', event => {
+        if (signal?.aborted) return;
+        if (event.type === 'result') resolve(event.result);
+        else if (event.type === 'error') reject(new Error(event.message));
+        else { try { onEvent?.(event); } catch (error) { reject(error); } }
+      });
+      worker.on('error', reject);
+      worker.on('exit', code => reject(new Error(`Analysis worker exited before result (${code})`)));
+    });
+  } finally {
+    signal?.removeEventListener('abort', abort);
+    await worker.terminate();
+  }
+}

package/node/dev-config.mjs

@@ -0,0 +1,18 @@
+/** CLI configuration only. Importing inspectra/node never loads a project's .env. */
+export function devOptions(values, env = process.env) {
+  const number = (value, name) => {
+    if (value === undefined) return undefined;
+    if (!/^\d+$/.test(value)) throw new TypeError(`${name} must be an integer`);
+    return Number(value);
+  };
+  const settings = {
+    port: number(values.port ?? env.INSPECTRA_PORT, 'port'),
+    allowedOrigins: values.origin ?? (env.INSPECTRA_ALLOWED_ORIGINS ?? '').split(',').map(origin => origin.trim()).filter(Boolean),
+  };
+  for (const [key, variable] of Object.entries({
+    concurrency: 'INSPECTRA_CONCURRENCY', maxQueued: 'INSPECTRA_MAX_QUEUED', maxSessions: 'INSPECTRA_MAX_SESSIONS',
+    scanTimeout: 'INSPECTRA_SCAN_TIMEOUT_MS', captureTimeout: 'INSPECTRA_CAPTURE_TIMEOUT_MS', bootstrapTTL: 'INSPECTRA_BOOTSTRAP_TTL_MS',
+    tokenTTL: 'INSPECTRA_SESSION_TTL_MS', previewInterval: 'INSPECTRA_PREVIEW_INTERVAL_MS',
+  })) settings[key] = number(env[variable], variable);
+  return settings;
+}

package/node/event-stream.mjs

@@ -0,0 +1,10 @@
+// write(false) means bytes were accepted into Node's buffer, not rejected.
+// Preserve ordinary backpressure; disconnect only subscribers exceeding a bound.
+export function sendEvent(res, data, end = false) {
+  if (res.destroyed || res.writableEnded) return;
+  if (data) {
+    res.write(data);
+    if (res.writableLength > 2 * 1024 * 1024) { res.destroy(); return; }
+  }
+  if (end) res.end();
+}

package/node/index.d.mts

@@ -0,0 +1,114 @@
+import type { Page } from 'playwright';
+import type { UISnapshot, UIAnalysisOptions } from 'shivax';
+import type { ComparisonResult, FigmaBaseline, PngBaseline } from '../client/index.mjs';
+type WithoutEnvelope<T> = T extends unknown ? Omit<T, 'id' | 'sessionId' | 'timestamp'> : never;
+export type CaptureEvent = WithoutEnvelope<import('../client/index.mjs').ScanEvent>;
+export interface CaptureOptions {
+  scope: UISnapshot['scope'];
+  uiChecks?: boolean;
+  spelling?: boolean;
+  maxNodes?: number;
+  includeText?: boolean;
+  timeout?: number;
+  ignoreSelectors?: string[];
+  requiredAssets?: string[];
+}
+export interface PageCapture {
+  snapshot: UISnapshot;
+  metadata: Record<string, unknown>;
+  screenshot?: { path: string; width: number; height: number };
+  accessibility?: unknown;
+}
+export interface PairOptions extends CaptureOptions {
+  baselineUrl: string;
+  targetUrl: string;
+  viewport?: { width: number; height: number };
+  deviceScaleFactor?: number;
+  signal?: AbortSignal;
+  accessibility?: boolean;
+  screenshots?: { baseline?: string; target?: string };
+  onEvent?: (event: CaptureEvent) => void;
+  onPage?: (page: Page, side: 'baseline' | 'target') => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>;
+}
+export interface CompareOptions extends CaptureOptions {
+  baseline: string | FigmaBaseline | PngBaseline | PngFileBaseline;
+  target: string;
+  output: string;
+  viewport?: { width: number; height: number };
+  deviceScaleFactor?: number;
+  signal?: AbortSignal;
+  analysisOptions?: UIAnalysisOptions;
+  analysisWorker?: boolean;
+  /** Node-only PAT; defaults to process.env.FIGMA_TOKEN. Never put this in ScanRequest. */
+  figmaToken?: string;
+  /** Injectable REST boundary for controlled integration tests. */
+  figmaFetch?: typeof fetch;
+  pngOcr?: PngOCRProvider;
+  onEvent?: PairOptions['onEvent'];
+  onPage?: PairOptions['onPage'];
+  accessibility?: boolean;
+}
+export declare function compare(options: CompareOptions): Promise<ComparisonResult>;
+export declare function captureUISnapshot(page: Page, options: CaptureOptions): Promise<UISnapshot>;
+export declare function captureUIPage(page: Page, options: CaptureOptions & { screenshotPath?: string }): Promise<PageCapture>;
+export declare function captureUISnapshotPair(options: PairOptions): Promise<{ baseline: PageCapture; target: PageCapture }>;
+export declare function scanAccessibility(page: Page, options?: { exclude?: string[]; bestPractice?: boolean }): Promise<unknown>;
+export declare function runUiCheck(options?: Record<string, unknown>): Promise<unknown>;
+
+export interface PreviewFrame {
+  sessionId: string;
+  scope: UISnapshot['scope'];
+  data: Uint8Array;
+  contentType: 'image/jpeg';
+  signal: AbortSignal;
+  side: 'baseline' | 'target';
+  timestamp: string;
+}
+export interface LocalRunnerOptions {
+  port?: number;
+  allowedOrigins?: string[];
+  bootstrapTTL?: number;
+  tokenTTL?: number;
+  concurrency?: number;
+  maxQueued?: number;
+  maxSessions?: number;
+  scanTimeout?: number;
+  /** Default per-capture timeout; bounded by scanTimeout. Explicit scan requests may override it. */
+  captureTimeout?: number;
+  previewInterval?: number;
+  figmaToken?: string;
+  figmaFetch?: typeof fetch;
+  pngOcr?: PngOCRProvider;
+  frameTransport?: (frame: PreviewFrame) => void | Promise<void>;
+  signal?: AbortSignal;
+}
+export declare function startLocalRunner(options?: LocalRunnerOptions): Promise<{
+  origin: string; token: string; expiresAt: number; close(): Promise<void>;
+}>;
+
+
+export interface FigmaCapture extends PageCapture { preview: Uint8Array }
+export declare function figmaNodeToSnapshot(entry: unknown, options: {
+  source: FigmaBaseline; scope: UISnapshot['scope']; viewport?: UISnapshot['viewport']; maxNodes?: number; includeText?: boolean;
+}): PageCapture;
+export declare function captureFigmaBaseline(source: FigmaBaseline, options: {
+  scope: UISnapshot['scope']; token?: string; fetch?: typeof fetch; signal?: AbortSignal;
+  timeout?: number; viewport?: UISnapshot['viewport']; maxNodes?: number; includeText?: boolean;
+  screenshotPath?: string; onEvent?: PairOptions['onEvent'];
+}): Promise<FigmaCapture>;
+
+
+export type PngFileBaseline = Omit<PngBaseline, 'data'> & { path: string };
+export interface PngObservations {
+  provider: string;
+  lines: { text: string; bounds: { x: number; y: number; width: number; height: number }; confidence: number }[];
+  regions?: { kind: 'surface' | 'image'; bounds: { x: number; y: number; width: number; height: number }; confidence: number; method: string }[];
+}
+export type PngOCRProvider = (input: { path: string; width: number; height: number; signal: AbortSignal; timeout: number; scope: UISnapshot['scope'] }) => PngObservations | Promise<PngObservations>;
+export declare function pngObservationsToSnapshot(observations: PngObservations, options: {
+  source: PngBaseline | PngFileBaseline; scope: UISnapshot['scope']; width: number; height: number; maxNodes?: number; includeText?: boolean;
+}): PageCapture;
+export declare function capturePNGBaseline(source: PngBaseline | PngFileBaseline, options: {
+  scope: UISnapshot['scope']; signal?: AbortSignal; timeout?: number; pngOcr?: PngOCRProvider;
+  maxNodes?: number; includeText?: boolean; screenshotPath?: string; onEvent?: PairOptions['onEvent'];
+}): Promise<PageCapture>;

package/node/index.mjs

@@ -0,0 +1,100 @@
+import { mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { analyzeUI, validateUIAnalysisOptions } from 'shivax';
+import { capturePNGBaseline, validatePNGBaseline } from '../scanner/png-snapshot.mjs';
+export { capturePNGBaseline, pngObservationsToSnapshot } from '../scanner/png-snapshot.mjs';
+import { captureFigmaBaseline, validateFigmaBaseline } from '../scanner/figma-snapshot.mjs';
+export { captureFigmaBaseline, figmaNodeToSnapshot } from '../scanner/figma-snapshot.mjs';
+import { captureUISnapshotPair } from '../scanner/browser-snapshot.js';
+export { captureUISnapshot, captureUIPage, captureUISnapshotPair } from '../scanner/browser-snapshot.js';
+export { scanAccessibility } from '../scanner/accessibility.mjs';
+export { runUiCheck } from '../ui-check.js';
+
+/** Local capture and Shivax analysis. A fresh output directory prevents scope mixing. */
+export async function compare({ baseline, target, viewport, output,
+  scope, signal, analysisOptions = {}, accessibility = true, onEvent, onPage, analysisWorker = false, uiChecks = false, spelling = false, figmaToken, figmaFetch, pngOcr, ...captureOptions } = {}) {
+  const isFigma = baseline?.type === 'figma', isPng = baseline?.type === 'png';
+  if (isPng) validatePNGBaseline(baseline);
+  viewport ??= isPng ? { width: baseline.viewport.width, height: baseline.viewport.height } : { width: 1440, height: 900 };
+  if (isFigma) validateFigmaBaseline(baseline);
+  for (const [key, value] of Object.entries(isFigma || isPng ? { target } : { baseline, target })) {
+    let url;
+    try { url = new URL(value); } catch { throw new TypeError(`${key} must be an absolute URL`); }
+    if (!['http:', 'https:', 'file:'].includes(url.protocol)) throw new TypeError(`${key} must use http, https or file`);
+  }
+  if (typeof output !== 'string' || !output.trim()) throw new TypeError('output directory is required');
+  if (typeof accessibility !== 'boolean') throw new TypeError('accessibility must be boolean');
+  if (typeof uiChecks !== 'boolean' || typeof spelling !== 'boolean') throw new TypeError('uiChecks and spelling must be boolean');
+  if ((isFigma || isPng) && uiChecks) throw new TypeError('Legacy uiChecks require URL baselines; image/design sources use Shivax analysis');
+  if (spelling && !uiChecks) throw new TypeError('spelling requires uiChecks');
+  if (uiChecks && captureOptions.includeText === false) throw new TypeError('UI checks require includeText');
+  validateUIAnalysisOptions(analysisOptions);
+  signal?.throwIfAborted();
+  // Validate capture configuration before creating any artifacts.
+  const { validateCaptureOptions } = await import('../scanner/browser-snapshot.js');
+  validateCaptureOptions({ ...captureOptions, scope, viewport });
+  const destination = path.resolve(output);
+  await mkdir(path.dirname(destination), { recursive: true });
+  // Exclusive reservation: never overwrite or mix an earlier company's report.
+  await mkdir(destination, { mode: 0o700 });
+  let staging;
+  try {
+    staging = await mkdtemp(path.join(destination, '.capture-'));
+    const baselineCapture = isPng ? await capturePNGBaseline(baseline, {
+      ...captureOptions, pngOcr, scope, signal, onEvent, screenshotPath: path.join(staging, 'baseline.png') }) : isFigma ? await captureFigmaBaseline(baseline, {
+      ...captureOptions, token: figmaToken, fetch: figmaFetch, signal, scope, onEvent,
+      viewport: { ...viewport, devicePixelRatio: captureOptions.deviceScaleFactor ?? 1 }, screenshotPath: path.join(staging, 'baseline.png') }) : undefined;
+    const pair = await captureUISnapshotPair({ ...captureOptions, baselineUrl: baseline, targetUrl: target,
+      viewport, scope, signal, accessibility, onEvent, onPage, uiChecks, baselineCapture,
+      screenshots: { baseline: path.join(staging, 'baseline.png'), target: path.join(staging, 'target.png') } });
+    if (isFigma) {
+      // Compare the same declared primary family; do not pretend to know the
+      // glyph font actually selected by the browser's fallback mechanism.
+      for (const node of pair.target.snapshot.nodes) {
+        const family = node.typography?.fontFamily;
+        if (family?.status !== 'known') continue;
+        const match = /^(?:"([^"]+)"|'([^']+)'|([^,]+))/.exec(family.value);
+        if (match) {
+          const primary = (match[1] ?? match[2] ?? match[3]).trim();
+          pair.target.metadata.nodes[node.id].declaredFontStack = family.value;
+          family.value = primary;
+          family.provenance.method = 'Primary declared CSS font family; actual glyph font unverified';
+        }
+      }
+    }
+    signal?.throwIfAborted();
+    const analysis = analysisWorker
+      ? await (await import('./analysis-worker.mjs')).analyzeInWorker(pair.baseline.snapshot, pair.target.snapshot, analysisOptions, signal, onEvent)
+      : analyzeUI(pair.baseline.snapshot, pair.target.snapshot, analysisOptions, state => onEvent?.({ type: 'state', state }));
+    if (isPng) for (const issue of analysis.issues) issue.reviewStatus = 'needs-review';
+    for (const issue of analysis.issues) onEvent?.({ type: 'issue', issue, ...(isPng ? { status: 'needs_review' } : {}) });
+    onEvent?.({ type: 'analysis', diagnostics: analysis.diagnostics, work: analysis.work });
+    signal?.throwIfAborted();
+    let uiCheck;
+    if (uiChecks) {
+      const { collectUICheck, checkSpelling } = await import('../ui-check.js');
+      const groups = collectUICheck(pair.baseline.uiInspection, pair.target.uiInspection);
+      const words = spelling ? await checkSpelling(pair.target.uiInspection.texts, [], signal) : [];
+      signal?.throwIfAborted();
+      uiCheck = { ...groups, spelling: words, spellingRan: spelling, provenance: { method: 'inspectra-ui-check', kind: 'inferred', confidence: null } };
+    }
+    const pngMatches = isPng ? await (await import('./png-highlights.mjs')).writePNGHighlights(pair, analysis, staging, signal) : undefined;
+    const review = isPng ? { status: 'needs_review', issues: analysis.issues.map(issue => ({ id: issue.id, status: 'needs_review' })), uncertain: analysis.matching.uncertain, uncertainTarget: analysis.matching.uncertainTarget } : undefined;
+    const result = { ...(isPng ? { review, matches: pngMatches } : {}), ...(uiCheck ? { uiCheck } : {}), version: 1, scope: pair.baseline.snapshot.scope,
+      baseline: pair.baseline.snapshot, target: pair.target.snapshot, analysis, issues: analysis.issues,
+      evidence: { baseline: pair.baseline.metadata, target: pair.target.metadata },
+      accessibility: accessibility ? { baseline: pair.baseline.accessibility ?? null, target: pair.target.accessibility } : null,
+      artifacts: { ...(isPng ? { baselineHighlights: path.join(destination, 'baseline.matches.svg'), targetHighlights: path.join(destination, 'target.matches.svg') } : {}), report: path.join(destination, 'report.json'),
+        baselineScreenshot: path.join(destination, 'baseline.png'), targetScreenshot: path.join(destination, 'target.png') } };
+    await writeFile(path.join(staging, 'report.json'), JSON.stringify(result, null, 2) + '\n', { mode: 0o600 });
+    signal?.throwIfAborted();
+    for (const name of ['baseline.png', 'target.png', 'report.json', ...(isPng ? ['baseline.matches.svg', 'target.matches.svg'] : [])]) await rename(path.join(staging, name), path.join(destination, name));
+    await rm(staging, { recursive: true });
+    return result;
+  } catch (error) {
+    await rm(destination, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export { startLocalRunner } from './runner.mjs';

package/node/job-manager.mjs

@@ -0,0 +1,172 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { compare } from './index.mjs';
+import { validateCaptureOptions } from '../scanner/browser-snapshot.js';
+import { validatePNGBaseline } from '../scanner/png-snapshot.mjs';
+import { validateFigmaBaseline } from '../scanner/figma-snapshot.mjs';
+import { validateUIAnalysisOptions } from 'shivax';
+
+export const terminal = state => ['completed', 'failed', 'cancelled'].includes(state);
+export const secret = () => randomBytes(32).toString('base64url');
+export function integer(value, name, min, max) {
+  if (!Number.isInteger(value) || value < min || value > max) throw new TypeError(`${name} must be ${min}..${max}`);
+  return value;
+}
+
+export class ScanJobs {
+  constructor({ root, concurrency = 1, maxQueued = 4, maxSessions = 16, tokenTTL = 900000,
+    scanTimeout = 60000, captureTimeout, previewInterval = 1000, frameTransport, figmaToken, figmaFetch, pngOcr } = {}) {
+    this.root = root; this.figmaToken = figmaToken; this.figmaFetch = figmaFetch; this.pngOcr = pngOcr;
+    this.concurrency = integer(concurrency, 'concurrency', 1, 4);
+    this.maxQueued = integer(maxQueued, 'maxQueued', 0, 32);
+    this.maxSessions = integer(maxSessions, 'maxSessions', 1, 64);
+    this.tokenTTL = integer(tokenTTL, 'tokenTTL', 100, 900000);
+    this.scanTimeout = integer(scanTimeout, 'scanTimeout', 100, 300000);
+    this.captureTimeout = integer(captureTimeout ?? Math.min(15000, this.scanTimeout), 'captureTimeout', 1, this.scanTimeout);
+    this.previewInterval = integer(previewInterval, 'previewInterval', 250, 10000);
+    if (frameTransport !== undefined && typeof frameTransport !== 'function') throw new TypeError('frameTransport must be a function');
+    this.frameTransport = frameTransport;
+    this.jobs = new Map(); this.queue = []; this.active = new Set(); this.closed = false;
+    this.sweeper = setInterval(() => { void this.sweep(); }, 1000); this.sweeper.unref();
+  }
+  create(input) {
+    if (this.closed) throw Object.assign(new Error('Runner is shutting down'), { status: 503 });
+    if (this.jobs.size >= this.maxSessions || (this.active.size >= this.concurrency && this.queue.length >= this.maxQueued)) {
+      throw Object.assign(new Error('Scan capacity reached'), { status: 429 });
+    }
+    if (!input || typeof input !== 'object' || Array.isArray(input)) throw new TypeError('A scan object is required');
+    const allowed = ['baseline', 'target', 'scope', 'viewport', 'timeout', 'maxNodes', 'includeText', 'ignoreSelectors', 'requiredAssets', 'analysisOptions', 'accessibility', 'uiChecks', 'spelling'];
+    if (Object.keys(input).some(key => !allowed.includes(key))) throw new TypeError('Unsupported scan option');
+    const options = structuredClone({ viewport: { width: 1440, height: 900 }, timeout: this.captureTimeout, maxNodes: 2000, ...input });
+    for (const key of ['baseline', 'target']) {
+      if (key === 'baseline' && options.baseline?.type === 'png') {
+        validatePNGBaseline(options.baseline, { allowPath: false });
+        if (options.baseline.data.length > 4 * 1024 * 1024 * 4 / 3 + 32) throw Object.assign(new Error('Inline PNG exceeds 4 MiB upload limit'), { status: 413 });
+        if (input.viewport === undefined) options.viewport = { width: options.baseline.viewport.width, height: options.baseline.viewport.height };
+        continue;
+      }
+      if (key === 'baseline' && options.baseline?.type === 'figma') { validateFigmaBaseline(options.baseline); continue; }
+      const url = new URL(options[key]);
+      if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new TypeError(`${key} requires an HTTP(S) URL without credentials`);
+    }
+    validateCaptureOptions(options); validateUIAnalysisOptions(options.analysisOptions ?? {});
+    if (options.viewport.width > 3840 || options.viewport.height > 2160 || options.maxNodes > 2000 || options.timeout > this.scanTimeout) throw new TypeError('Scan resource limit exceeded');
+    if (options.accessibility !== undefined && typeof options.accessibility !== 'boolean') throw new TypeError('accessibility must be boolean');
+    for (const key of ['uiChecks', 'spelling']) if (options[key] !== undefined && typeof options[key] !== 'boolean') throw new TypeError(`${key} must be boolean`);
+    if (['figma', 'png'].includes(options.baseline?.type) && options.uiChecks) throw new TypeError('Legacy uiChecks require URL baselines');
+    if (options.spelling && !options.uiChecks) throw new TypeError('spelling requires uiChecks');
+    if (options.uiChecks && options.includeText === false) throw new TypeError('UI checks require includeText');
+    options.analysisOptions = { ...options.analysisOptions,
+      maxWork: Math.min(options.analysisOptions?.maxWork ?? 250000, 500000),
+      matchingOptions: { ...options.analysisOptions?.matchingOptions,
+        maxWork: Math.min(options.analysisOptions?.matchingOptions?.maxWork ?? 1000000, 1000000) } };
+    const job = { id: randomUUID(), token: secret(), expiresAt: Date.now() + this.tokenTTL, options,
+      state: 'queued', events: [], eventBytes: 0, sequence: 0, listeners: new Set(), controller: new AbortController(),
+      frame: null, result: null, error: null, done: null };
+    job.output = path.join(this.root, job.id);
+    this.jobs.set(job.id, job); this.queue.push(job); this.emit(job, { type: 'state', state: 'queued' }); this.pump();
+    return job;
+  }
+  status(job) { return { id: job.id, state: job.state, scope: job.options.scope, expiresAt: job.expiresAt, error: job.error, lastEventId: job.sequence }; }
+  emit(job, event) {
+    if (terminal(job.state)) return;
+    if (event.type === 'state') job.state = event.state;
+    const item = { ...event, id: ++job.sequence, sessionId: job.id, timestamp: new Date().toISOString() };
+    const data = `id: ${item.id}\nevent: ${item.type}\ndata: ${JSON.stringify(item)}\n\n`;
+    job.events.push({ id: item.id, data }); job.eventBytes += Buffer.byteLength(data);
+    while (job.events.length > 512 || job.eventBytes > 1048576) job.eventBytes -= Buffer.byteLength(job.events.shift().data);
+    for (const listener of job.listeners) listener(data, terminal(job.state));
+  }
+  pump() {
+    while (!this.closed && this.active.size < this.concurrency && this.queue.length) {
+      const job = this.queue.shift();
+      if (terminal(job.state)) continue;
+      if (Date.now() >= job.expiresAt) { this.cancel(job); continue; }
+      this.active.add(job);
+      job.done = this.run(job).finally(() => { this.active.delete(job); this.pump(); });
+    }
+  }
+  async run(job) {
+    const timer = setTimeout(() => job.controller.abort(new DOMException(`Scan timed out after ${this.scanTimeout} ms; adjust INSPECTRA_SCAN_TIMEOUT_MS in the runner environment`, 'TimeoutError')), this.scanTimeout);
+    try {
+      job.result = await compare({ ...job.options, output: job.output, signal: job.controller.signal,
+        analysisWorker: true, figmaToken: this.figmaToken, figmaFetch: this.figmaFetch, pngOcr: this.pngOcr, onEvent: event => this.emit(job, event), onPage: (page, side) => this.preview(job, page, side) });
+      job.controller.signal.throwIfAborted();
+      this.emit(job, { type: 'state', state: 'completed' });
+    } catch (error) {
+      job.error = { name: error.name, message: error.message };
+      job.frame = null;
+      this.emit(job, { type: 'state', state: job.controller.signal.aborted && error.name !== 'TimeoutError' ? 'cancelled' : 'failed', error: job.error });
+    } finally { clearTimeout(timer); }
+  }
+  preview(job, page, side) {
+    let stopped = false, ready = false, delivered = false, lastCapture = 0, inFlight;
+    const capture = () => {
+      if (stopped || !ready || inFlight || job.controller.signal.aborted || Date.now() - lastCapture < this.previewInterval) return;
+      lastCapture = Date.now();
+      inFlight = (async () => {
+        try {
+          const data = await page.screenshot({ type: 'jpeg', quality: 55, timeout: 2000, animations: 'allow' });
+          if (stopped || job.controller.signal.aborted || data.length > 524288) return;
+          const frame = { data, contentType: 'image/jpeg', side, timestamp: new Date().toISOString() };
+          // A transport callback replaces in-memory delivery; HTTP preview then returns 204.
+          if (this.frameTransport) await this.deliverFrame(job, frame);
+          else job.frame = frame;
+          delivered = true;
+          this.emit(job, { type: 'preview', side, timestamp: frame.timestamp, bytes: data.length });
+        } catch (error) {
+          if (!stopped && !job.controller.signal.aborted) this.emit(job, { type: 'preview-error', side, message: error.message });
+        } finally { inFlight = null; }
+      })();
+    };
+    const loaded = () => { ready = true; capture(); };
+    page.on('domcontentloaded', loaded);
+    const timer = setInterval(capture, this.previewInterval); timer.unref();
+    return async () => {
+      clearInterval(timer); page.off('domcontentloaded', loaded);
+      await inFlight;
+      if (!delivered && !job.controller.signal.aborted) { capture(); await inFlight; }
+      stopped = true;
+    };
+  }
+  async deliverFrame(job, frame) {
+    const signal = job.controller.signal;
+    let timer, abort;
+    try {
+      await Promise.race([
+        Promise.resolve().then(() => this.frameTransport({ sessionId: job.id, scope: job.options.scope, ...frame, signal })),
+        new Promise((_, reject) => {
+          abort = () => reject(signal.reason);
+          signal.addEventListener('abort', abort, { once: true });
+          if (signal.aborted) return abort();
+          timer = setTimeout(() => reject(new Error('Preview transport timed out')), 2000);
+        }),
+      ]);
+    } finally { clearTimeout(timer); signal.removeEventListener('abort', abort); }
+  }
+  cancel(job) {
+    if (terminal(job.state)) return;
+    job.controller.abort(new DOMException('Scan cancelled', 'AbortError'));
+    if (job.state === 'queued' && !this.active.has(job)) {
+      this.queue = this.queue.filter(entry => entry !== job);
+      this.emit(job, { type: 'state', state: 'cancelled' });
+    }
+  }
+  async sweep() {
+    for (const job of this.jobs.values()) if (Date.now() >= job.expiresAt) {
+      this.cancel(job);
+      if (!terminal(job.state)) continue;
+      this.jobs.delete(job.id);
+      for (const listener of job.listeners) listener('', true);
+      await rm(job.output, { recursive: true, force: true });
+    }
+  }
+  async close() {
+    this.closed = true; clearInterval(this.sweeper);
+    for (const job of this.jobs.values()) this.cancel(job);
+    await Promise.allSettled([...this.active].map(job => job.done));
+    for (const job of this.jobs.values()) for (const listener of job.listeners) listener('', true);
+    this.jobs.clear(); this.queue = [];
+  }
+}

package/node/png-highlights.mjs

@@ -0,0 +1,30 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { pngDimensions, MAX_PNG_BYTES } from '../scanner/png-snapshot.mjs';
+const escape = value => String(value).replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[char]);
+
+/** Matched-region evidence only; correspondence comes exclusively from Shivax. */
+export async function writePNGHighlights(pair, analysis, staging, signal) {
+  const regions = analysis.matching.matches.flatMap((match, index) => {
+    const baseline = pair.baseline.snapshot.nodes.find(n => n.id === match.referenceId)?.bounds;
+    const target = pair.target.snapshot.nodes.find(n => n.id === match.targetId)?.bounds;
+    if (baseline?.status !== 'known' || target?.status !== 'known') return [];
+    return [{ id: `match-${index + 1}`, baselineNodeId: match.referenceId, targetNodeId: match.targetId,
+      baseline: baseline.value, target: target.value, confidence: match.confidence, status: 'needs_review' }];
+  });
+  for (const side of ['baseline', 'target']) {
+    signal?.throwIfAborted();
+    const image = await readFile(`${staging}/${side}.png`, { signal });
+    if (image.length > MAX_PNG_BYTES) throw new RangeError('Highlight screenshot exceeds byte limit');
+    const dimensions = pngDimensions(image);
+    const metadata = side === 'baseline' ? pair.baseline.metadata.image : null;
+    const scale = side === 'baseline' ? metadata.viewport.devicePixelRatio : pair.target.snapshot.viewport.devicePixelRatio;
+    const offset = side === 'baseline' && !metadata.fullPage ? metadata.scroll : { x: 0, y: 0 };
+    const boxes = regions.map(region => {
+      const box = region[side], x = (box.x - offset.x) * scale, y = (box.y - offset.y) * scale;
+      return `<g><title>${escape(`${region.id}: ${region.baselineNodeId} ↔ ${region.targetNodeId}; needs_review`)}</title><rect x="${x}" y="${y}" width="${box.width * scale}" height="${box.height * scale}" fill="none" stroke="#d946ef" stroke-width="2"/><text x="${Math.max(0, x)}" y="${Math.max(12, y + 12)}" fill="#111827" stroke="white" stroke-width="3" paint-order="stroke" font-size="12">${escape(region.id)}</text></g>`;
+    }).join('');
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${dimensions.width}" height="${dimensions.height}" viewBox="0 0 ${dimensions.width} ${dimensions.height}"><title>Matched regions — needs_review</title><image width="${dimensions.width}" height="${dimensions.height}" href="data:image/png;base64,${image.toString('base64')}"/>${boxes}</svg>`;
+    await writeFile(`${staging}/${side}.matches.svg`, svg, { mode: 0o600, signal });
+  }
+  return regions;
+}