xonecode 0.31.0 → 0.34.2

package/skills/xone-development/references/css/de-una-maqueta-a-xone.md

@@ -0,0 +1,83 @@
+# De una maqueta HTML (Stitch, Tailwind) a XOne
+
+Contenido: §1 cómo leer esta tabla · §2 medidas y unidades · §3 forma, bordes y fondos · §4 color · §5 texto y
+tipografías · §6 composición · §7 lo que no existe
+
+Una maqueta de Stitch trae un `code.html` con clases de Tailwind y una configuración propia (`tailwind.config`:
+colores con nombre, `borderRadius`, `fontFamily`, `fontSize`). Esta tabla dice cómo se escribe cada cosa en XOne.
+**XOne ignora en silencio lo que no conoce**: una clase traducida «a ojo» no da error, da una pantalla distinta.
+
+## 1. Cómo leer esta tabla
+
+Cada fila dice de dónde sale:
+
+- **medido**: comprobado en un emulador Android con una pantalla de prueba. Fíate.
+- **documentado**: lo dice otra referencia de esta skill, sin medida propia.
+- **sin medir**: no se ha comprobado. Pruébalo en el aparato antes de dar nada por bueno.
+
+Lo primero, siempre: lee la configuración de Tailwind del `code.html` (`tailwind.config = {…}`). Los nombres de las
+clases (`rounded-lg`, `text-key-numeric`, `bg-surface-container-high`) son de ESA maqueta y valen lo que diga ella.
+
+## 2. Medidas y unidades
+
+| En la maqueta | En XOne | De dónde |
+|---|---|---|
+| un ancho en px | `p`: `px_maqueta × resolution-width / ancho_de_la_maqueta`; o en `%` del contenedor | medido |
+| un alto en px | `p` con la misma cuenta. **Ojo**: un alto en `p` escala con el ALTO útil de la pantalla y un ancho con el ANCHO, así que en un teléfono alargado sale más alto (medido: ×1,72 en alto y ×1,5 en ancho, 15 % más alto de proporción) | medido |
+| `w-full` | `width="100%"` | documentado |
+| `p-N`, `px-N`, `py-N` | `lpadding`, `rpadding`, `tpadding`, `bpadding` (no hay abreviado) | documentado |
+| `m-N`, `mt-N`… | `lmargin`, `tmargin`… (no hay abreviado; `rmargin` en `%` se ignora) | documentado / medido |
+
+`p` no es el píxel y escala **por eje**: un ancho por `ancho_real / resolution-width`, un alto por
+`alto_útil / resolution-height` (el alto útil es la pantalla sin las barras de estado y de navegación). Lee los
+dos valores en el `app.xml` del proyecto.
+
+## 3. Forma, bordes y fondos
+
+| En la maqueta | En XOne | De dónde |
+|---|---|---|
+| `rounded-full` (píldora o círculo) | `border-corner-radius: 999` | medido |
+| `rounded-lg`, `rounded-xl`, `rounded-[Npx]` | `border-corner-radius` en **píxeles del aparato**, no en `p`, calculados como `px_maqueta × ancho_real / ancho_de_la_maqueta` (32 px en una maqueta de 390 son unos 89 en un aparato de 1080). **En un BOTÓN ese número es el radio; en un `<frame>` el radio sale al DOBLE**, así que en un frame se escribe la MITAD (esos 89 px son `border-corner-radius="44"` en un botón y `"22"` en un frame). Ni uno ni otro dependen de la densidad del aparato ni de la `resolution-width` de la app. El radio se recorta a la mitad del alto: en un frame, un valor de la mitad del alto o más ya es una píldora (o un círculo, si es cuadrado) | medido |
+| un botón sin borde | `border-width: 0`. Un `type="B"` pinta un contorno fino por omisión; `border: false`, `border: 0`, `framebox: false` y `labelbox: false` NO lo quitan | medido |
+| `border`, `border-COLOR` | **en un botón**: `border-width: 1; border-color: #RRGGBB`. **En un `<frame>` eso no pinta nada** (ni con `border="15"` ni con `border="true"`): el borde de un frame es `framebox="true"` y su color `forecolor="#RRGGBB"` (sale de unos 2 px) | medido |
+| `bg-gradient-to-br from-A to-B` | un SVG con `generar_fondo_svg` (tipo degradado, ángulo 45 para `to-br`): en un BOTÓN va en `img`, en un frame en `imgbk` (en un botón `imgbk` se ignora) | medido |
+| `shadow-[0_6px_14px_…]` (sombra exterior) | un SVG con `generar_fondo_svg` (tipo sombra). **No** `elevation` en algo redondeado: recorta el fondo por abajo | medido |
+| `shadow-[inset_…]` (brillo interior) | no hay equivalente; si importa, dibújalo en el mismo SVG del fondo | sin medir |
+| `border-corner-radius` sobre una imagen de fondo | no la recorta: la esquina se dibuja DENTRO del SVG | medido |
+| un `<frame>` sin nada dentro (una barra de color, un punto) | **no se pinta**: no llega ni al árbol de controles. Dentro tiene que haber al menos un control (una etiqueta `TL` con `title=" "` vale) | medido |
+
+## 4. Color
+
+| En la maqueta | En XOne | De dónde |
+|---|---|---|
+| `bg-<nombre>`, `text-<nombre>` | el `#RRGGBB` que diga `tailwind.config` para ese nombre, en `bgcolor` y `forecolor` / `text-forecolor` | documentado |
+| `bg-<nombre>/80` (transparencia) | `#AARRGGBB` con el alfa **primero**: 80 % es `CC`, 60 % `99`, 5 % `0D` | documentado |
+| un color en un SVG | `#RRGGBB` más `opacity` (HTML y SVG ponen el alfa al final; XOne al principio) | medido |
+
+## 5. Texto y tipografías
+
+| En la maqueta | En XOne | De dónde |
+|---|---|---|
+| una fuente de Google Fonts (`fontFamily` en la configuración, `fonts.googleapis.com` en el `<head>`) | su `.ttf` en `fonts/` y `fontname: Nombre.ttf` (`buscar_fuente` → `traer_fuente` lo trae: un `.ttf` estático por peso, `Inter-Bold.ttf`). El `.ttf` variable que da Google Fonts vale tal cual (sale con su peso por omisión). **Se sube desplegando entero**: la recarga en caliente no lleva `fonts/`. Un `fontname` que no está en el aparato saca un diálogo de error y el control no se pinta | medido |
+| `text-[Npx]`, `fontSize` de la configuración | `fontsize: N−8`. En Android la letra sale de **`fontsize` + 8 dp**: `fontsize: 20` pinta una letra de 28 dp, y `fontsize: 40` una de 48. Un píxel de la maqueta (viewport de unos 390 de ancho) es casi un dp del teléfono, así que `text-[48px]` → `fontsize: 40` y `text-[16px]` → `fontsize: 8`. Ese +8 es fijo: no escala con el tamaño ni depende de la `resolution-width` de `app.xml`. Medido con la fuente del sistema; con otra `fontname` el tamaño es el mismo, pero el alto de las mayúsculas cambia con la fuente. `textfont-size` y iOS, sin medir | medido (Android) |
+| `font-medium`, `font-semibold`, `font-bold` | la variante de la fuente con ese peso (`Roboto-Bold.ttf`) o `fontbold` | documentado |
+| `uppercase` | escribe el texto ya en mayúsculas | sin medir |
+| `tracking-*` (espaciado entre letras), `leading-*` (interlineado) | sin equivalente conocido | sin medir |
+| un texto que no cabe | `auto-fontsize="true"`, o una caja más alta: un `height` menor que la letra la corta por abajo | medido |
+| cambiar la fuente de un control (`fontname`) | **revisa la altura de su caja**: con el mismo `fontsize`, otra fuente coloca la letra a otra altura dentro de ella. Space Grotesk queda más abajo que Roboto, así que en una tecla con la altura justa se corta más por abajo (el `-` y el `+` casi desaparecen). Sube el `height` o baja el `fontsize`, y compruébalo con una captura | medido |
+| iconos `material-symbols-outlined` | `buscar_icono` → `icons/ic_<nombre>.svg`, en un `type="IMG"` (en el `img` de un botón se estira) | medido |
+
+## 6. Composición
+
+| En la maqueta | En XOne | De dónde |
+|---|---|---|
+| `grid grid-cols-4 gap-N` | una fila de controles con `width` en `%` que, con sus márgenes, sume como mucho el 100 %: el que se pasa desborda por la derecha | medido |
+| `flex justify-between` | márgenes en `%` entre los elementos de la fila | documentado |
+| `flex-col` | controles uno bajo otro (`newline`) dentro de un frame | documentado |
+| una cabecera fija (`fixed top-0`) | un `group` con `fixed="true"` y `orientation="top"` | documentado |
+
+## 7. Lo que no existe en XOne (no lo traduzcas, ni a medias)
+
+`hover:`, `active:`, `focus:`, `transition-*`, `animate-*`, `translate-*`, `scale-*`, `blur-*`, `backdrop-blur-*`,
+`opacity` animada, `pointer-events-*`, `select-none`, `overflow-x-auto` con barra oculta, `env(safe-area-inset-*)`.
+Son estados o animaciones del navegador; en XOne no hacen nada, y escribirlos con otro nombre no los hace existir.

package/skills/xone-development/references/css/patrones-material-y-temas.md

@@ -126,13 +126,15 @@ El footer es el frame inferior, normalmente con botones de acción.
 Los botones siguen el patron de Material Design con esquinas redondeadas y colores por estado:
 
 ```css
+/* Píldora: border-corner-radius: 999 (el radio va en PÍXELES del aparato y se recorta a la mitad del alto;
+   «28 = la mitad de 56p» solo vale en el aparato de referencia — medido en un emulador Android) */
 /* Boton primario - Accion principal */
 .btnPrimario {
     width: 90%;
     height: 56p;
     bgcolor: #1565C0;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
     fontname: Roboto-Bold.ttf;
@@ -146,7 +148,7 @@ Los botones siguen el patron de Material Design con esquinas redondeadas y color
     forecolor: #1565C0;
     border: true;
     border-color: #1565C0;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
 }
@@ -157,7 +159,7 @@ Los botones siguen el patron de Material Design con esquinas redondeadas y color
     height: 56p;
     bgcolor: #F44336;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
 }
@@ -168,7 +170,7 @@ Los botones siguen el patron de Material Design con esquinas redondeadas y color
     height: 56p;
     bgcolor: #4CAF50;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
     fontname: Roboto-Bold.ttf;
@@ -180,7 +182,7 @@ Los botones siguen el patron de Material Design con esquinas redondeadas y color
     height: 56p;
     bgcolor: #00BCD4;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
     fontname: Roboto-Bold.ttf;
@@ -226,7 +228,7 @@ Los botones siguen el patron de Material Design con esquinas redondeadas y color
     width: 95%;
     height: 56p;
     bgcolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     border: true;
     border-color: #E0E0E0;
     lmargin: 15p;
@@ -306,7 +308,7 @@ El FAB es un botón circular flotante que representa la acción principal de la
     width: 56p;
     height: 56p;
     bgcolor: #1565C0;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
 }
 
 /* FAB grande (64p) */
@@ -699,7 +701,7 @@ prop {
     height: 56p;
     bgcolor: #1565C0;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
     fontname: Roboto-Bold.ttf;
@@ -713,7 +715,7 @@ prop {
     forecolor: #1565C0;
     border: true;
     border-color: #1565C0;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
 }
@@ -724,7 +726,7 @@ prop {
     height: 56p;
     bgcolor: #F44336;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
 }
@@ -735,7 +737,7 @@ prop {
     height: 56p;
     bgcolor: #4CAF50;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     text-align: center;
     fontsize: 16;
     fontname: Roboto-Bold.ttf;
@@ -746,7 +748,7 @@ prop {
     width: 56p;
     height: 56p;
     bgcolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
 }
 
 /* FAB */
@@ -818,7 +820,7 @@ prop {
     width: 95%;
     height: 56p;
     bgcolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;
     border: true;
     border-color: #E0E0E0;
     lmargin: 15p;

package/skills/xone-development/references/css/propiedades-y-herencia.md

@@ -499,7 +499,7 @@ El atributo `visible` usa un sistema de mascara de bits que controla en que modo
     height: 56p;
     bgcolor: #1565C0;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;   /* píldora: el radio va en píxeles del aparato */
     ripple-effect: true;
     elevation: 4;
 }
@@ -573,7 +573,7 @@ El caso más común: una clase hereda de otra y sobreescribe algunos atributos.
     height: 56p;
     bgcolor: #1565C0;
     forecolor: #FFFFFF;
-    border-corner-radius: 28;
+    border-corner-radius: 999;   /* píldora: el radio va en píxeles del aparato */
     text-align: center;
     fontsize: 16;
     fontname: Roboto-Bold.ttf;

package/skills/xone-development/references/css/selectores-unidades-colores.md

@@ -492,7 +492,12 @@ frame {
 
 ### 3.1 `p` (puntos) - Unidad absoluta
 
-La unidad `p` representa **pixels en el dispositivo de referencia** definido por `resolution-width` y `resolution-height` en `app.xml`. En el dispositivo de referencia, `1p = 1px` real. En cualquier otro dispositivo, XOne escala automáticamente con la fórmula `tamaño_real_px = valor_p × (resolucion_real / resolution-width)`.
+La unidad `p` representa **pixels en el dispositivo de referencia** definido por `resolution-width` y `resolution-height` en `app.xml`. En el dispositivo de referencia, `1p = 1px` real. En cualquier otro dispositivo, XOne escala **cada eje por separado**:
+
+- un **ancho** en `p`: `px_reales = valor_p × (ancho_real / resolution-width)`;
+- un **alto** en `p`: `px_reales = valor_p × (alto_útil / resolution-height)`, donde el alto útil es la pantalla sin las barras de estado y de navegación.
+
+> **Medido** en un emulador Android de 1080×2400 con una app de `resolution-width="720"` y `resolution-height="1280"`: `width: 421p` → 631 px (×1,5) y `height: 120p` → 206 px (×1,72, porque el alto útil son 2205 px). Así que **la proporción de un control declarado en `p` cambia de un aparato a otro**: un cuadrado de `100p × 100p` sale más alto que ancho en un teléfono alargado.
 
 > **CRÍTICO: `p` ≠ Material `dp`.** Es un error común asumir que `p` equivale a `dp` (density-independent pixels) de Android. **NO lo es.** Para el dispositivo de referencia por defecto de XOne (1080×1920, xxhdpi, density 3×), Material `56dp` ≈ `168p`, NO `56p`. Aplicar valores Material directamente como `p` produce barras/botones ~3× más pequeños de lo necesario.
 
@@ -517,7 +522,7 @@ La unidad `p` representa **pixels en el dispositivo de referencia** definido por
 .btnPrimario {
     width: 90%;
     height: 124p;        /* Workflow "pill" CTA */
-    border-corner-radius: 62;
+    border-corner-radius: 999;   /* píldora en CUALQUIER aparato: el radio va en píxeles y se recorta a la mitad del alto */
 }
 ```
 
@@ -526,7 +531,7 @@ La unidad `p` representa **pixels en el dispositivo de referencia** definido por
 - Alturas fijas de headers, footers, botones
 - Tamaños de iconos y avatares
 - Margenes y paddings fijos
-- Radios de bordes (aunque estos van sin unidad)
+- **Los radios NO**: `border-corner-radius` va en **píxeles reales del aparato** y no escala con `p` (medido: un radio `50` en un botón de `100p` sale de ~48 px, un tercio de su alto real de 172 px). Para una píldora usa `border-corner-radius: 999`: el radio se recorta a la mitad del alto, sea cual sea el aparato
 - Dimensiones de componentes que no deben cambiar con el tamaño de pantalla
 
 ### 3.2 `%` (porcentaje) - Unidad relativa

package/skills/xone-development/references/indice-completo.md

@@ -60,6 +60,7 @@ Lee el fichero que corresponda antes de responder sobre atributos concretos, val
 - [css/dinamicos-cascada-y-componentes.md](references/css/dinamicos-cascada-y-componentes.md) — `##FLD_CAMPO##`, cascada de dispositivo, `strict-mode`, animaciones y tokens, gráficos, calendario y mapa
 - [css/patrones-material-y-temas.md](references/css/patrones-material-y-temas.md) — Patrones Material (header/body/footer, botones, inputs, tarjetas, FAB, toolbar, item de lista), temas light/dark y un `default.css` + `colors.css` completos y comentados
 - [css/buenas-practicas-y-parser.md](references/css/buenas-practicas-y-parser.md) — Buenas prácticas, anti-patrones, checklist de validación y detalle de las funciones del parser (`@import`, variables, `calc()`, `!important`, `!default`, `@extend`, modo estricto)
+- [css/de-una-maqueta-a-xone.md](references/css/de-una-maqueta-a-xone.md) — De una maqueta HTML de Stitch (Tailwind) a XOne, clase a clase: forma, bordes, fondos, color, tipografías y composición, con lo MEDIDO en el aparato separado de lo documentado
 
 ### Datos e integración
 - [datos/appdata.md](references/datos/appdata.md) — `appData` completo: colecciones, login/logout, paso de datos entre pantallas, macros globales, SQL directo, detección de dispositivo, `loadIncludeFile` y `loadCssFile`

package/skills/xone-development/references/xml-ui/atributos-coll-group-frame.md

@@ -211,10 +211,10 @@ Contenedor visual dentro de un grupo. Puede anidarse.
 |---|---|---|---|
 | `bgcolor` | color | heredado | Color de fondo del frame. |
 | `forecolor` | color | heredado | Color de texto del frame. |
-| `border` | int (mask) | `0` | Bordes activos: top=1, right=2, bottom=4, left=8. Sumar para combinar. |
-| `border-color` | color | — | Color del borde. |
-| `border-width` | medida | `0` | Grosor del borde. |
-| `border-corner-radius` | medida | `0` | Radio de esquinas redondeadas. |
+| `border` | int (mask) | `0` | Bordes activos: top=1, right=2, bottom=4, left=8. **Medido en Android: en un `<frame>` no pinta borde** (ni `border="15"` ni con `border-width`/`border-color`); el borde de un frame es `framebox="true"` + `forecolor`. |
+| `border-color` | color | — | Color del borde. En un frame no pinta (ver `border`). |
+| `border-width` | medida | `0` | Grosor del borde. En un frame no pinta (ver `border`). |
+| `border-corner-radius` | medida | `0` | Radio de esquinas redondeadas, en píxeles del aparato. **En un frame sale al DOBLE** que en un botón (`"20"` → unos 40 px; en un botón, unos 20): medido en Android. |
 | `tmargin` / `bmargin` / `lmargin` / `rmargin` | medida | `0` | Margenes externos. |
 | `tpadding` / `bpadding` / `lpadding` / `rpadding` | medida | `0` | Padding interno. |
 | `class` | string | `""` | Clase CSS. |

package/skills/xone-development/references/xml-ui/nodos-group-y-frame.md

@@ -422,10 +422,10 @@ XOne posiciona los elementos en **flujo lineal de arriba a abajo**: por defecto
 | `bgcolor` | color | Color de fondo | `bgcolor="#FFFFFF"` |
 | `forecolor` | color | Color del borde (en combinacion con `framebox`) | `forecolor="#666666"` |
 | `elevation` | integer | Elevacion / sombra (estilo Material Design) | `elevation="5"` |
-| `border-corner-radius` | string | Radio de esquinas redondeadas | `border-corner-radius="10"` |
-| `framebox` | boolean | Muestra un borde visible alrededor del frame | `framebox="true"` |
-| `border` | boolean | Muestra el borde del frame | `border="true"` |
-| `border-width` | integer | Ancho del borde en puntos | `border-width="2"` |
+| `border-corner-radius` | string | Radio de esquinas redondeadas. **Medido en Android: en un frame sale al DOBLE en píxeles del aparato** (`"20"` → unos 40 px), sin depender de la densidad ni de la resolución de la app | `border-corner-radius="10"` |
+| `framebox` | boolean | Muestra un borde visible alrededor del frame. **Es lo que pinta el borde de un frame** (medido), con `forecolor` de color | `framebox="true"` |
+| `border` | boolean | Muestra el borde del frame. **Medido en Android: en un frame NO pinta** (tampoco como máscara `border="15"`): usa `framebox` | `border="true"` |
+| `border-width` | integer | Ancho del borde en puntos. En un frame no pinta (ver `border`) | `border-width="2"` |
 | `border-left` | boolean | Muestra solo el borde izquierdo | `border-left="false"` |
 | `border-top` | boolean | Muestra solo el borde superior | `border-top="false"` |
 | `border-right` | boolean | Muestra solo el borde derecho | `border-right="false"` |

package/skills/xone-hotswap/lib/geometria.mjs

@@ -0,0 +1,147 @@
+/**
+ * La GEOMETRÍA de una captura: el árbol de controles y las barras del sistema EN EL MISMO MOMENTO,
+ * guardados al lado de la imagen con su nombre (`calc_08.jpg` → `calc_08.geometria.json`).
+ *
+ * POR QUÉ, y por qué AQUÍ. El crítico visual del host (`xone_critica_visual`) compara tecla a tecla
+ * —qué falta, en qué fila, qué tamaño, qué queda tapado— leyendo cajas, no píxeles. Para eso necesita
+ * el árbol de la MISMA pantalla que la captura: emparejarlo después por la fecha de los ficheros ya
+ * cruzó una vez el árbol de una ronda con la captura de otra, y una cifra «exacta» de la ronda
+ * equivocada es peor que ninguna. Sacarlo en el mismo comando que la captura lo hace imposible.
+ *
+ * Las barras salen de `dumpsys window` (`InsetsSource … type=navigationBars frame=[0,2337][1080,2400]`):
+ * con Android dibujando de borde a borde, un control puede quedar DEBAJO de la barra de navegación, y
+ * su alto cambia según el aparato y el modo de navegación (medido en un pixel8: 63 px con gestos), así
+ * que no se adivina.
+ *
+ * NUNCA hace fallar la captura: si no se puede, se dice por stderr y la captura queda sin geometría.
+ * Va a `$XONECODE_HOTSWAP` (andamio, como los volcados del canal), no a artefactos: no es algo que mirar.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { NODE, rutaDeAdb } from "./dispositivo.mjs";
+
+/** El nombre del fichero de geometría de una captura: su nombre sin extensión + `.geometria.json`. */
+export function nombreDeGeometria(nombreDeCaptura) {
+  return `${nombreDeCaptura.replace(/\.[A-Za-z0-9]{2,4}$/, "")}.geometria.json`;
+}
+
+/** Las barras del sistema de la salida de `dumpsys window`, o `undefined` si no salen. Pura. */
+export function barrasDeDumpsys(salida) {
+  const frame = (tipo) => {
+    const m = new RegExp(`type=${tipo} frame=\\[(-?\\d+),(-?\\d+)\\]\\[(-?\\d+),(-?\\d+)\\] visible=true`).exec(String(salida));
+    return m === null ? undefined : { izquierda: +m[1], arriba: +m[2], derecha: +m[3], abajo: +m[4] };
+  };
+  const estado = frame("statusBars");
+  const navegacion = frame("navigationBars");
+  if (estado === undefined && navegacion === undefined) return undefined;
+  return { ...(estado === undefined ? {} : { estado }), ...(navegacion === undefined ? {} : { navegacion }) };
+}
+
+/** Hasta dónde llegan los controles del árbol (el borde derecho y el inferior más lejanos). Pura. */
+export function extensionDelArbol(arbol) {
+  let ancho = 0;
+  let alto = 0;
+  const visitar = (n) => {
+    if (Array.isArray(n)) return n.forEach(visitar);
+    if (n === null || typeof n !== "object") return;
+    const b = n.bounds;
+    if (b && typeof b.left === "number" && typeof b.width === "number" && typeof b.top === "number" && typeof b.height === "number") {
+      ancho = Math.max(ancho, b.left + b.width);
+      alto = Math.max(alto, b.top + b.height);
+    }
+    for (const v of Object.values(n)) if (v !== null && typeof v === "object") visitar(v);
+  };
+  visitar(arbol);
+  return { ancho, alto };
+}
+
+/**
+ * La imagen es de UN CONTROL y no de la pantalla entera (`xone-hotswap shot name=…`): es claramente más pequeña que
+ * lo que ocupa el árbol. Su geometría no le corresponde —las cajas son de la pantalla— y el crítico mediría píxeles
+ * que no son (medido: una foto del visor salía con siete textos «recortados»). Pura.
+ */
+export function esCapturaDeUnControl(pantalla, arbol, barras) {
+  // La PANTALLA la dice la barra de navegación (llega al borde inferior y ocupa el ancho entero). Sin ella, lo que
+  // ocupa el árbol, que puede pasarse: medido, un pie flotante de la app llegaba a y=2542 en una pantalla de 2400, y
+  // la captura completa parecía la de un control.
+  const n = barras?.navegacion;
+  const e = n !== undefined ? { ancho: n.derecha, alto: n.abajo } : extensionDelArbol(arbol);
+  return pantalla !== undefined && e.alto > 0 && (pantalla.alto < e.alto * 0.95 || pantalla.ancho < e.ancho * 0.95);
+}
+
+/** El ancho y el alto de un PNG o un JPEG, leídos de su cabecera. `undefined` si no se sabe. Pura. */
+export function medidasDeImagen(bytes) {
+  if (bytes.length >= 24 && bytes[0] === 0x89 && bytes[1] === 0x50) return { ancho: bytes.readUInt32BE(16), alto: bytes.readUInt32BE(20) };
+  if (bytes[0] === 0xff && bytes[1] === 0xd8) {
+    let i = 2;
+    while (i + 9 < bytes.length) {
+      if (bytes[i] !== 0xff) return undefined;
+      const marca = bytes[i + 1];
+      const largo = bytes.readUInt16BE(i + 2);
+      if (marca >= 0xc0 && marca <= 0xc3) return { alto: bytes.readUInt16BE(i + 5), ancho: bytes.readUInt16BE(i + 7) };
+      i += 2 + largo;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Guarda `<captura>.geometria.json` en `$XONECODE_HOTSWAP`. Devuelve el nombre, o `undefined` y lo dice.
+ * `bytes` son los de la captura (para su tamaño); `serie`, el aparato.
+ */
+export function guardarGeometria({ nombreDeCaptura, bytes, serie, entorno = process.env }) {
+  const destino = entorno.XONECODE_HOTSWAP;
+  if (!destino) {
+    process.stderr.write("(sin XONECODE_HOTSWAP: la captura queda sin geometría para el crítico)\n");
+    return undefined;
+  }
+  let arbol;
+  const temporal = mkdtempSync(join(tmpdir(), "xonecode-geometria-"));
+  try {
+    // El cliente guarda un árbol grande en `$XONECODE_HOTSWAP`: se le da uno PROPIO para saber cuál es.
+    const cliente = join(import.meta.dirname, "..", "scripts", "xone-hotswap");
+    execFileSync(NODE, [cliente, "getAllElements", "format=xone", ...(serie ? ["--serie", serie] : [])], {
+      encoding: "utf8",
+      env: { ...entorno, XONECODE_HOTSWAP: temporal },
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 30_000,
+    });
+    const fichero = readdirSync(temporal).find((n) => n.endsWith(".json"));
+    if (fichero !== undefined) arbol = JSON.parse(readFileSync(join(temporal, fichero), "utf8"));
+  } catch {
+    // Sin canal o sin app: se queda sin árbol, y se dice abajo.
+  } finally {
+    rmSync(temporal, { recursive: true, force: true });
+  }
+  if (arbol === undefined) {
+    process.stderr.write("(no pude leer el árbol de controles: la captura queda sin geometría para el crítico)\n");
+    return undefined;
+  }
+  let barras;
+  try {
+    barras = barrasDeDumpsys(
+      execFileSync(rutaDeAdb(entorno), [...(serie ? ["-s", serie] : []), "shell", "dumpsys", "window"], {
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ["ignore", "pipe", "ignore"],
+        timeout: 15_000,
+      })
+    );
+  } catch {
+    // Sin barras, el crítico no puede decir qué queda tapado: lo dirá él.
+  }
+  const nombre = nombreDeGeometria(nombreDeCaptura);
+  const pantalla = medidasDeImagen(bytes);
+  if (esCapturaDeUnControl(pantalla, arbol, barras)) {
+    process.stderr.write("(captura de un control, no de la pantalla entera: sin geometría para el crítico)\n");
+    return undefined;
+  }
+  mkdirSync(destino, { recursive: true });
+  writeFileSync(
+    join(destino, nombre),
+    JSON.stringify({ v: 1, captura: nombreDeCaptura, en: new Date().toISOString(), ...(pantalla ? { pantalla } : {}), ...(barras ? { barras } : {}), arbol })
+  );
+  return nombre;
+}

package/skills/xone-hotswap/scripts/xone-captura-android

@@ -26,6 +26,7 @@ import { execFileSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
 import { join, basename } from "node:path";
 import { serieAndroid, rutaDeAdb, NODE } from "../lib/dispositivo.mjs";
+import { guardarGeometria } from "../lib/geometria.mjs";
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
@@ -183,3 +184,8 @@ try {
 }
 
 console.log(`captura guardada como ${nombre} (${bytes.length} bytes). Es de la vía nativa: enseña lo que el SISTEMA pinta, no lo que la app host dice.`);
+
+// Y su GEOMETRÍA, en el mismo momento: el árbol de controles y las barras del sistema, para que el
+// crítico visual compare tecla a tecla con la pantalla que ESTA captura enseña (`../lib/geometria.mjs`).
+const geometria = guardarGeometria({ nombreDeCaptura: nombre, bytes, serie });
+if (geometria !== undefined) console.log(`(con su geometría para el crítico: /hotswap/${geometria})`);

package/skills/xone-hotswap/scripts/xone-hotswap

@@ -55,6 +55,7 @@ process.on("warning", (aviso) => {
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { guardarGeometria } from "../lib/geometria.mjs";
 import { dispositivoDeLaSesion, puertoConMotivo, retirarOpciones, serieAndroid, PUERTO_DEL_HOTSWAP } from "../lib/dispositivo.mjs";
 
 /**
@@ -320,6 +321,13 @@ function sinBinarios(respuesta) {
     const bytes = imagen === undefined ? Buffer.from(valor, "utf8") : Buffer.from(valor, "base64");
     mkdirSync(destino, { recursive: true });
     writeFileSync(join(destino, nombre), bytes);
+    // Una captura se guarda con su GEOMETRÍA (árbol de controles y barras del sistema) del mismo
+    // momento, para el crítico visual (`../lib/geometria.mjs`). La llamada de dentro pide un árbol, no
+    // una imagen, así que no vuelve a entrar aquí.
+    if (imagen !== undefined) {
+      const geometria = guardarGeometria({ nombreDeCaptura: nombre, bytes, serie: seriePedida });
+      if (geometria !== undefined) process.stderr.write(`(con su geometría para el crítico: /hotswap/${geometria})\n`);
+    }
     // Con la ruta VIRTUAL delante, que es la que se puede volver a abrir. Una captura sigue
     // diciendo `/artefactos/`, que es donde está y donde la tarjeta del hilo la enseña.
     const virtual = imagen === undefined ? RUTA_VIRTUAL : "/artefactos/";

package/skills/xone-hotswap/scripts/xone-recargar-android

@@ -198,6 +198,21 @@ if (cambiados.length === 0) {
   console.log("nada que recargar: los ficheros del proyecto ya son los del aparato.");
   if (otros.length > 0 && posicionales.length === 0) {
     console.log(`(no se comparan ${otros.length} fichero(s) que no son xne/js/css/ini/xml: iconos, bd, files…)`);
+    // Una FUENTE no se queda en «no se compara»: un `fontname` que no está en el aparato saca un diálogo de error y el
+    // control no se pinta (medido). Se dice con el remedio.
+    // Solo las NUEVAS o cambiadas (git: cada turno commitea lo que dejó, así que una recién añadida está sin
+    // commitear); sin git no se dice nada, mejor que avisar de todas en cada recarga.
+    let fuentes = [];
+    try {
+      fuentes = execFileSync("git", ["status", "--porcelain", "--", "fonts"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] })
+        .split("\n")
+        .filter((l) => l.trim() !== "");
+    } catch {
+      fuentes = [];
+    }
+    if (fuentes.length > 0) {
+      console.log(`(hay ${fuentes.length} fuente(s) nueva(s) o cambiada(s) en fonts/ y la recarga NO las sube: despliega entero con xone-desplegar-android)`);
+    }
   }
   process.exit(0);
 }