@milpa/comal 0.2.2 → 0.2.4

package/src/visual/registry.mjs

@@ -0,0 +1,265 @@
+// Workspace registry for visual acceptance. Everything under visual/ is a
+// proposal the agent may edit: component specs, reference images and criteria.
+// Only what the human approved in the ledger (ledger.mjs) is enforced.
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { normalizeSteps } from './chrome.mjs';
+import { normalizeCriterion } from './measure.mjs';
+import { normalizeTolerance } from './pixel-diff.mjs';
+
+export const VISUAL_DIR = 'visual';
+const ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const fail = message => Object.assign(new Error(`Componente visual inválido: ${message}`), { code: 'VISUAL_COMPONENT_INVALID' });
+const only = (object, keys, label) => { for (const key of Object.keys(object)) if (!keys.includes(key)) throw fail(`${label}: campo desconocido ${key}`); };
+const selector = value => typeof value === 'string' && value.trim().length > 0 && value.length <= 1000;
+const inside = (root, file) => file === root || file.startsWith(root + path.sep);
+
+const PROTECTED = new Set(['.comal', '.harness', '.git']);
+/**
+ * Real path of target, which must stay inside the workspace after resolving
+ * symlinks and must not enter Comal's protected state (.comal, .harness) or .git.
+ */
+export async function confinedPath(cwd, target, label) {
+  const root = await fs.realpath(cwd);
+  let real;
+  try { real = await fs.realpath(path.resolve(cwd, target)); } catch (error) { throw fail(`${label}: no existe ${target}`); }
+  const relative = path.relative(root, real);
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) throw fail(`${label}: ${target} sale del workspace`);
+  if (relative.split(path.sep).some(part => PROTECTED.has(part))) throw fail(`${label}: ${target} está en estado protegido (.comal, .harness o .git)`);
+  return real;
+}
+
+export const pairKey = (fixture, state) => `${fixture}--${state}`;
+export function referencePaths(cwd, component, key) {
+  const base = path.join(cwd, VISUAL_DIR, 'references', component, key);
+  return { png: `${base}.png`, meta: `${base}.json` };
+}
+export const componentFile = (cwd, id) => path.join(cwd, VISUAL_DIR, 'components', `${id}.json`);
+export const criteriaFile = (cwd, id) => path.join(cwd, VISUAL_DIR, 'criteria', `${id}.json`);
+
+export async function listComponents(cwd) {
+  const dir = path.join(cwd, VISUAL_DIR, 'components');
+  const names = await fs.readdir(dir).catch(() => []);
+  return names.filter(name => name.endsWith('.json')).map(name => name.slice(0, -5)).filter(id => ID.test(id)).sort();
+}
+
+async function readSpecBytes(cwd, id) {
+  if (!ID.test(id || '')) throw fail(`id de componente inválido: ${id}`);
+  try { return await fs.readFile(componentFile(cwd, id)); }
+  catch (error) { throw fail(`no se pudo leer ${path.relative(cwd, componentFile(cwd, id))}: ${error.message}`); }
+}
+
+export async function loadComponent(cwd, id) { return parseComponent(cwd, id, await readSpecBytes(cwd, id)); }
+
+/** Validate spec bytes; the same bytes are what setupDigest covers. */
+export async function parseComponent(cwd, id, bytes) {
+  if (!ID.test(id || '')) throw fail(`id de componente inválido: ${id}`);
+  let raw;
+  try { raw = JSON.parse(Buffer.from(bytes).toString('utf8')); }
+  catch (error) { throw fail(`${path.relative(cwd, componentFile(cwd, id))} no es JSON: ${error.message}`); }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw fail('debe ser un objeto');
+  only(raw, ['id', 'adapter', 'extension', 'viewport', 'root', 'anchors', 'elements', 'regions', 'fixtures', 'states', 'setup', 'description'], 'componente');
+  if (raw.id !== id) throw fail(`id ${raw.id} no coincide con el archivo ${id}`);
+  if (raw.adapter !== 'content-script') throw fail('adapter debe ser content-script');
+  const root = path.resolve(cwd), extensionDir = path.resolve(cwd, String(raw.extension || ''));
+  if (typeof raw.extension !== 'string' || !inside(root, extensionDir) || extensionDir === root) throw fail('extension debe ser un directorio dentro del workspace');
+  const extensionReal = await confinedPath(cwd, extensionDir, 'extension');
+  const stat = await fs.stat(path.join(extensionReal, 'manifest.json')).catch(() => null);
+  if (!stat?.isFile()) throw fail(`extension ${raw.extension} no tiene manifest.json`);
+  const v = raw.viewport || {};
+  only(v, ['width', 'height', 'deviceScaleFactor'], 'viewport');
+  const dim = (value, min, max) => Number.isSafeInteger(value) && value >= min && value <= max;
+  if (!dim(v.width, 200, 4000) || !dim(v.height, 200, 4000)) throw fail('viewport.width/height enteros entre 200 y 4000');
+  const scale = v.deviceScaleFactor ?? 1;
+  if (![1, 2, 3].includes(scale)) throw fail('viewport.deviceScaleFactor 1, 2 o 3');
+  if (!selector(raw.root)) throw fail('root: selector del componente montado');
+  for (const key of ['anchors', 'elements', 'regions']) if (raw[key] !== undefined && (!Array.isArray(raw[key]) || raw[key].length > 20 || !raw[key].every(selector))) throw fail(`${key}: lista de selectores (máx 20)`);
+  if (!Array.isArray(raw.fixtures) || !raw.fixtures.length || raw.fixtures.length > 30) throw fail('fixtures: entre 1 y 30');
+  const fixtures = await Promise.all(raw.fixtures.map(async f => {
+    if (!f || typeof f !== 'object') throw fail('fixture inválido');
+    only(f, ['id', 'kind', 'dir', 'url', 'mandatory'], `fixture ${f.id}`);
+    if (!ID.test(f.id || '')) throw fail(`fixture id inválido ${f.id}`);
+    if (!['local', 'frozen', 'live'].includes(f.kind)) throw fail(`fixture ${f.id}: kind local, frozen o live`);
+    if (f.kind === 'live') {
+      if (f.dir !== undefined) throw fail(`fixture live ${f.id} no lleva dir`);
+      let url; try { url = new URL(f.url); } catch { throw fail(`fixture live ${f.id}: url inválida`); }
+      if (url.protocol !== 'https:') throw fail(`fixture live ${f.id}: url https`);
+      if (f.mandatory === true) throw fail(`fixture live ${f.id} no puede ser obligatorio: un sitio vivo cambia sin aviso`);
+      return Object.freeze({ id: f.id, kind: 'live', url: url.href, mandatory: false });
+    }
+    if (f.url !== undefined) throw fail(`fixture ${f.id}: url sólo para live`);
+    const dir = path.resolve(cwd, f.dir ?? path.join(VISUAL_DIR, 'fixtures', f.id));
+    if (!inside(root, dir)) throw fail(`fixture ${f.id}: dir dentro del workspace`);
+    if (f.mandatory !== undefined && typeof f.mandatory !== 'boolean') throw fail(`fixture ${f.id}: mandatory booleano`);
+    return Object.freeze({ id: f.id, kind: f.kind, dir: await confinedPath(cwd, dir, `fixture ${f.id}`), mandatory: f.mandatory ?? true });
+  }));
+  const fixtureIds = new Set(fixtures.map(f => f.id));
+  if (fixtureIds.size !== fixtures.length) throw fail('fixtures con id repetido');
+  if (!Array.isArray(raw.states) || !raw.states.length || raw.states.length > 30) throw fail('states: entre 1 y 30');
+  const states = raw.states.map(s => {
+    if (!s || typeof s !== 'object') throw fail('estado inválido');
+    only(s, ['id', 'fixtures', 'steps', 'description'], `estado ${s.id}`);
+    if (!ID.test(s.id || '')) throw fail(`estado id inválido ${s.id}`);
+    if (s.fixtures !== undefined && (!Array.isArray(s.fixtures) || !s.fixtures.length)) throw fail(`estado ${s.id}: fixtures lista no vacía`);
+    for (const fixture of s.fixtures || []) if (!fixtureIds.has(fixture)) throw fail(`estado ${s.id}: fixture ${fixture} no declarado`);
+    return Object.freeze({ id: s.id, fixtures: s.fixtures ? [...s.fixtures] : [...fixtureIds], steps: normalizeSteps(s.steps ?? []), description: s.description ?? null });
+  });
+  if (new Set(states.map(s => s.id)).size !== states.length) throw fail('states con id repetido');
+  return Object.freeze({ id, adapter: 'content-script', extension: raw.extension, extension_dir: extensionReal,
+    viewport: Object.freeze({ width: v.width, height: v.height, deviceScaleFactor: scale }), root: raw.root,
+    anchors: Object.freeze([...(raw.anchors || [])]), elements: Object.freeze([...(raw.elements || [])]), regions: Object.freeze([...(raw.regions || [])]),
+    fixtures: Object.freeze(fixtures), states: Object.freeze(states), setup: normalizeSteps(raw.setup ?? []), description: raw.description ?? null });
+}
+
+// Exact references tolerate at most this much; looser values would accept any capture.
+export const TOLERANCE_LIMITS = Object.freeze({ threshold: 0.2, maxDiffPixels: 100, maxDiffRatio: 0.0001 });
+export function normalizeReferenceMeta(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw fail('sidecar de referencia debe ser un objeto');
+  only(raw, ['mode', 'tolerance', 'fingerprint', 'source', 'captured_at', 'note'], 'referencia');
+  if (!['exact', 'mockup'].includes(raw.mode)) throw fail('referencia: mode exact o mockup');
+  if (raw.mode === 'mockup' && raw.tolerance !== undefined) throw fail('referencia mockup no lleva tolerance');
+  const tolerance = raw.mode === 'exact' ? normalizeTolerance(raw.tolerance) : null;
+  if (tolerance) for (const [key, limit] of Object.entries(TOLERANCE_LIMITS)) if (tolerance[key] > limit) throw fail(`referencia: tolerance.${key} excede ${limit}`);
+  return { mode: raw.mode, tolerance, fingerprint: raw.fingerprint ?? null,
+    source: raw.source ?? null, captured_at: raw.captured_at ?? null, note: raw.note ?? null };
+}
+
+export async function readReference(cwd, component, key) {
+  const paths = referencePaths(cwd, component, key);
+  const [png, metaBytes] = await Promise.all([fs.readFile(paths.png).catch(() => null), fs.readFile(paths.meta).catch(() => null)]);
+  if (!png || !metaBytes) return null;
+  let meta;
+  try { meta = normalizeReferenceMeta(JSON.parse(metaBytes.toString('utf8'))); }
+  catch (error) { return { file: path.relative(cwd, paths.png), error: error.message, digest: null }; }
+  const png_sha256 = sha256(png), meta_sha256 = sha256(metaBytes);
+  return { file: path.relative(cwd, paths.png), png, png_sha256, meta, meta_sha256, mode: meta.mode, digest: sha256(`${png_sha256}:${meta_sha256}`) };
+}
+
+export async function readProposedCriteria(cwd, component) {
+  const raw = await fs.readFile(criteriaFile(cwd, component), 'utf8').catch(() => null);
+  if (raw === null) return { criteria: [], errors: [] };
+  let list;
+  try { list = JSON.parse(raw); } catch (error) { return { criteria: [], errors: [`criteria/${component}.json no es JSON: ${error.message}`] }; }
+  if (!Array.isArray(list)) return { criteria: [], errors: [`criteria/${component}.json debe ser una lista`] };
+  const criteria = [], errors = [], ids = new Set();
+  for (const item of list) {
+    try { const c = normalizeCriterion(item); if (ids.has(c.id)) throw new Error(`id repetido ${c.id}`); ids.add(c.id); criteria.push(c); }
+    catch (error) { errors.push(error.message); }
+  }
+  return { criteria, errors };
+}
+
+/** Pairs, references and proposals of a component; pass the spec to use a snapshot of it. */
+export async function componentInventory(cwd, id, given = null) {
+  const spec = given ?? await loadComponent(cwd, id);
+  const pairs = [];
+  for (const fixture of spec.fixtures) for (const state of spec.states) {
+    if (!state.fixtures.includes(fixture.id)) continue;
+    const key = pairKey(fixture.id, state.id);
+    const reference = await readReference(cwd, id, key);
+    pairs.push({ fixture: fixture.id, state: state.id, key, kind: fixture.kind, mandatory: fixture.mandatory, reference: reference && { ...reference, png: undefined } });
+  }
+  const proposals = await readProposedCriteria(cwd, id), known = new Set(spec.states.map(s => s.id));
+  // A proposal naming a state the spec lacks is an error, not a criterion that silently never applies.
+  const unknown = c => (c.states || []).filter(s => !known.has(s));
+  const proposalErrors = [...proposals.errors, ...proposals.criteria.filter(c => unknown(c).length).map(c => `criterio ${c.id}: estados que el spec no tiene: ${unknown(c).join(', ')}`)];
+  return { spec, pairs, proposedCriteria: proposals.criteria.filter(c => !unknown(c).length), proposalErrors };
+}
+
+// Every file Chrome could load from the unpacked extension (node_modules
+// included). Symlinks are followed only while they stay inside the extension.
+async function walk(dir, root = dir, out = [], seen = new Set()) {
+  const real = await fs.realpath(dir);
+  if (seen.has(real)) return out;
+  seen.add(real);
+  for (const entry of (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name, 'en'))) {
+    if (entry.name === '.git') continue;
+    const full = path.join(dir, entry.name);
+    let stat = entry;
+    if (entry.isSymbolicLink()) {
+      const target = await fs.realpath(full).catch(() => null);
+      if (!target || !(target === root || target.startsWith(root + path.sep))) throw fail(`la extensión tiene un enlace que sale de ella: ${path.relative(root, full)}`);
+      stat = await fs.stat(full);
+    }
+    if (stat.isDirectory()) await walk(full, root, out, seen);
+    else if (stat.isFile()) out.push(full);
+    if (out.length > 20000) throw fail('la extensión tiene más de 20000 archivos');
+  }
+  return out;
+}
+
+/** Files of a tree (walk order) with the sha256 of their bytes. */
+async function hashTree(dir) {
+  const out = [];
+  for (const file of await walk(dir)) out.push({ rel: path.relative(dir, file), file, sha: sha256(await fs.readFile(file)) });
+  return out;
+}
+/** Copy a tree into dst and hash exactly the bytes copied. */
+async function copyTree(src, dst) {
+  const out = [];
+  for (const file of await walk(src)) {
+    const rel = path.relative(src, file), bytes = await fs.readFile(file), target = path.join(dst, rel);
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.writeFile(target, bytes);
+    out.push({ rel, file, sha: sha256(bytes) });
+  }
+  return out;
+}
+const treeDigest = entries => { const hash = createHash('sha256'); for (const e of entries) hash.update(e.rel).update('\0').update(e.sha).update('\n'); return hash.digest('hex'); };
+
+/**
+ * Digest of the component configuration the human approves: the spec bytes and
+ * the full content of every local or frozen fixture. Editing states, steps,
+ * root, mandatory flags or fixture pages changes it and blocks acceptance.
+ */
+function setupDigestFrom(specBytes, fixtures) {
+  const hash = createHash('sha256');
+  hash.update('spec\0').update(sha256(specBytes)).update('\n');
+  for (const fixture of fixtures) {
+    if (fixture.kind === 'live') { hash.update(`live\0${fixture.id}\0${fixture.url}\n`); continue; }
+    hash.update(`fixture\0${fixture.id}\0${fixture.kind}\n`);
+    for (const e of fixture.entries) hash.update(e.rel).update('\0').update(e.sha).update('\n');
+  }
+  return hash.digest('hex');
+}
+const manifestFrom = (specBytes, fixtures) => ({ spec_sha256: sha256(specBytes),
+  fixtures: Object.fromEntries(fixtures.map(f => [f.id, f.kind === 'live' ? { live: f.url } : Object.fromEntries(f.entries.map(e => [e.rel, e.sha]))])) });
+
+async function setupState(cwd, spec) {
+  const specBytes = await fs.readFile(componentFile(cwd, spec.id));
+  const fixtures = [];
+  for (const fixture of spec.fixtures) fixtures.push(fixture.kind === 'live' ? fixture : { ...fixture, entries: await hashTree(fixture.dir) });
+  return { digest: setupDigestFrom(specBytes, fixtures), manifest: manifestFrom(specBytes, fixtures) };
+}
+export async function setupDigest(cwd, spec) { return (await setupState(cwd, spec)).digest; }
+/** Per-file hashes of the setup, stored with its approval so status can show what changed. */
+export async function setupManifest(cwd, spec) { return (await setupState(cwd, spec)).manifest; }
+
+/** Files of the unpacked extension with their sha256, relative to cwd (for receipt observations). */
+export async function extensionFiles(cwd, spec) {
+  return (await hashTree(spec.extension_dir)).map(e => ({ file_path: path.relative(cwd, e.file), sha256: e.sha }));
+}
+
+export async function buildDigest(spec) { return treeDigest(await hashTree(spec.extension_dir)); }
+
+/**
+ * Private copy of everything a run uses: spec bytes, extension and local/frozen
+ * fixtures. Digests are computed over the copied bytes and the run serves and
+ * loads only the copy, so editing the workspace during a run cannot change what
+ * was verified versus what was approved.
+ */
+export async function snapshotComponent(cwd, id, dir) {
+  const specBytes = await readSpecBytes(cwd, id), source = await parseComponent(cwd, id, specBytes);
+  const extension = path.join(dir, 'extension'), extensionEntries = await copyTree(source.extension_dir, extension);
+  const fixtures = [];
+  for (const fixture of source.fixtures) {
+    if (fixture.kind === 'live') { fixtures.push(fixture); continue; }
+    const target = path.join(dir, 'fixtures', fixture.id);
+    fixtures.push({ ...fixture, dir: target, entries: await copyTree(fixture.dir, target) });
+  }
+  const spec = Object.freeze({ ...source, extension_dir: extension, fixtures: Object.freeze(fixtures.map(({ entries, ...f }) => Object.freeze(f))) });
+  return { spec, source, build_digest: treeDigest(extensionEntries), setup_digest: setupDigestFrom(specBytes, fixtures), setup_manifest: manifestFrom(specBytes, fixtures),
+    observed_files: extensionEntries.map(e => ({ file_path: path.relative(cwd, e.file), sha256: e.sha })) };
+}

package/src/visual/report.mjs

@@ -0,0 +1,64 @@
+// Delivery report: side-by-side reference / capture / diff for every pair and
+// a per-aspect verdict table. Also builds the composite image sent to models.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { cropImage, decodePng, encodePng } from './png.mjs';
+
+const esc = value => String(value ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** Region around a box, expanded by margin and clamped to the image. */
+export function regionAround(box, margin, width, height) {
+  if (!box) return { x: 0, y: 0, width, height };
+  const x = Math.max(0, Math.floor(box.x - margin)), y = Math.max(0, Math.floor(box.y - margin));
+  return { x, y, width: Math.min(width, Math.ceil(box.x + box.width + margin)) - x, height: Math.min(height, Math.ceil(box.y + box.height + margin)) - y };
+}
+
+function union(a, b) {
+  if (!a) return b; if (!b) return a;
+  const x = Math.min(a.x, b.x), y = Math.min(a.y, b.y);
+  return { x, y, width: Math.max(a.x + a.width, b.x + b.width) - x, height: Math.max(a.y + a.height, b.y + b.height) - y };
+}
+
+/** Horizontal composite of equally framed panels, cropped around focus when sizes allow. */
+export function composite(panels, focus) {
+  const images = panels.filter(Boolean).map(bytes => decodePng(bytes));
+  if (!images.length) return null;
+  const same = images.every(img => img.width === images[0].width && img.height === images[0].height);
+  const framed = same && focus ? images.map(img => { const r = regionAround(focus, 40, img.width, img.height); return r.width > 0 && r.height > 0 ? cropImage(img, r) : img; }) : images;
+  const gap = 8, height = Math.max(...framed.map(img => img.height)), width = framed.reduce((sum, img) => sum + img.width, 0) + gap * (framed.length - 1);
+  const data = new Uint8Array(width * height * 4).fill(255);
+  let left = 0;
+  for (const img of framed) {
+    for (let y = 0; y < img.height; y++) data.set(img.data.subarray(y * img.width * 4, (y + 1) * img.width * 4), (y * width + left) * 4);
+    left += img.width + gap;
+  }
+  return encodePng({ width, height, data });
+}
+export const focusOf = (componentBox, diffBounds) => union(componentBox, diffBounds);
+
+const VERDICT_COLOR = { pass: '#1a7f37', fail: '#cf222e', blocked: '#9a6700', not_comparable: '#9a6700', inconclusive: '#6e7781' };
+const badge = verdict => `<span class="v" style="background:${VERDICT_COLOR[verdict] || '#6e7781'}">${esc(verdict)}</span>`;
+
+export async function writeReport(dir, result) {
+  await fs.mkdir(dir, { recursive: true });
+  const pairs = result.pairs.map(pair => {
+    const img = (label, file) => file ? `<figure><figcaption>${label}</figcaption><img src="${esc(path.basename(file))}" alt="${label}"></figure>` : '';
+    const aspects = pair.aspects.map(a => `<tr><td>${esc(a.id)}</td><td>${badge(a.verdict)}</td><td>${esc(a.reason || a.evidence || '')}</td></tr>`).join('');
+    return `<section><h2>${esc(pair.fixture)} · ${esc(pair.state)} ${badge(pair.verdict)} <small>${esc(pair.mode || 'sin referencia')}${pair.mandatory ? ' · obligatorio' : ' · informativo'}</small></h2>
+      ${pair.reason ? `<p class="reason">${esc(pair.reason)}</p>` : ''}
+      <div class="row">${img('Referencia aprobada', pair.images.reference)}${img('Captura de aceptación', pair.images.capture)}${img('Diferencias', pair.images.diff)}</div>
+      ${pair.pixel ? `<p>Píxeles distintos: ${pair.pixel.mismatched} (${(pair.pixel.ratio * 100).toFixed(3)}%), antialiasing tolerado: ${pair.pixel.antialiased}</p>` : ''}
+      <table><thead><tr><th>Aspecto</th><th>Veredicto</th><th>Evidencia</th></tr></thead><tbody>${aspects || '<tr><td colspan="3">Sin aspectos evaluados.</td></tr>'}</tbody></table></section>`;
+  }).join('\n');
+  const pending = result.pending_criteria?.length ? `<p>Criterios propuestos sin confirmar (no cuentan): ${result.pending_criteria.map(c => esc(c.id)).join(', ')}</p>` : '';
+  const html = `<!doctype html><html lang="es"><meta charset="utf-8"><title>Aceptación visual · ${esc(result.component)}</title>
+<style>body{font:14px system-ui,sans-serif;margin:24px;color:#1f2328}h1{font-size:20px}h2{font-size:16px;margin-top:32px}.v{color:#fff;border-radius:4px;padding:1px 6px;font-size:12px}
+.row{display:flex;gap:12px;flex-wrap:wrap}figure{margin:0}figcaption{font-size:12px;color:#57606a}img{max-width:420px;border:1px solid #d0d7de}table{border-collapse:collapse;margin-top:8px}
+td,th{border:1px solid #d0d7de;padding:4px 8px;text-align:left;vertical-align:top}.reason{color:#9a6700}small{color:#57606a;font-weight:normal}</style>
+<h1>Aceptación visual · ${esc(result.component)} ${badge(result.status === 'passed' ? 'pass' : result.status === 'failed' ? 'fail' : 'blocked')}</h1>
+<p>Estado: <b>${esc(result.status)}</b>${result.reason ? ` — ${esc(result.reason)}` : ''}<br>Build: <code>${esc(result.build_digest)}</code> · Chrome: ${esc(result.fingerprint?.chrome)} · Corrida: ${esc(result.run_id)}</p>
+${pending}${pairs}</html>`;
+  const file = path.join(dir, 'report.html');
+  await fs.writeFile(file, html);
+  return file;
+}

package/src/visual/verify.mjs

@@ -0,0 +1,292 @@
+// Visual verification engine. The house (never the agent) loads the current
+// build of the extension in a fresh Chrome profile per pair, reaches each
+// (fixture, state), captures and measures it, and compares it against the
+// human-approved reference: pixels in exact mode, the independent judge in
+// mockup mode. Only approved references and confirmed criteria count.
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { launchChrome, defaultChromeBinary } from './chrome.mjs';
+import { startFixtureServer, readFixture } from './fixtures.mjs';
+import { environmentFingerprint, fingerprintDigest, fingerprintDifferences } from './fingerprint.mjs';
+import { componentInventory, readReference, referencePaths, pairKey, confinedPath, snapshotComponent } from './registry.mjs';
+import { openLedger } from './ledger.mjs';
+import { normalizeCriterion, evaluateMeasurable } from './measure.mjs';
+import { comparePixels } from './pixel-diff.mjs';
+import { decodePng, encodePng } from './png.mjs';
+import { composite, focusOf, writeReport } from './report.mjs';
+
+export const SITE_DRIFT_RATIO = 0.05;
+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;
+export const criteriaDigest = criteria => sha256(JSON.stringify(canonical([...criteria].sort((a, b) => a.id.localeCompare(b.id, 'en')))));
+export const referencesDigest = references => sha256(JSON.stringify(Object.keys(references).sort().map(key => [key, references[key].digest])));
+/** Approvals of the pairs the (approved) spec declares; orphaned approvals never count. */
+export const approvedReferences = (references, pairs) => Object.fromEntries(Object.entries(references).filter(([key]) => pairs.some(pair => pair.key === key)));
+const scaleBox = (box, scale) => box && { x: box.x * scale, y: box.y * scale, width: box.width * scale, height: box.height * scale };
+
+function factsRequest(spec, criteria) {
+  const measurable = criteria.filter(c => c.kind === 'measurable');
+  const elements = new Set(spec.elements), anchors = new Set([...spec.anchors, ...spec.regions]), properties = new Set(['color', 'background-color']);
+  for (const c of measurable) {
+    if (c.element !== 'root') elements.add(c.element);
+    if (c.check.type === 'relation') for (const anchor of [].concat(c.check.anchor)) anchors.add(anchor);
+    if (c.check.type === 'css') properties.add(c.check.property);
+  }
+  return { root: spec.root, elements: [...elements], anchors: [...anchors], properties: [...properties] };
+}
+
+// Mismatched pixels outside the component region, for live-site drift.
+function outsideRatio(reference, capture, box) {
+  if (reference.width !== capture.width || reference.height !== capture.height) return 1;
+  const result = comparePixels(reference, capture, { threshold: 0.1 });
+  if (!result.diff) return 1;
+  const x0 = box ? box.x - 4 : -1, y0 = box ? box.y - 4 : -1, x1 = box ? box.x + box.width + 4 : -1, y1 = box ? box.y + box.height + 4 : -1;
+  let outside = 0, total = 0;
+  for (let y = 0; y < capture.height; y++) for (let x = 0; x < capture.width; x++) {
+    if (x >= x0 && x <= x1 && y >= y0 && y <= y1) continue;
+    total++;
+    const i = (y * capture.width + x) * 4;
+    if (result.diff.data[i] === 255 && result.diff.data[i + 1] === 0) outside++;
+  }
+  return total ? outside / total : 0;
+}
+
+// Steps for the reference run without the extension: interactions with the
+// component itself (its host selector) and extension-context steps are skipped.
+function baselineSteps(spec, state) {
+  const host = spec.root.split('>>>')[0].trim();
+  return [...spec.setup, ...state.steps].filter(step => step.action !== 'extension' && !(step.selector && step.selector.split('>>>')[0].trim() === host));
+}
+const containsBox = (outer, inner) => inner.x >= outer.x - 2 && inner.y >= outer.y - 2 && inner.x + inner.width <= outer.x + outer.width + 2 && inner.y + inner.height <= outer.y + outer.height + 2;
+const sameBox = (a, b) => ['x', 'y', 'width', 'height'].every(key => Math.abs(a[key] - b[key]) < 0.5);
+
+/**
+ * Containment: elements that exist only with the extension and visibly paint
+ * must lie inside the component, its anchors or the approved regions. This is
+ * what stops an extension from painting the approved reference as a bitmap.
+ */
+async function checkContainment({ page, baselinePage, baselineElements, facts, spec }) {
+  const allowed = [facts.elements.root?.box, ...spec.anchors.concat(spec.regions).map(selector => facts.anchors[selector]?.box)].filter(Boolean);
+  const baseBySignature = new Map();
+  for (const entry of baselineElements) { if (!baseBySignature.has(entry.signature)) baseBySignature.set(entry.signature, []); baseBySignature.get(entry.signature).push(entry); }
+  const extBySignature = new Map();
+  for (const entry of await page.elements()) { if (!extBySignature.has(entry.signature)) extBySignature.set(entry.signature, []); extBySignature.get(entry.signature).push(entry); }
+  const candidates = [];
+  for (const [signature, list] of extBySignature) {
+    const base = baseBySignature.get(signature) || [];
+    if (list.length <= base.length) continue;
+    const baseBoxes = (await Promise.all(base.map(entry => baselinePage.rectOf(entry)))).filter(Boolean);
+    for (const entry of list) {
+      const box = await page.rectOf(entry);
+      if (!box || baseBoxes.some(b => sameBox(b, box))) continue;
+      candidates.push(entry);
+      if (candidates.length > 3000) return { verdict: 'inconclusive', reason: 'La extensión agregó más de 3000 elementos; no se pudo comprobar la contención.' };
+    }
+  }
+  const view = spec.viewport, violations = [];
+  for (const entry of candidates) {
+    const painted = await page.paintOf(entry);
+    if (!painted || painted.x >= view.width || painted.y >= view.height || painted.x + painted.width <= 0 || painted.y + painted.height <= 0) continue;
+    if (!allowed.some(box => containsBox(box, painted))) violations.push({ tag: painted.tag, paints: painted.reasons, box: { x: painted.x, y: painted.y, width: painted.width, height: painted.height }, signature: entry.signature.slice(-160) });
+  }
+  if (violations.length) return { verdict: 'fail', violations: violations.slice(0, 5),
+    reason: `La extensión pinta fuera de su componente en ${violations.length} elemento(s), p. ej. <${violations[0].tag}> (${violations[0].paints.join(', ')}) en x=${violations[0].box.x}, y=${violations[0].box.y}, ${violations[0].box.width}x${violations[0].box.height}. Si es legítimo, el humano puede declarar regions en el spec.` };
+  return { verdict: 'pass', reason: `${candidates.length} elemento(s) propio(s) de la extensión, todos dentro del componente o de sus regiones.` };
+}
+
+/** Load the build and reach one pair; returns capture bytes, facts, containment and any step error. */
+async function capturePair({ spec, fixture, state, server, chromeBinary, criteria, signal }) {
+  const offline = fixture.kind !== 'live', url = offline ? server.urlFor(fixture.id) : fixture.url;
+  const launch = () => launchChrome({ binary: chromeBinary, viewport: spec.viewport, hostRules: offline ? server.hostRules({ offline: true }) : [], ignoreCertificateErrors: offline, signal });
+  // Reference run without the extension, kept open until containment is measured.
+  let baseline = null, baselinePage = null, baselineElements = null, baselineError = null;
+  if (offline) {
+    baseline = await launch();
+    try { baselinePage = await baseline.openPage(); await baselinePage.navigate(url); await baselinePage.runSteps(baselineSteps(spec, state)); baselineElements = await baselinePage.elements(); }
+    catch (error) { if (signal?.aborted) { await baseline.close(); throw error; } baselineError = error.message; }
+  }
+  const session = await launch().catch(async error => { await baseline?.close(); throw error; });
+  try {
+    await session.loadExtension(spec.extension_dir);
+    const page = await session.openPage();
+    let stepError = null;
+    try {
+      await page.navigate(url);
+      await page.runSteps([...spec.setup, ...state.steps]);
+    } catch (error) { if (signal?.aborted) throw error; stepError = error.message; }
+    const capture = await page.screenshot();
+    let facts = { elements: {}, anchors: {} }, factsError = null;
+    try { facts = await page.facts(factsRequest(spec, criteria)); } catch (error) { if (signal?.aborted) throw error; factsError = error.message; }
+    let containment = null;
+    if (offline && !stepError && !factsError && facts.elements.root)
+      containment = baselineError ? { verdict: 'inconclusive', reason: `No se pudo reproducir el fixture sin la extensión: ${baselineError}` }
+        : await checkContainment({ page, baselinePage, baselineElements, facts, spec });
+    return { capture, facts, stepError, factsError, containment, fingerprint: environmentFingerprint({ version: session.version, viewport: spec.viewport, headless: session.headless }) };
+  } finally { await session.close(); await baseline?.close(); }
+}
+
+function overall(pairs) {
+  const mandatory = pairs.filter(p => p.mandatory);
+  if (!mandatory.length) return { status: 'blocked', reason: 'No hay pares obligatorios (fixtures locales o congelados).' };
+  if (mandatory.some(p => p.verdict === 'fail')) return { status: 'failed', reason: `${mandatory.filter(p => p.verdict === 'fail').length} par(es) obligatorio(s) no coinciden.` };
+  if (mandatory.every(p => p.verdict === 'pass')) return { status: 'passed', reason: null };
+  return { status: 'blocked', reason: `${mandatory.filter(p => p.verdict !== 'pass').length} par(es) obligatorio(s) sin veredicto concluyente.` };
+}
+
+/**
+ * mode 'acceptance': requires approved references and uses confirmed criteria.
+ * mode 'inspection': captures and measures with proposed criteria; nothing is approved.
+ */
+export async function verifyComponent(options) {
+  const snapshotDir = await fs.mkdtemp(path.join(os.tmpdir(), 'comal-visual-run-'));
+  try { return await verifySnapshot({ ...options, snapshot: await snapshotComponent(options.cwd, options.component, snapshotDir) }); }
+  finally { await fs.rm(snapshotDir, { recursive: true, force: true }); }
+}
+
+/** Run against an existing snapshot (snapshotComponent); verifyComponent takes and removes one. */
+export async function verifyFromSnapshot(options) { return verifySnapshot(options); }
+
+async function verifySnapshot({ cwd, stateDir, keyDir, component, judge, mode = 'acceptance', pairs: only, signal, chromeBinary = defaultChromeBinary(), runId = randomUUID(), evidenceRoot, snapshot }) {
+  const inventory = await componentInventory(cwd, component, snapshot.spec), spec = inventory.spec;
+  const ledger = await openLedger({ stateDir, keyDir }), effective = await ledger.effective(component);
+  const confirmed = effective.criteria.map(c => normalizeCriterion(c));
+  const criteria = mode === 'acceptance' ? confirmed : inventory.proposedCriteria;
+  const pending = inventory.proposedCriteria.filter(c => !confirmed.some(k => k.id === c.id && JSON.stringify(canonical(k)) === JSON.stringify(canonical(c))));
+  const setup_digest = snapshot.setup_digest;
+  const setupApproved = effective.setup?.digest === setup_digest;
+  // Acceptance runs only on the configuration the human approved (spec + fixtures).
+  const selected = mode === 'acceptance' && (!setupApproved || effective.invalid_entries) ? [] : inventory.pairs.filter(p => !only || only.includes(p.key));
+  const references = approvedReferences(effective.references, inventory.pairs);
+  const dir = path.join(evidenceRoot ?? path.join(cwd, 'evidence'), 'visual', component, runId);
+  await fs.mkdir(dir, { recursive: true });
+  const { build_digest, observed_files } = snapshot;
+  const localFixtures = spec.fixtures.filter(f => f.kind !== 'live' && selected.some(p => p.fixture === f.id));
+  const server = localFixtures.length ? await startFixtureServer({ fixtures: localFixtures.map(f => f.dir), stateDir }) : null;
+  const results = [], captures = new Map();
+  let fingerprint = null;
+  try {
+    for (const pair of selected) {
+      signal?.throwIfAborted();
+      const fixture = spec.fixtures.find(f => f.id === pair.fixture), state = spec.states.find(s => s.id === pair.state);
+      const shot = await capturePair({ spec, fixture, state, server, chromeBinary, criteria, signal });
+      fingerprint ??= shot.fingerprint;
+      captures.set(pair.key, shot);
+      const base = path.join(dir, pair.key), images = { capture: `${base}.capture.png` };
+      await fs.writeFile(images.capture, shot.capture);
+      const box = shot.facts.elements.root?.box ?? null;
+      // A criterion applies to the states it names (all when it names none); one naming a state the spec lacks can never be checked, so it blocks.
+      const ghostStates = c => (c.states || []).filter(s => !spec.states.some(x => x.id === s));
+      const applies = c => !ghostStates(c).length && (!c.states || c.states.includes(pair.state));
+      const unscoped = criteria.filter(c => ghostStates(c).length).map(c => ({ id: c.id, kind: c.kind, statement: c.statement, verdict: 'inconclusive', measured: null,
+        evidence: `El criterio nombra estados que el spec no tiene: ${ghostStates(c).join(', ')}.` }));
+      const measurements = [...criteria.filter(c => c.kind === 'measurable' && applies(c)).map(c => evaluateMeasurable(c, shot.facts)), ...unscoped,
+        ...(shot.containment ? [{ id: 'containment', kind: 'containment', statement: 'La extensión sólo pinta dentro de su componente', verdict: shot.containment.verdict, measured: shot.containment.violations ?? null, evidence: shot.containment.reason }] : [])];
+      const entry = { fixture: pair.fixture, state: pair.state, key: pair.key, kind: pair.kind, mandatory: pair.mandatory, mode: null, verdict: null, reason: null,
+        aspects: [], measurements, pixel: null, component_box: box, images };
+      const finish = (verdict, reason) => { entry.verdict = verdict; entry.reason = reason; results.push(entry); };
+      if (shot.stepError) { entry.aspects.push(...measurements); finish('fail', `No se llegó al estado: ${shot.stepError}`); continue; }
+      if (shot.factsError) { finish('fail', `No se pudieron medir el componente o sus elementos: ${shot.factsError}`); continue; }
+      if (!box) { finish('fail', `El componente ${spec.root} no está montado en este estado.`); continue; }
+      const reference = await readReference(cwd, component, pair.key);
+      if (reference?.error) { entry.aspects.push(...measurements); finish('blocked', `Referencia inválida: ${reference.error}`); continue; }
+      const approval = references[pair.key];
+      if (mode === 'acceptance') {
+        if (!reference) { entry.aspects.push(...measurements); finish('blocked', 'Falta la referencia de este par.'); continue; }
+        if (!approval || approval.digest !== reference.digest) { entry.aspects.push(...measurements); finish('blocked', approval ? 'La referencia cambió después de aprobarse; vuelve a aprobarla.' : 'La referencia no está aprobada.'); continue; }
+      }
+      if (!reference) { entry.aspects.push(...measurements); finish(measurements.some(m => m.verdict === 'fail') ? 'fail' : 'inconclusive', 'Sin referencia: sólo mediciones.'); continue; }
+      entry.mode = reference.mode;
+      images.reference = `${base}.reference.png`;
+      await fs.writeFile(images.reference, reference.png);
+      const refImage = decodePng(reference.png), capImage = decodePng(shot.capture);
+      if (reference.mode === 'exact') {
+        const differences = reference.meta.fingerprint ? fingerprintDifferences(reference.meta.fingerprint, shot.fingerprint) : ['fingerprint'];
+        if (differences.length) { entry.aspects.push(...measurements); finish('not_comparable', `El entorno de captura cambió (${differences.join(', ')}); recaptura y vuelve a aprobar la referencia.`); continue; }
+        const pixel = comparePixels(refImage, capImage, reference.meta.tolerance);
+        entry.pixel = pixel.reason ? { reason: pixel.reason } : { mismatched: pixel.mismatched, antialiased: pixel.antialiased, ratio: pixel.ratio, bounds: pixel.bounds };
+        if (pixel.diff) { images.diff = `${base}.diff.png`; await fs.writeFile(images.diff, encodePng(pixel.diff)); }
+        entry.aspects.push({ id: 'pixels', verdict: pixel.passed ? 'pass' : 'fail',
+          reason: pixel.reason === 'dimension_mismatch' ? `Tamaño distinto: referencia ${refImage.width}x${refImage.height}, captura ${capImage.width}x${capImage.height}.`
+            : pixel.passed ? `Coincide (${pixel.mismatched} píxeles distintos, ${pixel.antialiased} de antialiasing tolerados).`
+            : `${pixel.mismatched} píxeles distintos en x=${pixel.bounds.x}, y=${pixel.bounds.y}, ${pixel.bounds.width}x${pixel.bounds.height}.` }, ...measurements);
+      } else {
+        if (pair.kind === 'live') {
+          const drift = outsideRatio(refImage, capImage, scaleBox(box, spec.viewport.deviceScaleFactor));
+          if (drift > SITE_DRIFT_RATIO) { entry.aspects.push(...measurements); finish('inconclusive', `El sitio vivo cambió: ${(drift * 100).toFixed(1)}% de píxeles distintos fuera del componente (site_drift).`); continue; }
+        }
+        if (typeof judge !== 'function') {
+          entry.aspects.push(...measurements);
+          // Inspection never calls the reviewer; only an acceptance run without one is blocked.
+          if (mode === 'inspection') finish(measurements.some(m => m.verdict === 'fail') ? 'fail' : 'inconclusive', 'Inspección: el revisor independiente juzga los pares mockup sólo en VisualVerify; aquí sólo hay mediciones.');
+          else finish('blocked', 'No hay revisor visual independiente configurado.');
+          continue;
+        }
+        const verdict = await judge({ reference: reference.png, capture: shot.capture, criteria: criteria.filter(c => c.kind === 'judged' && applies(c)), measurements,
+          context: { component, fixture: pair.fixture, state: pair.state, origin: fixture.kind === 'live' ? fixture.url : server.urlFor(fixture.id), ...(box ? { component_box: box } : {}) }, signal });
+        entry.judge = { model: verdict.model ?? null, independent_model: verdict.independent_model ?? null, summary: verdict.summary ?? null };
+        entry.aspects.push(...verdict.aspects, ...measurements);
+        if (verdict.verdict === 'blocked') { finish('blocked', verdict.reason); continue; }
+      }
+      const verdicts = entry.aspects.map(a => a.verdict);
+      finish(verdicts.length && verdicts.every(v => v === 'pass') ? 'pass' : verdicts.includes('fail') ? 'fail' : 'inconclusive', null);
+    }
+  } finally { await server?.close(); }
+  for (const entry of results) {
+    const shot = captures.get(entry.key);
+    const panels = [entry.images.reference ? await fs.readFile(entry.images.reference) : null, shot.capture, entry.images.diff ? await fs.readFile(entry.images.diff) : null];
+    const image = composite(panels, focusOf(scaleBox(entry.component_box, spec.viewport.deviceScaleFactor), entry.pixel?.bounds));
+    if (image) { entry.images.composite = path.join(dir, `${entry.key}.composite.png`); await fs.writeFile(entry.images.composite, image); }
+  }
+  const verdict = mode !== 'acceptance' ? null : effective.invalid_entries
+    ? { status: 'blocked', reason: `El registro de aprobaciones tiene ${effective.invalid_entries} entrada(s) inválida(s).` }
+    : !setupApproved ? { status: 'blocked', reason: effective.setup ? 'La configuración del componente (spec o fixtures) cambió después de aprobarse; revísala y apruébala con /visual approve-setup.' : 'La configuración del componente (spec y fixtures) no está aprobada: /visual approve-setup.' }
+    : overall(results);
+  const result = { kind: mode, status: verdict ? verdict.status : 'inspected', reason: verdict ? verdict.reason : null,
+    component, run_id: runId, build_digest, setup_digest, setup_approved: setupApproved, references_digest: referencesDigest(references), criteria_digest: criteriaDigest(confirmed),
+    fingerprint, fingerprint_digest: fingerprint ? fingerprintDigest(fingerprint) : null,
+    criteria: criteria.map(c => c.id), pending_criteria: pending.map(c => ({ id: c.id, statement: c.statement })), proposal_errors: inventory.proposalErrors,
+    ledger_invalid_entries: effective.invalid_entries, pairs: results, observed_files, evidence_dir: path.relative(cwd, dir) };
+  result.report = path.relative(cwd, await writeReport(dir, result));
+  for (const entry of results) for (const key of Object.keys(entry.images)) entry.images[key] = path.relative(cwd, entry.images[key]);
+  result.captures = captures;
+  return result;
+}
+
+export const MAQUETTE_PATH = '/__comal_maquette__.html';
+
+/**
+ * Render a static maquette (the fixture page with the component drawn by hand)
+ * at the fixture's origin, without loading the extension, in the component
+ * viewport. Its capture can become an exact reference once the human approves it.
+ */
+export async function captureMaquette({ cwd, stateDir, component, fixture: fixtureId, file, chromeBinary = defaultChromeBinary(), signal }) {
+  const inventory = await componentInventory(cwd, component), spec = inventory.spec;
+  const fixture = spec.fixtures.find(f => f.id === fixtureId);
+  if (!fixture || fixture.kind === 'live') throw Object.assign(new Error(`La maqueta necesita un fixture local o congelado del componente; ${fixtureId} no lo es.`), { code: 'VISUAL_MAQUETTE_INVALID' });
+  const resolved = await confinedPath(cwd, file, 'maqueta');
+  const origin = (await readFixture(fixture.dir)).origin;
+  const server = await startFixtureServer({ fixtures: [fixture.dir], stateDir, overlays: [{ origin, path: MAQUETTE_PATH, file: resolved }] });
+  try {
+    const session = await launchChrome({ binary: chromeBinary, viewport: spec.viewport, hostRules: server.hostRules({ offline: true }), ignoreCertificateErrors: true, signal });
+    try {
+      const page = await session.openPage();
+      await page.navigate(origin + MAQUETTE_PATH);
+      return { capture: await page.screenshot(), origin, fingerprint: environmentFingerprint({ version: session.version, viewport: spec.viewport, headless: session.headless }) };
+    } finally { await session.close(); }
+  } finally { await server.close(); }
+}
+
+/** Write a proposed reference for a pair from a capture; it does not count until the human approves it. */
+export async function writeReferenceDraft({ cwd, component, fixture, state, mode, png, fingerprint, source, tolerance }) {
+  if (!['exact', 'mockup'].includes(mode)) throw Object.assign(new Error('mode debe ser exact o mockup'), { code: 'VISUAL_REFERENCE_INVALID' });
+  const paths = referencePaths(cwd, component, pairKey(fixture, state));
+  await fs.mkdir(path.dirname(paths.png), { recursive: true });
+  const meta = { mode, ...(mode === 'exact' ? { fingerprint, ...(tolerance ? { tolerance } : {}) } : {}), source, captured_at: new Date().toISOString() };
+  await fs.writeFile(paths.png, png);
+  await fs.writeFile(paths.meta, JSON.stringify(meta, null, 2) + '\n');
+  const reference = await readReference(cwd, component, pairKey(fixture, state));
+  return { png: path.relative(cwd, paths.png), meta: path.relative(cwd, paths.meta), sha256: sha256(png), digest: reference.digest };
+}