xonecode 0.38.44 → 0.39.4

package/dist/core/estilos.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Qué estilo le toca de verdad a un control, y de dónde sale.
+ *
+ * ## La medida que lo motiva
+ *
+ * Diez pasadas reales del mismo encargo visual («el título sale cortado»), 19-09-2026. En OCHO
+ * de ellas `xone_navegacion` es la PRIMERA tool del turno —el modelo sí empieza por donde se le
+ * dice— y luego deja de servirle: la usa una o dos veces y el resto del turno son **20-46
+ * lecturas y 30-42 `grep`**, de los cuales ~22 de cada 30 son **la misma clase con variantes**
+ * (`xnTituloHeaderC`, `.xnTituloHeader`, `xnHeader`, `xnLightTitle`, `font42`…). Más cinco
+ * ficheros CSS, varios `.xne` AJENOS buscando ejemplos, y nueve documentos de skill.
+ *
+ * El índice actual contesta sobre el MODELO `.xne` —colecciones, campos, referencias— y el
+ * trabajo de un arreglo visual vive en la capa de ESTILOS, que no tenía índice. Esto lo cierra.
+ *
+ * ## Lo que NO se rederiva
+ *
+ * La cascada de XOne la resuelve `xone-linter`, no este módulo: `Stylesheet.lookup` está
+ * anotado como fiel a `FindStylesheetByClassName` (`CXoneApplication.mm:6146-6166`), con la
+ * sutileza de que **un fichero posterior que redirige por `extends` gana al atributo DIRECTO de
+ * uno anterior** —resolución intercalada por fichero, no dos pasadas globales—, y
+ * `selectorsFor` implementa el orden de prioridad (`prop.clase:tipo` → `prop.clase` →
+ * `.clase` → `prop:tipo` → `prop`) con sus dos banderas. Reescribir eso aquí sería un segundo
+ * sitio donde decidir lo mismo, que es justo el argumento por el que `xone_navegacion` usa la
+ * librería en vez de reimplementar `CrossReferenceRule`.
+ *
+ * Aquí vive lo que se ENSEÑA y con qué topes. Puro: sin disco y sin librería.
+ */
+/** Un atributo que acaba aplicándose, y por dónde llegó. */
+export interface AtributoEfectivo {
+    atributo: string;
+    valor: string;
+    /** El selector que lo aportó, o la marca de que viene del XML. */
+    de: string;
+}
+export interface EstiloDeProp {
+    coll: string;
+    prop: string;
+    tipo?: string;
+    /** El `class=` del prop, tal cual. Ausente si no tiene. */
+    clase?: string;
+    /** Selectores candidatos, de MÁS a MENOS prioridad. */
+    selectores: readonly string[];
+    /** Lo que la hoja aporta, ya resuelto. */
+    deLaHoja: readonly AtributoEfectivo[];
+    /** Lo que el XML del prop pone a mano. **Gana siempre** sobre la hoja. */
+    delXml: readonly AtributoEfectivo[];
+    /** Qué fichero declara cada selector que aporta algo. */
+    declaradoEn: readonly {
+        selector: string;
+        fichero: string;
+    }[];
+}
+/**
+ * Topes de lo que se enseña.
+ *
+ * Existen porque esto viaja al contexto del modelo entero y una hoja grande tiene decenas de
+ * atributos por selector. **Lo que no cabe se CUENTA**, como en todas partes aquí: una lista
+ * recortada en silencio se lee como la lista entera, y sobre eso se concluye de más.
+ */
+export declare const LIMITES_ESTILOS: {
+    readonly atributos: 30;
+    readonly selectores: 12;
+    readonly declaraciones: 12;
+};
+/** La marca de que un valor no viene de la hoja sino del XML del propio control. */
+export declare const DEL_XML = "el XML del prop (gana a la hoja)";
+/**
+ * La respuesta, en el formato que el turno necesitaba.
+ *
+ * Las cuatro preguntas que los greps estaban haciendo a mano —qué se aplica, de qué selector,
+ * qué selectores compiten y en qué fichero están— en una sola llamada. El orden no es
+ * cosmético: primero lo que se aplica, que es lo que se preguntó; los selectores y los ficheros
+ * van después, porque son el CAMINO y solo hacen falta si hay que cambiar algo.
+ */
+export declare function pintarEstiloDeProp(e: EstiloDeProp): string;

package/dist/core/events.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Lo que un turno le cuenta al mundo. `agent/` los emite, `core/` decide qué se enseña,
+ * las pieles (TUI y stdio) los pintan.
+ *
+ * Ningún evento lleva argumentos de tool. Ni truncados: `studio_edit_file` lleva el
+ * contenido del fichero y una tool MCP lleva el bearer. Enseñar el progreso no puede ser
+ * la forma de filtrar un secreto, así que el TIPO no los puede llevar.
+ *
+ * La excepción aparente es `tool.detalle`, y no es una excepción: es lo ÚNICO que
+ * sale de los argumentos, un campo por tool elegido a mano en la lista blanca de
+ * `agent/turno/resumenDeTool.ts` — `file_path`, `path` o `pattern`, nunca contenido. Una
+ * tool sin entrada en la lista no lleva `detalle`, exista lo que exista en sus
+ * argumentos.
+ */
+import type { Artefacto } from "./artefactos.js";
+import type { TareaPropuesta } from "./repartoDeEncargo.js";
+export type { Artefacto };
+export type DomainEvent = {
+    tipo: "token";
+    texto: string;
+    msgId?: string;
+}
+/**
+ * El razonamiento del modelo, cuando lo publica (los bloques `thinking` de Gemini, y el
+ * equivalente de los demás). Va SEPARADO de `token` a propósito: no es la respuesta, y
+ * mezclarlo con ella es lo que hacía `String(content)` —volcar el `repr` de la lista con
+ * el razonamiento dentro— y por lo que el puente empezó a filtrar por bloques.
+ *
+ * Que exista el evento no obliga a nadie a pintarlo: `Piel.razonamiento` es opcional, y
+ * las pieles de terminal no lo implementan — así la salida de una tubería sigue siendo
+ * byte-idéntica.
+ */
+ | {
+    tipo: "razonamiento";
+    texto: string;
+    msgId?: string;
+    /** Quién pensó: el orquestador o un especialista. Ausente = no consta (deepagents). */
+    origen?: OrigenDeLaTool;
+}
+/**
+ * El RESUMEN con el que la librería compacta la conversación al pasar el umbral de contexto
+ * (`agent/turno/resumenDeContexto.ts`), en trozos. Tampoco es la respuesta: salía por el
+ * mismo stream que ella y se pintaba —y se guardaba— como un mensaje del asistente. Lo
+ * distingue una ETIQUETA de la llamada, no el texto.
+ *
+ * Opcional como `razonamiento`: las pieles de terminal no lo implementan, así que ahí deja
+ * de imprimirse (antes salía en inglés como si fuera la respuesta) y la tubería sigue igual.
+ */
+ | {
+    tipo: "resumen";
+    texto: string;
+    msgId?: string;
+} | {
+    tipo: "fase";
+    fase: Fase;
+    detalle?: string;
+} | {
+    tipo: "tool";
+    nombre: string;
+    detalle?: string;
+    error?: string;
+    origen?: OrigenDeLaTool;
+} | {
+    tipo: "plan";
+    tareas: TareaDelPlan[];
+} | {
+    tipo: "tarea";
+    id: string;
+    indice: number;
+    total: number;
+    estado: EstadoTarea;
+}
+/**
+ * El veredicto del simulador sobre lo que ESTE turno escribió.
+ *
+ * `verde`, `errores` y `avisos` son de los ficheros que el turno tocó. `hallazgos` los
+ * lista —código, fichero RELATIVO al proyecto, línea y mensaje; nunca contenido—, porque
+ * un «2 errores» sin decir dónde no lo puede arreglar nadie, ni el humano ni el paso de
+ * reparación que viene detrás. `preexistentes` cuenta los que el simulador vio en
+ * ficheros que el turno NO tocó: se dicen aparte porque atribuírselos al agente sería
+ * falso, y callarlos sería fingir que el proyecto está limpio.
+ */
+ | {
+    tipo: "verificacion";
+    verde: boolean;
+    errores: number;
+    avisos: number;
+    hallazgos?: HallazgoDelTurno[];
+    preexistentes?: number;
+} | {
+    tipo: "reparacion";
+    intento: number;
+    tope: number;
+}
+/**
+ * El agente ha dejado un ARTEFACTO: un diagrama, un panel, una captura. No es un fichero
+ * del proyecto —vive en la carpeta de la sesión, ver `core/artefactos.ts`— y por eso se
+ * escribe SIN aprobación humana. Que se anuncie es la contrapartida: una escritura que
+ * nadie aprueba tiene que decirse, o es una escritura muda.
+ *
+ * Lleva la ruta VIRTUAL (`/artefactos/…`) y nunca la del disco ni el contenido: por aquí
+ * pasa lo que acaba en el transcript y en el cable.
+ */
+ | {
+    tipo: "artefacto";
+    artefacto: Artefacto;
+}
+/**
+ * El agente le PREGUNTA a la persona y el turno se para ahí (`ask_user_question` del motor
+ * TrueForge). La pregunta ya viaja como texto —con sus opciones numeradas— por `token`, que
+ * es lo que ven stdio y la TUI; esto lleva lo MISMO como DATO, para la piel que sabe pintar
+ * un botón por opción. Datos y no texto por la regla de `DecisionDeConsola`: deducir las
+ * opciones de «1. …» sería leer la sintaxis que la propia piel acaba de escribir. Solo se
+ * emite con opciones: sin ellas no hay botón que pintar y el texto basta.
+ */
+ | {
+    tipo: "consulta";
+    pregunta: string;
+    opciones: string[];
+}
+/**
+ * Una pregunta del agente que el HARNESS contestó solo porque la sesión está en modo autónomo
+ * (`sesionTrueforge.ts`, `opcionRecomendada`): `elegida` es la opción `(Recommended)`, y ausente es que no había
+ * ninguna y lo decide el agente. Es un evento propio y no un `aviso` porque es una DECISIÓN que la persona tiene que
+ * ver (IXCODE-47): como aviso caía plegada en «Verificaciones» y quien la había pedido contestaba después en el chat
+ * sin saber que el agente ya había seguido. No es una `consulta` con una marca: todo lo que lee una `consulta` la toma
+ * por pendiente —la tarjeta para contestar, el análisis de soporte, la web móvil— y esta no espera a nadie. A
+ * diferencia de `consulta`, no ha salido antes por `token`: quien no la pinte recibe la línea de siempre.
+ */
+ | {
+    tipo: "consulta-autonoma";
+    pregunta: string;
+    opciones: string[];
+    elegida?: string;
+}
+/**
+ * El agente PROPONE repartir un encargo grande en tareas de fondo encadenadas (`proponer_tareas`,
+ * `core/repartoDeEncargo.ts`). No crea nada: la persona revisa cada tarea y decide si se encolan. A diferencia de
+ * `consulta`, esto NO ha salido antes por `token`, así que una piel que no lo pinte recibe una línea de texto.
+ */
+ | {
+    tipo: "propuesta-de-tareas";
+    motivo: string;
+    tareas: TareaPropuesta[];
+} | {
+    tipo: "bloqueado";
+    motivo: MotivoBloqueo;
+    explicacion: string;
+} | {
+    tipo: "pausa";
+    pendientes: PendienteDeAprobacion[];
+} | {
+    tipo: "aviso";
+    texto: string;
+    severidad: "info" | "aviso" | "grave";
+} | {
+    tipo: "fin";
+    ms: number;
+};
+/**
+ * QUIÉN pidió una tool: el orquestador o un especialista, y cuál si se sabe.
+ *
+ * El `rol` es EXACTO en los dos motores —un especialista siempre llega por la delegación, y eso
+ * se ve en el namespace de deepagents y en el hilo de TrueForge—; lo que puede faltar es el
+ * NOMBRE. deepagents no lo da (sus segmentos son ids opacos, ver `puente.ts#origenDeTool`) y
+ * TrueForge sí (`quienEs`, hilo → especialista). **Ausente es «no consta»**, y por eso no hay un
+ * booleano de exactitud al lado: permitiría la combinación imposible de un nombre «inexacto».
+ *
+ * El nombre es el de un especialista CARGADO, nunca el texto que el modelo puso al delegar ni un
+ * id de hilo: un nombre inventado por el modelo o un id opaco en el cable serían un dato con
+ * forma de dato que no lo es. Y el orquestador no lleva nombre porque solo hay uno.
+ *
+ * Ausente entero —el evento sin `origen`— es lo de antes: el doble guionizado y las sesiones
+ * guardadas antes de que existiera.
+ */
+export type OrigenDeLaTool = {
+    rol: "orquestador";
+} | {
+    rol: "especialista";
+    nombre?: string;
+};
+/** Las fases del lazo. Es lo que llena los 100-300 s en que el agente no habla. */
+/** Un hallazgo del simulador, ya relativo al proyecto. Sin contenido de ningún fichero. */
+export interface HallazgoDelTurno {
+    code: string;
+    severidad: "error" | "warning" | "info";
+    mensaje: string;
+    fichero?: string;
+    linea?: number;
+}
+export type Fase = "entendiendo" | "planificando" | "esperando-aprobacion" | "ejecutando" | "verificando" | "juzgando" | "subiendo" | "respondiendo";
+export type EstadoTarea = "pendiente" | "en-curso" | "hecha" | "fallida";
+export interface TareaDelPlan {
+    id: string;
+    descripcion: string;
+    /** Criterios de aceptación. VACÍO es honesto; un texto de relleno haría juzgar un adorno. */
+    aceptacion: string[];
+}
+/**
+ * Los tres motivos por los que el lazo para sin terminar, y son DISTINTOS a propósito.
+ *
+ * `no-progreso` no es «se acabaron los intentos»: es la misma huella de error dos veces,
+ * y se corta ANTES de agotar el presupuesto porque seguir no va a cambiar nada.
+ */
+export type MotivoBloqueo = "no-progreso" | "tope-reparaciones" | "tope-replanificaciones";
+export interface PendienteDeAprobacion {
+    id: string;
+    /** Qué especialista lo pide. Viaja aquí porque el interrupt NO dice de dónde viene. */
+    origen: string;
+    descripcion: string;
+    decisionesPermitidas: string[];
+    /**
+     * Escribe FUERA de la máquina: una tool de un conector MCP que no se declara de lectura (crear
+     * o generar en la cuenta de Stitch). No se aplica sola ni en modo autónomo ni en una tarea de
+     * fondo —el mismo trato que `/sync subir`—: sin una persona que diga que sí, es un no.
+     */
+    remota?: true;
+}

package/dist/core/exportacion.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Exportar un documento del proyecto a PDF: las reglas PURAS.
+ *
+ * **Por qué el harness y no el agente.** Producir un PDF es lo que las skills `pdf`/`docx`
+ * de Claude Code hacen ejecutando scripts, y a un motor externo no se le concede shell
+ * —`Bash` está denegada, y abrirla dejaría a ese hijo reescribir el proyecto sin diff ni
+ * aprobación—. Medido además sobre la máquina real: esas skills asumen el sandbox donde sus
+ * dependencias vienen puestas (`reportlab`, `pypdf`, `docx` de npm, `pandoc`), y ahí no
+ * estaba ninguna, así que conceder la shell no habría dado el PDF. Lo que sí hay en cualquier
+ * máquina que use la consola web es un navegador, y un navegador imprime — así que la
+ * conversión la hace el harness con un comando FIJO, y la shell del hijo sigue cerrada.
+ *
+ * Aquí solo está lo que se puede decidir sin tocar disco. Lanzar el navegador es de
+ * `agent/exportarPdf.ts`.
+ */
+/**
+ * Lo que se sabe convertir. Lista CERRADA: lo que no está no se intenta.
+ *
+ * `.md` porque es lo que el agente escribe cuando se le pide documentación, y `.html` porque
+ * es lo que produce la skill de artefactos. Un `.xne` o un `.js` no entran: imprimir código
+ * fuente a PDF no es una necesidad que nadie haya tenido, y ofrecerlo sería un botón que
+ * nadie pulsa sobre cada fichero del árbol.
+ */
+export declare const EXTENSIONES_EXPORTABLES: readonly [".md", ".html", ".htm"];
+/** ¿Hace falta convertir Markdown antes, o el fichero ya es HTML? */
+export declare function esMarkdown(ruta: string): boolean;
+/**
+ * Por qué no se puede exportar esa ruta, o AUSENTE si vale.
+ *
+ * No comprueba que exista ni que se pueda leer: de eso ya hay una barrera
+ * (`motivoDeRutaInaceptable` y el `realpath` de `leerFicheroDeProyecto`), y duplicarla aquí
+ * sería un segundo sitio donde decidir sobre una ruta.
+ */
+export declare function motivoDeExportacionInaceptable(ruta: string): string | undefined;
+/**
+ * Dónde queda el PDF: al lado del original y con su mismo nombre.
+ *
+ * **El destino lo DERIVA el código, nunca se recibe.** Es lo que impide que quien pide la
+ * exportación elija dónde escribir: con un destino por parámetro, esta función sería una
+ * forma de escribir cualquier fichero del proyecto sin pasar por ninguna aprobación.
+ */
+export declare function rutaDePdf(ruta: string): string;
+/**
+ * El documento listo para imprimir: el cuerpo HTML dentro de una hoja de estilos de PÁGINA.
+ *
+ * Los estilos no son decoración, son lo que hace legible un PDF de doce páginas y se
+ * comprobaron imprimiendo uno de verdad: `@page` con márgenes, `break-inside: avoid` en
+ * tablas y bloques de código —sin eso una tabla se parte por la mitad entre dos hojas— y
+ * `break-after: avoid` en los encabezados, para que un título no se quede solo al pie.
+ *
+ * **Y una imagen se limita también en ALTO**, no solo en ancho. Medido con una captura de móvil
+ * (1080×2400): con solo `max-width: 100%` medía unos 40 cm a todo el ancho de un A4, más que la
+ * página, y el PDF salía con el título solo en la primera hoja y la captura partida en las dos
+ * siguientes. Con `max-height` se reduce entera, sin deformarse, y cabe en una página.
+ *
+ * El título va ESCAPADO: sale de un nombre de fichero del proyecto, y un `<` ahí dentro
+ * rompería la cabecera del documento.
+ */
+export declare function documentoImprimible(cuerpo: string, titulo: string): string;
+/**
+ * La política que impide que imprimir ejecute nada.
+ *
+ * **Y es una CSP y no un flag del navegador, porque los flags NO lo hacen.** Medido contra
+ * el Chrome instalado con un documento que reescribe su propio texto desde un `<script>`:
+ * con `--disable-javascript`, con `--blink-settings=scriptEnabled=false` y sin nada, el
+ * script se ejecutó en los tres casos; y encima el segundo hace que `--print-to-pdf` no
+ * escriba el fichero, en silencio y con código de salida 0. Con esta CSP el script no corre.
+ *
+ * `default-src 'none'` corta además las peticiones de RED: un documento del proyecto podría
+ * llevar un `<img src="https://…">` que se lleve fuera el hecho de que se está imprimiendo.
+ * Lo que se deja es lo que un PDF necesita: imágenes locales o embebidas, estilos en línea
+ * —los nuestros— y tipografías locales.
+ */
+export declare const POLITICA_SIN_SCRIPTS: string;
+/**
+ * El mismo blindaje para un documento que YA es HTML y no pasa por nuestra plantilla.
+ *
+ * Se inserta lo antes posible: dentro de su `<head>` si lo tiene, dentro de su `<html>` si
+ * no, y al principio si no hay ninguno de los dos. **Inyectarla siempre TENSA y nunca
+ * afloja**: cuando un documento trae su propia CSP, el navegador exige que TODAS las
+ * políticas permitan cada carga, así que añadir la nuestra no puede ampliar lo que el
+ * documento ya se permitía.
+ *
+ * **Límite declarado**: esto es una transformación de TEXTO, no un parser. Un documento
+ * con un `<head` dentro de un comentario o de una cadena puede recibir la meta en un sitio
+ * raro; el peor caso es que no aplique, que es exactamente donde estábamos antes.
+ */
+export declare function conPoliticaSinScripts(html: string): string;

package/dist/core/fallos.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Qué se guarda cuando un turno revienta, y por qué justo eso.
+ *
+ * ## De dónde sale la lista
+ *
+ * De una sesión entera diagnosticando fallos reales a partir de lo que el usuario podía
+ * pegar. Cada cosa que hay aquí es una que hizo falta y no estaba:
+ *
+ * - **La CADENA de causas.** El error que llega arriba suele ser un envoltorio:
+ *   `MiddlewareError` guarda el de verdad en `cause`, y lo único que se veía era su
+ *   mensaje. Saber que el envoltorio lo puso `wrapToolCall` —o sea, que reventó dentro de
+ *   un subagente— fue lo que cerró el caso de DeepSeek, y hubo que deducirlo del prefijo
+ *   del nombre.
+ * - **El MODELO de cada papel.** Tres de los fallos del día eran de un proveedor concreto
+ *   y el informe no lo decía; se preguntó a mano cada vez.
+ * - **Los últimos PASOS.** Un `400` no dice nada; «tras delegar en dos subagentes» sí.
+ *   Solo los NOMBRES, nunca los argumentos — la misma regla que `core/events.ts`.
+ *
+ * ## Lo que NO se guarda, y es deliberado
+ *
+ * Ni el contenido de un fichero, ni los argumentos de una tool, ni los mensajes mandados
+ * al modelo. Un registro de fallos que copie el prompt es una copia del proyecto en el
+ * disco, y además crece sin control. Lo que se guarda cabe en una pantalla y se puede
+ * pegar entero en una conversación, que es exactamente para lo que existe.
+ *
+ * **Y esto sí puede llevar rutas de la máquina**, a diferencia de todo lo que viaja por el
+ * cable (`sinRutas`): el fichero vive en el proyecto de quien lo genera y nunca cruza un
+ * túnel. La regla de las rutas es del transporte, no del disco.
+ */
+/** Un eslabón de la cadena: el envoltorio y lo que envolvía. */
+export interface CausaDeFallo {
+    nombre: string;
+    mensaje: string;
+}
+export interface RegistroDeFallo {
+    v: 1;
+    at: string;
+    /** El id de la conversación (el `thread_id`), cuando el fallo ocurrió dentro de una. */
+    chat?: string;
+    /** El encargo, recortado: sirve para reconocer el turno, no para reproducirlo. */
+    peticion?: string;
+    /** Del envoltorio hacia dentro. El PRIMERO es el que llegó arriba. */
+    causas: CausaDeFallo[];
+    /** Papel → «proveedor/modelo». Sin él, «falla con DeepSeek» hay que preguntarlo. */
+    modelos?: Record<string, string>;
+    /** Los últimos pasos, por NOMBRE. Nunca argumentos. */
+    pasos?: string[];
+}
+/** Lo que cabe de la petición: suficiente para reconocerla de un vistazo. */
+export declare const TOPE_DE_PETICION = 200;
+/** Cuántos eslabones se siguen. Una cadena más larga que esto es un ciclo o un bug ajeno. */
+export declare const TOPE_DE_CAUSAS = 8;
+/** Cuántos pasos se recuerdan: los que caben en una pantalla. */
+export declare const TOPE_DE_PASOS = 20;
+/**
+ * Desenvuelve un error hasta el fondo, siguiendo `cause`.
+ *
+ * **Con tope y con guarda de ciclo.** Una `cause` que apunte a un ancestro es raro pero
+ * posible —y un bucle aquí se come el proceso justo cuando ya algo ha ido mal—, así que se
+ * recuerdan los objetos vistos. Lo que no sea un `Error` se describe por lo que es: un
+ * `throw "texto"` también llega aquí, y perderlo por no ser una instancia sería tirar la
+ * única pista.
+ */
+export declare function cadenaDeCausas(error: unknown): CausaDeFallo[];
+/** El registro entero, listo para una línea de JSONL. Puro: el reloj entra. */
+export declare function registroDeFallo(fallo: {
+    error: unknown;
+    peticion?: string;
+    modelos?: Record<string, string>;
+    pasos?: readonly string[];
+}, ahora?: Date): RegistroDeFallo;
+/**
+ * El registro en texto, para pegarlo en una conversación.
+ *
+ * Existe porque el JSONL es para las máquinas y lo que de verdad pasa es que alguien copia
+ * el fallo y lo pega. Una línea de JSON de 600 caracteres se pega igual pero no se LEE, y
+ * quien la recibe pierde el tiempo desenrollándola en vez de mirando el error.
+ */
+export declare function falloLegible(registro: RegistroDeFallo): string;

package/dist/core/fondosSvg.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Fondos SVG para frames y botones: degradados, sombras y resplandores (IXCODE-18).
+ *
+ * XOne no tiene degradados ni desenfoques propios, y el `imgbk` acepta SVG. Es la parte PURA:
+ * una plantilla por tipo, sin red ni puerto. Lo que vuelve es texto que `write_file` escribe.
+ *
+ * ## Por qué un generador y no un SVG tecleado por el modelo
+ *
+ * Un degradado son ids, `url(#…)`, offsets y coordenadas, y un error ahí no da error: XOne
+ * ignora en silencio lo que no entiende y el fondo simplemente no se ve. Una plantilla no se
+ * equivoca en eso, y valida los colores antes de escribir nada.
+ *
+ * ## Lo que se midió en un emulador Android (`docs/DECISIONES.md`, «Fondos SVG en XOne»)
+ *
+ * - `linearGradient`, `radialGradient` y `stop-opacity` SE PINTAN. Los FILTROS (`feGaussianBlur`,
+ *   `feDropShadow`) SE IGNORAN: por eso aquí no hay ni un `<filter>`. La sombra son rectángulos
+ *   apilados de opacidad baja, y el resplandor un degradado que acaba transparente.
+ * - `border-corner-radius` NO recorta el `imgbk`: **la esquina se DIBUJA en el SVG**.
+ * - Con `preserveAspectRatio="none"` y una proporción distinta a la del control, la esquina sale
+ *   achatada; con el `viewBox` de la MISMA proporción sale limpia. Por eso se pide el ancho y el
+ *   alto del control, y el `viewBox` los lleva.
+ *
+ * Sin `preserveAspectRatio`, XOne ya estira el SVG hasta llenar el control (medido: uno 1:1 en un
+ * frame ancho se deformó a elipse, sin bandas). Se escribe `none` igualmente: es lo que se mide
+ * hoy y no depende de que otro renderizador use `meet` y deje bandas vacías.
+ *
+ * ## Todo va RELATIVO al alto
+ *
+ * El `viewBox` mide 100 de alto y `ancho/alto·100` de ancho, y el radio, el margen y la sombra
+ * están en esa escala. Así solo importa la PROPORCIÓN del control, no sus píxeles: el mismo SVG
+ * vale en cualquier densidad mientras la relación ancho/alto se mantenga.
+ */
+/**
+ * ## Los colores llegan COMO EN XONE, y se convierten
+ *
+ * XOne escribe un color `#RRGGBB` o `#AARRGGBB` —el alfa PRIMERO, como Android (la documentación:
+ * `fillcolor: "#7F00FF00"`, «ARGB: semi-transparente»)—. SVG y CSS de HTML lo esperan al final,
+ * `#RRGGBBAA`. Copiar un `#7F00FF00` tal cual a un SVG lo leería como rojo 7F, azul FF y alfa 0:
+ * transparente y del color equivocado, sin un solo error. Por eso la tool acepta la forma de XOne
+ * y aquí se separa en `#RRGGBB` + opacidad (`stop-opacity`/`fill-opacity`), que es lo que SVG
+ * entiende en cualquier renderizador.
+ */
+export declare const NOMBRE_GENERAR_FONDO = "generar_fondo_svg";
+/**
+ * Las medidas de un control se declaran en XOne mezclando unidades (`width="90%" height="60p"`),
+ * y la tool las acepta así. **Es una ESTIMACIÓN**, sobre el aparato donde se midió: un ancho de
+ * pantalla de 1080 px y 1,144 px por `p` (`90%`×`90p` salieron 972×103 en el árbol de controles).
+ * En otro dispositivo el `%` sigue a la pantalla y la `p` a la densidad, así que la proporción
+ * cambia; la respuesta de la tool lo dice.
+ */
+export declare const ANCHO_DE_PANTALLA_DE_REFERENCIA = 1080;
+export declare const PIXELES_POR_P = 1.144;
+/** De `90%`, `60p`, `120px` o `120` a píxeles de referencia. `%` solo en el ancho. */
+export declare function medidaEnPixeles(valor: string | number, eje: "ancho" | "alto"): {
+    px: number;
+} | {
+    motivo: string;
+};
+export declare const TIPOS_DE_FONDO: readonly ["degradado-lineal", "degradado-radial", "sombra", "glow"];
+export type TipoDeFondo = (typeof TIPOS_DE_FONDO)[number];
+/** Proporción ancho/alto aceptada: fuera de ella la tarjeta de la sombra no cabe o no es un botón. */
+export declare const PROPORCION_MINIMA = 0.5;
+export declare const PROPORCION_MAXIMA = 40;
+declare const INTENSIDAD_DE_SOMBRA: {
+    readonly suave: 0.03;
+    readonly media: 0.05;
+    readonly fuerte: 0.08;
+};
+export type IntensidadDeSombra = keyof typeof INTENSIDAD_DE_SOMBRA;
+export declare const INTENSIDADES: IntensidadDeSombra[];
+/** Un color ya en la forma de SVG: el `#RRGGBB` y su opacidad aparte (1 = opaco). */
+export interface ColorSvg {
+    hex: string;
+    opacidad: number;
+}
+/** Por qué no vale como color de XOne, o `undefined`. Vale `#RGB`, `#RRGGBB` y `#AARRGGBB`. */
+export declare function motivoDeColorDeXoneInaceptable(color: string): string | undefined;
+/**
+ * De un color de XOne al de SVG. **`#AARRGGBB` de XOne → `#RRGGBB` + opacidad**: el alfa es el
+ * PRIMER byte, no el último como en el `#RRGGBBAA` de HTML.
+ */
+export declare function colorDeXoneASvg(color: string): ColorSvg;
+export interface PeticionDeFondo {
+    tipo: TipoDeFondo;
+    /** Ancho y alto del CONTROL, en cualquier unidad: solo cuenta la proporción. */
+    ancho: number;
+    alto: number;
+    /** Colores de XOne (`#RRGGBB` o `#AARRGGBB`). De 2 a 4 en los degradados; 1 en `sombra` y `glow`. */
+    colores: string[];
+    /** 0 = de izquierda a derecha, 90 = de arriba abajo. Solo `degradado-lineal`. Por omisión 90. */
+    angulo?: number;
+    /** Esquina, como porcentaje del alto (0 a 50; 50 es una píldora). Por omisión 25. */
+    radio?: number;
+    /** Solo `sombra`. */
+    intensidad?: IntensidadDeSombra;
+    /** Solo `glow`: el color de detrás, también de XOne. Ausente = transparente. */
+    fondo?: string;
+}
+export interface FondoGenerado {
+    svg: string;
+    /** El ancho del `viewBox` (el alto es 100), para decirlo en la respuesta. */
+    anchoDelViewBox: number;
+}
+/** Un nombre de fichero sin ruta ni punto: el fichero será `bg_<nombre>.svg`. */
+export declare function motivoDeNombreDeFondoInaceptable(nombre: string): string | undefined;
+export declare function nombreDeFicheroDeFondo(nombre: string): string;
+export declare function rutaDeFondo(nombre: string): string;
+/** Por qué la petición no vale, o `undefined`. Las cosas que la plantilla no sabría dibujar. */
+export declare function motivoDePeticionInaceptable(p: PeticionDeFondo): string | undefined;
+/**
+ * El SVG de la petición. **Lanza si no es válida**: quien lo llama comprueba antes con
+ * `motivoDePeticionInaceptable` y devuelve el motivo como texto (la tool no lanza).
+ */
+export declare function generarFondo(p: PeticionDeFondo): FondoGenerado;
+export {};

package/dist/core/fotoDeColecciones.d.ts

@@ -0,0 +1,45 @@
+/**
+ * La FOTO del modelo XOne de un proyecto para la pestaña Colecciones: lo mismo que contesta
+ * `xone_navegacion`, entero y de una vez, para que una persona lo mire.
+ *
+ * **Sale del MISMO índice que la tool** (`core/navegacion.ts#construirIndice`) y no de una
+ * segunda lectura del modelo: «qué apunta a qué» se decide en un sitio, y el día que la tool y
+ * la pestaña contestaran distinto sobre el mismo proyecto no habría forma de saber cuál miente.
+ *
+ * Todo lo que lleva son rutas VIRTUALES y nombres del proyecto —lo que ya ve el agente—, nunca
+ * una ruta de la máquina: viaja por el cable. Y, como el índice, **no dice qué colecciones son
+ * huérfanas**: se midió y el 50 % eran falsos positivos (ver `core/navegacion.ts`).
+ */
+import { type ModeloDeNavegacion, type Referencia } from "./navegacion.js";
+export interface ColeccionDeLaFoto {
+    nombre: string;
+    /** Ruta VIRTUAL del `.xne`. */
+    fichero: string;
+    campos: {
+        nombre: string;
+        tipo?: string;
+    }[];
+    eventos: string[];
+    nodos: string[];
+    conexiones: string[];
+    /** Lo que ELLA apunta: sus atributos y los scripts que viven dentro de ella. */
+    apuntaA: Referencia[];
+    /** Lo que apunta HACIA ella, venga de donde venga. */
+    leApuntan: Referencia[];
+}
+export interface FotoDeColecciones {
+    colecciones: ColeccionDeLaFoto[];
+    /** Cuántas colecciones tiene el proyecto: más que `colecciones.length` = se recortó. */
+    total: number;
+    /** Por dónde arranca la app, según `app.xml`. Vacío = no consta, que no es «no hay». */
+    entrada: string[];
+    login: string[];
+    /** Referencias a una colección que no existe. */
+    rotas: Referencia[];
+}
+/**
+ * Cuántas colecciones caben en una foto. Un proyecto real anda por las decenas; el tope existe
+ * para que uno raro no mande un mensaje sin fondo, y lo que queda fuera se CUENTA (`total`).
+ */
+export declare const TOPE_DE_COLECCIONES_EN_LA_FOTO = 400;
+export declare function fotoDeColecciones(modelo: ModeloDeNavegacion, tope?: number): FotoDeColecciones;