inspectra-engine 0.0.0-stage → 1.0.2

package/scanner/figma-snapshot.mjs

@@ -0,0 +1,221 @@
+// Node-only Figma REST adapter. No credentials or API clients belong in inspectra/client.
+import { writeFile } from 'node:fs/promises';
+import { normalizeUISnapshot } from 'shivax';
+import { parseFigmaUrl } from '../compare.js';
+
+export function validateFigmaBaseline(source) {
+  if (!source || source.type !== 'figma' || Object.keys(source).some(key => !['type', 'url', 'nodeId', 'unitsPerCssPixel', 'roleMappings'].includes(key))) throw new TypeError('Invalid Figma baseline');
+  const url = new URL(source.url);
+  if (url.protocol !== 'https:' || !['figma.com', 'www.figma.com'].includes(url.hostname) || url.username || url.password || url.port) throw new TypeError('An HTTPS Figma file URL is required');
+  const nodeId = source.nodeId ?? url.searchParams.get('node-id');
+  if (typeof nodeId !== 'string' || !/^I?[0-9]+[:-][0-9]+(?:;I?[0-9]+[:-][0-9]+)*$/.test(nodeId)) throw new TypeError('Select a Figma frame/node using nodeId or the URL node-id');
+  url.search = ''; url.searchParams.set('node-id', nodeId);
+  const parsed = parseFigmaUrl(url.href);
+  const scale = source.unitsPerCssPixel ?? 1;
+  if (!Number.isFinite(scale) || scale < 0.01 || scale > 100) throw new TypeError('unitsPerCssPixel must be 0.01..100');
+  if (source.roleMappings !== undefined && (!source.roleMappings || typeof source.roleMappings !== 'object' || Array.isArray(source.roleMappings) || Object.entries(source.roleMappings).some(([id, role]) => !/^I?[0-9]+:[0-9]+(?:;I?[0-9]+:[0-9]+)*$/.test(id) || typeof role !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(role)))) throw new TypeError('Invalid Figma roleMappings');
+  return { ...parsed, scale };
+}
+const finite = value => typeof value === 'number' && Number.isFinite(value);
+const rectangle = box => box && ['x', 'y', 'width', 'height'].every(key => finite(box[key])) && box.width >= 0 && box.height >= 0;
+const provenance = (kind, method, reference) => ({ sourceType: 'figma', kind, method, ...(reference ? { reference } : {}) });
+const known = (value, method, reference) => ({ status: 'known', value, provenance: provenance('design', method, reference), confidence: { score: 1 } });
+const unknown = (method, reference) => ({ status: 'unknown', provenance: provenance('unknown', method, reference), confidence: { score: null } });
+
+/** Pure conversion. API data is scoped per call; unsupported evidence stays outside the strict schema. */
+export function figmaNodeToSnapshot(entry, { source, scope, viewport, maxNodes = 10000, includeText = true } = {}) {
+  const { nodeId, fileKey, scale } = validateFigmaBaseline(source);
+  if (!scope || !['company', 'personal'].includes(scope.kind) || typeof scope.id !== 'string' || !scope.id.trim()) throw new TypeError('An explicit scope is required');
+  if (typeof includeText !== 'boolean') throw new TypeError('includeText must be boolean');
+  if (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > 10000) throw new TypeError('Invalid maxNodes');
+  const root = entry?.document;
+  if (!root || root.id !== nodeId) throw new Error('Selected Figma node was not found');
+  if (root.visible === false || root.opacity === 0 || !rectangle(root.absoluteBoundingBox) || !root.absoluteBoundingBox.width || !root.absoluteBoundingBox.height) throw new Error('Selected Figma node has no visible measurable bounds');
+  const origin = root.absoluteBoundingBox;
+  const nodes = [], relationships = [], metadata = { fileKey, nodeId, unitsPerCssPixel: scale, nodes: {}, diagnostics: [], components: {}, componentSets: {}, componentRelationships: [], imageRefs: [] };
+  const diagnostic = (id, property, message) => metadata.diagnostics.push({ nodeId: id, property, message });
+  const refs = new Set(), ids = new Set();
+  const stack = [{ node: root, parent: null, transformed: false, uniformScale: 1, opacity: 1, clip: null }];
+  let visited = 0;
+  while (stack.length) {
+    const { node, parent, transformed, uniformScale, opacity, clip } = stack.pop();
+    if (++visited > maxNodes) throw new RangeError('Figma node limit exceeded');
+    if (node.visible === false || node.opacity === 0) continue;
+    const rawBox = node.absoluteBoundingBox;
+    if (clip && rectangle(rawBox) && (rawBox.x + rawBox.width <= clip.x || rawBox.y + rawBox.height <= clip.y || rawBox.x >= clip.x + clip.width || rawBox.y >= clip.y + clip.height)) continue;
+    if (typeof node.id !== 'string' || !/^I?[0-9]+:[0-9]+(?:;I?[0-9]+:[0-9]+)*$/.test(node.id) || ids.has(node.id)) throw new Error('Invalid or duplicate Figma node id');
+    ids.add(node.id);
+    const id = node.id, detail = { name: node.name, type: node.type, parentId: parent, siblingIds: (node.children ?? []).map(child => child.id) };
+    metadata.nodes[id] = detail;
+    const vector = ['VECTOR', 'BOOLEAN_OPERATION', 'STAR', 'LINE', 'ELLIPSE', 'POLYGON'].includes(node.type);
+    const images = (Array.isArray(node.fills) ? node.fills : []).filter(fill => fill.visible !== false && fill.type === 'IMAGE');
+    for (const image of images) if (image.imageRef) refs.add(image.imageRef);
+    detail.fills = node.fills ?? [];
+    detail.images = images.map(({ imageRef, scaleMode, imageTransform, scalingFactor }) => ({ imageRef, scaleMode, imageTransform, scalingFactor }));
+    if (vector) detail.vector = { fillGeometry: node.fillGeometry ?? [], strokeGeometry: node.strokeGeometry ?? [], relativeTransform: node.relativeTransform, size: node.size };
+    if (node.componentId) {
+      detail.component = { id: node.componentId, properties: node.componentProperties ?? {}, overrides: node.overrides ?? [] };
+      metadata.components[node.componentId] = entry.components?.[node.componentId] ?? { unavailable: true };
+      const setId = entry.components?.[node.componentId]?.componentSetId;
+      if (setId) metadata.componentSets[setId] = entry.componentSets?.[setId] ?? { unavailable: true };
+      metadata.componentRelationships.push({ from: id, to: node.componentId, type: 'instance-of', provenance: provenance('design', 'Figma instance.componentId', id), confidence: { score: 1 } });
+      if (!entry.components?.[node.componentId]) diagnostic(id, 'component', 'Component definition is unavailable; instance geometry is retained');
+    }
+    let role = source.roleMappings?.[id];
+    if (role) detail.role = { value: role, provenance: provenance('design', 'explicit caller role mapping', id), confidence: { score: 1 } };
+    else {
+      role = id === nodeId ? 'document' : node.type === 'TEXT' ? (/^(heading|title|h[1-6])(?:[\s/_:-]|$)/i.test(node.name ?? '') ? 'heading' : 'paragraph') : images.length || vector ? 'img' : 'generic';
+      detail.role = { value: role, provenance: provenance('estimated', 'Figma layer type/name mapped to a presentation role; not DOM semantics', id), confidence: { score: 0.5 } };
+      if (node.type === 'TEXT' || node.type === 'INSTANCE') diagnostic(id, 'role', 'Figma has no guaranteed DOM semantics; use roleMappings when the inferred presentation role is unsuitable');
+    }
+    const box = rawBox;
+    const bounds = rectangle(box) ? known({ x: box.x - origin.x, y: box.y - origin.y, width: box.width, height: box.height }, 'absoluteBoundingBox minus selected frame origin', id) : unknown('Figma absoluteBoundingBox unavailable', id);
+    if (bounds.status === 'unknown') diagnostic(id, 'bounds', 'Bounds are unknown; coordinates were not reconstructed');
+    const output = { id, role, bounds };
+    if (node.type === 'TEXT' && includeText && typeof node.characters === 'string') {
+      output.text = node.characters.slice(0, 2048);
+      if (node.characters.length > 2048) diagnostic(id, 'text', 'Text truncated at the UISnapshot limit');
+    }
+    // Rotated/non-uniformly transformed descendants have exact bounding boxes,
+    // but local CSS typography/padding cannot be reconstructed from those boxes.
+    const matrix = node.relativeTransform;
+    const localScale = uniformScale * (Array.isArray(matrix) ? Math.abs(matrix[0]?.[0] ?? 1) : 1);
+    const accumulatedOpacity = opacity * (node.opacity ?? 1);
+    const distorted = transformed || (Array.isArray(matrix) && (Math.abs(matrix[0]?.[1] ?? 0) > 1e-6 || Math.abs(matrix[1]?.[0] ?? 0) > 1e-6 || (matrix[0]?.[0] ?? 1) <= 0 || (matrix[1]?.[1] ?? 1) <= 0 || Math.abs(Math.abs(matrix[0]?.[0] ?? 1) - Math.abs(matrix[1]?.[1] ?? 1)) > 1e-6));
+    if (distorted) diagnostic(id, 'transform', 'Rotation/skew/non-uniform transform: local typography/layout are unknown; absolute bounds remain exact');
+    if (node.type === 'TEXT') {
+      const style = node.style ?? {}, mixed = Object.values(node.styleOverrideTable ?? {}).some(override => Object.keys(override).length);
+      detail.unsupportedTypography = Object.fromEntries(['italic', 'textDecoration', 'textCase', 'paragraphSpacing', 'paragraphIndent', 'boundVariables'].filter(key => style[key] !== undefined).map(key => [key, style[key]]));
+      if (Object.keys(detail.unsupportedTypography).length) diagnostic(id, 'typography-properties', 'Additional text properties retained as evidence; UISnapshot v1 does not compare them');
+      detail.font = { family: style.fontFamily, postScriptName: style.fontPostScriptName, availability: 'unverified' };
+      diagnostic(id, 'font', 'Design font is requested metadata; browser glyph font availability/substitution cannot be established by Figma');
+      const typography = {};
+      const put = (key, value, method = `Figma style.${key}`) => { typography[key] = distorted || mixed ? unknown(mixed ? 'Mixed text styles require manual review' : 'Transformed text style unresolved', id) : value !== undefined ? known(typeof value === 'number' && key !== 'fontWeight' ? value * localScale : value, `${method}; uniform transform scale ${localScale}`, id) : unknown(`${method} unavailable`, id); };
+      put('fontFamily', typeof style.fontFamily === 'string' && style.fontFamily.length <= 256 ? style.fontFamily : undefined);
+      for (const key of ['fontSize', 'fontWeight', 'letterSpacing']) put(key, finite(style[key]) ? style[key] : undefined);
+      put('lineHeight', style.lineHeightUnit === 'PIXELS' && finite(style.lineHeightPx) ? style.lineHeightPx : style.lineHeightUnit === 'FONT_SIZE_%' && finite(style.lineHeightPercentFontSize) && finite(style.fontSize) ? style.fontSize * style.lineHeightPercentFontSize / 100 : undefined, 'Figma explicit pixel/percent-of-font-size line height; intrinsic remains unknown');
+      put('textAlign', ({ LEFT: 'left', RIGHT: 'right', CENTER: 'center', JUSTIFIED: 'justify' })[style.textAlignHorizontal]);
+      const fills = (node.fills ?? style.fills ?? []).filter(fill => fill.visible !== false);
+      const paint = fills.length === 1 && fills[0].type === 'SOLID' ? fills[0] : null;
+      const color = paint?.color;
+      put('color', color && ['r', 'g', 'b'].every(key => finite(color[key])) ? { r: color.r * 255, g: color.g * 255, b: color.b * 255, a: (color.a ?? 1) * (paint.opacity ?? 1) } : undefined, 'Figma single solid text paint; uncomposited sRGB');
+      if (mixed) { detail.styleOverrides = node.styleOverrideTable; diagnostic(id, 'typography', 'Mixed text styles retained as evidence; no single style is asserted'); }
+      if (accumulatedOpacity !== 1 || (paint?.opacity ?? 1) !== 1 || (color?.a ?? 1) !== 1) { typography.color = unknown('Translucent text requires background compositing', id); diagnostic(id, 'color', 'Uncomposited translucent paint is not compared as rendered text color'); }
+      output.typography = typography;
+    }
+    const layout = {};
+    if (['HORIZONTAL', 'VERTICAL', 'GRID'].includes(node.layoutMode)) {
+      const horizontal = node.layoutMode === 'HORIZONTAL';
+      const put = (key, value, method = `Figma auto-layout ${key}`) => { layout[key] = distorted || value === undefined ? unknown(distorted ? 'Transformed auto-layout unresolved' : `${method} unavailable or unsupported`, id) : known(typeof value === 'number' ? value * localScale : value, `${method}; uniform transform scale ${localScale}`, id); };
+      put('display', node.layoutMode === 'GRID' ? 'grid' : 'flex');
+      if (node.layoutMode !== 'GRID') put('flexDirection', horizontal ? 'row' : 'column');
+      for (const key of ['paddingTop', 'paddingRight', 'paddingBottom', 'paddingLeft']) put(key, finite(node[key]) ? node[key] : undefined);
+      const gap = finite(node.itemSpacing) && node.itemSpacing >= 0 ? node.itemSpacing : undefined;
+      put('rowGap', node.layoutMode === 'GRID' ? node.gridRowGap : !horizontal ? gap : node.layoutWrap === 'WRAP' ? node.counterAxisSpacing : 0);
+      put('columnGap', node.layoutMode === 'GRID' ? node.gridColumnGap : horizontal ? gap : node.layoutWrap === 'WRAP' ? node.counterAxisSpacing : 0);
+      if (node.layoutMode !== 'GRID') {
+        put('justifyContent', ({ MIN: 'flex-start', MAX: 'flex-end', CENTER: 'center', SPACE_BETWEEN: 'space-between' })[node.primaryAxisAlignItems]);
+        put('alignItems', ({ MIN: 'flex-start', MAX: 'flex-end', CENTER: 'center', BASELINE: 'baseline' })[node.counterAxisAlignItems]);
+      }
+      if ((node.itemSpacing ?? 0) < 0) diagnostic(id, 'spacing', 'Negative item spacing is overlap, not a CSS gap; gap measurement remains unknown');
+      if (node.layoutWrap === 'WRAP') diagnostic(id, 'layoutWrap', 'Wrap mode retained as evidence; UISnapshot has no wrap property');
+      detail.autoLayout = { mode: node.layoutMode, wrap: node.layoutWrap, positioning: node.layoutPositioning, primarySizing: node.primaryAxisSizingMode, counterSizing: node.counterAxisSizingMode, itemSpacing: node.itemSpacing };
+      output.layout = layout;
+    }
+    for (const key of ['effects', 'strokes', 'constraints', 'boundVariables', 'layoutGrids', 'isMask', 'maskType']) if (node[key] && (typeof node[key] !== 'object' || Object.keys(node[key]).length)) diagnostic(id, key, 'Property retained in evidence but not represented by UISnapshot v1');
+    detail.unsupported = Object.fromEntries(['effects', 'strokes', 'constraints', 'boundVariables', 'layoutGrids', 'isMask', 'maskType'].filter(key => node[key] !== undefined).map(key => [key, node[key]]));
+    nodes.push(output);
+    if (parent) relationships.push({ from: parent, to: id, type: 'parent-child', provenance: provenance('design', 'Figma children hierarchy', id), confidence: { score: 1 } });
+    let childClip = clip;
+    if (node.clipsContent && rectangle(box) && !distorted) {
+      const left = Math.max(clip?.x ?? box.x, box.x), top = Math.max(clip?.y ?? box.y, box.y);
+      childClip = { x: left, y: top, width: Math.max(0, Math.min(clip ? clip.x + clip.width : box.x + box.width, box.x + box.width) - left), height: Math.max(0, Math.min(clip ? clip.y + clip.height : box.y + box.height, box.y + box.height) - top) };
+      detail.clip = childClip;
+    }
+    if (node.clipsContent && distorted) diagnostic(id, 'clipping', 'Transformed clipping cannot be resolved from an axis-aligned rectangle');
+    for (const child of [...(node.children ?? [])].reverse()) stack.push({ node: child, parent: id, transformed: distorted, uniformScale: localScale, opacity: accumulatedOpacity, clip: childClip });
+  }
+  metadata.imageRefs = [...refs];
+  const snapshot = normalizeUISnapshot({ version: 1, sourceType: 'figma', scope: { kind: scope.kind, id: scope.id },
+    viewport: viewport ?? { width: origin.width / scale, height: origin.height / scale, devicePixelRatio: 1 },
+    coordinates: { unit: 'design-unit', unitsPerCssPixel: scale, origin: 'artboard' }, nodes, relationships });
+  if (viewport && Math.abs(origin.width / scale - viewport.width) > 0.01) diagnostic(nodeId, 'viewport', 'Selected frame width differs from the target viewport; no implicit responsive scaling was applied');
+  return { snapshot, metadata };
+}
+
+async function bytes(response, maxBytes) {
+  const chunks = []; let size = 0;
+  if (!response.body) throw new Error('Figma response is empty');
+  for await (const chunk of response.body) {
+    size += chunk.length;
+    if (size > maxBytes) throw new RangeError('Figma response exceeds resource limit');
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+export async function captureFigmaBaseline(source, { token = process.env.FIGMA_TOKEN, signal, timeout = 15000, fetch: request = globalThis.fetch, screenshotPath, onEvent, ...options } = {}) {
+  const { fileKey, nodeId, scale } = validateFigmaBaseline(source);
+  if (!Number.isInteger(timeout) || timeout <= 0) throw new TypeError('Figma timeout must be a positive integer');
+  if (typeof request !== 'function') throw new TypeError('Figma fetch must be a function');
+  if (typeof token !== 'string' || !token.trim()) throw new Error('FIGMA_TOKEN is required in the Node process');
+  const deadline = AbortSignal.timeout(timeout);
+  const combined = AbortSignal.any([...(signal ? [signal] : []), deadline]);
+  let stage = "loading the selected frame";
+  try {
+    combined.throwIfAborted();
+    const api = async endpoint => {
+      let response;
+      try { response = await request(`https://api.figma.com/v1/${endpoint}`, { headers: { 'X-Figma-Token': token }, signal: combined, redirect: 'error' }); }
+      catch { combined.throwIfAborted(); throw new Error('Figma API request failed'); }
+      if (!response.ok) {
+        await response.body?.cancel();
+        const labels = { 401: 'invalid or expired token', 403: 'permission denied or token lacks file_content:read', 404: 'file or node not found', 429: 'rate limit reached; retry later' };
+        throw Object.assign(new Error(`Figma API ${response.status}: ${labels[response.status] ?? 'request failed'}`), { status: response.status });
+      }
+      let data;
+      try { data = JSON.parse((await bytes(response, 16 * 1024 * 1024)).toString('utf8')); }
+      catch { combined.throwIfAborted(); throw new Error('Invalid or oversized Figma API response'); }
+      if (data.err) throw new Error('Figma API could not provide the selected node');
+      return data;
+    };
+    onEvent?.({ type: 'state', state: 'loading', side: 'baseline' });
+    const data = await api(`files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}&geometry=paths`);
+    onEvent?.({ type: 'state', state: 'extracting', side: 'baseline' });
+    const capture = figmaNodeToSnapshot(data.nodes?.[nodeId], { ...options, source });
+    capture.metadata.version = data.version ?? null;
+    onEvent?.({ type: 'snapshot', side: 'baseline', nodes: capture.snapshot.nodes.length });
+    // Resolve only image references present in the selected subtree; no cross-file cache.
+    if (capture.metadata.imageRefs.length) {
+      stage = "loading image references";
+      const fills = await api(`files/${fileKey}/images`);
+      capture.metadata.images = Object.fromEntries(capture.metadata.imageRefs.map(ref => [ref, { available: Boolean(fills.meta?.images?.[ref] ?? fills.images?.[ref]) }]));
+      for (const [ref, image] of Object.entries(capture.metadata.images)) if (!image.available) capture.metadata.diagnostics.push({ nodeId, property: 'image', message: `Image reference ${ref} is unavailable` });
+    }
+    stage = "rendering the selected frame";
+    const render = await api(`images/${fileKey}?ids=${encodeURIComponent(nodeId)}&format=png&scale=${Math.max(0.01, Math.min(4, 1 / scale))}&use_absolute_bounds=true${data.version ? `&version=${encodeURIComponent(data.version)}` : ''}`);
+    let imageUrl;
+    try {
+      imageUrl = new URL(render.images?.[nodeId]);
+      if (imageUrl.protocol !== 'https:' || imageUrl.username || imageUrl.password || !/(^|\.)(amazonaws\.com|figma\.com|figmausercontent\.com|cloudfront\.net)$/.test(imageUrl.hostname)) throw new Error();
+    } catch { throw new Error('Figma did not return a trusted render URL for the selected node'); }
+    stage = "downloading the frame preview";
+    let response;
+    try { response = await request(imageUrl.href, { signal: combined, redirect: 'error' }); }
+    catch { combined.throwIfAborted(); throw new Error('Figma preview download failed'); }
+    if (!response.ok) { await response.body?.cancel(); throw new Error(`Figma preview download failed (${response.status})`); }
+    const image = await bytes(response, 32 * 1024 * 1024);
+    if (image.length < 24 || !image.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) || image.toString('ascii', 12, 16) !== 'IHDR') throw new Error('Figma preview is not a PNG');
+    const width = image.readUInt32BE(16), height = image.readUInt32BE(20);
+    if (!width || !height || width * height > 32 * 1024 * 1024) throw new Error('Figma preview dimensions exceed resource limit');
+    combined.throwIfAborted();
+    capture.metadata.preview = { width, height, requestedScale: Math.max(0.01, Math.min(4, 1 / scale)), semanticsIndependentOfPreview: true };
+    if (screenshotPath) await writeFile(screenshotPath, image, { mode: 0o600, signal: combined });
+    combined.throwIfAborted();
+    return { ...capture, preview: image };
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason;
+    if (deadline.aborted) throw new DOMException(`Figma baseline timed out after ${timeout} ms while ${stage}. Select a smaller frame or increase INSPECTRA_CAPTURE_TIMEOUT_MS in the local runner environment.`, 'TimeoutError');
+    throw error;
+  }
+}

package/scanner/legacy-image-tools.cjs

@@ -0,0 +1,14 @@
+// Optional dependencies used only by the preserved legacy image APIs.
+function load(name) {
+  try {
+    return require(name);
+  } catch (error) {
+    if (error.code !== 'MODULE_NOT_FOUND' || !error.message.includes(`'${name}'`)) throw error;
+    throw new Error(`Legacy pixel comparison requires ${name}. Install pixelmatch@^8 and pngjs@^7 to use this optional feature.`, { cause: error });
+  }
+}
+exports.getPNG = () => load('pngjs').PNG;
+exports.getPixelmatch = () => {
+  const module = load('pixelmatch');
+  return module.default || module;
+};

package/scanner/ocr/local.mjs

@@ -0,0 +1,52 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+const exec = promisify(execFile);
+async function run(command, args, { signal, timeout }) {
+  signal?.throwIfAborted();
+  const task = exec(command, args, { signal, timeout, maxBuffer: 4 * 1024 * 1024, detached: process.platform !== 'win32' });
+  const stop = () => {
+    // Swift may launch compiler/interpreter children; terminate only this OCR group.
+    if (process.platform !== 'win32' && task.child?.pid) { try { process.kill(-task.child.pid, 'SIGKILL'); } catch {} }
+    else task.child?.kill();
+  };
+  signal?.addEventListener('abort', stop, { once: true });
+  if (signal?.aborted) stop();
+  try { return await task; }
+  catch (error) { stop(); throw error; }
+  finally { signal?.removeEventListener('abort', stop); }
+}
+
+/** TSV words -> line observations. Confidence is provider evidence, not calibrated probability. */
+export function parseTesseractTSV(tsv) {
+  const groups = new Map();
+  for (const row of tsv.trim().split(/\r?\n/).slice(1)) {
+    const parts = row.split('\t');
+    if (parts[0] !== '5' || !parts.slice(11).join('\t').trim()) continue;
+    const [x, y, width, height, confidence] = parts.slice(6, 11).map(Number);
+    if (![x, y, width, height, confidence].every(Number.isFinite) || confidence < 0) continue;
+    const key = parts.slice(1, 5).join(':');
+    const item = { text: parts.slice(11).join('\t'), bounds: { x, y, width, height }, confidence: confidence / 100 };
+    const group = groups.get(key) ?? []; group.push(item); groups.set(key, group);
+  }
+  return { provider: 'tesseract-local', lines: [...groups.values()].map(words => {
+    const x = Math.min(...words.map(w => w.bounds.x)), y = Math.min(...words.map(w => w.bounds.y));
+    return { text: words.map(w => w.text).join(' '), confidence: Math.min(...words.map(w => w.confidence)),
+      bounds: { x, y, width: Math.max(...words.map(w => w.bounds.x + w.bounds.width)) - x, height: Math.max(...words.map(w => w.bounds.y + w.bounds.height)) - y } };
+  }) };
+}
+
+export async function localOCR({ path, signal, timeout }) {
+  try {
+    if (process.platform === 'darwin') {
+      const { stdout } = await run('/usr/bin/swift', [fileURLToPath(new URL('./vision.swift', import.meta.url)), path], { signal, timeout });
+      return JSON.parse(stdout);
+    }
+    const { stdout } = await run('tesseract', [path, 'stdout', '-l', 'eng', '--psm', '3', 'tsv'], { signal, timeout });
+    return parseTesseractTSV(stdout);
+  } catch (error) {
+    signal?.throwIfAborted();
+    if (error.killed) throw new DOMException('Local OCR timed out', 'TimeoutError');
+    throw new Error('Local OCR unavailable or failed. macOS requires Swift command-line tools and Vision; other systems require tesseract with eng data. Alternatively supply pngOcr in Node.');
+  }
+}

package/scanner/ocr/vision.swift

@@ -0,0 +1,29 @@
+// Local macOS OCR. Image data never leaves this process/machine.
+import Foundation
+import Vision
+import ImageIO
+
+guard CommandLine.arguments.count == 2,
+      let source = CGImageSourceCreateWithURL(URL(fileURLWithPath: CommandLine.arguments[1]) as CFURL, nil),
+      let image = CGImageSourceCreateImageAtIndex(source, 0, nil) else {
+    FileHandle.standardError.write(Data("Unable to decode PNG for local OCR\n".utf8)); exit(1)
+}
+let request = VNRecognizeTextRequest()
+request.recognitionLevel = .accurate
+request.usesLanguageCorrection = false
+let handler = VNImageRequestHandler(cgImage: image, options: [:])
+do {
+    try handler.perform([request])
+    let width = Double(image.width), height = Double(image.height)
+    let lines: [[String: Any]] = (request.results ?? []).compactMap { observation in
+        guard let text = observation.topCandidates(1).first else { return nil }
+        let box = observation.boundingBox
+        return ["text": text.string, "confidence": Double(text.confidence),
+                "bounds": ["x": Double(box.minX) * width, "y": (1 - Double(box.maxY)) * height,
+                           "width": Double(box.width) * width, "height": Double(box.height) * height]]
+    }
+    let output = try JSONSerialization.data(withJSONObject: ["provider": "apple-vision-local", "lines": lines])
+    FileHandle.standardOutput.write(output)
+} catch {
+    FileHandle.standardError.write(Data("Local Vision OCR failed\n".utf8)); exit(1)
+}

package/scanner/png-regions.mjs

@@ -0,0 +1,53 @@
+/** Single-image visual segmentation only. Never reads target pixels or performs comparison. */
+export async function detectPNGRegions(page, dataURL, lines) {
+  return page.evaluate(async ({ dataURL, lines }) => {
+    const image = new Image(); image.src = dataURL; await image.decode();
+    const ratio = Math.min(1, 512 / image.width, 2048 / image.height);
+    const width = Math.max(1, Math.round(image.width * ratio)), height = Math.max(1, Math.round(image.height * ratio));
+    const canvas = document.createElement('canvas'); canvas.width = width; canvas.height = height;
+    const context = canvas.getContext('2d', { willReadFrequently: true }); context.fillStyle = 'white'; context.fillRect(0, 0, width, height); context.drawImage(image, 0, 0, width, height);
+    const pixels = context.getImageData(0, 0, width, height).data;
+    const colors = new Uint16Array(width * height);
+    for (let i = 0; i < colors.length; i++) colors[i] = (Math.round(pixels[i * 4] / 32) << 8) | (Math.round(pixels[i * 4 + 1] / 32) << 4) | Math.round(pixels[i * 4 + 2] / 32);
+    const seen = new Uint8Array(colors.length), queue = new Int32Array(colors.length), regions = [];
+    for (let start = 0; start < colors.length; start++) {
+      if (seen[start]) continue;
+      let head = 0, tail = 1, left = width, top = height, right = 0, bottom = 0;
+      queue[0] = start; seen[start] = 1;
+      const value = colors[start];
+      while (head < tail) {
+        const index = queue[head++], x = index % width, y = Math.floor(index / width);
+        left = Math.min(left, x); top = Math.min(top, y); right = Math.max(right, x + 1); bottom = Math.max(bottom, y + 1);
+        for (const next of [x > 0 ? index - 1 : -1, x + 1 < width ? index + 1 : -1, y > 0 ? index - width : -1, y + 1 < height ? index + width : -1]) {
+          if (next >= 0 && !seen[next] && colors[next] === value) { seen[next] = 1; queue[tail++] = next; }
+        }
+      }
+      const w = right - left, h = bottom - top, area = w * h, coverage = tail / area;
+      if (w / ratio < 28 || h / ratio < 18 || area > width * height * 0.92 || coverage < 0.35) continue;
+      const bounds = { x: left / ratio, y: top / ratio, width: Math.min(image.width - left / ratio, w / ratio), height: Math.min(image.height - top / ratio, h / ratio) };
+      const containsText = lines.some(line => line.bounds.x + line.bounds.width / 2 >= bounds.x && line.bounds.x + line.bounds.width / 2 <= bounds.x + bounds.width && line.bounds.y + line.bounds.height / 2 >= bounds.y && line.bounds.y + line.bounds.height / 2 <= bounds.y + bounds.height);
+      regions.push({ bounds, kind: containsText ? 'surface' : 'image', confidence: containsText ? 0.55 : 0.35, method: 'quantized connected flat-color region; image/surface identity is heuristic' });
+    }
+    // Texture regions identify possible photos/illustrations even without flat backgrounds.
+    const tile = 12, cols = Math.ceil(width / tile), rows = Math.ceil(height / tile), busy = new Uint8Array(cols * rows);
+    for (let ty = 0; ty < rows; ty++) for (let tx = 0; tx < cols; tx++) {
+      const cx = (tx + 0.5) * tile / ratio, cy = (ty + 0.5) * tile / ratio;
+      if (lines.some(line => cx >= line.bounds.x - tile / ratio && cx <= line.bounds.x + line.bounds.width + tile / ratio && cy >= line.bounds.y - tile / ratio && cy <= line.bounds.y + line.bounds.height + tile / ratio)) continue;
+      const palette = new Set();
+      for (let y = ty * tile; y < Math.min(height, (ty + 1) * tile); y += 2) for (let x = tx * tile; x < Math.min(width, (tx + 1) * tile); x += 2) palette.add(colors[y * width + x]);
+      if (palette.size >= 7) busy[ty * cols + tx] = 1;
+    }
+    for (let start = 0; start < busy.length; start++) {
+      if (!busy[start]) continue;
+      const stack = [start]; busy[start] = 0; let minX = cols, maxX = 0, minY = rows, maxY = 0, count = 0;
+      while (stack.length) {
+        const i = stack.pop(), x = i % cols, y = Math.floor(i / cols); count++;
+        minX = Math.min(minX, x); maxX = Math.max(maxX, x + 1); minY = Math.min(minY, y); maxY = Math.max(maxY, y + 1);
+        for (const next of [x > 0 ? i - 1 : -1, x + 1 < cols ? i + 1 : -1, y > 0 ? i - cols : -1, y + 1 < rows ? i + cols : -1]) if (next >= 0 && busy[next]) { busy[next] = 0; stack.push(next); }
+      }
+      if (count < 6 || (maxX - minX) * tile / ratio < 48 || (maxY - minY) * tile / ratio < 36) continue;
+      regions.push({ bounds: { x: minX * tile / ratio, y: minY * tile / ratio, width: Math.min(image.width - minX * tile / ratio, (maxX - minX) * tile / ratio), height: Math.min(image.height - minY * tile / ratio, (maxY - minY) * tile / ratio) }, kind: 'image', confidence: 0.4, method: 'connected texture tiles excluding OCR text; possible illustration/photo' });
+    }
+    return regions.sort((a, b) => b.bounds.width * b.bounds.height - a.bounds.width * a.bounds.height).slice(0, 256);
+  }, { dataURL, lines });
+}

package/scanner/png-snapshot.mjs

@@ -0,0 +1,192 @@
+// Node-only PNG observation adapter. It never consumes target DOM or target pixels.
+import { readFile, stat, mkdtemp, writeFile, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { chromium } from 'playwright';
+import { normalizeUISnapshot } from 'shivax';
+import { localOCR } from './ocr/local.mjs';
+import { detectPNGRegions } from './png-regions.mjs';
+
+export const MAX_PNG_BYTES = 16 * 1024 * 1024;
+const MAX_PIXELS = 32 * 1024 * 1024;
+export function validatePNGBaseline(source, { allowPath = true } = {}) {
+  if (!source || source.type !== 'png' || Object.keys(source).some(key => !['type', 'path', 'data', 'viewport', 'fullPage', 'scroll'].includes(key))) throw new TypeError('Invalid PNG baseline');
+  if ((source.path !== undefined && typeof source.path !== 'string') || (source.data !== undefined && typeof source.data !== 'string')) throw new TypeError('PNG path/data must be strings');
+  if ((typeof source.path === 'string') === (typeof source.data === 'string') || (source.path !== undefined && (!allowPath || !source.path.trim()))) throw new TypeError('PNG requires exactly one local path or base64 data; local paths are not accepted over HTTP');
+  const v = source.viewport;
+  if (!v || Object.keys(v).some(key => !['width', 'height', 'devicePixelRatio'].includes(key)) || ![v.width, v.height].every(n => Number.isInteger(n) && n > 0 && n <= 16384) || !Number.isFinite(v.devicePixelRatio) || v.devicePixelRatio < 0.25 || v.devicePixelRatio > 8) throw new TypeError('PNG viewport width, height and devicePixelRatio metadata are required');
+  if (source.fullPage !== undefined && typeof source.fullPage !== 'boolean') throw new TypeError('PNG fullPage must be boolean');
+  if (source.scroll !== undefined && (!source.scroll || Object.keys(source.scroll).some(key => !['x', 'y'].includes(key)) || ![source.scroll.x, source.scroll.y].every(n => Number.isFinite(n) && n >= 0 && n <= 1000000))) throw new TypeError('Invalid PNG scroll offset');
+  if (source.fullPage && source.scroll && (source.scroll.x || source.scroll.y)) throw new TypeError('Full-page PNG must use a document origin at zero');
+  if (source.data !== undefined && source.data.length > MAX_PNG_BYTES * 4 / 3 + 32) throw new RangeError('PNG data exceeds byte limit');
+}
+export function pngDimensions(bytes) {
+  if (bytes.length < 24 || !bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])) || bytes.toString('ascii', 12, 16) !== 'IHDR') throw new TypeError('A PNG image is required');
+  const width = bytes.readUInt32BE(16), height = bytes.readUInt32BE(20);
+  if (!width || !height || width * height > MAX_PIXELS) throw new RangeError('PNG exceeds image dimension limit');
+  return { width, height };
+}
+const area = box => box.width * box.height;
+const union = boxes => { const x = Math.min(...boxes.map(b => b.x)), y = Math.min(...boxes.map(b => b.y)); return { x, y, width: Math.max(...boxes.map(b => b.x + b.width)) - x, height: Math.max(...boxes.map(b => b.y + b.height)) - y }; };
+const contains = (box, other) => other.x >= box.x - 2 && other.y >= box.y - 2 && other.x + other.width <= box.x + box.width + 2 && other.y + other.height <= box.y + box.height + 2;
+const centerInside = (box, other) => other.x + other.width / 2 >= box.x && other.x + other.width / 2 <= box.x + box.width && other.y + other.height / 2 >= box.y && other.y + other.height / 2 <= box.y + box.height;
+const evidence = (kind, method) => ({ sourceType: 'png', kind, method });
+const estimate = (value, method, quality) => ({ status: 'known', value, provenance: evidence('estimated', method), confidence: { score: Math.max(0, Math.min(0.9, quality)) } });
+const unknown = method => ({ status: 'unknown', provenance: evidence('unknown', method), confidence: { score: null } });
+const median = items => [...items].sort((a, b) => a - b)[Math.floor(items.length / 2)] ?? 1;
+function checkBox(box, width, height) {
+  return box && ['x', 'y', 'width', 'height'].every(key => Number.isFinite(box[key])) && box.x >= 0 && box.y >= 0 && box.width > 0 && box.height > 0 && box.x + box.width <= width + 2 && box.y + box.height <= height + 2;
+}
+
+// OCR boxes may straddle an image edge by a fraction of a pixel (Apple Vision).
+// Allow only the same two-image-pixel tolerance used for other observed boxes,
+// then intersect with the actual image. Larger/malformed observations still fail.
+function ocrBox(box, width, height) {
+  if (!box || !['x', 'y', 'width', 'height'].every(key => Number.isFinite(box[key])) || box.width <= 0 || box.height <= 0 || box.x < -2 || box.y < -2 || box.x + box.width > width + 2 || box.y + box.height > height + 2) return undefined;
+  const x = Math.max(0, box.x), y = Math.max(0, box.y);
+  const right = Math.min(width, box.x + box.width), bottom = Math.min(height, box.y + box.height);
+  if (right <= x || bottom <= y) return undefined;
+  return { x, y, width: right - x, height: bottom - y };
+}
+
+/** Convert OCR and single-image observations; grouping is never a second cross-snapshot matcher. */
+export function pngObservationsToSnapshot(observations, { source, scope, width, height, maxNodes = 2000, includeText = true } = {}) {
+  validatePNGBaseline(source);
+  if (!scope || !['company', 'personal'].includes(scope.kind) || typeof scope.id !== 'string' || !scope.id.trim()) throw new TypeError('Explicit PNG workspace scope is required');
+  if (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > 10000 || typeof includeText !== 'boolean') throw new TypeError('Invalid PNG capture limits');
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || width * height > MAX_PIXELS) throw new TypeError('Invalid PNG observation dimensions');
+  const dpr = source.viewport.devicePixelRatio;
+  if ((source.fullPage ? width < Math.round(source.viewport.width * dpr) - 1 : Math.abs(width - Math.round(source.viewport.width * dpr)) > 1) || (!source.fullPage && Math.abs(height - Math.round(source.viewport.height * dpr)) > 1) || (source.fullPage && height < Math.round(source.viewport.height * dpr) - 1)) throw new TypeError('PNG dimensions disagree with explicit screenshot viewport metadata');
+  if (!observations || typeof observations.provider !== 'string' || !observations.provider.trim() || observations.provider.length > 256 || !Array.isArray(observations.lines) || observations.lines.length > 1000 || !Array.isArray(observations.regions ?? []) || (observations.regions?.length ?? 0) > 256) throw new TypeError('Invalid or excessive PNG observations');
+  const diagnostics = [], nodes = [], relationships = [], details = {};
+  const lines = observations.lines.map((line, index) => {
+    if (typeof line?.text !== 'string' || line.text.length > 10000 || !Number.isFinite(line.confidence) || line.confidence < 0 || line.confidence > 1) throw new TypeError(`Invalid OCR line observation ${index}: text or confidence is malformed`);
+    const bounds = ocrBox(line.bounds, width, height);
+    if (!bounds) throw new TypeError(`Invalid OCR line observation ${index}: bounds are outside the PNG or malformed`);
+    if (['x', 'y', 'width', 'height'].some(key => Math.abs(bounds[key] - line.bounds[key]) > 1e-9)) diagnostics.push({ code: 'ocr-bounds-clipped', lineIndex: index, originalBounds: { ...line.bounds }, bounds: { ...bounds }, message: 'OCR bounds within two image pixels of an edge were clipped to the image; coordinates remain estimated.' });
+    return { ...line, bounds, text: line.text.trim(), index };
+  }).filter(line => line.text && line.confidence >= 0.25).sort((a, b) => a.bounds.y - b.bounds.y || a.bounds.x - b.bounds.x);
+  const typical = median(lines.map(line => line.bounds.height));
+  const offset = { x: (source.scroll?.x ?? 0) * dpr, y: (source.scroll?.y ?? 0) * dpr };
+  const observed = [];
+  const add = (role, box, quality, method, extra = {}) => {
+    const id = `p${observed.length}`;
+    observed.push({ id, role, box, quality: Math.min(quality, 0.85), method, ...extra }); return id;
+  };
+  add('document', { x: 0, y: 0, width, height }, 0.5, 'Screenshot extent is not an exact DOM document box', { kind: 'document' });
+  const consumed = new Set();
+  for (const region of observations.regions ?? []) {
+    if (!checkBox(region.bounds, width, height) || !Number.isFinite(region.confidence) || region.confidence < 0 || region.confidence > 1 || !['surface', 'image'].includes(region.kind) || typeof region.method !== 'string' || region.method.length > 2048) throw new TypeError('Invalid visual region observation');
+    const inside = lines.filter(line => centerInside(region.bounds, line.bounds));
+    const button = inside.length > 0 && inside.length <= 2 && inside.map(l => l.text).join(' ').length < 80 && region.bounds.height <= typical * 4 && region.bounds.width < width * 0.65 && region.bounds.width >= Math.max(...inside.map(l => l.bounds.width)) * 1.15;
+    if (button && inside.every(line => !consumed.has(line.index))) {
+      inside.forEach(line => consumed.add(line.index));
+      add('button', region.bounds, Math.min(region.confidence, ...inside.map(l => l.confidence), 0.55), `${region.method}; enclosed short OCR label suggests a button`, { text: inside.map(l => l.text).join(' '), kind: 'button', ocrLines: inside });
+    } else if (inside.length >= 2 || (inside.length && region.bounds.height > typical * 4)) {
+      add('generic', region.bounds, Math.min(region.confidence, 0.5), `${region.method}; containing text suggests a visual section`, { kind: 'section' });
+    } else if (!inside.length && !observed.some(item => item.kind === 'image' && contains(item.box, region.bounds))) add('img', region.bounds, Math.min(region.confidence, 0.4), `${region.method}; image identity cannot be proven from pixels alone`, { kind: 'image' });
+  }
+  const paragraphs = [];
+  for (const line of lines.filter(line => !consumed.has(line.index))) {
+    const previous = paragraphs.at(-1);
+    if (previous && line.bounds.height < typical * 1.4 && previous.every(l => l.bounds.height < typical * 1.4) && Math.abs(line.bounds.x - previous[0].bounds.x) < typical * 0.6 && line.bounds.y >= previous.at(-1).bounds.y + previous.at(-1).bounds.height && line.bounds.y - (previous.at(-1).bounds.y + previous.at(-1).bounds.height) < typical * 0.8) previous.push(line);
+    else paragraphs.push([line]);
+  }
+  for (const paragraph of paragraphs) {
+    const box = union(paragraph.map(line => line.bounds));
+    const heading = paragraph[0].bounds.height >= typical * 1.4;
+    add(heading ? 'heading' : 'paragraph', box, Math.min(...paragraph.map(l => l.confidence), heading ? 0.65 : 0.75), `${observations.provider}; OCR glyph extent; ${heading ? 'larger relative glyph height suggests heading' : 'adjacent similar OCR lines suggest paragraph'}`, { text: paragraph.map(l => l.text).join(' '), kind: heading ? 'heading' : 'paragraph', ocrLines: paragraph });
+  }
+  // Visual rows/columns are evidence about arrangement, not assertions of CSS flex/grid.
+  const leaves = observed.filter(item => ['heading', 'paragraph', 'button', 'image'].includes(item.kind));
+  for (const [axis, kind] of [['y', 'row'], ['x', 'column']]) {
+    const groups = [];
+    for (const item of [...leaves].sort((a, b) => a.box[axis] - b.box[axis])) {
+      let group = groups.find(items => Math.abs(items[0].box[axis] - item.box[axis]) <= typical * 0.7);
+      if (!group) { group = []; groups.push(group); } group.push(item);
+    }
+    for (const group of groups.filter(items => items.length > 1)) {
+      const box = union(group.map(item => item.box));
+      if (observed.some(item => contains(item.box, box) && contains(box, item.box))) continue;
+      add('generic', box, 0.45, `Aligned observed ${axis === 'x' ? 'left edges' : 'top edges'} suggest a ${kind}; CSS implementation unknown`, { kind, members: group.map(item => item.id) });
+    }
+  }
+  if (observed.length > maxNodes) throw new RangeError('PNG node limit exceeded');
+  for (const item of observed) {
+    const bounds = { ...item.box, x: item.box.x + offset.x, y: item.box.y + offset.y };
+    const node = { id: item.id, role: item.role, bounds: estimate(bounds, item.method, item.quality) };
+    if (item.text !== undefined && includeText) node.text = item.text.slice(0, 2048);
+    if (item.text !== undefined) node.typography = Object.fromEntries(['fontFamily', 'fontWeight', 'fontSize', 'lineHeight', 'letterSpacing', 'color'].map(key => [key, unknown(`PNG OCR does not establish reliable CSS ${key}`)]));
+    node.layout = Object.fromEntries(['display', 'marginTop', 'marginRight', 'marginBottom', 'marginLeft'].map(key => [key, unknown('Visual grouping/whitespace does not establish CSS layout or margin values')]));
+    nodes.push(node);
+    details[item.id] = { kind: item.kind, role: estimate(item.role, item.method, item.quality), imageBounds: estimate(item.box, item.method, item.quality), ...(item.members ? { members: item.members } : {}), ...(item.ocrLines ? { ocr: item.ocrLines.map(line => ({ ...(includeText ? { text: line.text } : {}), bounds: line.bounds, providerConfidence: line.confidence, confidence: { score: Math.min(0.9, line.confidence) }, provenance: evidence('estimated', `${observations.provider} OCR text localization`) })) } : {}) };
+    if (item.id !== 'p0') {
+      const parent = observed.filter(candidate => candidate.id !== item.id && ['document', 'section', 'row', 'column'].includes(candidate.kind) && contains(candidate.box, item.box) && area(candidate.box) > area(item.box) * 1.05).sort((a, b) => area(a.box) - area(b.box))[0] ?? observed[0];
+      relationships.push({ from: parent.id, to: item.id, type: 'parent-child', provenance: evidence('estimated', 'Visual containment, not observed DOM ancestry'), confidence: { score: Math.min(parent.quality, item.quality, 0.5) } });
+    }
+  }
+  for (const heading of observed.filter(item => item.kind === 'heading')) {
+    const description = observed.filter(item => item.kind === 'paragraph' && item.box.y >= heading.box.y + heading.box.height && item.box.y - heading.box.y < typical * 7 && Math.abs(item.box.x - heading.box.x) < typical * 2).sort((a, b) => a.box.y - b.box.y)[0];
+    if (description) relationships.push({ from: heading.id, to: description.id, type: 'heading-description', provenance: evidence('estimated', 'Spatial heading and nearby paragraph association'), confidence: { score: 0.4 } });
+  }
+  for (const image of observed.filter(item => item.kind === 'image')) {
+    const text = observed.filter(item => ['heading', 'paragraph'].includes(item.kind) && Math.abs(item.box.y - image.box.y) < typical * 8).sort((a, b) => Math.abs(a.box.y - image.box.y) - Math.abs(b.box.y - image.box.y))[0];
+    if (text) relationships.push({ from: image.id, to: text.id, type: 'image-content', provenance: evidence('estimated', 'Nearest nearby text suggests image/content association'), confidence: { score: 0.3 } });
+  }
+  diagnostics.push({ code: 'image-inference', message: 'All PNG regions, roles and relationships are estimates and need review; OCR confidence is not a calibrated probability.' });
+  if (!lines.length) diagnostics.push({ code: 'no-text', message: 'OCR found no usable text. Text-free regions may remain unmatched; no text was invented.' });
+  const snapshot = normalizeUISnapshot({ version: 1, sourceType: 'png', scope: { kind: scope.kind, id: scope.id }, viewport: { ...source.viewport }, coordinates: { unit: 'image-px', unitsPerCssPixel: dpr, origin: 'document' }, nodes, relationships });
+  return { snapshot, metadata: { provider: observations.provider, image: { width, height, viewport: { ...source.viewport }, fullPage: source.fullPage ?? false, scroll: { ...(source.scroll ?? { x: 0, y: 0 }) } }, nodes: details, diagnostics, reviewStatus: 'needs_review' } };
+}
+
+export async function capturePNGBaseline(source, { scope, signal, timeout = 30000, pngOcr = localOCR, maxNodes = 2000, includeText = true, screenshotPath, onEvent } = {}) {
+  validatePNGBaseline(source);
+  if (!Number.isInteger(timeout) || timeout <= 0 || typeof pngOcr !== 'function') throw new TypeError('Invalid PNG OCR configuration');
+  signal?.throwIfAborted();
+  const combined = AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(timeout)]);
+  let bytes;
+  if (source.path) {
+    const info = await stat(source.path);
+    if (!info.isFile()) throw new TypeError('PNG path must be a regular file');
+    if (info.size > MAX_PNG_BYTES) throw new RangeError('PNG exceeds byte limit');
+    bytes = await readFile(source.path, { signal: combined });
+  } else {
+    const text = source.data.replace(/^data:image\/png;base64,/, '');
+    if (!text.length || (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text))) throw new TypeError('PNG data must be valid base64');
+    bytes = Buffer.from(text, 'base64');
+  }
+  if (bytes.length > MAX_PNG_BYTES) throw new RangeError('PNG exceeds byte limit');
+  const { width, height } = pngDimensions(bytes);
+  // Check metadata before invoking OCR or launching a browser.
+  pngObservationsToSnapshot({ provider: 'validation', lines: [] }, { source, scope, width, height, maxNodes, includeText });
+  combined.throwIfAborted();
+  const temporary = await mkdtemp(path.join(os.tmpdir(), 'inspectra-png-'));
+  let browser, abort;
+  try {
+    onEvent?.({ type: 'state', state: 'loading', side: 'baseline' });
+    const file = path.join(temporary, 'input.png'); await writeFile(file, bytes, { mode: 0o600, signal: combined });
+    browser = await chromium.launch();
+    abort = () => { void browser.close().catch(() => {}); }; combined.addEventListener('abort', abort, { once: true });
+    combined.throwIfAborted();
+    const context = await browser.newContext({ offline: true }); const page = await context.newPage();
+    const dataURL = `data:image/png;base64,${bytes.toString('base64')}`;
+    // Decode independently of OCR; malformed PNG payloads are explicit errors.
+    const decoded = await page.evaluate(async data => { const image = new Image(); image.src = data; await image.decode(); return { width: image.naturalWidth, height: image.naturalHeight }; }, dataURL);
+    if (decoded.width !== width || decoded.height !== height) throw new TypeError('PNG decoded orientation/dimensions disagree with screenshot metadata');
+    onEvent?.({ type: 'state', state: 'extracting', side: 'baseline' });
+    let stop;
+    const cancelled = new Promise((_, reject) => { stop = () => reject(combined.reason); combined.addEventListener('abort', stop, { once: true }); if (combined.aborted) stop(); });
+    let observations;
+    try { observations = await Promise.race([pngOcr({ path: file, width, height, signal: combined, timeout, scope: { ...scope } }), cancelled]); }
+    finally { combined.removeEventListener('abort', stop); }
+    // Validate provider output before it enters browser evaluation.
+    pngObservationsToSnapshot(observations, { source, scope, width, height, maxNodes, includeText });
+    const regions = await detectPNGRegions(page, dataURL, observations.lines.map(line => ({ ...line, bounds: ocrBox(line.bounds, width, height) })));
+    const capture = pngObservationsToSnapshot({ ...observations, regions: [...(observations.regions ?? []), ...regions].slice(0, 256) }, { source, scope, width, height, maxNodes, includeText });
+    onEvent?.({ type: 'snapshot', side: 'baseline', nodes: capture.snapshot.nodes.length });
+    combined.throwIfAborted();
+    if (screenshotPath) await writeFile(screenshotPath, bytes, { mode: 0o600, signal: combined });
+    return capture;
+  } catch (error) { combined.throwIfAborted(); throw error; }
+  finally { if (abort) combined.removeEventListener('abort', abort); try { await browser?.close(); } finally { await rm(temporary, { recursive: true, force: true }); } }
+}

package/scripts/check-build.mjs

@@ -0,0 +1,12 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+for (const file of ['node/index.mjs', 'node/dev-config.mjs', 'node/runner.mjs', 'node/job-manager.mjs', 'node/analysis-worker.mjs', 'client/index.mjs', 'bin/inspectra.mjs', 'scanner/browser-snapshot.js', 'scanner/accessibility.mjs', 'scanner/figma-snapshot.mjs', 'scanner/png-snapshot.mjs', 'scanner/png-regions.mjs', 'scanner/ocr/local.mjs', 'node/png-highlights.mjs']) {
+  execFileSync(process.execPath, ['--check', file], { stdio: 'inherit' });
+}
+await import('../node/index.mjs');
+await import('../client/index.mjs');
+// Client runtime must remain dependency-free; shared Shivax types are type-only.
+if (/\b(?:import|require)\s*(?:\(|[{*'"(])/.test(readFileSync(new URL('../client/index.mjs', import.meta.url), 'utf8'))) {
+  throw new Error('Browser client must not import Node scanner dependencies');
+}
+console.log('Package entry points verified');