xonecode 0.38.41 → 0.39.2

package/dist/core/atributosXone.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Un ÍNDICE DE CONSULTA RÁPIDA de los atributos XML de XOne por nodo, sacado de las tablas de la referencia de la skill.
+ * No la sustituye: dice si un atributo está en las tablas y DÓNDE leer el detalle.
+ *
+ * Existe por una medida: en cuatro pasadas de la misma calculadora los agentes leyeron las referencias de la skill 45-61
+ * veces, 15-25 ficheros distintos, los mismos releídos una y otra vez (`atributos-prop.md` son 34 KB), casi siempre para
+ * contestar «¿existe este atributo en este nodo?». Esa pregunta es la cara del bug mudo de XOne: un atributo inventado o
+ * puesto en el nodo equivocado no da error, se ignora.
+ *
+ * Tres reglas, para que el índice no contradiga a la skill:
+ * - **Se lee de las tablas, no se escribe a mano**: una copia se desfasa y entonces miente.
+ * - **Si dos ficheros de la skill no coinciden, se enseñan LOS DOS** con el aviso, en vez de quedarse con uno. La skill
+ *   se contradice a sí misma (medido: `imgbk` en `<group>` está en `nodos-group-y-frame.md` y no en
+ *   `atributos-coll-group-frame.md`; `border` en `<frame>` es una máscara en uno y un booleano en el otro).
+ * - **Nunca afirma «no existe»**: que no esté en estas tablas no lo prueba —la skill documenta atributos también en texto,
+ *   en el CSS y por tipo de control—, así que dice «no está en las tablas» y da la búsqueda en la skill.
+ *
+ * La forma que se reconoce: una sección `## N. Nodo \`<x>\`` (o `## N. Nodo x - …`), o el nodo del fichero entero cuando
+ * su título no lo parte en secciones; filas `| \`atributo\` | …` en tablas cuya primera columna es «Atributo»; la
+ * descripción es la columna «Descripción» (o la última); «Tipo» y «Default» si la cabecera las trae. Una fila puede nombrar
+ * varios (`\`a\` / \`b\``). Puro: `core/` no lee disco.
+ */
+export interface AtributoDeNodo {
+    atributo: string;
+    nodo: string;
+    tipo?: string;
+    defecto?: string;
+    descripcion: string;
+    /** De dónde sale, para ir al detalle: el fichero de la skill y la subsección («§3.4 Apariencia»). */
+    fichero: string;
+    seccion?: string;
+}
+/** Las filas de atributos de UN fichero de referencia. `nodoDelFichero`: el nodo cuando el fichero no lo parte por secciones. */
+export declare function interpretarReferenciaDeAtributos(texto: string, fichero: string, nodoDelFichero?: string): AtributoDeNodo[];
+export interface IndiceDeAtributos {
+    /** atributo (en minúsculas) → nodo → lo que dice cada fichero que lo documenta. */
+    porAtributo: ReadonlyMap<string, ReadonlyMap<string, readonly AtributoDeNodo[]>>;
+    porNodo: ReadonlyMap<string, readonly AtributoDeNodo[]>;
+    ficheros: readonly string[];
+}
+export declare function indiceDeAtributos(entradas: readonly AtributoDeNodo[]): IndiceDeAtributos;
+/** ¿Los ficheros que documentan este atributo en este nodo dicen TIPOS distintos? */
+export declare function tiposQueNoCoinciden(fuentes: readonly AtributoDeNodo[]): boolean;
+export declare const PIE_DEL_INDICE = "(\u00CDndice de consulta r\u00E1pida de las tablas de la skill: el detalle, los ejemplos y lo que cambia por tipo de control est\u00E1n en el fichero citado, y si discrepan manda la skill.)";
+/**
+ * La respuesta, en texto para el modelo. Con `atributo` (y opcionalmente `nodo`): en qué nodos está, con tipo, omisión,
+ * descripción corta y fichero; si otro fichero dice otra cosa, también. Con solo `nodo`: sus atributos por nombre,
+ * agrupados por subsección. `busqueda` compone la búsqueda en la skill para cuando no está (la da quien monta la tool).
+ */
+export declare function consultarAtributos(indice: IndiceDeAtributos, pregunta: {
+    atributo?: string;
+    nodo?: string;
+}, busqueda?: (atributo: string) => string): string;

package/dist/core/bitacora.d.ts

@@ -0,0 +1,21 @@
+/**
+ * La bitácora de UN turno. Se construye al empezarlo y muere con él.
+ *
+ * El alcance es la mitad del valor: una bitácora de proceso haría que los avisos de
+ * honestidad («el verificador es de pega») salieran en todos los turnos posteriores al
+ * primero, incluido un «cuéntame un chiste» que no verificó nada. Un aviso que salta
+ * cuando no ha pasado nada enseña al usuario a ignorarlo, que es lo contrario de lo que
+ * se compra con él.
+ *
+ * Por eso `corrio()` pregunta por lo que ha pasado AHORA, y nunca se le pregunta al objeto
+ * de dependencias, que vive en el proceso entero.
+ */
+export declare class Bitacora {
+    private readonly lineas;
+    /** `nodo` es la clave que luego consulta `corrio()`; `detalle` es para el humano. */
+    anota(nodo: string, detalle?: string): void;
+    /** ¿Ha corrido este nodo en ESTE turno? */
+    corrio(nodo: string): boolean;
+    get todo(): readonly string[];
+    get vacia(): boolean;
+}

package/dist/core/cloudstudio.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Los tipos que cruzan la frontera CloudStudio ↔ xonecode.
+ *
+ * Viven en `core/` a propósito: son datos, no transporte. El SDK MCP se queda en `agent/`.
+ */
+/** Una entrada del inventario remoto, tal cual la da `get_project_structure`. */
+export interface EntradaRemota {
+    /** Ruta POSIX relativa a la raíz del proyecto. */
+    ruta: string;
+    bytes: number;
+}
+export type ManifiestoRemoto = EntradaRemota[];
+/**
+ * Lo que devuelve `estructura()`: las entradas vistas Y si el servidor las recortó.
+ *
+ * `studio_get_project_structure` trunca (medido: con `maxFiles:60` ya venía
+ * `truncated:true`; el tope duro es 2000). Tirar ese dato y devolver solo el array deja
+ * al llamador sin forma de saber que quedó algo fuera — y el manifiesto es lo que
+ * sostiene el candado de borrado en CloudStudio.
+ */
+export interface EstructuraRemota {
+    entradas: ManifiestoRemoto;
+    truncado: boolean;
+}
+/** Qué proyecto y qué rama tiene abiertos el servidor AHORA. */
+export interface ContextoRemoto {
+    proyecto: string;
+    rama: string;
+}
+/** Lo que queda escrito en `.xonecode/cloudstudio/sync.json`: diagnóstico, no estado. */
+export interface EstadoDeSync {
+    proyecto: {
+        id: string;
+        nombre: string;
+    };
+    rama: string;
+    fecha: string;
+    /** Cómo se bajó. `parcial` obliga al candado de borrado. */
+    via: "zip" | "parcial";
+    /** El inventario del remoto en el momento de bajar. */
+    manifiesto: ManifiestoRemoto;
+    /** Las rutas que REALMENTE se pudieron traer. */
+    descargados: string[];
+    /** Por qué falló el ZIP, cuando `via` es `parcial`. Es la pista para arreglarlo. */
+    motivo?: string;
+    /**
+     * El listado de la raíz llegó truncado al enumerar el remoto (`enumerarRemoto`).
+     *
+     * El manifiesto es lo que sostiene el candado de borrado: si vino incompleto, puede
+     * faltarle una ruta que sí existe en Studio, y esa ausencia no se puede demostrar
+     * después. Se declara aquí, en el propio `sync.json`, en vez de vivir solo en un aviso
+     * de consola que nadie vuelve a leer una vez pasa el turno.
+     */
+    raizTruncada?: boolean;
+    /**
+     * Los ficheros bajados que no se pueden leer como lo que son (`validarTrasDescarga`): una
+     * cadena JSON en vez del fichero, o un `app.xml`/`.xne` mal formado. Ausente = todo se lee.
+     * Se escribe aquí por lo mismo que `raizTruncada`: el aviso de consola no sobrevive al turno,
+     * y una copia así no arranca en el aparato (IXCODE-16).
+     */
+    ilegibles?: Array<{
+        ruta: string;
+        motivo: string;
+    }>;
+}
+/**
+ * Una operación de subida ya decidida. La ejecuta `agent/cloudstudio/subida.ts`.
+ *
+ * El binario solo tiene modo `base64`. El modo `chunked` del servidor NO está
+ * implementado: `CloudStudioPort.subirBinario` ni siquiera lleva el modo, y el adaptador
+ * manda siempre base64. Mientras siga así, un binario que no cabe en base64 no es una
+ * operación pendiente sino una operación IMPOSIBLE (`OperacionOmitida`) — dejarla en el
+ * plan atascaba la subida entera para siempre, porque la ref solo avanza sin fallos.
+ *
+ * **`clase` viaja porque es lo que se MIRA al decidir, y `tipo` no lo dice.** Un texto que
+ * ya estaba en Studio y se edita y un texto que es nuevo se suben igual —con la misma
+ * tool—, así que mirando `tipo` son la misma operación: quien decide cuál de los dos es ve
+ * «no se modifica» / «se añade», y eso es justo lo que se comprueba antes de publicar algo
+ * en un servidor remoto. Es el dato de `CambioLocal.clase` (`core/planDeSubida.ts`), que
+ * hasta ahora se calculaba y se tiraba en la puerta. El borrado NO la lleva: su `tipo` ya
+ * la dice, y un campo que solo puede valer una cosa es una invitación a contradecirse.
+ */
+export type OperacionDeSubida = {
+    tipo: "texto";
+    ruta: string;
+    clase: "nuevo" | "modificado";
+} | {
+    tipo: "binario";
+    ruta: string;
+    bytes: number;
+    modo: "base64";
+    clase: "nuevo" | "modificado";
+} | {
+    tipo: "borrado";
+    ruta: string;
+};
+/**
+ * Algo que había que sincronizar y NO se puede, con el porqué.
+ *
+ * Es el camino de escape: sale del plan, se declara (por consola y en `sync.log`) y deja
+ * que la ref avance con el resto. Sin él, una sola operación imposible —la primera imagen
+ * borrada, el primer `.db` de más de 5 MB— dejaba `/sync subir` inútil de forma
+ * PERMANENTE: fallaba, la ref no se movía, el siguiente `/sync` recalculaba el mismo plan
+ * y volvía a fallar, para siempre.
+ */
+export interface OperacionOmitida {
+    ruta: string;
+    /** En castellano y accionable: qué hacer con esto, no solo que no se hizo. */
+    motivo: string;
+}
+/**
+ * El hueco de política que autoriza una subida — NO «preguntar al humano»: quién lo
+ * rellena es una decisión de la piel, no del motor. `agent/cloudstudio/subida.ts` solo exige que
+ * ALGUIEN lo rellene (fail-closed por TIPO: no hay forma de llamar a `subir()` sin decir
+ * cómo se autoriza) y no presupone que detrás haya una persona.
+ *
+ * Dos políticas previstas:
+ * - **Interactiva** (la única implementada hoy, en `cli/`): un humano ve el plan y
+ *   responde sí/no. Sin TTY, sin un sí explícito, no se sube.
+ * - **Autónoma** (futura, NO implementada): la rellenará el papel `afilado` — el juez —
+ *   cuando el usuario trabaje sin mirar. Pero un veredicto de juez a secas no basta: hace
+ *   falta ADEMÁS que el código compruebe condiciones deterministas antes de invocarlo
+ *   siquiera —verificador en verde, árbol limpio, plan sin pendientes—, porque a un
+ *   modelo se le puede pedir que avise de algo y no avisar; en este repo los avisos son
+ *   código, no prompt. Hoy no existe el lazo plan→ejecuta→verifica→juzga que la
+ *   sustentaría, así que esta política no se implementa todavía: el hueco queda limpio
+ *   para enchufarla el día que exista.
+ */
+export type PoliticaDeAprobacion = (plan: readonly OperacionDeSubida[]) => Promise<AutorizacionDeSubida>;
+/**
+ * Lo que contesta la política: nada (`false`), el plan ENTERO (`true`), o solo las rutas que
+ * la persona dejó marcadas (`{rutas}`) — la consola web deja elegir qué ficheros suben.
+ *
+ * **Nunca se decide por su veracidad**: `{rutas: []}` es un objeto y por tanto «verdadero», y
+ * leerlo así convertiría «no marqué nada» en «súbelo». Lo que se ejecuta lo dice SIEMPRE
+ * `planAutorizado`, y un plan autorizado vacío es un rechazo.
+ */
+export type AutorizacionDeSubida = boolean | {
+    rutas: readonly string[];
+};
+/**
+ * Las operaciones que se ejecutan de verdad: el plan cruzado con lo autorizado.
+ *
+ * Es una INTERSECCIÓN y no una lista que llega de fuera: una ruta que no está en el plan —un
+ * cliente roto, una selección de otra pregunta— no añade nada, solo puede quitar. Conserva el
+ * orden del plan, que es el que decidió `planDeSubida`.
+ */
+export declare function planAutorizado(plan: readonly OperacionDeSubida[], autorizacion: AutorizacionDeSubida): OperacionDeSubida[];
+/**
+ * Quién autoriza que «Actualizar repo local» VACÍE la copia y la baje entera.
+ *
+ * Es el mismo hueco fail-closed por TIPO que `PoliticaDeAprobacion`: sin confirmación no se
+ * vacía nada, y la bajada vuelve a la regla de antes —se niega con cambios sin commitear—. Lo
+ * que se decide va DELANTE: `sinCommitear` es lo que se va a perder, y se pierde además la
+ * historia de git de la copia, que se rehace desde cero con la bajada como primer commit.
+ */
+export type ConfirmacionDeBajada = (loQueSePierde: {
+    sinCommitear: readonly string[];
+}) => Promise<boolean>;
+/**
+ * Las TRES acciones de `/sync`, con nombre propio.
+ *
+ * Existían escritas tres veces —en el puerto `Consola.sincronizar`, en el manejador del comando
+ * y en la ayuda— y una cuarta estaba a punto al aparecer el acto `sincronizacion`, que también
+ * tiene que decir cuál fue. Nombradas aquí, que es donde vive la sincronización, y no en `cli/`:
+ * el acto que las guarda es de `core/`.
+ */
+export type AccionDeSincronizacion = "estado" | "bajar" | "subir";

package/dist/core/codificacion.d.ts

@@ -0,0 +1,81 @@
+/**
+ * La codificación de un fichero de texto del proyecto, en las dos direcciones, con UNA tabla por
+ * juego de caracteres.
+ *
+ * Los proyectos XOne traen sus `.xne` en UTF-8 o en ISO-8859 (`<?xml … encoding="iso-8859-15"?>`,
+ * lo que emiten las plantillas de la skill). XOne los lee según ese `encoding=`, así que guardarlos
+ * en otra codificación rompería cada tilde sin un error que leer: un bug mudo, y el mismo que la
+ * skill nombra como «encoding incoherente». Lo que hace falta es escribir en la codificación que el
+ * fichero YA tenía, o la que DECLARA si todavía no la delatan sus bytes.
+ *
+ * Dos tablas de 8 bits, y se elige UNA por fichero en las dos direcciones —leer con una y escribir
+ * con otra movería caracteres—:
+ * - `iso-8859-15` si el prólogo lo declara: el € en 0xA4.
+ * - `windows-1252` en todo lo demás (lo que `TextDecoder("latin1")` es en WHATWG): el € en 0x80, y
+ *   los cinco bytes que windows-1252 no define salen como el control C1 del mismo número.
+ * Cada codificador se CONSTRUYE invirtiendo su decodificador byte a byte, no se copia de una tabla:
+ * así la ida y vuelta es exacta por construcción, C1 incluidos.
+ *
+ * Puro: `Uint8Array` y `TextDecoder`, sin `Buffer` ni disco.
+ */
+export type Tabla8Bits = "windows-1252" | "iso-8859-15";
+export type CodificacionDeEscritura = "utf-8" | Tabla8Bits;
+/** Bytes de 8 bits → texto, con la tabla del fichero. */
+export declare function decodificar8Bits(bytes: Uint8Array, tabla: Tabla8Bits): string;
+/** El carácter que no cabe y su línea (desde 1), para poder decirlo. */
+export interface CaracterNoRepresentable {
+    caracter: string;
+    linea: number;
+}
+/**
+ * Texto → bytes de 8 bits, o el PRIMER carácter que no cabe. Nunca se sustituye por `?`: un `?` en
+ * lugar de una letra es otra forma del bug mudo. Se recorre por CODE POINT, así que un emoji (dos
+ * unidades UTF-16) se nombra entero.
+ */
+export declare function codificar8Bits(texto: string, tabla: Tabla8Bits): {
+    bytes: Uint8Array;
+} | CaracterNoRepresentable;
+/** Cómo se NOMBRA la tabla en un mensaje para una persona o para el agente. */
+export declare function nombreDeTabla(tabla: Tabla8Bits): string;
+/**
+ * La codificación que DECLARA el prólogo XML, mirada como la mira `xone-linter`
+ * (`XmlParser.js#detectEncoding`): la cabeza del texto, `<?xml … encoding="…"`, y «8859-15» antes
+ * que «8859-1» (que lo contiene). Lo que no es un prólogo al principio —sin contar el BOM y los
+ * blancos— no declara nada, y una codificación que no sabemos escribir tampoco.
+ */
+export declare function codificacionDeclarada(cabeza: string): CodificacionDeEscritura | undefined;
+/** La tabla de 8 bits de unos bytes que NO son UTF-8: la que declare su prólogo, o windows-1252. */
+export declare function tablaDeLosBytes(bytes: Uint8Array): Tabla8Bits;
+/** UTF-8 ESTRICTO, el mismo criterio que la lectura para decidir que un fichero no lo es. */
+export declare function esUtf8Valido(bytes: Uint8Array): boolean;
+/**
+ * En qué bytes se guarda `texto` sobre lo que hay (`actual`, ausente si el fichero es NUEVO). En
+ * orden:
+ * 1. Lo que ya no es UTF-8 sigue en 8 bits: con la tabla que declare lo que se escribe, si declara
+ *    una de 8 bits (la que usará la próxima lectura), o si no con la de sus bytes (`tablaDeLosBytes`).
+ * 2. Un UTF-8 con algo que no es ASCII se queda en UTF-8: nunca se transcodifica lo que nadie tocó.
+ * 3. Un ASCII puro —que es UTF-8 válido y no delata nada— o un fichero nuevo siguen lo que DECLARE el
+ *    texto que se escribe; sin declaración, UTF-8. Es el caso de toda colección nueva con la
+ *    plantilla de la skill (`encoding="iso-8859-15"`): sin esto, su primera tilde iba en UTF-8 bajo
+ *    una declaración de 8 bits.
+ */
+export declare function codificacionParaEscribir(actual: Uint8Array | undefined, texto: string): CodificacionDeEscritura;
+/**
+ * Bytes de un texto del proyecto → el texto que ve el AGENTE: UTF-8 si lo es (con el BOM dentro,
+ * como `readFile(…, "utf8")`, que es lo que hace la librería), y si no, su tabla de 8 bits. Es lo
+ * que tiene que leer cualquiera que compare contra lo que el agente leyó —el ANTES de la tarjeta de
+ * aprobación—: con UTF-8 a secas, un ancla con tilde no calzaba y cada línea con tilde salía cambiada.
+ */
+export declare function decodificarComoTexto(bytes: Uint8Array): string;
+/**
+ * Un diff de git, en BYTES, → el texto que se enseña. LÍNEA A LÍNEA con la regla de siempre: la que
+ * es UTF-8 válido se lee como UTF-8, y la que no, con la tabla de 8 bits del fichero (`tabla`, que
+ * decide quien llama mirando el fichero: la de su prólogo, o windows-1252).
+ *
+ * Existe por una captura suya: el diff de los cambios de la sesión leía la salida de git como
+ * UTF-8, y en un `.xne` Latin-1 cada tilde salía «Aplicaci�n» — el fichero estaba bien, el diff lo
+ * enseñaba roto. Línea a línea y no el diff entero porque las cabeceras de git van en ASCII y un
+ * fichero que CAMBIÓ de codificación trae una mitad en cada una: decidir una sola para todo
+ * rompería la otra mitad.
+ */
+export declare function decodificarParche(bytes: Uint8Array, tabla: Tabla8Bits): string;

package/dist/core/comandoExterno.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Qué `Bash` se le deja correr a un agente EXTERNO (Claude Code) que declara `ejecucion: true`.
+ *
+ * En los motores externos la shell está cerrada: lo que el hijo ejecuta va directo a la máquina,
+ * sin nuestras guardas. La excepción es ESTRECHA a propósito: una sola llamada a uno de los
+ * scripts de las skills que el agente declara (`xone-hotswap`, `xone-log-android`…), por su
+ * NOMBRE, con argumentos que la shell no puede reinterpretar. Todo lo demás se deniega.
+ *
+ * La gramática sale de cómo se llaman de verdad (`skills/xone-hotswap/SKILL.md`): palabras
+ * sueltas (`--app MiApp`, `name=MAP_BT_ACEPTAR`, `--`, nombres de fichero) y, para un texto con
+ * espacios, comillas SIMPLES —dentro de ellas la shell no expande nada—. Se rechaza lo demás:
+ * comillas dobles, `$`, backticks, `\`, comodines, `~`, `{}`, `#`, redirecciones, tuberías,
+ * encadenados, saltos de línea y una asignación `VAR=` delante.
+ */
+/**
+ * El motivo por el que ese comando NO se deja correr, o `undefined` si se deja. `scripts` son los
+ * nombres (sin ruta) de los ejecutables de las skills del agente. El motivo dice la forma que sí
+ * vale: sin eso el modelo reintenta con `./scripts/…` o con la ruta de la variable.
+ */
+export declare function motivoDeComandoExternoInaceptable(comando: string, scripts: readonly string[]): string | undefined;
+/**
+ * El MISMO comando, lanzado con `node` y la ruta del script: lo que hace falta en Windows, donde un script sin extensión
+ * no se ejecuta por su nombre. Se llama SOLO con un comando que `motivoDeComandoExternoInaceptable` ya admitió, así que
+ * la forma es «nombre args» y los argumentos no llevan nada que la shell interprete; la ruta la pone el código, con `/`
+ * (el Bash de Claude Code en Windows es Git Bash) y entre comillas simples. `undefined` si el script no tiene ruta o si
+ * la ruta trae una comilla simple: antes que componer un escape, no se ejecuta.
+ */
+export declare function comandoConNode(comando: string, rutas: Readonly<Record<string, string>>, 
+/**
+ * El Node con que se lanza: la ruta ABSOLUTA del que corre xonecode (`process.execPath`), no `node` a secas. Medido en
+ * Windows: en el Git Bash del hijo `node` no estaba en el PATH («node: command not found»). Ausente = `node`.
+ */
+node?: string): string | undefined;
+/** El script de `xone-development` que pasa un `.xne` de 8 bits a UTF-8 (`skills/xone-development/lib/aUtf8.mjs`). */
+export declare const SCRIPT_A_UTF8 = "xone-a-utf8";
+/**
+ * Qué hacer con un `.xne` en ISO-8859-15 o windows-1252, que las tools de Claude Code no saben escribir. Medido:
+ * 2.1.301 lo rechaza ANTES del hook y de `canUseTool` (xonecode no puede escribirlo por él), y 2.1.263/2.1.280
+ * escribían UTF-8 dentro de un fichero que declara ISO-8859-15, rompiendo cada tilde sin aviso. Y todos lo LEEN con
+ * «�». Decisión suya: que lo convierta él a UTF-8, y se le dice aquí. Solo si el script está entre los suyos.
+ */
+export declare const TEXTO_DE_A_UTF8: string;
+/**
+ * Lo que se le DICE al hijo de su shell, sacado de lo que de verdad se le concede. Sin esto lo descubría a base de
+ * denegaciones: medido en una tarea de Maset, el desarrollador en Claude Code (con «Ejecuta comandos» marcado y skills
+ * sin ningún script) probó `Bash` y concluyó que «solo admite un script que el sandbox también rechaza». Sin ejecución
+ * concedida no se dice nada: el SDK ya le enseña `Bash`, y el hook la deniega con su motivo.
+ */
+export declare function textoDeLaShellExterna(scripts: readonly string[] | undefined): string | undefined;

package/dist/core/compararCapturas.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Comparar la ESTRUCTURA de dos pantallas con aritmética de píxeles (IXCODE-18).
+ *
+ * ## Por qué existe, medido
+ *
+ * Pidiendo a un agente «haz este diseño» (una calculadora de Stitch), el turno cerró diciendo «sin
+ * solape ni recorte: los controles caben» mientras el teclado ocupaba un tercio de la pantalla y
+ * las teclas salían cortadas. El crítico visual había dicho rojo y el propio agente lo descartó
+ * como «no fiable»: dos opiniones de modelos, ninguna cifra. Con cifras el desacuerdo no cabe: la
+ * maqueta ocupaba el 96 % del alto y la captura el 33 %.
+ *
+ * ## Qué mide, y por qué solo eso
+ *
+ * Es DETERMINISTA: las mismas dos imágenes dan siempre los mismos números, y no depende de que el
+ * modelo tenga visión. Mide **dónde hay contenido**, no cómo es:
+ *
+ * 1. El FONDO es el color más frecuente (una pantalla de app es un fondo liso con cosas encima).
+ * 2. «Contenido» es todo píxel que se aparta del fondo más que `UMBRAL_DE_CONTENIDO`.
+ * 3. La ocupación por FRANJAS horizontales (`FRANJAS_DE_FILAS`) y verticales
+ *    (`FRANJAS_DE_COLUMNAS`), y hasta dónde llega el contenido.
+ *
+ * Todo en PORCENTAJES del área útil, así que una maqueta de 390 px y una captura de 1080 px se
+ * comparan sin escalar. Se recorta un margen arriba y abajo (barra de estado y de navegación).
+ *
+ * **Lo que NO hace, y se dice en cada respuesta**: no ve texto cortado, ni estilo (píldoras contra
+ * lápidas), ni colores. Y **no cuenta teclas**: se probó y no es fiable (las teclas oscuras sobre
+ * fondo oscuro se funden: 12 manchas en una maqueta de unas 20). Da el ESQUELETO; el parecido y las
+ * roturas siguen siendo cosa del crítico con visión.
+ *
+ * `core/` no decodifica imágenes: recibe los píxeles ya en RGBA (`agent/dispositivos/
+ * decodificarImagen.ts` los saca de un PNG o un JPEG).
+ */
+export interface ImagenRgba {
+    ancho: number;
+    alto: number;
+    /** RGBA, 4 bytes por píxel, fila a fila. */
+    datos: Uint8Array | Uint8ClampedArray;
+}
+/** Fracción del alto que se recorta arriba y abajo: barra de estado y barra de navegación. */
+export declare const RECORTE_DE_BARRAS = 0.05;
+export declare const FRANJAS_DE_FILAS = 10;
+export declare const FRANJAS_DE_COLUMNAS = 8;
+/** Suma de diferencias por canal a partir de la cual un píxel ya no es el fondo. */
+export declare const UMBRAL_DE_CONTENIDO = 24;
+/**
+ * El ENCAJE: cuánto puede separarse cada borde del contenido (arriba, abajo, izquierda, derecha) del de la maqueta, en
+ * fracción de la pantalla. Existe porque las distancias por franjas PROMEDIAN: calc12 cumplía el 10 % en horizontal
+ * (8 %) con el teclado acabando al 85 % del ancho donde la maqueta llega al 96 %, y 12 puntos vacíos abajo. Calibrado
+ * contra las capturas de las pasadas: la mejor (calc9) queda en 0-1,6 puntos por lado.
+ */
+export declare const TOLERANCIA_DE_ENCAJE = 0.03;
+/** Diferencia de ocupación (en puntos de 0 a 1) a partir de la cual una franja se señala. */
+export declare const DIFERENCIA_QUE_SE_SEÑALA = 0.3;
+/** Diferencia media de perfil bajo la que dos pantallas se dan por parecidas en estructura. */
+export declare const DISTANCIA_PARECIDA = 0.12;
+export interface MedidaDePantalla {
+    /** El color de fondo detectado, RGB. */
+    fondo: [number, number, number];
+    /** De 0 a 1: hasta dónde llega el contenido (primera a última fila con contenido, sobre el alto útil). */
+    inicioDelContenido: number;
+    finDelContenido: number;
+    /** De 0 a 1: dónde empieza y acaba el contenido a lo ANCHO, la mediana de las franjas del alto que tienen contenido. */
+    izquierdaDelContenido: number;
+    derechaDelContenido: number;
+    /** Ocupación (0 a 1) de cada franja horizontal, de arriba abajo. */
+    filas: number[];
+    /** Ocupación (0 a 1) de cada franja vertical, de izquierda a derecha. */
+    columnas: number[];
+}
+export type Veredicto = "parecida" | "distinta";
+export interface Comparacion {
+    referencia: MedidaDePantalla;
+    captura: MedidaDePantalla;
+    /** Diferencia media de ocupación por franjas, de 0 (igual) a 1. */
+    distanciaVertical: number;
+    distanciaHorizontal: number;
+    /** Cuánto se separa cada borde del contenido del de la maqueta (captura − referencia, fracción de la pantalla). */
+    encaje: {
+        arriba: number;
+        abajo: number;
+        izquierda: number;
+        derecha: number;
+    };
+    hallazgos: string[];
+    veredicto: Veredicto;
+}
+/** Lo más que puede ocupar un MARCO a cada lado, en fracción del ancho. */
+export declare const ANCHO_MAXIMO_DEL_MARCO = 0.03;
+/** La imagen sin su marco lateral, si lo tiene (`columnasDeMarco`). Sin marco, la MISMA imagen. */
+export declare function sinMarcoLateral(img: ImagenRgba, recorte?: number): ImagenRgba;
+/**
+ * La ocupación de una imagen. **Lanza si no se puede medir** (vacía o diminuta): quien llama lo
+ * convierte en texto. Lo primero, sin el marco lateral que trae una maqueta (`sinMarcoLateral`).
+ */
+export declare function medirPantalla(entrada: ImagenRgba, recorte?: number): MedidaDePantalla;
+/** El peor borde, en valor absoluto: lo que decide si encaja. */
+export declare function desajusteDeEncaje(e: Comparacion["encaje"]): number;
+/** Compara dos pantallas ya medidas. Puro: los números salen de `medirPantalla`. */
+export declare function compararMedidas(referencia: MedidaDePantalla, captura: MedidaDePantalla): Comparacion;
+/** Medir las dos y compararlas. */
+export declare function compararPantallas(referencia: ImagenRgba, captura: ImagenRgba): Comparacion;
+export declare function informeDeComparacion(c: Comparacion): string[];
+/**
+ * Una zona de la imagen, en FRACCIONES de la imagen entera (0 a 1): `x`, `y` y su tamaño. Así sirve
+ * igual a 1080×2400 que a cualquier otra resolución.
+ */
+export interface Region {
+    x: number;
+    y: number;
+    ancho: number;
+    alto: number;
+}
+/** Fracción de píxeles de la zona que tienen que diferir para dar la zona por CAMBIADA. */
+export declare const UMBRAL_DE_CAMBIO = 0.003;
+export interface Cambio {
+    region: Region;
+    /** Fracción (0 a 1) de los píxeles de la zona que cambiaron. */
+    cambiados: number;
+    /** El rectángulo mínimo que contiene todo lo que cambió, en fracciones de la imagen; ausente si nada cambió. */
+    cajaDelCambio?: Region;
+    veredicto: "cambio" | "igual";
+}
+/** Por qué una zona no vale, o `undefined`. */
+export declare function motivoDeRegionInaceptable(r: Region): string | undefined;
+/**
+ * Cuánto cambió una zona entre dos capturas. **Lanza** si no son comparables: las dos tienen que ser
+ * del MISMO tamaño (dos capturas del mismo aparato); comparar tamaños distintos es la pregunta de
+ * `compararPantallas`, no ésta.
+ *
+ * Es lo que un agente escribía a mano cada pasada (46 scripts de Python con PIL y 31 `md5`): un
+ * `md5` igual solo dice que TODA la imagen es igual, no si cambió lo que importaba, y uno distinto
+ * puede ser solo un cursor parpadeando.
+ */
+export declare function medirCambio(antes: ImagenRgba, despues: ImagenRgba, region?: Region): Cambio;
+/** El informe en texto. En «igual» dice las DOS explicaciones posibles, para que no se elija una sin mirar. */
+export declare function informeDeCambio(c: Cambio): string[];