@milpa/comal 0.2.2 → 0.2.3

package/src/visual/chrome.mjs

@@ -0,0 +1,379 @@
+// House-owned Chrome driver for visual acceptance. Launches the local stable
+// Chrome with a throwaway profile and speaks CDP over --remote-debugging-pipe,
+// which also enables Extensions.loadUnpacked (branded Chrome dropped
+// --load-extension). Selectors pierce shadow roots (open or closed) and enter
+// iframes, including out-of-process extension frames, with ` >>> ` segments.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const CANDIDATES = ['/usr/bin/google-chrome-stable', '/usr/bin/google-chrome', '/opt/google/chrome/chrome', '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'];
+export function defaultChromeBinary(env = process.env) { return env.COMAL_VISUAL_CHROME || CANDIDATES.find(file => existsSync(file)) || CANDIDATES[0]; }
+
+const fail = (message, code = 'VISUAL_CHROME', extra = {}) => Object.assign(new Error(message), { code, ...extra });
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+
+class CdpPipe {
+  constructor(child) {
+    this.out = child.stdio[3]; this.id = 0; this.pending = new Map(); this.listeners = new Set(); this.buffer = ''; this.closed = null;
+    child.stdio[4].setEncoding('utf8');
+    child.stdio[4].on('data', chunk => {
+      this.buffer += chunk;
+      for (let end = this.buffer.indexOf('\0'); end >= 0; end = this.buffer.indexOf('\0')) {
+        const message = JSON.parse(this.buffer.slice(0, end)); this.buffer = this.buffer.slice(end + 1);
+        if (message.id !== undefined && this.pending.has(message.id)) { const entry = this.pending.get(message.id); this.pending.delete(message.id); entry.settle(message); }
+        else for (const listener of [...this.listeners]) listener(message);
+      }
+    });
+    this.out.on('error', () => {});
+  }
+  send(method, params = {}, sessionId, timeoutMs = 30000) {
+    if (this.closed) return Promise.reject(this.closed);
+    const id = ++this.id;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { this.pending.delete(id); reject(fail(`CDP ${method} no respondió en ${timeoutMs} ms.`, 'VISUAL_CDP_TIMEOUT')); }, timeoutMs);
+      this.pending.set(id, { settle: message => { clearTimeout(timer); message.error ? reject(fail(`CDP ${method}: ${message.error.message}`, 'VISUAL_CDP_ERROR', { cdp: message.error })) : resolve(message.result); },
+        reject: error => { clearTimeout(timer); reject(error); } });
+      this.out.write(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }) + '\0');
+    });
+  }
+  on(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+  waitFor(predicate, timeoutMs, label) {
+    return new Promise((resolve, reject) => {
+      const off = this.on(message => { if (predicate(message)) { clearTimeout(timer); off(); resolve(message); } });
+      const timer = setTimeout(() => { off(); reject(fail(`${label} no ocurrió en ${timeoutMs} ms.`, 'VISUAL_CDP_TIMEOUT')); }, timeoutMs);
+    });
+  }
+  close(error) { this.closed = error; for (const entry of this.pending.values()) entry.reject(error); this.pending.clear(); }
+}
+
+const KEYS = Object.freeze({
+  Enter: { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, text: '\r' }, Escape: { key: 'Escape', code: 'Escape', windowsVirtualKeyCode: 27 },
+  Tab: { key: 'Tab', code: 'Tab', windowsVirtualKeyCode: 9 }, ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', windowsVirtualKeyCode: 40 },
+  ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', windowsVirtualKeyCode: 38 }, Backspace: { key: 'Backspace', code: 'Backspace', windowsVirtualKeyCode: 8 },
+});
+export const STEP_ACTIONS = Object.freeze(['click', 'hover', 'focus', 'type', 'key', 'wait', 'sleep', 'extension']);
+
+/** Validate a list of steps; throws with the offending index. */
+export function normalizeSteps(steps) {
+  if (!Array.isArray(steps) || steps.length > 100) throw fail('Los pasos deben ser una lista de como máximo 100.', 'VISUAL_STEP_INVALID');
+  return steps.map((step, index) => {
+    const bad = message => fail(`Paso ${index} inválido: ${message}`, 'VISUAL_STEP_INVALID');
+    if (!step || typeof step !== 'object' || !STEP_ACTIONS.includes(step.action)) throw bad(`action debe ser ${STEP_ACTIONS.join(', ')}`);
+    const allowed = { click: ['selector'], hover: ['selector'], focus: ['selector'], type: ['text', 'selector'], key: ['key'], wait: ['selector', 'state', 'timeout_ms'], sleep: ['ms'], extension: ['expression'] }[step.action];
+    for (const key of Object.keys(step)) if (key !== 'action' && !allowed.includes(key)) throw bad(`campo desconocido ${key}`);
+    const selector = value => typeof value === 'string' && value.trim() && value.length <= 1000;
+    if (['click', 'hover', 'focus', 'wait'].includes(step.action) && !selector(step.selector)) throw bad('selector requerido');
+    if (step.action === 'type' && (typeof step.text !== 'string' || step.text.length > 500 || step.selector !== undefined && !selector(step.selector))) throw bad('text de hasta 500 caracteres');
+    if (step.action === 'key' && !(step.key in KEYS)) throw bad(`key en ${Object.keys(KEYS).join(', ')}`);
+    if (step.action === 'wait' && (!['present', 'visible', 'absent'].includes(step.state ?? 'visible') || step.timeout_ms !== undefined && !(Number.isSafeInteger(step.timeout_ms) && step.timeout_ms > 0 && step.timeout_ms <= 15000))) throw bad('state present|visible|absent y timeout_ms <= 15000');
+    if (step.action === 'sleep' && !(Number.isSafeInteger(step.ms) && step.ms >= 0 && step.ms <= 5000)) throw bad('ms entre 0 y 5000');
+    if (step.action === 'extension' && (typeof step.expression !== 'string' || !step.expression.trim() || step.expression.length > 20000)) throw bad('expression requerida');
+    return Object.freeze({ ...step });
+  });
+}
+
+const FACTS_FN = `function(props){const r=this.getBoundingClientRect(),cs=getComputedStyle(this),styles={};for(const p of props)styles[p]=cs.getPropertyValue(p);
+const backgrounds=[];let n=this,guard=0;while(n&&guard++<200){if(n.nodeType===1)backgrounds.push(getComputedStyle(n).backgroundColor);n=n.parentNode||n.host||null;}
+return{box:{x:r.left,y:r.top,width:r.width,height:r.height},styles,backgrounds};}`;
+const VISIBLE_FN = `function(){const r=this.getBoundingClientRect(),cs=getComputedStyle(this);return r.width>0&&r.height>0&&cs.visibility!=='hidden'&&cs.display!=='none'&&Number(cs.opacity)>0;}`;
+const FRAME_OFFSET_FN = `function(){const r=this.getBoundingClientRect(),cs=getComputedStyle(this);return{x:r.left+this.clientLeft+parseFloat(cs.paddingLeft||'0'),y:r.top+this.clientTop+parseFloat(cs.paddingTop||'0')};}`;
+const PAINT_FN = `function(){const cs=getComputedStyle(this);if(cs.display==='none'||cs.visibility==='hidden'||Number(cs.opacity)===0)return null;
+const r=this.getBoundingClientRect();if(!(r.width>0&&r.height>0))return null;const tag=this.localName,reasons=[];
+const clear=c=>c==='transparent'||/rgba\\([^)]*,\\s*0\\)$/.test(c);
+if(['img','canvas','video','svg','iframe','object','embed','picture','frame'].includes(tag))reasons.push(tag);
+if(!clear(cs.backgroundColor))reasons.push('background');if(cs.backgroundImage!=='none')reasons.push('background-image');
+if(['Top','Right','Bottom','Left'].some(s=>parseFloat(cs['border'+s+'Width'])>0&&cs['border'+s+'Style']!=='none'&&!clear(cs['border'+s+'Color'])))reasons.push('border');
+if(cs.boxShadow!=='none')reasons.push('box-shadow');if(cs.outlineStyle!=='none'&&parseFloat(cs.outlineWidth)>0)reasons.push('outline');
+if([...this.childNodes].some(n=>n.nodeType===3&&n.data.trim()))reasons.push('text');
+for(const p of ['::before','::after']){const ps=getComputedStyle(this,p);if(ps.content&&ps.content!=='none'&&ps.content!=='normal')reasons.push(p);}
+return reasons.length?{x:r.left,y:r.top,width:r.width,height:r.height,tag,reasons}:null;}`;
+const round = value => Math.round(value * 100) / 100;
+
+export class Page {
+  constructor(session, targetId, sessionId) { this.session = session; this.cdp = session.cdp; this.targetId = targetId; this.sessionId = sessionId; this.frames = new Map(); }
+  async init() {
+    const { viewport } = this.session;
+    this.off = this.cdp.on(message => {
+      if (message.method === 'Target.attachedToTarget' && (message.sessionId === this.sessionId || [...this.frames.values()].includes(message.sessionId))) {
+        const { sessionId, targetInfo } = message.params;
+        if (targetInfo.type === 'iframe') { this.frames.set(targetInfo.targetId, sessionId); this.cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true }, sessionId).catch(() => {}); }
+      }
+      if (message.method === 'Target.detachedFromTarget') for (const [frame, sid] of this.frames) if (sid === message.params.sessionId) this.frames.delete(frame);
+    });
+    await this.cdp.send('Page.enable', {}, this.sessionId);
+    await this.cdp.send('Emulation.setDeviceMetricsOverride', { width: viewport.width, height: viewport.height, deviceScaleFactor: viewport.deviceScaleFactor ?? 1, mobile: false }, this.sessionId);
+    await this.cdp.send('Target.setAutoAttach', { autoAttach: true, waitForDebuggerOnStart: false, flatten: true }, this.sessionId);
+    return this;
+  }
+  async navigate(url, { timeoutMs = 30000 } = {}) {
+    const loaded = this.cdp.waitFor(m => m.method === 'Page.loadEventFired' && m.sessionId === this.sessionId, timeoutMs, `Carga de ${url}`);
+    const result = await this.cdp.send('Page.navigate', { url }, this.sessionId, timeoutMs);
+    if (result.errorText) { loaded.catch(() => {}); throw fail(`No se pudo abrir ${url}: ${result.errorText}`, 'VISUAL_NAVIGATION_FAILED'); }
+    await loaded;
+    await this.evaluate('document.fonts ? document.fonts.ready.then(() => true) : true');
+  }
+  async evaluate(expression, sessionId = this.sessionId) {
+    const result = await this.cdp.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId);
+    if (result.exceptionDetails) throw fail(`La expresión falló: ${result.exceptionDetails.exception?.description || result.exceptionDetails.text}`, 'VISUAL_EVALUATE_FAILED');
+    return result.result.value;
+  }
+  async frameSession(frameId, timeoutMs = 5000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) { if (this.frames.has(frameId)) return this.frames.get(frameId); await sleep(50); }
+    return null;
+  }
+  async call(handle, functionDeclaration, args = []) {
+    // backendNodeId is stable for the node's lifetime; frontend nodeIds are
+    // invalidated by every DOM.getDocument and are only used transiently.
+    const { object } = await this.cdp.send('DOM.resolveNode', { backendNodeId: handle.backendNodeId }, handle.session);
+    try {
+      const result = await this.cdp.send('Runtime.callFunctionOn', { objectId: object.objectId, functionDeclaration, arguments: args.map(value => ({ value })), returnByValue: true, awaitPromise: true }, handle.session);
+      if (result.exceptionDetails) throw fail(`Falló en el elemento: ${result.exceptionDetails.exception?.description || result.exceptionDetails.text}`, 'VISUAL_EVALUATE_FAILED');
+      return result.result.value;
+    } finally { this.cdp.send('Runtime.releaseObject', { objectId: object.objectId }, handle.session).catch(() => {}); }
+  }
+  /** Resolve a piercing selector to a handle {session, backendNodeId, offset}, or null. */
+  async handle(selector, from = null) {
+    try { return await this.#handle(selector, from); }
+    catch (error) {
+      // A document replaced mid-resolution (an iframe finishing its navigation)
+      // invalidates node ids: the element is not there yet, which is not an error.
+      if (error.code === 'VISUAL_CDP_ERROR' && /Could not find node|No node with given id|Cannot find context|No frame|Node is detached/i.test(error.message)) return null;
+      throw error;
+    }
+  }
+  async #handle(selector, from) {
+    const segments = String(selector).split('>>>').map(s => s.trim());
+    if (!segments.length || segments.some(s => !s)) throw fail(`Selector inválido: ${selector}`, 'VISUAL_SELECTOR_INVALID');
+    let session = from?.session ?? this.sessionId, offset = { ...(from?.offset ?? { x: 0, y: 0 }) };
+    const root = (await this.cdp.send('DOM.getDocument', { depth: 0 }, session)).root.nodeId;
+    const push = async (backendNodeId, sid) => (await this.cdp.send('DOM.pushNodesByBackendIdsToFrontend', { backendNodeIds: [backendNodeId] }, sid)).nodeIds[0];
+    let node = from ? await push(from.backendNodeId, session) : root;
+    if (!node) return null;
+    for (let i = 0; i < segments.length; i++) {
+      let found;
+      try { found = (await this.cdp.send('DOM.querySelector', { nodeId: node, selector: segments[i] }, session)).nodeId; }
+      // CDP reports a querySelector SyntaxError as a generic "DOM Error while querying".
+      catch (error) { if (/DOM Error while querying|not valid selector|SyntaxError/i.test(error.message)) throw fail(`Selector CSS inválido: ${segments[i]}`, 'VISUAL_SELECTOR_INVALID'); return null; }
+      if (!found) return null;
+      const described = (await this.cdp.send('DOM.describeNode', { nodeId: found, depth: 1, pierce: true }, session)).node;
+      if (i === segments.length - 1) return { session, backendNodeId: described.backendNodeId, offset };
+      if (described.shadowRoots?.length) { node = await push(described.shadowRoots[0].backendNodeId, session); continue; }
+      if (described.nodeName === 'IFRAME' || described.nodeName === 'FRAME') {
+        const frameOffset = await this.call({ session, backendNodeId: described.backendNodeId }, FRAME_OFFSET_FN);
+        offset = { x: offset.x + frameOffset.x, y: offset.y + frameOffset.y };
+        if (described.contentDocument) { node = await push(described.contentDocument.backendNodeId, session); continue; }
+        const child = described.frameId && await this.frameSession(described.frameId);
+        if (!child) return null;
+        session = child; node = (await this.cdp.send('DOM.getDocument', { depth: 0 }, child)).root.nodeId; continue;
+      }
+      return null;
+    }
+    return null;
+  }
+  async resolve(selector) { const handle = await this.handle(selector); return handle ? handle.backendNodeId : null; }
+  async visible(selector) { const handle = await this.handle(selector); return handle ? Boolean(await this.call(handle, VISIBLE_FN)) : false; }
+  async box(handle) {
+    const facts = await this.call(handle, FACTS_FN, [[]]);
+    return { x: round(facts.box.x + handle.offset.x), y: round(facts.box.y + handle.offset.y), width: round(facts.box.width), height: round(facts.box.height) };
+  }
+  async facts({ root, elements = [], anchors = [], properties = [] }) {
+    const rootHandle = await this.handle(root);
+    const result = { elements: {}, anchors: {} };
+    const collect = async handle => {
+      const facts = await this.call(handle, FACTS_FN, [properties]);
+      return { box: { x: round(facts.box.x + handle.offset.x), y: round(facts.box.y + handle.offset.y), width: round(facts.box.width), height: round(facts.box.height) }, styles: facts.styles, backgrounds: facts.backgrounds };
+    };
+    if (rootHandle) {
+      result.elements.root = await collect(rootHandle);
+      for (const selector of elements) { const handle = await this.handle(selector, rootHandle); if (handle) result.elements[selector] = await collect(handle); }
+    }
+    for (const selector of anchors) { const handle = await this.handle(selector); if (handle) result.anchors[selector] = { box: (await collect(handle)).box }; }
+    return result;
+  }
+  /**
+   * Every rendered element of the page (pierced shadow roots, same-process
+   * frames) with a structural signature: ancestor tags, ids and classes, no
+   * sibling indexes, so inserting extension nodes does not rename page nodes.
+   */
+  async elements() {
+    const { root } = await this.cdp.send('DOM.getDocument', { depth: -1, pierce: true }, this.sessionId);
+    const out = [], SKIP = new Set(['head', 'script', 'style', 'template', 'noscript', 'link', 'meta', 'title', 'base']);
+    const visit = (node, path, frames) => {
+      if (node.nodeType === 1) {
+        if (SKIP.has(node.localName)) return;
+        const attrs = {}; for (let i = 0; i + 1 < (node.attributes || []).length; i += 2) attrs[node.attributes[i]] = node.attributes[i + 1];
+        path = `${path}/${node.localName}${attrs.id ? '#' + attrs.id : ''}${attrs.class?.trim() ? '.' + attrs.class.trim().split(/\s+/).sort().join('.') : ''}`;
+        out.push({ signature: path, backendNodeId: node.backendNodeId, frames });
+        if (out.length > 20000) throw fail('La página tiene más de 20000 elementos.', 'VISUAL_PAGE_TOO_LARGE');
+      }
+      for (const child of node.children || []) visit(child, path, frames);
+      for (const shadow of node.shadowRoots || []) visit(shadow, path + '/#shadow', frames);
+      if (node.contentDocument) visit(node.contentDocument, path + '/#document', [...frames, node.backendNodeId]);
+    };
+    visit(root, '', []);
+    return out;
+  }
+  async #elementHandle(entry) {
+    let offset = { x: 0, y: 0 };
+    for (const frame of entry.frames) { const o = await this.call({ session: this.sessionId, backendNodeId: frame }, FRAME_OFFSET_FN); offset = { x: offset.x + o.x, y: offset.y + o.y }; }
+    return { session: this.sessionId, backendNodeId: entry.backendNodeId, offset };
+  }
+  /** Border box of an element() entry in page coordinates, or null when it has none. */
+  async rectOf(entry) {
+    try { const box = await this.box(await this.#elementHandle(entry)); return box.width > 0 && box.height > 0 ? box : null; }
+    catch (error) { if (error.code === 'VISUAL_CDP_ERROR') return null; throw error; }
+  }
+  /** Box of an element() entry when it visibly paints something (background, image, media, border, text, shadow or pseudo content). */
+  async paintOf(entry) {
+    try {
+      const handle = await this.#elementHandle(entry), painted = await this.call(handle, PAINT_FN);
+      return painted && { ...painted, x: round(painted.x + handle.offset.x), y: round(painted.y + handle.offset.y), width: round(painted.width), height: round(painted.height) };
+    } catch (error) { if (error.code === 'VISUAL_CDP_ERROR') return null; throw error; }
+  }
+  async screenshot({ clip } = {}) {
+    let params = { format: 'png', captureBeyondViewport: false };
+    if (clip) {
+      const metrics = await this.cdp.send('Page.getLayoutMetrics', {}, this.sessionId), view = metrics.cssLayoutViewport || { pageX: 0, pageY: 0 };
+      const x = Math.floor(clip.x), y = Math.floor(clip.y), width = Math.ceil(clip.x + clip.width) - x, height = Math.ceil(clip.y + clip.height) - y;
+      if (width < 1 || height < 1) throw fail('El recorte de la captura está vacío.', 'VISUAL_CLIP_EMPTY');
+      params = { ...params, clip: { x: x + (view.pageX || 0), y: y + (view.pageY || 0), width, height, scale: 1 } };
+    }
+    const shot = await this.cdp.send('Page.captureScreenshot', params, this.sessionId);
+    return Buffer.from(shot.data, 'base64');
+  }
+  // Centre of the element in main-viewport coordinates. When it is outside the
+  // viewport, scroll it in (inside its frame, then the page) and resolve the
+  // handle again: frame offsets change with every scroll.
+  async pointer(selector, type) {
+    const view = this.session.viewport;
+    const inView = b => b.width > 0 && b.height > 0 && b.x + b.width / 2 >= 0 && b.y + b.height / 2 >= 0 && b.x + b.width / 2 <= view.width && b.y + b.height / 2 <= view.height;
+    let handle = await this.required(selector), box = await this.box(handle);
+    if (!inView(box) && box.width > 0 && box.height > 0) {
+      await this.call(handle, "function(){this.scrollIntoView({block:'center',inline:'center'});}");
+      handle = await this.required(selector); box = await this.box(handle);
+      if (!inView(box)) {
+        await this.evaluate(`window.scrollBy(${Math.round(box.x + box.width / 2 - view.width / 2)}, ${Math.round(box.y + box.height / 2 - view.height / 2)})`);
+        handle = await this.required(selector); box = await this.box(handle);
+      }
+    }
+    if (!(box.width > 0 && box.height > 0)) throw fail(`${selector} no tiene caja visible para el puntero.`, 'VISUAL_STEP_FAILED');
+    if (!inView(box)) throw fail(`${selector} sigue fuera del viewport después de desplazarlo; no se hizo clic.`, 'VISUAL_STEP_FAILED');
+    const x = box.x + box.width / 2, y = box.y + box.height / 2;
+    await this.cdp.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y }, this.sessionId);
+    if (type === 'click') {
+      await this.cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, this.sessionId);
+      await this.cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, this.sessionId);
+    }
+  }
+  async required(selector) { const handle = await this.handle(selector); if (!handle) throw fail(`No se encontró ${selector}.`, 'VISUAL_STEP_FAILED'); return handle; }
+  async runSteps(input) {
+    for (const step of normalizeSteps(input)) {
+      if (step.action === 'click' || step.action === 'hover') await this.pointer(step.selector, step.action);
+      else if (step.action === 'focus') await this.call(await this.required(step.selector), 'function(){this.focus();}');
+      else if (step.action === 'type') {
+        if (step.selector) await this.call(await this.required(step.selector), 'function(){this.focus();}');
+        for (const ch of step.text) {
+          await this.cdp.send('Input.dispatchKeyEvent', { type: 'keyDown', text: ch, unmodifiedText: ch, key: ch }, this.sessionId);
+          await this.cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: ch }, this.sessionId);
+        }
+      } else if (step.action === 'key') {
+        const key = KEYS[step.key];
+        await this.cdp.send('Input.dispatchKeyEvent', { type: key.text ? 'keyDown' : 'rawKeyDown', ...key }, this.sessionId);
+        await this.cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', key: key.key, code: key.code, windowsVirtualKeyCode: key.windowsVirtualKeyCode }, this.sessionId);
+      } else if (step.action === 'wait') {
+        const state = step.state ?? 'visible', timeout = step.timeout_ms ?? 5000, deadline = Date.now() + timeout;
+        for (;;) {
+          const ok = state === 'present' ? (await this.resolve(step.selector)) !== null : state === 'absent' ? (await this.resolve(step.selector)) === null : await this.visible(step.selector);
+          if (ok) break;
+          if (Date.now() >= deadline) throw fail(`Espera agotada: ${step.selector} no llegó a "${state}" en ${timeout} ms.`, 'VISUAL_WAIT_TIMEOUT');
+          await sleep(100);
+        }
+      } else if (step.action === 'sleep') await sleep(step.ms);
+      else if (step.action === 'extension') {
+        if (!this.session.extensionId) throw fail('El paso extension requiere una extensión cargada.', 'VISUAL_STEP_FAILED');
+        await this.session.evaluateInExtension(this.session.extensionId, step.expression);
+      }
+    }
+  }
+  async close() { this.off?.(); await this.cdp.send('Target.closeTarget', { targetId: this.targetId }).catch(() => {}); }
+}
+
+export class ChromeSession {
+  constructor({ child, cdp, profile, version, viewport, headless }) { Object.assign(this, { child, cdp, profile, version, viewport, headless, extensionId: null }); }
+  async loadExtension(dir) {
+    const { id } = await this.cdp.send('Extensions.loadUnpacked', { path: path.resolve(dir) });
+    this.extensionId = id; return id;
+  }
+  async evaluateInExtension(extensionId, expression, { timeoutMs = 10000 } = {}) {
+    const prefix = `chrome-extension://${extensionId}/`, deadline = Date.now() + 10000;
+    const find = async () => (await this.cdp.send('Target.getTargets')).targetInfos.find(info => info.type === 'service_worker' && info.url.startsWith(prefix));
+    // MV3 workers start on demand; wake an idle one through a helper page.
+    let target = await find(), helper = null, woke = 0;
+    try {
+      while (!target && Date.now() < deadline) {
+        if (Date.now() - woke > 1000) {
+          helper ??= await this.openPage();
+          await this.cdp.send('ServiceWorker.enable', {}, helper.sessionId).catch(() => {});
+          await this.cdp.send('ServiceWorker.startWorker', { scopeURL: prefix }, helper.sessionId).catch(() => {});
+          woke = Date.now();
+        }
+        await sleep(100); target = await find();
+      }
+    } finally { await helper?.close(); }
+    if (!target) throw fail(`La extensión ${extensionId} no tiene un service worker activo; el paso extension lo requiere.`, 'VISUAL_EXTENSION_WORKER_MISSING');
+    const { sessionId } = await this.cdp.send('Target.attachToTarget', { targetId: target.targetId, flatten: true });
+    try {
+      const result = await this.cdp.send('Runtime.evaluate', { expression, awaitPromise: true, returnByValue: true }, sessionId, timeoutMs);
+      if (result.exceptionDetails) throw fail(`La expresión de la extensión falló: ${result.exceptionDetails.exception?.description || result.exceptionDetails.text}`, 'VISUAL_EVALUATE_FAILED');
+      return result.result.value;
+    } finally { await this.cdp.send('Target.detachFromTarget', { sessionId }).catch(() => {}); }
+  }
+  async openPage() {
+    const { targetId } = await this.cdp.send('Target.createTarget', { url: 'about:blank' });
+    const { sessionId } = await this.cdp.send('Target.attachToTarget', { targetId, flatten: true });
+    return new Page(this, targetId, sessionId).init();
+  }
+  async close() {
+    if (this.closing) return this.closing;
+    this.releaseSignal?.();
+    this.closing = (async () => {
+      const exited = this.child.exitCode !== null || this.child.signalCode !== null ? Promise.resolve() : new Promise(resolve => this.child.once('exit', resolve));
+      await this.cdp.send('Browser.close', {}, undefined, 3000).catch(() => {});
+      const timer = setTimeout(() => this.child.kill('SIGKILL'), 3000);
+      await exited; clearTimeout(timer);
+      await fs.rm(this.profile, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(() => {});
+    })();
+    return this.closing;
+  }
+}
+
+export async function launchChrome({ binary = defaultChromeBinary(), viewport = { width: 1280, height: 800, deviceScaleFactor: 1 }, hostRules = [], ignoreCertificateErrors = false, headless = true, signal } = {}) {
+  if (!existsSync(binary)) throw fail(`No existe el binario de Chrome ${binary}. Define COMAL_VISUAL_CHROME.`, 'VISUAL_CHROME_MISSING');
+  signal?.throwIfAborted();
+  const profile = await fs.mkdtemp(path.join(os.tmpdir(), 'comal-visual-'));
+  const args = [...(headless ? ['--headless=new'] : []), '--remote-debugging-pipe', '--enable-unsafe-extension-debugging', `--user-data-dir=${profile}`,
+    '--no-first-run', '--no-default-browser-check', '--disable-component-update', '--disable-sync', '--disable-background-networking', '--password-store=basic',
+    '--hide-scrollbars', '--force-color-profile=srgb', `--window-size=${viewport.width},${viewport.height}`,
+    ...(hostRules.length ? [`--host-resolver-rules=${hostRules.join(',')}`] : []), ...(ignoreCertificateErrors ? ['--ignore-certificate-errors'] : []), 'about:blank'];
+  const child = spawn(binary, args, { stdio: ['ignore', 'ignore', 'pipe', 'pipe', 'pipe'] });
+  let stderr = '';
+  child.stderr.on('data', chunk => { stderr = (stderr + chunk).slice(-4000); });
+  const cdp = new CdpPipe(child);
+  child.once('exit', (code, signalName) => cdp.close(fail(`Chrome terminó (${code ?? signalName}). ${stderr.trim().split('\n').slice(-3).join(' ')}`, 'VISUAL_CHROME_EXITED')));
+  child.once('error', error => cdp.close(fail(`Chrome no arrancó: ${error.message}`, 'VISUAL_CHROME_EXITED')));
+  try {
+    const { product } = await cdp.send('Browser.getVersion', {}, undefined, 20000);
+    const session = new ChromeSession({ child, cdp, profile, version: product, viewport: { deviceScaleFactor: 1, ...viewport }, headless });
+    const onAbort = () => session.close();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    session.releaseSignal = () => signal?.removeEventListener('abort', onAbort);
+    return session;
+  } catch (error) {
+    child.kill('SIGKILL'); await fs.rm(profile, { recursive: true, force: true }).catch(() => {});
+    throw error;
+  }
+}

package/src/visual/fingerprint.mjs

@@ -0,0 +1,30 @@
+// Environment fingerprint for exact-mode references: two captures only compare
+// pixel by pixel when Chrome, platform, viewport, scale, headless mode and the
+// installed fonts are the same.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import os from 'node:os';
+
+let fontsCache;
+function fontsDigest() {
+  if (fontsCache !== undefined) return fontsCache;
+  const listed = spawnSync('fc-list', ['--format', '%{family}|%{style}|%{file}\n'], { encoding: 'utf8', timeout: 10000 });
+  fontsCache = listed.status === 0 ? createHash('sha256').update(listed.stdout.split('\n').filter(Boolean).sort().join('\n')).digest('hex') : null;
+  return fontsCache;
+}
+
+export function environmentFingerprint({ version, viewport, headless = true }) {
+  return Object.freeze({ chrome: version, platform: process.platform, release: os.release(), arch: process.arch,
+    viewport: { width: viewport.width, height: viewport.height }, device_scale_factor: viewport.deviceScaleFactor ?? 1,
+    headless: Boolean(headless), fonts_sha256: fontsDigest() });
+}
+
+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 fingerprintDigest = fingerprint => createHash('sha256').update(JSON.stringify(canonical(fingerprint))).digest('hex');
+
+/** Field names that differ, so a report can say why a pair is not comparable. */
+export function fingerprintDifferences(expected, actual) {
+  const keys = new Set([...Object.keys(expected || {}), ...Object.keys(actual || {})]);
+  return [...keys].filter(key => JSON.stringify(canonical(expected?.[key])) !== JSON.stringify(canonical(actual?.[key]))).sort();
+}

package/src/visual/fixtures.mjs

@@ -0,0 +1,201 @@
+// Fixture pages for visual acceptance. A local fixture is a directory with
+// fixture.json and static files; a frozen fixture is a recorded copy of a live
+// page. Both are served over HTTPS at their own origin: Chrome resolves the
+// fixture hosts to this server through --host-resolver-rules, so a frozen copy
+// of https://site.example/login keeps its origin and URLs need no rewriting.
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import fs from 'node:fs/promises';
+import https from 'node:https';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+const ID = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const fail = (message, code = 'VISUAL_FIXTURE_INVALID') => Object.assign(new Error(message), { code });
+const sha256 = bytes => createHash('sha256').update(bytes).digest('hex');
+const TYPES = { '.html': 'text/html; charset=utf-8', '.htm': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml', '.webp': 'image/webp',
+  '.ico': 'image/x-icon', '.woff': 'font/woff', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.otf': 'font/otf', '.txt': 'text/plain; charset=utf-8' };
+
+export async function readFixture(dir) {
+  let raw;
+  try { raw = JSON.parse(await fs.readFile(path.join(dir, 'fixture.json'), 'utf8')); }
+  catch (error) { throw fail(`Fixture sin fixture.json legible en ${dir}: ${error.message}`); }
+  if (!raw || typeof raw !== 'object' || !ID.test(raw.id || '')) throw fail(`Fixture ${dir}: id en minúsculas, dígitos o guiones.`);
+  const origin = raw.origin ?? `https://${raw.id}.fixture.test`;
+  let parsed;
+  try { parsed = new URL(origin); } catch { throw fail(`Fixture ${raw.id}: origin inválido.`); }
+  if (parsed.protocol !== 'https:' || parsed.origin !== origin || parsed.port) throw fail(`Fixture ${raw.id}: origin debe ser https://host sin puerto ni ruta.`);
+  const entry = raw.entry ?? '/';
+  if (typeof entry !== 'string' || !entry.startsWith('/')) throw fail(`Fixture ${raw.id}: entry debe empezar con /.`);
+  return { id: raw.id, origin, entry, frozen: raw.frozen ?? null, dir: await fs.realpath(dir) };
+}
+
+/** Self-signed certificate kept in stateDir/visual/tls; Chrome runs with --ignore-certificate-errors. */
+export async function fixtureCertificate(stateDir) {
+  const base = path.join(stateDir, 'visual'), dir = path.join(base, 'tls');
+  const read = async () => ({ key: await fs.readFile(path.join(dir, 'key.pem')), cert: await fs.readFile(path.join(dir, 'cert.pem')) });
+  try { return await read(); } catch {}
+  // Generate in a private directory and publish it with one atomic rename, so
+  // concurrent first runs never leave a mismatched key and certificate.
+  await fs.mkdir(base, { recursive: true, mode: 0o700 });
+  const temp = await fs.mkdtemp(path.join(base, 'tls-'));
+  try {
+    await run('openssl', ['req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-keyout', path.join(temp, 'key.pem'), '-out', path.join(temp, 'cert.pem'), '-days', '3650', '-subj', '/CN=comal-visual-fixtures'], { timeout: 30000 });
+    await fs.rename(temp, dir).catch(async error => {
+      if (!['ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error;
+      // Another run published first, or an old partial directory is in the way.
+      if (await read().then(() => true, () => false)) return;
+      await fs.rm(dir, { recursive: true, force: true });
+      await fs.rename(temp, dir);
+    });
+  } finally { await fs.rm(temp, { recursive: true, force: true }); }
+  return read();
+}
+
+async function frozenTable(fixture) {
+  const responses = JSON.parse(await fs.readFile(path.join(fixture.dir, 'responses.json'), 'utf8'));
+  if (!Array.isArray(responses)) throw fail(`Fixture ${fixture.id}: responses.json debe ser una lista.`);
+  const byHost = new Map();
+  for (const entry of responses) {
+    // Bodies are content-addressed: only a sha256 file name inside bodies/ is servable.
+    if (!entry || !/^[a-f0-9]{64}$/.test(entry.file || '') || typeof entry.url !== 'string') throw fail(`Fixture ${fixture.id}: entrada de responses.json inválida (file debe ser un sha256).`);
+    if (entry.status !== undefined && !(Number.isSafeInteger(entry.status) && entry.status >= 100 && entry.status <= 599)) throw fail(`Fixture ${fixture.id}: status inválido.`);
+    if (entry.content_type !== undefined && (typeof entry.content_type !== 'string' || entry.content_type.length > 200 || /[\r\n]/.test(entry.content_type))) throw fail(`Fixture ${fixture.id}: content_type inválido.`);
+    let url; try { url = new URL(entry.url); } catch { throw fail(`Fixture ${fixture.id}: url inválida en responses.json.`); }
+    if (url.protocol !== 'https:') throw fail(`Fixture ${fixture.id}: sólo respuestas https.`);
+    const host = url.host;
+    if (!byHost.has(host)) byHost.set(host, new Map());
+    byHost.get(host).set(url.pathname + url.search, entry);
+  }
+  return byHost;
+}
+
+/** overlays: [{origin, path, file}] serves one extra file at a fixture origin (maquettes). */
+export async function startFixtureServer({ fixtures, stateDir, overlays = [] }) {
+  const loaded = [];
+  for (const dir of fixtures) loaded.push(await readFixture(dir));
+  const ids = new Set();
+  for (const fixture of loaded) { if (ids.has(fixture.id)) throw fail(`Fixture duplicado ${fixture.id}.`); ids.add(fixture.id); }
+  const routes = new Map();
+  for (const fixture of loaded) {
+    if (fixture.frozen) for (const [host, table] of await frozenTable(fixture)) routes.set(host, { kind: 'frozen', fixture, table });
+    else routes.set(new URL(fixture.origin).host, { kind: 'local', fixture });
+  }
+  const misses = [];
+  const { key, cert } = await fixtureCertificate(stateDir);
+  const server = https.createServer({ key, cert }, async (req, res) => {
+    const host = String(req.headers.host || '').replace(/:\d+$/, ''), route = routes.get(host);
+    const notFound = () => { misses.push(`${host}${req.url}`); res.statusCode = 404; res.end(); };
+    try {
+      if (!route || !['GET', 'HEAD'].includes(req.method)) return notFound();
+      const url = new URL(req.url, `https://${host}`);
+      const overlay = overlays.find(o => new URL(o.origin).host === host && o.path === url.pathname);
+      if (overlay) { res.setHeader('content-type', TYPES[path.extname(overlay.file).toLowerCase()] || 'text/html; charset=utf-8'); return res.end(req.method === 'HEAD' ? undefined : await fs.readFile(overlay.file)); }
+      if (route.kind === 'frozen') {
+        const entry = route.table.get(url.pathname + url.search) || route.table.get(url.pathname);
+        if (!entry) return notFound();
+        const bodies = path.join(route.fixture.dir, 'bodies'), file = await fs.realpath(path.join(bodies, entry.file)).catch(() => null);
+        if (!file || path.dirname(file) !== await fs.realpath(bodies)) return notFound();
+        const body = await fs.readFile(file);
+        res.statusCode = entry.status || 200; res.setHeader('content-type', entry.content_type || 'application/octet-stream');
+        return res.end(req.method === 'HEAD' ? undefined : body);
+      }
+      let relative = decodeURIComponent(url.pathname);
+      if (relative.endsWith('/')) relative += 'index.html';
+      const candidate = path.resolve(route.fixture.dir, '.' + relative);
+      // Resolve symlinks: a served file must stay inside the fixture directory.
+      const file = await fs.realpath(candidate).catch(() => null);
+      if (!file || !file.startsWith(route.fixture.dir + path.sep) || path.basename(file) === 'fixture.json') return notFound();
+      const body = await fs.readFile(file).catch(() => null);
+      if (!body) return notFound();
+      res.setHeader('content-type', TYPES[path.extname(file).toLowerCase()] || 'application/octet-stream');
+      res.end(req.method === 'HEAD' ? undefined : body);
+    } catch { if (!res.headersSent) notFound(); else res.destroy(); }
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); });
+  const port = server.address().port;
+  return {
+    port, misses, fixtures: loaded,
+    hostRules: ({ offline = false } = {}) => [...[...routes.keys()].map(host => `MAP ${host} 127.0.0.1:${port}`), ...(offline ? ['MAP * ~NOTFOUND'] : [])],
+    urlFor(id, entry) { const fixture = loaded.find(f => f.id === id); if (!fixture) throw fail(`Fixture desconocido ${id}.`); return fixture.origin + (entry ?? fixture.entry); },
+    close: () => new Promise(resolve => { server.closeAllConnections?.(); server.close(() => resolve()); }),
+  };
+}
+
+// Runs inside each frame: serialises the live DOM without scripts or inline
+// handlers, open shadow roots as declarative templates and CSSOM-inserted rules.
+const SERIALIZE = `(() => {
+  const VOID = new Set(['area','base','br','col','embed','hr','img','input','link','meta','source','track','wbr']);
+  const esc = s => s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+  const attr = s => s.replace(/&/g,'&amp;').replace(/"/g,'&quot;');
+  const rules = sheet => { try { return [...sheet.cssRules].map(r => r.cssText).join('\\n'); } catch { return null; } };
+  const adopted = root => (root.adoptedStyleSheets || []).map(s => '<style data-comal-adopted>' + esc(rules(s) || '') + '</style>').join('');
+  const children = node => [...node.childNodes].map(ser).join('');
+  function ser(node) {
+    if (node.nodeType === 3) return node.parentNode && node.parentNode.localName === 'style' ? node.data : esc(node.data);
+    if (node.nodeType !== 1) return '';
+    const tag = node.localName;
+    if (tag === 'script' || tag === 'noscript') return '';
+    if (tag === 'meta' && /content-security-policy/i.test(node.getAttribute('http-equiv') || '')) return '';
+    if (tag === 'link' && /preload|modulepreload/i.test(node.rel || '') && /script/i.test(node.getAttribute('as') || node.rel)) return '';
+    let attrs = '';
+    for (const a of node.attributes) if (!/^on/i.test(a.name)) attrs += ' ' + a.name + '="' + attr(a.value) + '"';
+    if (tag === 'input' && node.value && node.type !== 'password' && !node.hasAttribute('value')) attrs += ' value="' + attr(node.value) + '"';
+    if (VOID.has(tag)) return '<' + tag + attrs + '>';
+    let inner = '';
+    if (node.shadowRoot && node.shadowRoot.mode === 'open') inner += '<template shadowrootmode="open">' + adopted(node.shadowRoot) + children(node.shadowRoot) + '</template>';
+    if (tag === 'style') { const text = node.sheet ? rules(node.sheet) : null; inner += text !== null && text !== node.textContent.trim() ? text : node.textContent; }
+    else inner += tag === 'template' ? children(node.content) : children(node);
+    return '<' + tag + attrs + '>' + inner + '</' + tag + '>';
+  }
+  const html = ser(document.documentElement);
+  return '<!doctype html>' + html.replace(/<\\/head>/, adopted(document) + '</head>');
+})()`;
+
+function frameTree(tree, out = []) { out.push(tree); for (const child of tree.childFrames || []) frameTree(child, out); return out; }
+
+/** Record a live page into dir as a frozen fixture and return its fixture.json. */
+export async function freezePage({ session, url, dir, id, settleMs = 1500, signal }) {
+  if (!ID.test(id || '')) throw fail('id de fixture inválido.');
+  const source = new URL(url);
+  if (source.protocol !== 'https:' || source.port) throw fail('Sólo se congelan páginas https sin puerto explícito.');
+  const page = await session.openPage();
+  try {
+    await page.navigate(url);
+    await new Promise(resolve => setTimeout(resolve, settleMs));
+    signal?.throwIfAborted();
+    await fs.mkdir(path.join(dir, 'bodies'), { recursive: true });
+    const responses = new Map();
+    const store = async (resourceUrl, body, contentType) => {
+      const clean = new URL(resourceUrl); clean.hash = '';
+      if (!/^https?:$/.test(clean.protocol)) return;
+      const file = sha256(body);
+      await fs.writeFile(path.join(dir, 'bodies', file), body);
+      responses.set(clean.href, { url: clean.href, status: 200, content_type: contentType, file });
+    };
+    const sessions = [page.sessionId, ...page.frames.values()];
+    for (const sid of sessions) {
+      const { frameTree: tree } = await page.cdp.send('Page.getResourceTree', {}, sid);
+      for (const node of frameTree(tree)) {
+        for (const resource of node.resources || []) {
+          if (['Script', 'Document'].includes(resource.type) || resource.failed || resource.canceled) continue;
+          const content = await page.cdp.send('Page.getResourceContent', { frameId: node.frame.id, url: resource.url }, sid).catch(() => null);
+          if (!content) continue;
+          await store(resource.url, Buffer.from(content.content, content.base64Encoded ? 'base64' : 'utf8'), resource.mimeType || 'application/octet-stream');
+        }
+        if (!/^https?:/.test(node.frame.url)) continue;
+        const { executionContextId } = await page.cdp.send('Page.createIsolatedWorld', { frameId: node.frame.id, worldName: 'comal-freeze' }, sid);
+        const result = await page.cdp.send('Runtime.evaluate', { expression: SERIALIZE, contextId: executionContextId, returnByValue: true }, sid);
+        if (result.exceptionDetails) throw fail(`No se pudo serializar ${node.frame.url}: ${result.exceptionDetails.text}`, 'VISUAL_FREEZE_FAILED');
+        await store(node.frame.url + (node.frame.urlFragment || ''), Buffer.from(result.result.value, 'utf8'), 'text/html; charset=utf-8');
+      }
+    }
+    const fixture = { id, origin: source.origin, entry: source.pathname + source.search,
+      frozen: { source_url: url, frozen_at: new Date().toISOString(), chrome: session.version, responses: responses.size } };
+    await fs.writeFile(path.join(dir, 'responses.json'), JSON.stringify([...responses.values()], null, 1) + '\n');
+    await fs.writeFile(path.join(dir, 'fixture.json'), JSON.stringify(fixture, null, 2) + '\n');
+    return { ...fixture, dir: path.resolve(dir) };
+  } finally { await page.close(); }
+}