@meiti/render 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MEITI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @meiti/render
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Render testing built for AI agents, not for people.
+
+Today an agent tests a screen like a person would: take a screenshot, send it to a vision model, guess where to click, take another screenshot. It is slow, expensive and fragile. `@meiti/render` gives the agent what it actually needs:
+
+- **A map of the screen instead of a picture.** Every element that matters, with its role, name, text, value, state and position, as text. It takes a few milliseconds and any model can read it.
+- **Actions by intent instead of coordinates.** `fill "Email" with ...`, `click "Save"`. The element is found by its role, label or visible text. If it is not there, the answer says what is.
+- **Seeing by comparing maps.** Act, scan, compare with the previous map: what appeared, what disappeared, what changed, what moved. "Nothing changed" is information too: a button that does nothing.
+- **What a screenshot never shows.** The requests sent to the server and their status, page errors, native dialogs.
+- **Visual issues measured exactly, no vision model needed.** Horizontal overflow, cut text, covered or off-screen elements, small touch targets, low contrast, broken images, buttons without a name.
+- **Knows whether the page loaded, and whether it is the right one.** Every map starts with the page state: LOADED, DID NOT LOAD (HTTP error, the browser's own error page, nothing visible, a screen that only shows an error) or NOT THE EXPECTED PAGE (with `expect_page`: something that identifies the page you meant to open). On a page that did not load or is not the expected one, negative checks like "not there" answer CANNOT PROVE instead of a false yes.
+- **Before and after.** Compare two versions of an app (home page plus up to 3 linked pages, phone and desktop): worse, better or the same.
+
+It works with apps that render inside same-origin iframes and waits until the screen is stable (two identical maps in a row and nothing loading) before reading it.
+
+## Use it from an agent (MCP)
+
+```bash
+npx -y @meiti/render
+```
+
+Add it to any MCP client as a stdio server with the command `npx -y @meiti/render`. It needs Node 18 or newer and a Chrome: the one puppeteer downloads, otherwise the Chrome installed on the machine, or the executable you set in `MEITI_RENDER_CHROME`.
+
+Tools:
+
+| Tool | What it does |
+|---|---|
+| `render_open` | Opens a URL (any size: 375 for a phone) and returns the map, its visual issues and the requests that failed while loading. Optional: `storage`, `cookies` and `headers` to open it already signed in, and `wait_for` for an element that appears after a request. Each session runs in its own browser context. |
+| `render_act` | One action by intent (`click`, `fill`, `select`, `check`, `key`, `goto`) and what changed. |
+| `render_expect` | Checks what you expect: yes or no, with the exact proof. `no_errors` takes `ignore` for errors that are not the app's own. |
+| `render_scan` | Scans the current screen again. |
+| `render_compare` | Compares two versions of the same app. |
+| `render_close` | Closes a session. |
+
+Example of what the agent reads after `render_act {"type": "click", "target": "Add"}`:
+
+```
+Acted on button:Add in 858 ms.
+What changed: appeared 1: listitem:Milk; moved 4
+Requests:
+- POST http://localhost:3000/api/items → 201
+Page errors: none
+```
+
+## Use it from code
+
+```js
+import puppeteer from 'puppeteer';
+import { SesionRender } from '@meiti/render';
+
+const browser = await puppeteer.launch();
+const session = await SesionRender.abrir(browser, 'http://localhost:3000', { ancho: 375, alto: 812 });
+await session.hacer({ tipo: 'llenar', objetivo: 'Email', valor: 'ana@example.com' });
+const result = await session.hacer({ tipo: 'clic', objetivo: 'Save' });
+console.log(result.cambio.resumen);
+console.log(session.verificar([{ pedido: { metodo: 'POST', url_contiene: '/api/users', status: 201 } }]));
+```
+
+## Verified by Healer
+
+`@meiti/render` is a MEITI tool, verified by [Healer](https://meiti.dev/healer) with exams that have known answers, run on every version:
+
+| Exam | Result |
+|---|---|
+| Visual issues (one planted issue per page, plus clean pages) | 11 of 11, 0 false alarms, ~4 ms per scan |
+| Actions and expectations (JavaScript error, silent 500, missing button) | 10 of 10 |
+| Apps rendered in iframes, loading states, native dialogs | 7 of 7 |
+| Before and after (worse, better, same) | 3 of 3 |
+
+## License
+
+MIT

package/dist/escaner-navegador.js

@@ -0,0 +1,160 @@
+// 🛰️ Escáner de render: corre DENTRO de la página (se inyecta como texto, ver escaner.ts; el código que pasa por tsx se
+// rompe al inyectarlo). Devuelve el MAPA de la pantalla: los parámetros renderizados de cada elemento que importa (qué es,
+// qué dice, en qué estado está, dónde está y cómo se ve), más las fallas visuales que se pueden medir exacto.
+// JavaScript plano a propósito: nada de TypeScript ni de sintaxis que un navegador viejo no entienda.
+(function escanearPantalla() {
+  var TOPE = 800;
+  var vw = window.innerWidth, vh = window.innerHeight;
+  var doc = document.documentElement;
+  var elementos = [];
+  var vistos = Object.create(null);
+  var fallas = [];
+  var refs = []; // el elemento real de cada entrada del mapa, para actuar sobre él por su id (ver sesion.ts)
+
+  function rolDe(el) {
+    var r = el.getAttribute('role');
+    if (r) return r;
+    var t = el.tagName.toLowerCase();
+    if (t === 'a' && el.hasAttribute('href')) return 'link';
+    if (t === 'button') return 'button';
+    if (t === 'input') {
+      var tipo = (el.getAttribute('type') || 'text').toLowerCase();
+      if (tipo === 'checkbox') return 'checkbox';
+      if (tipo === 'radio') return 'radio';
+      if (tipo === 'submit' || tipo === 'button' || tipo === 'reset') return 'button';
+      if (tipo === 'hidden') return null;
+      return 'textbox';
+    }
+    if (t === 'textarea') return 'textbox';
+    if (t === 'select') return 'combobox';
+    if (t === 'img') return 'img';
+    if (/^h[1-6]$/.test(t)) return 'heading';
+    if (t === 'li') return 'listitem';
+    if (t === 'tr') return 'row';
+    if (t === 'nav') return 'navigation';
+    if (t === 'dialog') return 'dialog';
+    if (t === 'label') return 'label';
+    return null;
+  }
+  function textoPropio(el) {
+    var s = '';
+    for (var i = 0; i < el.childNodes.length; i++) if (el.childNodes[i].nodeType === 3) s += el.childNodes[i].nodeValue;
+    return s.replace(/\s+/g, ' ').trim();
+  }
+  function textoDe(el) { return (el.innerText || el.textContent || '').replace(/\s+/g, ' ').trim(); }
+  function nombreDe(el, rol) {
+    var a = el.getAttribute('aria-label');
+    if (a) return a.trim();
+    var lb = el.getAttribute('aria-labelledby');
+    if (lb) { var ref = document.getElementById(lb); if (ref) return textoDe(ref); }
+    if (el.id) { var l = document.querySelector('label[for="' + el.id.replace(/"/g, '\\"') + '"]'); if (l) return textoDe(l); }
+    var padreLabel = el.closest && el.closest('label');
+    if (padreLabel && padreLabel !== el) return textoDe(padreLabel);
+    if (rol === 'img') return (el.getAttribute('alt') || '').trim();
+    if (rol === 'textbox' || rol === 'combobox') return (el.getAttribute('placeholder') || el.getAttribute('name') || '').trim();
+    var t = el.getAttribute('title');
+    var tx = textoDe(el);
+    return (tx || t || '').slice(0, 120);
+  }
+  function esVisible(el, cs, caja) {
+    if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0) return false;
+    if (caja.width < 1 || caja.height < 1) return false;
+    return true;
+  }
+  function esClicable(el, rol, cs) {
+    if (['button', 'link', 'checkbox', 'radio', 'textbox', 'combobox', 'tab', 'menuitem', 'switch', 'option'].indexOf(rol) >= 0) return true;
+    return cs.cursor === 'pointer' && !!el.onclick;
+  }
+  // Color efectivo del fondo: el primer ancestro con fondo no transparente.
+  function rgba(c) { var m = /rgba?\(([^)]+)\)/.exec(c || ''); if (!m) return null; var p = m[1].split(',').map(function (x) { return parseFloat(x); }); return { r: p[0], g: p[1], b: p[2], a: p.length > 3 ? p[3] : 1 }; }
+  function fondoDe(el) {
+    for (var n = el; n && n.nodeType === 1; n = n.parentElement) {
+      var c = rgba(getComputedStyle(n).backgroundColor);
+      if (c && c.a > 0.5) return c;
+      if (getComputedStyle(n).backgroundImage !== 'none') return null; // sobre una imagen no se puede juzgar
+    }
+    return { r: 255, g: 255, b: 255, a: 1 };
+  }
+  function luminancia(c) { var f = function (v) { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c.r) + 0.7152 * f(c.g) + 0.0722 * f(c.b); }
+  function contraste(a, b) { var l1 = luminancia(a), l2 = luminancia(b); return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05); }
+
+  var todos = document.body ? document.body.querySelectorAll('*') : [];
+  for (var i = 0; i < todos.length && elementos.length < TOPE; i++) {
+    var el = todos[i];
+    var tag = el.tagName.toLowerCase();
+    if (tag === 'script' || tag === 'style' || tag === 'noscript' || tag === 'template') continue;
+    var rol = rolDe(el);
+    var propio = textoPropio(el);
+    if (!rol && !propio) continue;
+    var cs = getComputedStyle(el);
+    var caja = el.getBoundingClientRect();
+    var visible = esVisible(el, cs, caja);
+    if (!visible && !rol) continue;
+    var nombre = rol ? nombreDe(el, rol) : '';
+    var texto = (propio || (rol ? textoDe(el) : '')).slice(0, 200);
+    var clave = (rol || 'texto') + ':' + (nombre || texto).slice(0, 60);
+    vistos[clave] = (vistos[clave] || 0) + 1;
+    var id = vistos[clave] > 1 ? clave + '#' + vistos[clave] : clave;
+    var estado = {};
+    if (el.disabled || el.getAttribute('aria-disabled') === 'true') estado.deshabilitado = true;
+    if (el.checked || el.getAttribute('aria-checked') === 'true') estado.marcado = true;
+    if (el.required || el.getAttribute('aria-required') === 'true') estado.requerido = true;
+    if ((el.validity && el.validity.valid === false) || el.getAttribute('aria-invalid') === 'true') estado.invalido = true;
+    if (el.getAttribute('aria-expanded')) estado.expandido = el.getAttribute('aria-expanded') === 'true';
+    if (document.activeElement === el) estado.enfocado = true;
+    var e = {
+      id: id, rol: rol || 'texto', nombre: nombre || undefined, texto: texto || undefined,
+      valor: (tag === 'input' || tag === 'textarea' || tag === 'select') && el.type !== 'password' ? String(el.value || '').slice(0, 120) : undefined,
+      estado: Object.keys(estado).length ? estado : undefined,
+      caja: { x: Math.round(caja.left), y: Math.round(caja.top + window.scrollY), w: Math.round(caja.width), h: Math.round(caja.height) },
+      visible: visible,
+      estilo: { color: cs.color, fondo: cs.backgroundColor, fuente: Math.round(parseFloat(cs.fontSize)), peso: cs.fontWeight },
+    };
+    // A dónde lleva un enlace de la misma app (para recorrer sus pantallas, ver versiones.ts).
+    if (rol === 'link' && el.href) { try { var u = new URL(el.href, location.href); if (u.origin === location.origin && u.pathname + u.search !== location.pathname + location.search) e.destino = u.pathname + u.search; } catch (x) { /* dirección rara */ } }
+    elementos.push(e);
+    refs.push(el);
+    if (!visible) continue;
+
+    var clicable = esClicable(el, rol, cs);
+    // Fallas que se pueden medir exacto.
+    if ((cs.overflow === 'hidden' || cs.overflowX === 'hidden' || cs.textOverflow === 'ellipsis') && el.scrollWidth > el.clientWidth + 1 && texto)
+      fallas.push({ tipo: 'texto_cortado', id: id, detalle: 'the text needs ' + el.scrollWidth + ' px and only ' + el.clientWidth + ' px are visible' });
+    if (clicable && (caja.right > vw + 1 || caja.left < -1))
+      fallas.push({ tipo: 'fuera_de_pantalla', id: id, detalle: 'it spans ' + Math.round(caja.left) + ' to ' + Math.round(caja.right) + ' px on a ' + vw + ' px wide screen' });
+    // Un enlace en medio de una oración no cuenta (la norma de accesibilidad lo exceptúa: no puede medir 24 px de alto sin
+    // romper el párrafo). Medido el 2026-11-12 en connect.html: cuatro falsas alarmas así.
+    var enLinea = cs.display === 'inline' && el.parentElement && textoDe(el.parentElement).length > textoDe(el).length + 10;
+    if (clicable && !enLinea && vw < 600 && (caja.width < 24 || caja.height < 24))
+      fallas.push({ tipo: 'toque_chico', id: id, detalle: Math.round(caja.width) + ' x ' + Math.round(caja.height) + ' px (at least 24 x 24 for a finger)' });
+    if (clicable && caja.top < vh && caja.bottom > 0) {
+      var cx = caja.left + caja.width / 2, cy = caja.top + caja.height / 2;
+      if (cx >= 0 && cx < vw && cy >= 0 && cy < vh) {
+        var arriba = document.elementFromPoint(cx, cy);
+        if (arriba && arriba !== el && !el.contains(arriba) && !arriba.contains(el))
+          fallas.push({ tipo: 'tapado', id: id, detalle: 'another element sits on its center: ' + (arriba.tagName.toLowerCase()) + (arriba.id ? '#' + arriba.id : '') + ' "' + textoDe(arriba).slice(0, 40) + '"' });
+      }
+    }
+    if ((rol === 'button' || rol === 'link') && !nombre)
+      fallas.push({ tipo: 'sin_nombre', id: id, detalle: 'a ' + rol + ' with no text or aria-label: neither a screen reader user nor an agent can tell what it does' });
+    if (tag === 'img' && el.complete && el.naturalWidth === 0)
+      fallas.push({ tipo: 'imagen_rota', id: id, detalle: 'it did not load: ' + (el.getAttribute('src') || '').slice(0, 80) });
+    if (propio) {
+      var color = rgba(cs.color), fondo = fondoDe(el);
+      if (color && fondo && color.a > 0.5) {
+        var tam = parseFloat(cs.fontSize), negrita = Number(cs.fontWeight) >= 700;
+        var grande = tam >= 24 || (negrita && tam >= 18.66);
+        var r = contraste(color, fondo);
+        if (r < (grande ? 3 : 4.5)) fallas.push({ tipo: 'contraste', id: id, detalle: 'contrast ' + r.toFixed(2) + ':1 (minimum ' + (grande ? '3' : '4.5') + ':1)' });
+      }
+    }
+  }
+  if (doc.scrollWidth > vw + 1) fallas.push({ tipo: 'desborde_horizontal', id: null, detalle: 'the page is ' + doc.scrollWidth + ' px wide on a ' + vw + ' px screen: it scrolls sideways' });
+
+  window.__renderRefs = refs;
+  return {
+    url: location.href, titulo: document.title,
+    pantalla: { ancho: vw, alto: vh, ancho_total: doc.scrollWidth, alto_total: doc.scrollHeight },
+    elementos: elementos, fallas: fallas, recortado: elementos.length >= TOPE,
+  };
+})()

package/dist/escaner.d.ts

@@ -0,0 +1,94 @@
+import type { Frame, Page } from 'puppeteer';
+export interface ElementoMapa {
+    id: string;
+    rol: string;
+    nombre?: string;
+    texto?: string;
+    valor?: string;
+    estado?: {
+        deshabilitado?: boolean;
+        marcado?: boolean;
+        requerido?: boolean;
+        invalido?: boolean;
+        expandido?: boolean;
+        enfocado?: boolean;
+    };
+    caja: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    visible: boolean;
+    estilo: {
+        color: string;
+        fondo: string;
+        fuente: number;
+        peso: string;
+    };
+    destino?: string;
+}
+export type TipoFalla = 'desborde_horizontal' | 'texto_cortado' | 'fuera_de_pantalla' | 'toque_chico' | 'tapado' | 'sin_nombre' | 'imagen_rota' | 'contraste';
+export interface FallaRender {
+    tipo: TipoFalla;
+    id: string | null;
+    detalle: string;
+}
+export interface MapaPantalla {
+    url: string;
+    titulo: string;
+    pantalla: {
+        ancho: number;
+        alto: number;
+        ancho_total: number;
+        alto_total: number;
+    };
+    elementos: ElementoMapa[];
+    fallas: FallaRender[];
+    recortado: boolean;
+    ms: number;
+}
+export declare const referenciaDe: (mapa: MapaPantalla, i: number) => {
+    marco: Frame;
+    indice: number;
+} | null;
+/**
+ * Escanea la pantalla actual de la página y devuelve su mapa.
+ * 🧩 [Aprendido de MEITI, ojo_optico.js, bug real del 2026-08-05/06] Cada molde de una app de MEITI se dibuja dentro de su
+ * propio <iframe src="sandbox-runtime.html">, uno por molde: un escaneo solo del documento principal no ve nada. Se escanea
+ * cada marco y se une todo en un solo mapa, con las posiciones llevadas a la pantalla real.
+ */
+export declare function escanear(pagina: Page): Promise<MapaPantalla>;
+export declare function escanearEstable(pagina: Page, opciones?: {
+    maxMs?: number;
+    pausaMs?: number;
+}): Promise<MapaPantalla>;
+export interface CambioElemento {
+    id: string;
+    campos: Record<string, {
+        antes: unknown;
+        despues: unknown;
+    }>;
+}
+export interface ComparacionMapas {
+    sin_cambios: boolean;
+    aparecieron: ElementoMapa[];
+    desaparecieron: ElementoMapa[];
+    cambiaron: CambioElemento[];
+    se_movieron: {
+        id: string;
+        dx: number;
+        dy: number;
+    }[];
+    fallas_nuevas: FallaRender[];
+    fallas_resueltas: FallaRender[];
+    foco: {
+        antes: string | null;
+        despues: string | null;
+    };
+    resumen: string;
+}
+/** Compara dos mapas: lo que cambió entre uno y otro es lo que hizo la acción del medio. */
+export declare function comparar(antes: MapaPantalla, despues: MapaPantalla): ComparacionMapas;
+/** El mapa en texto corto, para un modelo: una línea por elemento visible. */
+export declare function mapaEnTexto(mapa: MapaPantalla, tope?: number): string;

package/dist/escaner.js

@@ -0,0 +1,162 @@
+// 🛰️ [PRUEBA DE RENDER PARA AGENTES, 2026-11-12, primera herramienta pensada para agentes, idea del usuario: "en vez de ver
+// imágenes y dar clics en el navegador, algo que de verdad sirva a un agente; el mapa interactivo como un GPS y un escáner:
+// acción 1, escaneo 1, mapa 1; acción 2, escaneo 2, mapa 2; comparo el mapa 1 con el 2: si todo sigue igual o se nota el
+// cambio, eso es ver"].
+// - Escanear: el MAPA de la pantalla son los parámetros renderizados de cada elemento (qué es, qué dice, en qué estado está,
+//   dónde está y cómo se ve), no una foto. Se lee en milisegundos y lo entiende cualquier modelo.
+// - Comparar dos mapas: qué apareció, qué desapareció, qué cambió, qué se movió. Que no cambie nada también es información
+//   (un botón que no hace nada).
+// - Fallas visuales medidas exacto, sin modelo de visión: desborde, texto cortado, elementos tapados, toques chicos,
+//   contraste, imágenes rotas, botones sin nombre.
+// Primer paso: escáner, comparador y examen con respuesta conocida (benchmark/render). Después: acciones por intención,
+// expectativas y la herramienta MCP en el conector de Healer.
+import fs from 'node:fs';
+import path from 'node:path';
+// El código que corre en la página: junto a este archivo (en el paquete @meiti/render) o en la carpeta de trabajo de Healer
+// (en producción corre dist/ compilado y tsc no copia .js sueltos). Se lee una vez.
+let codigoCache = null;
+const CODIGO = () => {
+    if (codigoCache)
+        return codigoCache;
+    const candidatos = [new URL('./escaner-navegador.js', import.meta.url), path.resolve(process.cwd(), 'src', 'render', 'escaner-navegador.js')];
+    for (const c of candidatos) {
+        try {
+            codigoCache = fs.readFileSync(c, 'utf8');
+            return codigoCache;
+        }
+        catch { /* sigue */ }
+    }
+    throw new Error('no se encontró escaner-navegador.js');
+};
+// De qué marco (documento principal o iframe) y en qué lugar de su lista salió cada elemento del mapa: para actuar sobre él
+// (ver sesion.ts). Va aparte del mapa porque un Frame no se puede serializar.
+const referencias = new WeakMap();
+export const referenciaDe = (mapa, i) => referencias.get(mapa)?.[i] ?? null;
+/**
+ * Escanea la pantalla actual de la página y devuelve su mapa.
+ * 🧩 [Aprendido de MEITI, ojo_optico.js, bug real del 2026-08-05/06] Cada molde de una app de MEITI se dibuja dentro de su
+ * propio <iframe src="sandbox-runtime.html">, uno por molde: un escaneo solo del documento principal no ve nada. Se escanea
+ * cada marco y se une todo en un solo mapa, con las posiciones llevadas a la pantalla real.
+ */
+export async function escanear(pagina) {
+    const inicio = Date.now();
+    const codigo = CODIGO();
+    const principal = (await pagina.mainFrame().evaluate(codigo));
+    const refs = principal.elementos.map((_, indice) => ({ marco: pagina.mainFrame(), indice }));
+    const cuenta = new Map();
+    const base = (id) => id.replace(/#\d+$/, '');
+    for (const e of principal.elementos)
+        cuenta.set(base(e.id), (cuenta.get(base(e.id)) ?? 0) + 1);
+    const scrollY = Number(await pagina.evaluate('window.scrollY').catch(() => 0)) || 0;
+    for (const marco of pagina.frames()) {
+        if (marco === pagina.mainFrame())
+            continue;
+        const caja = await (await marco.frameElement().catch(() => null))?.boundingBox().catch(() => null);
+        if (!caja || caja.width < 1 || caja.height < 1)
+            continue; // iframe oculto
+        let sub;
+        try {
+            sub = (await marco.evaluate(codigo));
+        }
+        catch {
+            continue;
+        } // de otro origen: no se puede leer
+        const renombre = new Map();
+        sub.elementos.forEach((e, indice) => {
+            const b = base(e.id);
+            const n = (cuenta.get(b) ?? 0) + 1;
+            cuenta.set(b, n);
+            const id = n > 1 ? `${b}#${n}` : b;
+            renombre.set(e.id, id);
+            principal.elementos.push({ ...e, id, caja: { ...e.caja, x: e.caja.x + Math.round(caja.x), y: e.caja.y + Math.round(caja.y) + scrollY } });
+            refs.push({ marco, indice });
+        });
+        for (const f of sub.fallas)
+            principal.fallas.push({ ...f, id: f.id ? renombre.get(f.id) ?? f.id : null, detalle: f.id ? f.detalle : `${f.detalle} (inside a ${Math.round(caja.width)} px frame)` });
+        principal.recortado ||= sub.recortado;
+    }
+    const mapa = { ...principal, ms: Date.now() - inicio };
+    referencias.set(mapa, refs);
+    return mapa;
+}
+// Lo que dice que una pantalla todavía está cargando (el "Preparando esta sección..." de MEITI y los de cualquier app).
+const CARGANDO = /^(cargando|loading|preparando|espere|please wait)/i;
+const cargando = (m) => m.elementos.some((e) => e.visible && (e.rol === 'progressbar' || CARGANDO.test(e.texto ?? '') || CARGANDO.test(e.nombre ?? '')));
+/**
+ * 🕰️ Escaneo estable [aprendido de MEITI, ojo_optico.js: "las capturas eran pantallazos en la nada", 2026-09-15]: una página
+ * "cargó" antes de que sus datos lleguen. Con mapas se sabe sin adivinar un tiempo fijo: se escanea, se espera un instante
+ * y se vuelve a escanear; cuando dos mapas seguidos son iguales y no queda nada cargando, la pantalla está lista. Si no se
+ * estabiliza en maxMs, se devuelve lo último (nunca cuelga).
+ */
+// Una copia del mapa con otro tiempo, que conserva a qué marco pertenece cada elemento.
+const conMs = (m, ms) => { const r = { ...m, ms }; const refs = referencias.get(m); if (refs)
+    referencias.set(r, refs); return r; };
+export async function escanearEstable(pagina, opciones = {}) {
+    const inicio = Date.now();
+    const maxMs = opciones.maxMs ?? 8_000, pausa = opciones.pausaMs ?? 350;
+    let anterior = await escanear(pagina);
+    while (Date.now() - inicio < maxMs) {
+        await new Promise((ok) => setTimeout(ok, pausa));
+        const actual = await escanear(pagina);
+        if (comparar(anterior, actual).sin_cambios && !cargando(actual))
+            return conMs(actual, Date.now() - inicio);
+        anterior = actual;
+    }
+    return conMs(anterior, Date.now() - inicio);
+}
+const MOVIMIENTO_MINIMO_PX = 4;
+const claveFalla = (f) => `${f.tipo}|${f.id ?? ''}`;
+/** Compara dos mapas: lo que cambió entre uno y otro es lo que hizo la acción del medio. */
+export function comparar(antes, despues) {
+    const a = new Map(antes.elementos.map((e) => [e.id, e]));
+    const b = new Map(despues.elementos.map((e) => [e.id, e]));
+    const aparecieron = despues.elementos.filter((e) => !a.has(e.id) && e.visible);
+    const desaparecieron = antes.elementos.filter((e) => e.visible && (!b.has(e.id) || !b.get(e.id).visible));
+    const cambiaron = [];
+    const se_movieron = [];
+    for (const [id, x] of a) {
+        const y = b.get(id);
+        if (!y || !x.visible || !y.visible)
+            continue;
+        const campos = {};
+        for (const campo of ['texto', 'valor', 'nombre'])
+            if ((x[campo] ?? '') !== (y[campo] ?? ''))
+                campos[campo] = { antes: x[campo], despues: y[campo] };
+        // El foco se mueve con cada clic: es real, pero no es un efecto de la acción (se informa aparte, en "foco").
+        const sinFoco = (e) => { const { enfocado: _f, ...resto } = e ?? {}; return resto; };
+        if (JSON.stringify(sinFoco(x.estado)) !== JSON.stringify(sinFoco(y.estado)))
+            campos.estado = { antes: sinFoco(x.estado), despues: sinFoco(y.estado) };
+        for (const campo of ['color', 'fondo', 'fuente'])
+            if (x.estilo[campo] !== y.estilo[campo])
+                campos[campo] = { antes: x.estilo[campo], despues: y.estilo[campo] };
+        if (Object.keys(campos).length)
+            cambiaron.push({ id, campos });
+        const dx = y.caja.x - x.caja.x, dy = y.caja.y - x.caja.y;
+        if (Math.abs(dx) >= MOVIMIENTO_MINIMO_PX || Math.abs(dy) >= MOVIMIENTO_MINIMO_PX)
+            se_movieron.push({ id, dx, dy });
+    }
+    const fa = new Set(antes.fallas.map(claveFalla)), fb = new Set(despues.fallas.map(claveFalla));
+    const fallas_nuevas = despues.fallas.filter((f) => !fa.has(claveFalla(f)));
+    const fallas_resueltas = antes.fallas.filter((f) => !fb.has(claveFalla(f)));
+    const enfocado = (m) => m.elementos.find((e) => e.estado?.enfocado)?.id ?? null;
+    const foco = { antes: enfocado(antes), despues: enfocado(despues) };
+    const sin_cambios = !aparecieron.length && !desaparecieron.length && !cambiaron.length && !se_movieron.length && antes.url === despues.url;
+    const partes = [
+        antes.url !== despues.url ? `went to another page (${despues.url})` : '',
+        aparecieron.length ? `appeared ${aparecieron.length}: ${aparecieron.slice(0, 5).map((e) => e.id).join(', ')}` : '',
+        desaparecieron.length ? `disappeared ${desaparecieron.length}: ${desaparecieron.slice(0, 5).map((e) => e.id).join(', ')}` : '',
+        cambiaron.length ? `changed ${cambiaron.length}: ${cambiaron.slice(0, 5).map((c) => `${c.id} (${Object.keys(c.campos).join(', ')})`).join(', ')}` : '',
+        se_movieron.length ? `moved ${se_movieron.length}` : '',
+        fallas_nuevas.length ? `new visual issues: ${fallas_nuevas.map((f) => f.tipo).join(', ')}` : '',
+    ].filter(Boolean);
+    return { sin_cambios, aparecieron, desaparecieron, cambiaron, se_movieron, fallas_nuevas, fallas_resueltas, foco, resumen: sin_cambios ? 'nothing changed on the screen' : partes.join('; ') };
+}
+/** El mapa en texto corto, para un modelo: una línea por elemento visible. */
+export function mapaEnTexto(mapa, tope = 150) {
+    const lineas = mapa.elementos.filter((e) => e.visible).slice(0, tope).map((e) => {
+        const estado = e.estado ? ' [' + Object.entries(e.estado).filter(([, v]) => v).map(([k]) => k).join(', ') + ']' : '';
+        const valor = e.valor !== undefined ? ` = "${e.valor}"` : '';
+        return `${e.rol}${e.nombre ? ` "${e.nombre}"` : e.texto ? ` "${e.texto.slice(0, 80)}"` : ''}${valor}${estado} @${e.caja.x},${e.caja.y} ${e.caja.w}x${e.caja.h}`;
+    });
+    return [`${mapa.titulo || mapa.url} (${mapa.pantalla.ancho}x${mapa.pantalla.alto})`, ...lineas, ...mapa.fallas.map((f) => `ISSUE ${f.tipo}${f.id ? ` at ${f.id}` : ''}: ${f.detalle}`)].join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { escanear, escanearEstable, comparar, mapaEnTexto, type MapaPantalla, type ElementoMapa, type FallaRender, type TipoFalla, type ComparacionMapas } from './escaner.js';
+export { SesionRender, resolver, type Accion, type Expectativa, type ResultadoAccion, type ResultadoExpectativa, type PedidoRed, type EstadoCarga, type HuellaPagina } from './sesion.js';
+export { rutasDeLaApp, recorrerApp, compararVersiones, PANTALLAS, type RecorridoApp, type ResultadoVisual, type RegresionVisual } from './recorrido.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { escanear, escanearEstable, comparar, mapaEnTexto } from './escaner.js';
+export { SesionRender, resolver } from './sesion.js';
+export { rutasDeLaApp, recorrerApp, compararVersiones, PANTALLAS } from './recorrido.js';

package/dist/recorrido.d.ts

@@ -0,0 +1,37 @@
+import type { Page } from 'puppeteer';
+import { type MapaPantalla } from './escaner.js';
+export declare const PANTALLAS: readonly [{
+    readonly nombre: 'phone';
+    readonly ancho: 375;
+    readonly alto: 812;
+}, {
+    readonly nombre: 'desktop';
+    readonly ancho: 1280;
+    readonly alto: 800;
+}];
+export interface RecorridoApp {
+    rutas: string[];
+    mapas: Record<string, MapaPantalla>;
+    no_abrieron: string[];
+}
+/** Las rutas a recorrer: la de inicio y hasta MAX_RUTAS - 1 de las que llevan sus enlaces (siempre las mismas, en orden). */
+export declare function rutasDeLaApp(pagina: Page, base: string): Promise<string[]>;
+/** Recorre las rutas en cada pantalla y saca un mapa de cada una. */
+export declare function recorrerApp(pagina: Page, base: string, rutas: string[]): Promise<RecorridoApp>;
+export interface RegresionVisual {
+    pantalla: string;
+    tipo: 'falla_nueva' | 'desaparecio' | 'no_abre';
+    detalle: string;
+}
+export interface ResultadoVisual {
+    veredicto: 'peor' | 'igual' | 'mejor' | 'sin_datos';
+    pantallas: number;
+    fallas_antes: number;
+    fallas_despues: number;
+    regresiones: RegresionVisual[];
+    mejoras: string[];
+    resumen: string;
+    ms?: number;
+}
+/** Compara el recorrido de la versión original con el de la reparada, pantalla por pantalla. */
+export declare function compararVersiones(antes: RecorridoApp, despues: RecorridoApp): ResultadoVisual;

package/dist/recorrido.js

@@ -0,0 +1,85 @@
+import { escanearEstable as escanear, comparar } from './escaner.js';
+export const PANTALLAS = [
+    { nombre: 'phone', ancho: 375, alto: 812 },
+    { nombre: 'desktop', ancho: 1280, alto: 800 },
+];
+const MAX_RUTAS = 4;
+const INTERACTIVOS = new Set(['button', 'link', 'textbox', 'combobox', 'checkbox', 'radio', 'tab', 'menuitem', 'switch']);
+/** Las rutas a recorrer: la de inicio y hasta MAX_RUTAS - 1 de las que llevan sus enlaces (siempre las mismas, en orden). */
+export async function rutasDeLaApp(pagina, base) {
+    await pagina.setViewport({ width: 1280, height: 800 });
+    await pagina.goto(base, { waitUntil: 'networkidle2', timeout: 30_000 });
+    const mapa = await escanear(pagina);
+    const destinos = [...new Set(mapa.elementos.filter((e) => e.destino).map((e) => e.destino))].sort();
+    return ['/', ...destinos.filter((d) => d !== '/')].slice(0, MAX_RUTAS);
+}
+/** Recorre las rutas en cada pantalla y saca un mapa de cada una. */
+export async function recorrerApp(pagina, base, rutas) {
+    const mapas = {};
+    const no_abrieron = [];
+    for (const ruta of rutas) {
+        for (const p of PANTALLAS) {
+            const clave = `${ruta} @${p.nombre}`;
+            // 🔁 [2026-11-12, primera corrida real: "/ @phone ahora abre" en una app que abría igual] Justo después de arrancar el
+            // servidor, la primera navegación puede tropezar: una pantalla solo cuenta como que no abre si falla dos veces.
+            let ultimoError = '';
+            for (let intento = 1; intento <= 2 && !mapas[clave]; intento++) {
+                try {
+                    await pagina.setViewport({ width: p.ancho, height: p.alto });
+                    const r = await pagina.goto(new URL(ruta, base).href, { waitUntil: 'networkidle2', timeout: 30_000 });
+                    if (r && r.status() >= 400) {
+                        ultimoError = `answered ${r.status()}`;
+                        if (intento === 1)
+                            await new Promise((ok) => setTimeout(ok, 1_500));
+                        continue;
+                    }
+                    mapas[clave] = await escanear(pagina);
+                }
+                catch (error) {
+                    ultimoError = String(error?.message || error).slice(0, 80);
+                    if (intento === 1)
+                        await new Promise((ok) => setTimeout(ok, 1_500));
+                }
+            }
+            if (!mapas[clave])
+                no_abrieron.push(`${clave} (${ultimoError})`);
+        }
+    }
+    return { rutas, mapas, no_abrieron };
+}
+const describirFalla = (f) => `${f.tipo}${f.id ? ` en ${f.id}` : ''}: ${f.detalle}`;
+/** Compara el recorrido de la versión original con el de la reparada, pantalla por pantalla. */
+export function compararVersiones(antes, despues) {
+    const regresiones = [];
+    const mejoras = [];
+    let pantallas = 0, fallasAntes = 0, fallasDespues = 0;
+    for (const [clave, a] of Object.entries(antes.mapas)) {
+        const b = despues.mapas[clave];
+        if (!b) {
+            regresiones.push({ pantalla: clave, tipo: 'no_abre', detalle: despues.no_abrieron.find((x) => x.startsWith(clave)) ?? 'it does not open in the new version' });
+            continue;
+        }
+        pantallas++;
+        fallasAntes += a.fallas.length;
+        fallasDespues += b.fallas.length;
+        const c = comparar(a, b);
+        for (const f of c.fallas_nuevas)
+            regresiones.push({ pantalla: clave, tipo: 'falla_nueva', detalle: describirFalla(f) });
+        for (const e of c.desaparecieron.filter((x) => INTERACTIVOS.has(x.rol)))
+            regresiones.push({ pantalla: clave, tipo: 'desaparecio', detalle: `${e.rol} "${e.nombre ?? e.texto ?? e.id}" is gone` });
+        for (const f of c.fallas_resueltas)
+            mejoras.push(`${clave}: ${describirFalla(f)}`);
+    }
+    // Una pantalla que no abría en la original y ahora sí también es una mejora.
+    for (const x of antes.no_abrieron) {
+        const clave = x.split(' (')[0];
+        if (despues.mapas[clave])
+            mejoras.push(`${clave}: it opens now`);
+    }
+    const veredicto = !pantallas && !regresiones.length ? 'sin_datos' : regresiones.length ? 'peor' : mejoras.length ? 'mejor' : 'igual';
+    const resumen = veredicto === 'sin_datos' ? 'no screen could be opened'
+        : veredicto === 'peor' ? `the new version is worse in ${regresiones.length} point(s): ${regresiones.slice(0, 3).map((r) => `${r.pantalla}, ${r.detalle}`).join('; ')}`
+            : veredicto === 'mejor' ? `the new version is better: ${mejoras.slice(0, 3).join('; ')}`
+                : `the same in the ${pantallas} screens checked`;
+    return { veredicto, pantallas, fallas_antes: fallasAntes, fallas_despues: fallasDespues, regresiones, mejoras, resumen };
+}