@milpa/comal 0.2.2 → 0.2.3

package/src/visual/operations.mjs

@@ -0,0 +1,211 @@
+// House operations for visual acceptance. Agent operations inspect, draft and
+// verify; only human operations (audience 'human', no tool permission, cli/tui
+// surfaces) can approve references, confirm criteria or revoke them.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { comalEnvironment } from '../compat.mjs';
+import { IMAGE_LIMIT } from '../vision.mjs';
+import { launchChrome, defaultChromeBinary } from './chrome.mjs';
+import { freezePage } from './fixtures.mjs';
+import { openLedger, defaultKeyDir } from './ledger.mjs';
+import { normalizeCriterion } from './measure.mjs';
+import { componentInventory, listComponents, loadComponent, pairKey, readReference, referencePaths, setupDigest, setupManifest, VISUAL_DIR } from './registry.mjs';
+import { verifyComponent, writeReferenceDraft, captureMaquette } from './verify.mjs';
+import { composite } from './report.mjs';
+
+const sha256 = value => createHash('sha256').update(value).digest('hex');
+const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object'
+  ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])])) : value;
+const ID = { type: 'string', pattern: '^[a-z0-9][a-z0-9-]{0,62}$' };
+const DIGEST = { type: 'string', pattern: '^[a-f0-9]{12,64}$' };
+const schema = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+const READ = { workspace: 'read', external: 'none', process: 'none', authority: 'none' };
+const BROWSER = { workspace: 'write', external: 'read', process: 'spawn', authority: 'none' };
+const HUMAN = { workspace: 'none', external: 'none', process: 'none', authority: 'visual_acceptance' };
+const fail = (message, code = 'VISUAL_OPERATION_REFUSED') => Object.assign(new Error(message), { code });
+
+function imageBlock(bytes) {
+  if (!bytes || comalEnvironment().COMAL_VISION === 'off' || bytes.length > IMAGE_LIMIT) return null;
+  return { type: 'image', mimeType: 'image/png', data: Buffer.from(bytes).toString('base64') };
+}
+const publicResult = ({ captures, ...rest }) => rest;
+function requireHuman(options) { if (options.actor?.kind !== 'human') throw fail('Sólo el humano puede aprobar, confirmar o revocar en la aceptación visual; usa /visual.', 'HOUSE_REFUSED'); }
+
+const short = digest => digest ? digest.slice(0, 12) : null;
+const criterionDigest = criterion => sha256(JSON.stringify(canonical(criterion)));
+// The human approves what status shows: digest prefixes bind each approval to those exact bytes.
+function digestMatches(prefix, digest) { return typeof prefix === 'string' && /^[a-f0-9]{12,64}$/.test(prefix) && typeof digest === 'string' && digest.startsWith(prefix); }
+// Files added, removed or changed between the approved setup manifest and now.
+function setupChanges(approved, current) {
+  if (!approved?.fixtures) return null;
+  const changes = [];
+  if (approved.spec_sha256 !== current.spec_sha256) changes.push('spec');
+  for (const id of new Set([...Object.keys(approved.fixtures), ...Object.keys(current.fixtures)])) {
+    const before = approved.fixtures[id] || {}, after = current.fixtures[id] || {};
+    if (!approved.fixtures[id]) { changes.push(`fixture ${id}: nuevo`); continue; }
+    if (!current.fixtures[id]) { changes.push(`fixture ${id}: eliminado`); continue; }
+    for (const file of new Set([...Object.keys(before), ...Object.keys(after)])) if (before[file] !== after[file]) changes.push(`fixture ${id}/${file}: ${!before[file] ? 'nuevo' : !after[file] ? 'eliminado' : 'modificado'}`);
+  }
+  return changes.slice(0, 50);
+}
+
+async function status(cwd, stateDir, keyDir, component) {
+  if (!component) {
+    const ids = await listComponents(cwd);
+    return { components: ids, hint: ids.length ? 'VisualStatus {component} muestra pares, referencias y criterios.' : `No hay componentes: crea ${VISUAL_DIR}/components/<id>.json (ver docs/visual-acceptance.md).` };
+  }
+  const inventory = await componentInventory(cwd, component), effective = await (await openLedger({ stateDir, keyDir })).effective(component);
+  const setup = await setupDigest(cwd, inventory.spec), manifest = await setupManifest(cwd, inventory.spec);
+  const setupState = !effective.setup ? 'not_approved' : effective.setup.digest === setup ? 'approved' : 'changed_after_approval';
+  const pairs = inventory.pairs.map(pair => {
+    const approval = effective.references[pair.key];
+    const state = !pair.reference ? 'missing' : pair.reference.error ? 'invalid' : !approval ? 'draft' : approval.digest === pair.reference.digest ? 'approved' : 'changed_after_approval';
+    return { key: pair.key, fixture: pair.fixture, state: pair.state, kind: pair.kind, mandatory: pair.mandatory, reference: state, mode: pair.reference?.mode ?? null,
+      ...(pair.reference?.meta ? { tolerance: pair.reference.meta.tolerance, file: pair.reference.file, digest: short(pair.reference.digest) } : {}),
+      ...(pair.reference?.error ? { error: pair.reference.error } : {}),
+      ...(state === 'draft' || state === 'changed_after_approval' ? { human_action: `/visual approve ${component} ${pair.fixture} ${pair.state} ${short(pair.reference.digest)}` } : {}) };
+  });
+  const confirmed = effective.criteria.map(c => c.id);
+  return { component, extension: inventory.spec.extension, root: inventory.spec.root,
+    setup: { state: setupState, digest: short(setup), fixtures: inventory.spec.fixtures.map(f => ({ id: f.id, kind: f.kind, mandatory: f.mandatory, ...(f.url ? { url: f.url } : { files: Object.keys(manifest.fixtures[f.id] || {}).length }) })),
+      ...(setupState === 'changed_after_approval' ? { changes_since_approval: setupChanges(effective.setup.payload?.manifest, manifest) } : {}),
+      ...(setupState !== 'approved' ? { human_action: `/visual approve-setup ${component} ${short(setup)}` } : {}) },
+    pairs,
+    criteria: { confirmed, pending: inventory.proposedCriteria.filter(c => !confirmed.includes(c.id)).map(c => ({ ...c, digest: short(criterionDigest(c)), human_action: `/visual confirm ${component} ${c.id} ${short(criterionDigest(c))}` })), proposal_errors: inventory.proposalErrors },
+    ledger_invalid_entries: effective.invalid_entries };
+}
+
+export function visualOperations({ cwd, stateDir, keyDir = defaultKeyDir(), judge, chromeBinary = defaultChromeBinary() }) {
+  const ledger = () => openLedger({ stateDir, keyDir });
+  return [
+    { name: 'VisualStatus', description: 'Visual acceptance registry: components under visual/components, their fixture x state pairs, which references are approved by the human, confirmed vs pending criteria. Read only.',
+      input_schema: schema({ component: ID }, []), effects: READ,
+      run: async input => JSON.stringify(await status(cwd, stateDir, keyDir, input.component)) },
+    { name: 'VisualBoard', description: 'Human view of the visual acceptance registry (/visual status).', audience: 'human', surfaces: ['cli', 'tui'], permission: null, effects: READ,
+      input_schema: schema({ component: ID }, []), run: async (input, options) => { requireHuman(options); return JSON.stringify(await status(cwd, stateDir, keyDir, input.component)); } },
+    { name: 'VisualCapture', description: 'Inspection only: the house loads the current extension build in a fresh Chrome profile, reaches one fixture/state of a component and returns the capture (pixels reach you as an image) plus measurements of proposed criteria. Never approves anything.',
+      input_schema: schema({ component: ID, fixture: ID, state: ID }, ['component', 'fixture', 'state']), effects: BROWSER,
+      run: async (input, options) => {
+        const key = pairKey(input.fixture, input.state);
+        const result = await verifyComponent({ cwd, stateDir, keyDir, component: input.component, mode: 'inspection', pairs: [key], signal: options.signal, chromeBinary });
+        if (!result.pairs.length) throw fail(`El componente ${input.component} no tiene el par ${key}.`);
+        const shot = result.captures.get(key), reference = await readReference(cwd, input.component, key);
+        const image = imageBlock(reference?.png ? composite([reference.png, shot.capture]) : shot.capture);
+        return JSON.stringify({ ...publicResult(result), image_layout: reference?.png ? 'reference | capture' : 'capture', ...(image ? { image } : {}), scope: 'inspection_not_acceptance' });
+      } },
+    { name: 'VisualVerify', description: 'Visual ACCEPTANCE of a component, run by the house on the current extension build: every fixture x state pair is captured in a fresh profile and compared against the human-approved reference (pixels in exact mode, an independent vision judge in mockup mode) plus confirmed criteria. status passed|failed|blocked. Use it as the WorkPlan check of UI tasks: {operation:"VisualVerify",arguments:{component},assertions:[{kind:"json_equals",pointer:"/status",value:"passed"}]}.',
+      input_schema: schema({ component: ID }, ['component']), effects: BROWSER,
+      run: async (input, options) => {
+        const result = await verifyComponent({ cwd, stateDir, keyDir, component: input.component, mode: 'acceptance', judge, signal: options.signal, chromeBinary });
+        for (const file of result.observed_files) options.observe?.({ kind: 'file_read', file_path: file.file_path, sha256: file.sha256 });
+        if (result.status === 'passed') await (await ledger()).recordAccepted({ component: input.component, build_digest: result.build_digest, setup_digest: result.setup_digest,
+          references_digest: result.references_digest, criteria_digest: result.criteria_digest, run_id: result.run_id, session_id: options.sessionId ?? null, invocation_id: options.invocation_id ?? null, at: new Date().toISOString() });
+        for (const pair of result.pairs) {
+          const refs = referencePaths(cwd, input.component, pair.key);
+          for (const file of [refs.png, refs.meta]) { const bytes = await fs.readFile(file).catch(() => null); if (bytes) options.observe?.({ kind: 'file_read', file_path: path.relative(cwd, file), sha256: sha256(bytes) }); }
+        }
+        const ordered = [...result.pairs].sort((a, b) => (a.verdict === 'pass') - (b.verdict === 'pass') || b.mandatory - a.mandatory);
+        const images = [];
+        for (const pair of ordered) {
+          if (images.length >= 2 || !pair.images.composite) continue;
+          const block = imageBlock(await fs.readFile(path.join(cwd, pair.images.composite)));
+          if (block) images.push({ pair: pair.key, layout: pair.images.diff ? 'reference | capture | diff' : pair.images.reference ? 'reference | capture' : 'capture', image: block });
+        }
+        const next = result.status === 'passed' ? 'Aceptación visual aprobada para este build. Entrega el reporte al humano para su aceptación final.'
+          : result.status === 'failed' ? 'Corrige la extensión según los aspectos que fallan y vuelve a correr VisualVerify. No edites referencias aprobadas.'
+          : 'Bloqueado: resuelve el motivo (referencias o criterios sin aprobar, entorno distinto, revisor sin visión). El humano aprueba con /visual.';
+        return JSON.stringify({ ...publicResult(result), images, next_action: next });
+      } },
+    { name: 'VisualFreeze', description: 'Record a live https page as a frozen fixture under visual/fixtures/<fixture> (DOM without scripts, CSS and resources) so it replays offline at its own origin. Does not overwrite an existing fixture.',
+      input_schema: schema({ url: { type: 'string', minLength: 9, maxLength: 2000, pattern: '^https://' }, fixture: ID }, ['url', 'fixture']), effects: BROWSER,
+      run: async (input, options) => {
+        const dir = path.join(cwd, VISUAL_DIR, 'fixtures', input.fixture);
+        if (await fs.stat(dir).catch(() => null)) throw fail(`Ya existe ${path.relative(cwd, dir)}; elige otro id de fixture.`);
+        const session = await launchChrome({ binary: chromeBinary, viewport: { width: 1280, height: 800, deviceScaleFactor: 1 }, signal: options.signal });
+        try {
+          const fixture = await freezePage({ session, url: input.url, dir, id: input.fixture, signal: options.signal });
+          return JSON.stringify({ fixture: { ...fixture, dir: path.relative(cwd, dir) }, next_action: `Agrégalo al componente como {"id":"${input.fixture}","kind":"frozen"}.` });
+        } finally { await session.close(); }
+      } },
+    { name: 'VisualReferenceDraft', description: 'Propose a reference image for one fixture/state: source "capture" uses the current extension build, source "maquette" renders a static HTML maquette (inside the workspace) at the fixture origin without the extension. It is only a draft until the human approves it with /visual approve. The maquette replaces the whole page, so draw the page as it should look with the component open; files of the fixture are served at the same origin. Keep maquettes under visual/maquettes/<component>/<fixture>--<state>.html and pass that path as maquette (required with source "maquette"). mode "mockup" is judged by an independent visual reviewer (structure, colour, size, spacing, position); "exact" compares pixels with the reference.',
+      input_schema: schema({ component: ID, fixture: ID, state: ID, mode: { enum: ['exact', 'mockup'] }, source: { enum: ['capture', 'maquette'] }, maquette: { type: 'string', minLength: 1, maxLength: 1000 } }, ['component', 'fixture', 'state', 'mode', 'source']), effects: BROWSER,
+      run: async (input, options) => {
+        const key = pairKey(input.fixture, input.state), spec = await loadComponent(cwd, input.component);
+        if (!spec.states.some(s => s.id === input.state && s.fixtures.includes(input.fixture))) throw fail(`El componente ${input.component} no tiene el par ${key}.`);
+        let shot;
+        if (input.source === 'maquette') {
+          if (!input.maquette) throw fail('source maquette requiere maquette (ruta del HTML).');
+          shot = await captureMaquette({ cwd, stateDir, component: input.component, fixture: input.fixture, file: input.maquette, chromeBinary, signal: options.signal });
+        } else {
+          if (input.maquette) throw fail('maquette sólo aplica con source maquette.');
+          const result = await verifyComponent({ cwd, stateDir, keyDir, component: input.component, mode: 'inspection', pairs: [key], signal: options.signal, chromeBinary });
+          if (result.pairs[0]?.reason && /No se llegó|no está montado/.test(result.pairs[0].reason)) throw fail(`No se puede proponer la captura: ${result.pairs[0].reason}`);
+          shot = result.captures.get(key);
+        }
+        const written = await writeReferenceDraft({ cwd, component: input.component, fixture: input.fixture, state: input.state, mode: input.mode, png: shot.capture, fingerprint: shot.fingerprint, source: input.source });
+        for (const file of [written.png, written.meta]) options.observe?.({ kind: 'file_read', file_path: file, sha256: sha256(await fs.readFile(path.join(cwd, file))) });
+        const image = imageBlock(shot.capture);
+        return JSON.stringify({ draft: written, mode: input.mode, approved: false, ...(image ? { image } : {}), human_action: `/visual approve ${input.component} ${input.fixture} ${input.state} ${short(written.digest)}` });
+      } },
+    { name: 'VisualApproveSetup', description: 'Human approval of the component configuration (spec file and every local/frozen fixture) shown by /visual status.', audience: 'human', surfaces: ['cli', 'tui'], permission: null, effects: HUMAN,
+      input_schema: schema({ component: ID, digest: DIGEST }, ['component', 'digest']),
+      run: async (input, options) => {
+        requireHuman(options);
+        const spec = await loadComponent(cwd, input.component), digest = await setupDigest(cwd, spec), manifest = await setupManifest(cwd, spec);
+        if (!digestMatches(input.digest, digest)) throw fail(`La configuración de ${input.component} no coincide con el digest ${input.digest} (actual ${short(digest)}); revisa /visual status antes de aprobar.`);
+        const entry = await (await ledger()).append({ kind: 'setup', component: input.component, key: 'setup', digest, payload: { fixtures: spec.fixtures.map(f => ({ id: f.id, kind: f.kind, mandatory: f.mandatory })), states: spec.states.map(s => s.id), root: spec.root, extension: spec.extension, manifest },
+          approver: options.actor.id, session_id: options.sessionId, invocation_id: options.invocation_id });
+        return JSON.stringify({ approved_setup: { component: input.component, digest, at: entry.at } });
+      } },
+    { name: 'VisualApprove', description: 'Human approval of the current reference image of one fixture/state, bound to the digest shown by /visual status.', audience: 'human', surfaces: ['cli', 'tui'], permission: null, effects: HUMAN,
+      input_schema: schema({ component: ID, fixture: ID, state: ID, digest: DIGEST }, ['component', 'fixture', 'state', 'digest']),
+      run: async (input, options) => {
+        requireHuman(options);
+        await loadComponent(cwd, input.component);
+        const key = pairKey(input.fixture, input.state), reference = await readReference(cwd, input.component, key);
+        if (!reference) throw fail(`No existe la referencia ${path.relative(cwd, referencePaths(cwd, input.component, key).png)} con su .json.`);
+        if (reference.error) throw fail(`Referencia inválida: ${reference.error}`);
+        if (!digestMatches(input.digest, reference.digest)) throw fail(`La referencia ${key} cambió desde que la viste (digest actual ${short(reference.digest)}); revísala de nuevo antes de aprobar.`);
+        const entry = await (await ledger()).append({ kind: 'reference', component: input.component, key, digest: reference.digest,
+          payload: { mode: reference.mode, tolerance: reference.meta.tolerance, png_sha256: reference.png_sha256, meta_sha256: reference.meta_sha256, file: reference.file }, approver: options.actor.id, session_id: options.sessionId, invocation_id: options.invocation_id });
+        return JSON.stringify({ approved: { component: input.component, key, mode: reference.mode, tolerance: reference.meta.tolerance, file: reference.file, digest: reference.digest, at: entry.at } });
+      } },
+    { name: 'VisualConfirm', description: 'Human confirmation of one proposed criterion from visual/criteria/<component>.json, bound to the digest shown by /visual status; from now on it is a permanent criterion of that component.', audience: 'human', surfaces: ['cli', 'tui'], permission: null, effects: HUMAN,
+      input_schema: schema({ component: ID, criterion: { type: 'string', pattern: '^[a-z0-9][a-z0-9._-]{0,63}$' }, digest: DIGEST }, ['component', 'criterion', 'digest']),
+      run: async (input, options) => {
+        requireHuman(options);
+        const { proposedCriteria: criteria, proposalErrors: errors } = await componentInventory(cwd, input.component), found = criteria.find(c => c.id === input.criterion);
+        if (!found) throw fail(`No hay un criterio propuesto ${input.criterion} válido en ${VISUAL_DIR}/criteria/${input.component}.json.${errors.length ? ' Errores: ' + errors.join('; ') : ''}`);
+        const criterion = normalizeCriterion(found), digest = criterionDigest(criterion);
+        if (!digestMatches(input.digest, digest)) throw fail(`El criterio ${criterion.id} cambió desde que lo viste (digest actual ${short(digest)}); revísalo de nuevo antes de confirmar.`);
+        const entry = await (await ledger()).append({ kind: 'criterion', component: input.component, key: criterion.id, digest, payload: criterion,
+          approver: options.actor.id, session_id: options.sessionId, invocation_id: options.invocation_id });
+        return JSON.stringify({ confirmed: { component: input.component, criterion, at: entry.at } });
+      } },
+    { name: 'VisualRevoke', description: 'Human revocation of the approved configuration, an approved reference or a confirmed criterion of a component.', audience: 'human', surfaces: ['cli', 'tui'], permission: null, effects: HUMAN,
+      input_schema: schema({ component: ID, kind: { enum: ['setup', 'reference', 'criterion'] }, key: { type: 'string', minLength: 1, maxLength: 200 } }, ['component', 'kind', 'key']),
+      run: async (input, options) => {
+        requireHuman(options);
+        const effective = await (await ledger()).effective(input.component);
+        const present = input.kind === 'setup' ? (input.key === 'setup' ? effective.setup : null) : input.kind === 'reference' ? effective.references[input.key] : effective.criteria_records[input.key];
+        if (!present) throw fail(`No hay ${input.kind === 'setup' ? 'una configuración aprobada' : input.kind === 'reference' ? 'una referencia aprobada' : 'un criterio confirmado'} ${input.key} en ${input.component}.`);
+        const entry = await (await ledger()).append({ kind: 'revoke', component: input.component, key: `${input.kind}:${input.key}`, digest: present.digest, payload: {},
+          approver: options.actor.id, session_id: options.sessionId, invocation_id: options.invocation_id });
+        // Revoking the setup retires the component from the close guard's drift rule.
+        if (input.kind === 'setup') await (await ledger()).forgetAccepted(input.component);
+        return JSON.stringify({ revoked: { component: input.component, kind: input.kind, key: input.key, at: entry.at } });
+      } },
+  ];
+}
+
+/** Parse "/visual ..." arguments into [operation, input]. */
+export function parseVisualCommand(arg) {
+  const words = String(arg || '').trim().split(/\s+/).filter(Boolean), [action = 'status', ...rest] = words;
+  if (action === 'status' && rest.length <= 1) return ['VisualBoard', rest[0] ? { component: rest[0] } : {}];
+  if (action === 'approve-setup' && rest.length === 2) return ['VisualApproveSetup', { component: rest[0], digest: rest[1] }];
+  if (action === 'approve' && rest.length === 4) return ['VisualApprove', { component: rest[0], fixture: rest[1], state: rest[2], digest: rest[3] }];
+  if (action === 'confirm' && rest.length === 3) return ['VisualConfirm', { component: rest[0], criterion: rest[1], digest: rest[2] }];
+  if (action === 'revoke' && rest.length === 3 && ['setup', 'reference', 'criterion'].includes(rest[1])) return ['VisualRevoke', { component: rest[0], kind: rest[1], key: rest[2] }];
+  throw fail('Uso: /visual [status [C]] | approve-setup C DIGEST | approve C FIXTURE ESTADO DIGEST | confirm C CRITERIO DIGEST | revoke C setup|reference|criterion CLAVE (DIGEST: el prefijo que muestra /visual status)', 'VISUAL_COMMAND_INVALID');
+}

package/src/visual/pixel-diff.mjs

@@ -0,0 +1,96 @@
+// Exact-mode pixel comparison. Perceptual YIQ colour distance with a threshold,
+// plus antialiasing detection so font smoothing at one-pixel edges is the only
+// tolerated difference by default. Images are RGBA8 ({width, height, data}).
+
+export const DEFAULT_EXACT_TOLERANCE = Object.freeze({ threshold: 0.1, includeAntialiasing: false, maxDiffPixels: 0, maxDiffRatio: 0 });
+const MAX_YIQ_DELTA = 35215;
+
+export function normalizeTolerance(value) {
+  if (value === undefined || value === null) return DEFAULT_EXACT_TOLERANCE;
+  const bad = message => Object.assign(new Error(`Tolerancia inválida: ${message}`), { code: 'VISUAL_TOLERANCE_INVALID' });
+  if (typeof value !== 'object' || Array.isArray(value)) throw bad('debe ser un objeto');
+  for (const key of Object.keys(value)) if (!(key in DEFAULT_EXACT_TOLERANCE)) throw bad(`campo desconocido ${key}`);
+  const t = { ...DEFAULT_EXACT_TOLERANCE, ...value };
+  if (typeof t.threshold !== 'number' || !(t.threshold >= 0 && t.threshold <= 1)) throw bad('threshold entre 0 y 1');
+  if (typeof t.includeAntialiasing !== 'boolean') throw bad('includeAntialiasing booleano');
+  if (!Number.isSafeInteger(t.maxDiffPixels) || t.maxDiffPixels < 0) throw bad('maxDiffPixels entero >= 0');
+  if (typeof t.maxDiffRatio !== 'number' || !(t.maxDiffRatio >= 0 && t.maxDiffRatio <= 1)) throw bad('maxDiffRatio entre 0 y 1');
+  return Object.freeze(t);
+}
+
+// Colour channels blended over white, as a viewer would see a transparent pixel.
+function blended(data, i) {
+  const a = data[i + 3] / 255;
+  return [255 + (data[i] - 255) * a, 255 + (data[i + 1] - 255) * a, 255 + (data[i + 2] - 255) * a];
+}
+const yOf = (r, g, b) => r * 0.29889531 + g * 0.58662247 + b * 0.11448223;
+const iOf = (r, g, b) => r * 0.59597799 - g * 0.2741761 - b * 0.32180189;
+const qOf = (r, g, b) => r * 0.21147017 - g * 0.52261711 + b * 0.31114694;
+
+// Signed perceptual distance: positive when the second pixel is lighter.
+function colorDelta(a, ia, b, ib, yOnly = false) {
+  const [r1, g1, b1] = blended(a, ia), [r2, g2, b2] = blended(b, ib);
+  const y = yOf(r1, g1, b1) - yOf(r2, g2, b2);
+  if (yOnly) return y;
+  const i = iOf(r1, g1, b1) - iOf(r2, g2, b2), q = qOf(r1, g1, b1) - qOf(r2, g2, b2);
+  const delta = 0.5053 * y * y + 0.299 * i * i + 0.1957 * q * q;
+  return y > 0 ? -delta : delta;
+}
+
+// True when (x, y) has many identical neighbours (part of a flat area).
+function flatNeighbours(img, x, y) {
+  let same = 0; const i = (y * img.width + x) * 4;
+  for (let ny = Math.max(0, y - 1); ny <= Math.min(img.height - 1, y + 1); ny++)
+    for (let nx = Math.max(0, x - 1); nx <= Math.min(img.width - 1, x + 1); nx++) {
+      if (nx === x && ny === y) continue;
+      const j = (ny * img.width + nx) * 4;
+      if (img.data[i] === img.data[j] && img.data[i + 1] === img.data[j + 1] && img.data[i + 2] === img.data[j + 2] && img.data[i + 3] === img.data[j + 3]) same++;
+      if (same > 2) return true;
+    }
+  return false;
+}
+
+// A pixel is antialiased when, in one image, it sits between a darkest and a
+// brightest neighbour and either of those belongs to a flat area in both images.
+function antialiased(img, x, y, other) {
+  let zeroes = x === 0 || x === img.width - 1 || y === 0 || y === img.height - 1 ? 1 : 0;
+  let min = 0, max = 0, minX = -1, minY = -1, maxX = -1, maxY = -1;
+  const i = (y * img.width + x) * 4;
+  for (let ny = Math.max(0, y - 1); ny <= Math.min(img.height - 1, y + 1); ny++)
+    for (let nx = Math.max(0, x - 1); nx <= Math.min(img.width - 1, x + 1); nx++) {
+      if (nx === x && ny === y) continue;
+      const delta = colorDelta(img.data, i, img.data, (ny * img.width + nx) * 4, true);
+      if (delta === 0) { if (++zeroes > 2) return false; }
+      else if (delta < min) { min = delta; minX = nx; minY = ny; }
+      else if (delta > max) { max = delta; maxX = nx; maxY = ny; }
+    }
+  if (min === 0 || max === 0) return false;
+  return (flatNeighbours(img, minX, minY) && flatNeighbours(other, minX, minY)) || (flatNeighbours(img, maxX, maxY) && flatNeighbours(other, maxX, maxY));
+}
+
+export function comparePixels(reference, actual, toleranceInput) {
+  const tolerance = normalizeTolerance(toleranceInput);
+  if (reference.width !== actual.width || reference.height !== actual.height)
+    return { passed: false, reason: 'dimension_mismatch', reference_size: { width: reference.width, height: reference.height },
+      actual_size: { width: actual.width, height: actual.height }, mismatched: null, antialiased: null, ratio: null, bounds: null, diff: null, tolerance };
+  const { width, height } = reference, total = width * height, maxDelta = MAX_YIQ_DELTA * tolerance.threshold * tolerance.threshold;
+  const diff = new Uint8Array(total * 4);
+  let mismatched = 0, aa = 0, minX = width, minY = height, maxX = -1, maxY = -1;
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    const i = (y * width + x) * 4, delta = Math.abs(colorDelta(reference.data, i, actual.data, i));
+    let colour;
+    if (delta > maxDelta) {
+      if (!tolerance.includeAntialiasing && (antialiased(reference, x, y, actual) || antialiased(actual, x, y, reference))) { aa++; colour = [255, 255, 0, 255]; }
+      else { mismatched++; colour = [255, 0, 0, 255]; if (x < minX) minX = x; if (y < minY) minY = y; if (x > maxX) maxX = x; if (y > maxY) maxY = y; }
+    } else {
+      // Faded grayscale of the reference keeps the layout readable under the marks.
+      const [r, g, b] = blended(reference.data, i), v = 255 + (yOf(r, g, b) - 255) * 0.1;
+      colour = [v, v, v, 255];
+    }
+    diff.set(colour, i);
+  }
+  const ratio = mismatched / total;
+  return { passed: mismatched <= tolerance.maxDiffPixels || ratio <= tolerance.maxDiffRatio && tolerance.maxDiffRatio > 0,
+    reason: null, mismatched, antialiased: aa, ratio, bounds: maxX < 0 ? null : { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 },
+    diff: { width, height, data: diff }, tolerance };
+}

package/src/visual/png.mjs

@@ -0,0 +1,103 @@
+// Minimal PNG codec for visual acceptance: 8-bit, non-interlaced grayscale, RGB,
+// gray+alpha and RGBA, which covers Chrome captures and common image tools.
+// Decoded images are always RGBA8 ({width, height, data: Uint8Array}).
+import { deflateSync, inflateSync } from 'node:zlib';
+
+const SIGNATURE = Buffer.from('89504e470d0a1a0a', 'hex');
+export const PNG_MAX_PIXELS = 40_000_000;
+const CHANNELS = { 0: 1, 2: 3, 4: 2, 6: 4 };
+
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) { let c = n; for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1; table[n] = c >>> 0; }
+  return table;
+})();
+function crc32(buffer) {
+  let crc = 0xffffffff;
+  for (let i = 0; i < buffer.length; i++) crc = CRC_TABLE[(crc ^ buffer[i]) & 0xff] ^ (crc >>> 8);
+  return (crc ^ 0xffffffff) >>> 0;
+}
+const fail = message => Object.assign(new Error(`PNG inválido: ${message}`), { code: 'VISUAL_PNG_INVALID' });
+
+export function pngDimensions(bytes) {
+  return bytes?.length >= 24 && SIGNATURE.equals(bytes.subarray(0, 8)) && bytes.subarray(12, 16).toString('latin1') === 'IHDR'
+    ? { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) } : null;
+}
+
+export function decodePng(input) {
+  const bytes = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  if (bytes.length < 8 || !SIGNATURE.equals(bytes.subarray(0, 8))) throw fail('firma ausente');
+  let offset = 8, header = null; const idat = [];
+  while (offset < bytes.length) {
+    if (offset + 12 > bytes.length) throw fail('chunk truncado');
+    const length = bytes.readUInt32BE(offset), type = bytes.subarray(offset + 4, offset + 8).toString('latin1');
+    const end = offset + 12 + length;
+    if (end > bytes.length) throw fail('chunk truncado');
+    const body = bytes.subarray(offset + 8, offset + 8 + length);
+    if (crc32(bytes.subarray(offset + 4, offset + 8 + length)) !== bytes.readUInt32BE(offset + 8 + length)) throw fail(`CRC de ${type}`);
+    if (type === 'IHDR') {
+      if (length !== 13) throw fail('IHDR');
+      header = { width: body.readUInt32BE(0), height: body.readUInt32BE(4), depth: body[8], color: body[9], compression: body[10], filter: body[11], interlace: body[12] };
+      if (!header.width || !header.height) throw fail('dimensiones vacías');
+      if (header.width * header.height > PNG_MAX_PIXELS) throw Object.assign(new Error(`PNG excede ${PNG_MAX_PIXELS} pixels.`), { code: 'VISUAL_PNG_TOO_LARGE' });
+      if (header.depth !== 8 || !(header.color in CHANNELS)) throw fail('sólo se admiten 8 bits gris, RGB, gris+alfa o RGBA (sin paleta)');
+      if (header.compression !== 0 || header.filter !== 0 || header.interlace !== 0) throw fail('sólo se admiten imágenes no entrelazadas');
+    } else if (type === 'IDAT') idat.push(body);
+    else if (type === 'IEND') break;
+    offset = end;
+  }
+  if (!header) throw fail('IHDR ausente');
+  if (!idat.length) throw fail('IDAT ausente');
+  const channels = CHANNELS[header.color], stride = header.width * channels;
+  let raw;
+  try { raw = inflateSync(Buffer.concat(idat), { maxOutputLength: (stride + 1) * header.height + 1 }); }
+  catch { throw fail('datos comprimidos'); }
+  if (raw.length !== (stride + 1) * header.height) throw fail('tamaño de datos');
+  const pixels = new Uint8Array(stride * header.height);
+  for (let y = 0; y < header.height; y++) {
+    const filter = raw[y * (stride + 1)], src = y * (stride + 1) + 1, dst = y * stride;
+    for (let i = 0; i < stride; i++) {
+      const a = i >= channels ? pixels[dst + i - channels] : 0, b = y ? pixels[dst - stride + i] : 0, c = y && i >= channels ? pixels[dst - stride + i - channels] : 0;
+      let predictor;
+      if (filter === 0) predictor = 0; else if (filter === 1) predictor = a; else if (filter === 2) predictor = b;
+      else if (filter === 3) predictor = (a + b) >> 1;
+      else if (filter === 4) { const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c); predictor = pa <= pb && pa <= pc ? a : pb <= pc ? b : c; }
+      else throw fail(`filtro ${filter}`);
+      pixels[dst + i] = (raw[src + i] + predictor) & 255;
+    }
+  }
+  const data = new Uint8Array(header.width * header.height * 4);
+  for (let i = 0, j = 0; i < header.width * header.height; i++, j += channels) {
+    const o = i * 4;
+    if (channels === 4) { data[o] = pixels[j]; data[o + 1] = pixels[j + 1]; data[o + 2] = pixels[j + 2]; data[o + 3] = pixels[j + 3]; }
+    else if (channels === 3) { data[o] = pixels[j]; data[o + 1] = pixels[j + 1]; data[o + 2] = pixels[j + 2]; data[o + 3] = 255; }
+    else if (channels === 2) { data[o] = data[o + 1] = data[o + 2] = pixels[j]; data[o + 3] = pixels[j + 1]; }
+    else { data[o] = data[o + 1] = data[o + 2] = pixels[j]; data[o + 3] = 255; }
+  }
+  return { width: header.width, height: header.height, data };
+}
+
+function pngChunk(type, body) {
+  const length = Buffer.alloc(4); length.writeUInt32BE(body.length);
+  const typed = Buffer.concat([Buffer.from(type, 'latin1'), body]);
+  const crc = Buffer.alloc(4); crc.writeUInt32BE(crc32(typed));
+  return Buffer.concat([length, typed, crc]);
+}
+
+export function encodePng({ width, height, data }) {
+  if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1) throw fail('dimensiones');
+  if (data.length !== width * height * 4) throw fail('los datos no son RGBA del tamaño declarado');
+  const stride = width * 4, raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) { raw[y * (stride + 1)] = 0; Buffer.from(data.buffer, data.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1); }
+  const ihdr = Buffer.alloc(13); ihdr.writeUInt32BE(width, 0); ihdr.writeUInt32BE(height, 4); ihdr[8] = 8; ihdr[9] = 6;
+  return Buffer.concat([SIGNATURE, pngChunk('IHDR', ihdr), pngChunk('IDAT', deflateSync(raw)), pngChunk('IEND', Buffer.alloc(0))]);
+}
+
+/** Crop an RGBA image to an integer rectangle fully inside it. */
+export function cropImage(image, { x, y, width, height }) {
+  if (![x, y, width, height].every(Number.isSafeInteger) || x < 0 || y < 0 || width < 1 || height < 1 || x + width > image.width || y + height > image.height)
+    throw Object.assign(new Error('Recorte fuera de la imagen.'), { code: 'VISUAL_CROP_OUTSIDE' });
+  const data = new Uint8Array(width * height * 4);
+  for (let row = 0; row < height; row++) data.set(image.data.subarray(((y + row) * image.width + x) * 4, ((y + row) * image.width + x + width) * 4), row * width * 4);
+  return { width, height, data };
+}