@meiti/render 0.0.0-stage → 0.1.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,72 @@
-# 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.
+- **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 and its visual issues. |
+| `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. |
+| `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 } 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 };
+}

package/dist/sesion.d.ts

@@ -0,0 +1,92 @@
+import type { Browser, Page } from 'puppeteer';
+import { type MapaPantalla, type ComparacionMapas } from './escaner.js';
+export type Accion = {
+    tipo: 'clic';
+    objetivo: string;
+} | {
+    tipo: 'llenar';
+    objetivo: string;
+    valor: string;
+} | {
+    tipo: 'elegir';
+    objetivo: string;
+    valor: string;
+} | {
+    tipo: 'marcar';
+    objetivo: string;
+    valor?: boolean;
+} | {
+    tipo: 'tecla';
+    tecla: string;
+} | {
+    tipo: 'ir';
+    url: string;
+};
+export interface PedidoRed {
+    metodo: string;
+    url: string;
+    status: number;
+}
+export interface ResultadoAccion {
+    accion: Accion;
+    objetivo: string | null;
+    ok: boolean;
+    error?: string;
+    cambio: ComparacionMapas | null;
+    red: PedidoRed[];
+    errores_pagina: string[];
+    dialogos: string[];
+    ms: number;
+}
+export type Expectativa = {
+    existe: string;
+} | {
+    no_existe: string;
+} | {
+    texto: string;
+    contiene: string;
+} | {
+    aparecio: string;
+} | {
+    desaparecio: string;
+} | {
+    sin_cambios: boolean;
+} | {
+    sin_fallas: true | string[];
+} | {
+    sin_errores: true;
+} | {
+    pedido: {
+        metodo?: string;
+        url_contiene: string;
+        status?: number;
+    };
+};
+export interface ResultadoExpectativa {
+    expectativa: Expectativa;
+    cumple: boolean;
+    prueba: string;
+}
+/** El índice en el mapa del elemento al que se refiere el agente (-1 si no está). */
+export declare function resolver(mapa: MapaPantalla, objetivo: string): number;
+export declare class SesionRender {
+    readonly pagina: Page;
+    mapa: MapaPantalla | null;
+    ultima: ResultadoAccion | null;
+    private red;
+    private errores;
+    private dialogos;
+    private constructor();
+    static abrir(navegador: Browser, url: string, pantalla?: {
+        ancho: number;
+        alto: number;
+    }, preparar?: (pagina: Page) => Promise<void>): Promise<SesionRender>;
+    escanear(): Promise<MapaPantalla>;
+    private marcoDe;
+    private elemento;
+    /** Acción → escaneo → mapa nuevo → comparación con el anterior. */
+    hacer(accion: Accion): Promise<ResultadoAccion>;
+    /** El agente dice qué espera; la sesión contesta sí o no, con la prueba. */
+    verificar(expectativas: Expectativa[]): ResultadoExpectativa[];
+    cerrar(): Promise<void>;
+}

package/dist/sesion.js

@@ -0,0 +1,199 @@
+import { escanear, escanearEstable, comparar, referenciaDe } from './escaner.js';
+const normal = (s) => (s ?? '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/\s+/g, ' ').trim();
+const INTERACTIVOS = new Set(['button', 'link', 'textbox', 'combobox', 'checkbox', 'radio', 'tab', 'menuitem', 'switch', 'option']);
+const describir = (e) => `${e.rol}${e.nombre ? ` "${e.nombre}"` : e.texto ? ` "${e.texto.slice(0, 60)}"` : ''}${e.valor !== undefined ? ` = "${e.valor}"` : ''} @${e.caja.x},${e.caja.y}`;
+/** El índice en el mapa del elemento al que se refiere el agente (-1 si no está). */
+export function resolver(mapa, objetivo) {
+    const els = mapa.elementos;
+    const exacto = els.findIndex((e) => e.id === objetivo);
+    if (exacto >= 0)
+        return exacto;
+    // 🩹 [2026-11-13, examen de uso real v2: el modelo copió la línea del mapa, 'combobox "Categoría"', y no se encontraba] Se acepta
+    // el objetivo como lo escribe un modelo: "rol:nombre", 'rol "nombre"' (con o sin la comilla de cierre) y lo que sobra después de
+    // un " | " o un " = " (restos del formato de la respuesta) se descarta.
+    const limpio = objetivo.split(/\s+[|=]\s*/)[0].trim();
+    let rol = null, texto = limpio;
+    const m = /^([a-z]+):(.+)$/.exec(limpio) || /^([a-z]+)\s+["'“‘](.+?)["'”’]?$/.exec(limpio);
+    if (m && els.some((e) => e.rol === m[1])) {
+        rol = m[1];
+        texto = m[2].trim();
+    }
+    if (texto !== objetivo) {
+        const exacto2 = els.findIndex((e) => e.id === (rol ? `${rol}:${texto}` : texto));
+        if (exacto2 >= 0)
+            return exacto2;
+    }
+    const buscado = normal(texto);
+    const candidatos = els.map((e, i) => ({ e, i })).filter(({ e }) => e.visible && (!rol || e.rol === rol));
+    const puntaje = (e) => {
+        const n = normal(e.nombre), t = normal(e.texto);
+        const base = n === buscado || t === buscado ? 3 : n.includes(buscado) || t.includes(buscado) ? 1 : 0;
+        return base ? base + (INTERACTIVOS.has(e.rol) ? 1 : 0) : 0;
+    };
+    const mejor = candidatos.map((c) => ({ ...c, p: puntaje(c.e) })).filter((c) => c.p > 0).sort((a, b) => b.p - a.p)[0];
+    return mejor ? mejor.i : -1;
+}
+/** Lo más parecido a lo que pidió el agente, para decirle qué hay cuando no encuentra lo que busca. */
+function parecidos(mapa, objetivo) {
+    const palabras = normal(objetivo).split(/[\s:]+/).filter((p) => p.length > 2);
+    return mapa.elementos.filter((e) => e.visible && INTERACTIVOS.has(e.rol))
+        .map((e) => ({ e, p: palabras.filter((w) => normal(e.nombre).includes(w) || normal(e.texto).includes(w)).length }))
+        .sort((a, b) => b.p - a.p).slice(0, 5).map(({ e }) => e.id);
+}
+export class SesionRender {
+    pagina;
+    mapa = null;
+    ultima = null;
+    red = [];
+    errores = [];
+    dialogos = [];
+    constructor(pagina) {
+        this.pagina = pagina;
+        pagina.on('response', (r) => {
+            const tipo = r.request().resourceType();
+            if (tipo === 'xhr' || tipo === 'fetch' || tipo === 'document')
+                this.red.push({ metodo: r.request().method(), url: r.url(), status: r.status() });
+        });
+        pagina.on('console', (m) => { if (m.type() === 'error')
+            this.errores.push(m.text().slice(0, 300)); });
+        pagina.on('pageerror', (e) => { this.errores.push(String(e?.message || e).slice(0, 300)); });
+        // 🩹 [Aprendido de MEITI, ojo_optico.js] Un alert()/confirm() sin contestar deja la página congelada y cuelga todo lo que
+        // sigue: se acepta solo y queda anotado como dialogo (el agente lo ve en la respuesta de la acción).
+        pagina.on('dialog', (d) => { this.dialogos.push(`${d.type()}: ${d.message().slice(0, 200)}`); d.accept().catch(() => { }); });
+    }
+    static async abrir(navegador, url, pantalla = { ancho: 1280, alto: 800 }, preparar) {
+        const pagina = await navegador.newPage();
+        await pagina.setViewport({ width: pantalla.ancho, height: pantalla.alto });
+        if (preparar)
+            await preparar(pagina); // por ejemplo, un servidor simulado (exámenes)
+        const sesion = new SesionRender(pagina);
+        await pagina.goto(url, { waitUntil: 'networkidle2', timeout: 60_000 });
+        sesion.mapa = await escanearEstable(pagina);
+        return sesion;
+    }
+    async escanear() {
+        this.mapa = await escanear(this.pagina);
+        return this.mapa;
+    }
+    // El elemento real, en su marco (documento principal o el iframe de su molde, ver escaner.ts).
+    marcoDe(mapa, indice) {
+        const r = referenciaDe(mapa, indice);
+        if (!r || r.marco.detached)
+            throw new Error('the screen changed since the last scan: scan again');
+        return r;
+    }
+    async elemento(mapa, indice) {
+        const r = this.marcoDe(mapa, indice);
+        const h = await r.marco.evaluateHandle(`window.__renderRefs && window.__renderRefs[${r.indice}]`);
+        const el = h.asElement();
+        if (!el)
+            throw new Error('the element is no longer on the page');
+        return el;
+    }
+    /** Acción → escaneo → mapa nuevo → comparación con el anterior. */
+    async hacer(accion) {
+        const inicio = Date.now();
+        const antes = this.mapa ?? (await this.escanear());
+        this.red = [];
+        this.errores = [];
+        this.dialogos = [];
+        let objetivo = null;
+        try {
+            if ('objetivo' in accion) {
+                const i = resolver(antes, accion.objetivo);
+                if (i < 0) {
+                    const hay = parecidos(antes, accion.objetivo);
+                    throw new Error(`could not find "${accion.objetivo}" on the screen${hay.length ? `; on the screen there is: ${hay.join(', ')}` : ''}`);
+                }
+                objetivo = antes.elementos[i].id;
+                const el = await this.elemento(antes, i);
+                if (accion.tipo === 'clic')
+                    await el.click();
+                else if (accion.tipo === 'llenar') {
+                    await el.click({ count: 3 });
+                    await this.pagina.keyboard.press('Backspace');
+                    await el.type(accion.valor);
+                }
+                else if (accion.tipo === 'marcar') {
+                    if (!!antes.elementos[i].estado?.marcado !== (accion.valor ?? true))
+                        await el.click();
+                }
+                else if (accion.tipo === 'elegir') {
+                    const elegido = await this.marcoDe(antes, i).marco.evaluate(`(function () {
+            var el = window.__renderRefs[${this.marcoDe(antes, i).indice}], v = ${JSON.stringify(accion.valor)}.toLowerCase();
+            for (var k = 0; k < el.options.length; k++) {
+              var o = el.options[k];
+              if (o.value.toLowerCase() === v || o.text.trim().toLowerCase() === v) { el.value = o.value; el.dispatchEvent(new Event('input', { bubbles: true })); el.dispatchEvent(new Event('change', { bubbles: true })); return true; }
+            }
+            return false;
+          })()`);
+                    if (!elegido)
+                        throw new Error(`"${accion.objetivo}" has no option "${accion.valor}"`);
+                }
+            }
+            else if (accion.tipo === 'tecla')
+                await this.pagina.keyboard.press(accion.tecla);
+            else if (accion.tipo === 'ir')
+                await this.pagina.goto(accion.url, { waitUntil: 'networkidle2', timeout: 60_000 });
+            // Que termine lo que la acción disparó (pedidos, animaciones cortas) antes de volver a escanear.
+            await this.pagina.waitForNetworkIdle({ idleTime: 300, timeout: 4_000 }).catch(() => { });
+            await new Promise((ok) => setTimeout(ok, 150));
+            const despues = await escanearEstable(this.pagina, { maxMs: 6_000 });
+            this.mapa = despues;
+            this.ultima = { accion, objetivo, ok: true, cambio: comparar(antes, despues), red: [...this.red], errores_pagina: [...this.errores], dialogos: [...this.dialogos], ms: Date.now() - inicio };
+        }
+        catch (error) {
+            this.ultima = { accion, objetivo, ok: false, error: String(error?.message || error), cambio: null, red: [...this.red], errores_pagina: [...this.errores], dialogos: [...this.dialogos], ms: Date.now() - inicio };
+        }
+        return this.ultima;
+    }
+    /** El agente dice qué espera; la sesión contesta sí o no, con la prueba. */
+    verificar(expectativas) {
+        const mapa = this.mapa;
+        const u = this.ultima;
+        return expectativas.map((x) => {
+            if (!mapa)
+                return { expectativa: x, cumple: false, prueba: 'no map yet' };
+            const buscar = (o) => { const i = resolver(mapa, o); return i >= 0 ? mapa.elementos[i] : null; };
+            if ('existe' in x) {
+                const e = buscar(x.existe);
+                return { expectativa: x, cumple: !!e, prueba: e ? describir(e) : `"${x.existe}" is not on the screen` };
+            }
+            if ('no_existe' in x) {
+                const e = buscar(x.no_existe);
+                return { expectativa: x, cumple: !e, prueba: e ? `it is there: ${describir(e)}` : 'not there' };
+            }
+            if ('texto' in x) {
+                const e = buscar(x.texto);
+                const dice = e ? [e.valor, e.texto, e.nombre].filter((v) => v !== undefined).join(' | ') : '';
+                return { expectativa: x, cumple: !!e && normal(dice).includes(normal(x.contiene)), prueba: e ? `${e.id} says "${dice}"` : `"${x.texto}" is not on the screen` };
+            }
+            if ('aparecio' in x || 'desaparecio' in x) {
+                const lista = 'aparecio' in x ? u?.cambio?.aparecieron : u?.cambio?.desaparecieron;
+                const buscado = normal('aparecio' in x ? x.aparecio : x.desaparecio);
+                const e = lista?.find((el) => el.id === ('aparecio' in x ? x.aparecio : x.desaparecio) || normal(el.nombre).includes(buscado) || normal(el.texto).includes(buscado));
+                return { expectativa: x, cumple: !!e, prueba: e ? describir(e) : `after the last action: ${u?.cambio?.resumen ?? 'no action yet'}` };
+            }
+            if ('sin_cambios' in x) {
+                const sin = !!u?.cambio?.sin_cambios;
+                return { expectativa: x, cumple: sin === x.sin_cambios, prueba: u?.cambio?.resumen ?? 'no action yet' };
+            }
+            if ('sin_fallas' in x) {
+                const fallas = mapa.fallas.filter((f) => x.sin_fallas === true || x.sin_fallas.includes(f.tipo));
+                return { expectativa: x, cumple: !fallas.length, prueba: fallas.length ? fallas.map((f) => `${f.tipo}${f.id ? ` en ${f.id}` : ''}: ${f.detalle}`).join('; ') : 'none' };
+            }
+            if ('sin_errores' in x) {
+                const err = u?.errores_pagina ?? [];
+                return { expectativa: x, cumple: !err.length, prueba: err.length ? err.join(' | ') : 'none' };
+            }
+            if ('pedido' in x) {
+                const p = x.pedido;
+                const coinciden = (u?.red ?? []).filter((r) => r.url.includes(p.url_contiene) && (!p.metodo || r.metodo === p.metodo.toUpperCase()));
+                const ok = coinciden.some((r) => p.status === undefined ? r.status < 400 : r.status === p.status);
+                return { expectativa: x, cumple: ok, prueba: coinciden.length ? coinciden.map((r) => `${r.metodo} ${r.url} → ${r.status}`).join('; ') : `no requests to "${p.url_contiene}"` };
+            }
+            return { expectativa: x, cumple: false, prueba: 'unknown expectation' };
+        });
+    }
+    async cerrar() { await this.pagina.close().catch(() => { }); }
+}

package/mcp.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// 🛰️ @meiti/render: servidor MCP por stdio (JSON-RPC 2.0) para que un agente pruebe una pantalla sin fotos ni coordenadas.
+// Abre una sesión de navegador y la mantiene: cada acción es acción → escaneo → mapa nuevo → comparación con el anterior
+// (idea del usuario: "como un GPS y un escáner; comparar el mapa 1 con el mapa 2 es ver"). El motor vive en dist/ (armado
+// desde Healer, sanador/src/render). Textos para agentes en inglés, como todo lo que es para clientes.
+import readline from 'node:readline';
+import puppeteer from 'puppeteer';
+import { SesionRender, mapaEnTexto, rutasDeLaApp, recorrerApp, compararVersiones } from './dist/index.js';
+
+const VERSION = '0.1.0';
+const sesiones = new Map();
+let navegador = null;
+// Chrome: MEITI_RENDER_CHROME si se indica, el que descargó puppeteer, o el Chrome instalado en la máquina. Con npm 11+ los
+// scripts de instalación pueden quedar bloqueados y puppeteer no descarga el suyo: entonces se usa el del sistema.
+const ARGS = ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'];
+async function lanzar() {
+  if (process.env.MEITI_RENDER_CHROME) return puppeteer.launch({ headless: true, args: ARGS, executablePath: process.env.MEITI_RENDER_CHROME });
+  try { return await puppeteer.launch({ headless: true, args: ARGS }); } catch (propio) {
+    try { return await puppeteer.launch({ headless: true, args: ARGS, channel: 'chrome' }); } catch {
+      throw new Error(`No Chrome found (${String(propio?.message || propio).split(String.fromCharCode(10))[0]}). Install one with "npx puppeteer browsers install chrome", or set MEITI_RENDER_CHROME to the path of a Chrome or Chromium executable.`);
+    }
+  }
+}
+const abrirNavegador = async () => (navegador ??= await lanzar());
+
+const ACCIONES = { click: 'clic', fill: 'llenar', select: 'elegir', check: 'marcar', key: 'tecla', goto: 'ir' };
+function accionInterna(a) {
+  const tipo = ACCIONES[a?.type];
+  if (!tipo) throw new Error('action.type is one of: click, fill, select, check, key, goto');
+  if (tipo === 'tecla') return { tipo, tecla: String(a.key || '') };
+  if (tipo === 'ir') return { tipo, url: String(a.url || '') };
+  if (!a.target) throw new Error('action.target is required (an id from the map, a label or a visible text)');
+  if (tipo === 'marcar') return { tipo, objetivo: String(a.target), valor: a.value === undefined ? true : !!a.value };
+  return { tipo, objetivo: String(a.target), ...(tipo === 'llenar' || tipo === 'elegir' ? { valor: String(a.value ?? '') } : {}) };
+}
+function expectativaInterna(x) {
+  if ('exists' in x) return { existe: String(x.exists) };
+  if ('not_exists' in x) return { no_existe: String(x.not_exists) };
+  if ('text' in x) return { texto: String(x.text), contiene: String(x.contains ?? '') };
+  if ('appeared' in x) return { aparecio: String(x.appeared) };
+  if ('disappeared' in x) return { desaparecio: String(x.disappeared) };
+  if ('no_changes' in x) return { sin_cambios: !!x.no_changes };
+  if ('no_issues' in x) return { sin_fallas: Array.isArray(x.no_issues) ? x.no_issues : true };
+  if ('no_errors' in x) return { sin_errores: true };
+  if ('request' in x) return { pedido: { metodo: x.request?.method, url_contiene: String(x.request?.url_contains ?? ''), status: x.request?.status } };
+  throw new Error(`Unknown expectation: ${JSON.stringify(x)}`);
+}
+const sesionDe = (id) => { const s = sesiones.get(String(id)); if (!s) throw new Error(`No open session "${id}". Call render_open first.`); return s; };
+const fallasEnTexto = (fallas) => (fallas.length ? fallas.map((f) => `- ${f.tipo}${f.id ? ` (${f.id})` : ''}: ${f.detalle}`).join('\n') : 'none');
+
+const HERRAMIENTAS = [
+  {
+    name: 'render_open',
+    description: 'Open a page in a real browser and return its MAP: every element that matters (role, name, text, value, state, position) plus visual issues measured exactly (horizontal overflow, cut text, covered or off-screen elements, small touch targets, low contrast, broken images, unnamed buttons). Works inside same-origin iframes. Returns a session id for render_act, render_expect and render_scan.',
+    inputSchema: { type: 'object', properties: { url: { type: 'string' }, width: { type: 'number', description: 'Viewport width. Default 1280; use 375 for a phone.' }, height: { type: 'number', description: 'Default 800.' } }, required: ['url'] },
+    async run(a) {
+      const sesion = await SesionRender.abrir(await abrirNavegador(), String(a.url), { ancho: Number(a.width) || 1280, alto: Number(a.height) || 800 });
+      const id = Math.random().toString(36).slice(2, 10);
+      sesiones.set(id, sesion);
+      return `Session ${id}\n\n${mapaEnTexto(sesion.mapa)}`;
+    },
+  },
+  {
+    name: 'render_act',
+    description: 'Do one action by INTENT (no coordinates) and return what changed on the screen: elements that appeared, disappeared, changed or moved (or "nothing changed": a control that does nothing), requests to the server with their status, page errors and native dialogs (accepted automatically). target is an id from the map (like "button:Save"), a label or a visible text; if it is not on the screen, the answer lists what is there.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        session: { type: 'string' },
+        action: { type: 'object', description: '{ "type": "click" | "fill" | "select" | "check" | "key" | "goto", "target": "...", "value": "...", "key": "Enter", "url": "..." }' },
+        include_map: { type: 'boolean', description: 'Also return the full new map. Default false (the change is usually enough).' },
+      },
+      required: ['session', 'action'],
+    },
+    async run(a) {
+      const sesion = sesionDe(a.session);
+      const r = await sesion.hacer(accionInterna(a.action));
+      if (!r.ok) return `Could not do it: ${r.error}`;
+      const red = r.red.filter((p) => !/\.(css|js|png|jpe?g|svg|woff2?|ico)(\?|$)/.test(p.url));
+      return [
+        `Acted on ${r.objetivo ?? '(page)'} in ${r.ms} ms.`,
+        `What changed: ${r.cambio?.resumen}`,
+        red.length ? `Requests:\n${red.map((p) => `- ${p.metodo} ${p.url} → ${p.status}`).join('\n')}` : 'Requests: none',
+        `Page errors: ${r.errores_pagina.length ? r.errores_pagina.join(' | ') : 'none'}`,
+        r.dialogos.length ? `Native dialogs (accepted): ${r.dialogos.join(' | ')}` : '',
+        r.cambio?.fallas_nuevas.length ? `New visual issues:\n${fallasEnTexto(r.cambio.fallas_nuevas)}` : '',
+        a.include_map ? `\n${mapaEnTexto(sesion.mapa)}` : '',
+      ].filter(Boolean).join('\n');
+    },
+  },
+  {
+    name: 'render_expect',
+    description: 'Check what you expect against the current screen and the last action; each answer is yes or no with its proof (the exact element or request). Expectations: {"exists": "..."}, {"not_exists": "..."}, {"text": "...", "contains": "..."}, {"appeared": "..."}, {"disappeared": "..."}, {"no_changes": true}, {"no_issues": true | ["contraste", ...]}, {"no_errors": true}, {"request": {"method": "POST", "url_contains": "/api/x", "status": 201}}.',
+    inputSchema: { type: 'object', properties: { session: { type: 'string' }, expectations: { type: 'array', items: { type: 'object' } } }, required: ['session', 'expectations'] },
+    async run(a) {
+      const resultados = sesionDe(a.session).verificar((a.expectations || []).map(expectativaInterna));
+      // Se devuelve la expectativa tal como la mandó el agente (no la forma interna).
+      return resultados.map((r, i) => `${r.cumple ? 'YES' : 'NO '} ${JSON.stringify(a.expectations[i])} · ${r.prueba}`).join('\n');
+    },
+  },
+  {
+    name: 'render_scan',
+    description: 'Scan the current screen again (waits until it is stable) and return the full map with its visual issues.',
+    inputSchema: { type: 'object', properties: { session: { type: 'string' } }, required: ['session'] },
+    async run(a) { const s = sesionDe(a.session); await s.escanear(); return mapaEnTexto(s.mapa); },
+  },
+  {
+    name: 'render_compare',
+    description: 'Compare two versions of the same app (for example before and after a change): the home page and up to 3 pages it links to, on a phone and a desktop. Says WORSE if a visual issue appears, an interactive element disappears or a page stops opening; BETTER if issues were fixed; SAME otherwise.',
+    inputSchema: { type: 'object', properties: { url_before: { type: 'string' }, url_after: { type: 'string' } }, required: ['url_before', 'url_after'] },
+    async run(a) {
+      const pagina = await (await abrirNavegador()).newPage();
+      try {
+        const rutas = await rutasDeLaApp(pagina, String(a.url_after)).catch(() => ['/']);
+        const despues = await recorrerApp(pagina, String(a.url_after), rutas);
+        const antes = await recorrerApp(pagina, String(a.url_before), rutas);
+        const r = compararVersiones(antes, despues);
+        const etiqueta = { peor: 'WORSE', mejor: 'BETTER', igual: 'SAME', sin_datos: 'NO DATA' }[r.veredicto];
+        return [`${etiqueta}: ${r.resumen}`, `Pages: ${rutas.join(', ')} (${r.pantallas} screens). Visual issues before ${r.fallas_antes}, after ${r.fallas_despues}.`,
+          ...r.regresiones.map((x) => `- ${x.tipo} · ${x.pantalla} · ${x.detalle}`), ...r.mejoras.map((m) => `+ fixed · ${m}`)].join('\n');
+      } finally { await pagina.close().catch(() => {}); }
+    },
+  },
+  {
+    name: 'render_close',
+    description: 'Close a session.',
+    inputSchema: { type: 'object', properties: { session: { type: 'string' } }, required: ['session'] },
+    async run(a) { const s = sesiones.get(String(a.session)); if (s) { await s.cerrar(); sesiones.delete(String(a.session)); } return 'Closed.'; },
+  },
+];
+
+const responder = (id, result) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n');
+const fallar = (id, code, message) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n');
+const cerrarTodo = async () => { if (navegador) await navegador.close().catch(() => {}); process.exit(0); };
+
+const lector = readline.createInterface({ input: process.stdin });
+lector.on('close', cerrarTodo);
+lector.on('line', async (linea) => {
+  let m;
+  try { m = JSON.parse(linea); } catch { return; }
+  if (m.id === undefined) return;
+  try {
+    if (m.method === 'initialize') return responder(m.id, { protocolVersion: m.params?.protocolVersion || '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'meiti-render', title: 'MEITI Render', version: VERSION, websiteUrl: 'https://meiti.dev/agents' }, instructions: 'Test screens like an agent, not like a person: render_open returns a map of the screen; render_act does one action by intent and tells you what changed; render_expect checks what you expect. Compare maps instead of looking at screenshots.' });
+    if (m.method === 'ping') return responder(m.id, {});
+    if (m.method === 'tools/list') return responder(m.id, { tools: HERRAMIENTAS.map(({ run, ...h }) => h) });
+    if (m.method === 'tools/call') {
+      const h = HERRAMIENTAS.find((x) => x.name === m.params?.name);
+      if (!h) return fallar(m.id, -32602, `Unknown tool: ${m.params?.name}`);
+      try { return responder(m.id, { content: [{ type: 'text', text: await h.run(m.params?.arguments || {}) }] }); }
+      catch (e) { return responder(m.id, { content: [{ type: 'text', text: String(e?.message || e) }], isError: true }); }
+    }
+    return fallar(m.id, -32601, `Method not supported: ${m.method}`);
+  } catch (e) {
+    return fallar(m.id, -32603, String(e?.message || e));
+  }
+});

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "@meiti/render",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Render testing built for AI agents: a structured map of the screen instead of screenshots, actions by intent instead of coordinates, and map-to-map comparison to see what changed. MCP server and library. Verified by Healer.",
+  "type": "module",
+  "license": "MIT",
+  "author": "MEITI (https://meiti.dev)",
+  "homepage": "https://meiti.dev/agents",
+  "repository": { "type": "git", "url": "git+https://github.com/meiti-dev/render.git" },
+  "bugs": { "url": "https://github.com/meiti-dev/render/issues" },
+  "keywords": ["mcp", "ai-agents", "testing", "render", "puppeteer", "accessibility", "visual-regression"],
+  "bin": { "meiti-render": "mcp.mjs" },
+  "exports": { ".": "./dist/index.js" },
+  "types": "./dist/index.d.ts",
+  "files": ["dist", "mcp.mjs", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "node armar.mjs",
+    "prepack": "node armar.mjs",
+    "test": "node prueba-mcp.mjs"
+  },
+  "dependencies": {
+    "puppeteer": "^25.16.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.20.3"
+  }
+}