xonecode 0.3.0 → 0.5.0

package/skills/artifacts-builder/scripts/bundle_artifact.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Colapsa un HTML con ficheros locales a UN solo fichero autocontenido.
+
+Mismo trabajo que `html-inline` de la skill original de Anthropic, pero sin
+npm: el contenedor tiene python3 y node, no npm.
+
+Los recursos absolutos (http/https, //) se dejan como estan — el CSP decide que
+CDNs se permiten (ver `validate_artifact.py`, que es quien enforza esa lista
+blanca de hosts); este script no repite esa lista, solo distingue local de
+absoluto por el esquema de la URL.
+
+Solo libreria estandar.
+"""
+from __future__ import annotations
+
+import base64
+import mimetypes
+import pathlib
+import re
+import sys
+from urllib.parse import urlparse
+
+# Un unico regex con alternancia: `re.sub` solo escanea el string ORIGINAL, no
+# vuelve a mirar lo que el propio callback acaba de insertar. Con tres pases
+# separados (link, luego script, luego img) el pase de imagenes podia colarse
+# DENTRO de un <script> ya inlineado si el JS traia algo con pinta de
+# `<img src="...">` en un string literal — corrupcion silenciosa del JS.
+_RECURSO = re.compile(
+    r"""<link\b[^>]*\bhref\s*=\s*["'](?P<css>[^"']+)["'][^>]*>"""
+    r"""|<script\b[^>]*\bsrc\s*=\s*["'](?P<js>[^"']+)["'][^>]*>\s*</script>"""
+    r"""|(?P<imgpre><img\b[^>]*\bsrc\s*=\s*["'])(?P<img>[^"']+)(?P<imgpost>["'])""",
+    re.I,
+)
+
+
+def _es_local(url: str) -> bool:
+    u = (url or "").strip()
+    if not u or u.startswith(("data:", "blob:", "#")):
+        return False
+    p = urlparse(u)
+    if p.scheme in ("http", "https") or u.startswith("//"):
+        return False
+    return True
+
+
+def _leer(base: pathlib.Path, url: str) -> bytes | None:
+    ruta = (base / url.lstrip("/")).resolve()
+    try:
+        # No salir del directorio del artifact.
+        ruta.relative_to(base.resolve())
+    except ValueError:
+        print(f"[bundle] fuera del directorio, se ignora: {url}", file=sys.stderr)
+        return None
+    if not ruta.is_file():
+        print(f"[bundle] no encontrado, se deja el tag: {url}", file=sys.stderr)
+        return None
+    return ruta.read_bytes()
+
+
+def empaquetar(html: str, base: pathlib.Path) -> str:
+    """Devuelve el HTML con todo recurso LOCAL embebido."""
+    base = pathlib.Path(base)
+
+    def _sub(m: re.Match[str]) -> str:
+        if m.group("css") is not None:
+            url = m.group("css")
+            if not _es_local(url) or "stylesheet" not in m.group(0).lower():
+                return m.group(0)
+            datos = _leer(base, url)
+            if datos is None:
+                return m.group(0)
+            return "<style>\n" + datos.decode("utf-8", "replace") + "\n</style>"
+
+        if m.group("js") is not None:
+            url = m.group("js")
+            if not _es_local(url):
+                return m.group(0)
+            datos = _leer(base, url)
+            if datos is None:
+                return m.group(0)
+            return "<script>\n" + datos.decode("utf-8", "replace") + "\n</script>"
+
+        # Imagen.
+        pre, url, post = m.group("imgpre"), m.group("img"), m.group("imgpost")
+        if not _es_local(url):
+            return m.group(0)
+        datos = _leer(base, url)
+        if datos is None:
+            return m.group(0)
+        mime = mimetypes.guess_type(url)[0] or "application/octet-stream"
+        return pre + f"data:{mime};base64," + base64.b64encode(datos).decode() + post
+
+    return _RECURSO.sub(_sub, html)
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) not in (2, 3):
+        print("uso: bundle_artifact.py <entrada.html> [salida.html]", file=sys.stderr)
+        return 2
+    entrada = pathlib.Path(argv[1])
+    salida = pathlib.Path(argv[2]) if len(argv) == 3 else entrada
+    resultado = empaquetar(entrada.read_text(encoding="utf-8"), entrada.parent)
+    salida.write_text(resultado, encoding="utf-8")
+    print(f"OK: {salida} ({len(resultado.encode('utf-8')) / 1024:.0f} KB)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/skills/artifacts-builder/scripts/validate_artifact.py

@@ -0,0 +1,345 @@
+#!/usr/bin/env python3
+"""Comprueba que un HTML cumple el contrato de artifact de NappAI.
+
+Contrato (nivel 0): el artifact es autocontenido y NO habla con nadie. Cada
+regla de aqui espeja una directiva del CSP con que se sirve; si se cambia una,
+se cambia la otra.
+
+OJO: esto es analisis estatico y se puede enganar (JS ofuscado). La garantia
+real es el CSP de la respuesta, que lo impone el navegador. Esto da
+realimentacion rapida al modelo, no seguridad.
+
+Solo libreria estandar: corre en un contenedor pelado sin pip.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from html.parser import HTMLParser
+from urllib.parse import urlparse
+
+TOPE_BYTES = 5 * 1024 * 1024
+
+CDN_SCRIPT = {"cdnjs.cloudflare.com", "cdn.jsdelivr.net"}
+CDN_ESTILO = CDN_SCRIPT | {"fonts.googleapis.com"}
+CDN_FUENTE = {"fonts.gstatic.com"}
+
+_RED = [
+    (re.compile(r"\bfetch\s*\("), "fetch()"),
+    (re.compile(r"\bXMLHttpRequest\b"), "XMLHttpRequest"),
+    (re.compile(r"\bWebSocket\s*\("), "WebSocket"),
+    (re.compile(r"\bEventSource\s*\("), "EventSource"),
+    (re.compile(r"\bsendBeacon\s*\("), "navigator.sendBeacon()"),
+    (re.compile(r"\bimport\s*\("), "import() dinamico"),
+]
+
+
+# Almacenamiento del navegador. **Estas tres LANZAN en el sandbox del widget**, que pinta el
+# artifact en un iframe con `sandbox="allow-scripts allow-downloads allow-modals"` y SIN
+# `allow-same-origin`: el documento tiene origen opaco y merely LEER una de ellas da
+#
+#     Failed to read the 'localStorage' property from 'Window':
+#     The document is sandboxed and lacks the 'allow-same-origin' flag.
+#
+# Es la MISMA clase que `fetch`: no es un gusto, es que el navegador lo rompe. Y es PEOR que
+# `fetch`, porque el throw se lleva el bloque `<script>` entero y el fallo es MUDO --- medido en
+# produccion el 2026-08-31: la pagina se veia perfecta y el diagrama era un rectangulo vacio.
+_ALMACEN = ("localStorage", "sessionStorage", "indexedDB")
+
+#: Ventanas alrededor de un acceso donde se busca su `try`/`catch`. Es analisis de texto y se
+#: puede enganar --- como todo este fichero, que lo dice en su docstring--- pero caza el caso
+#: comun: el acceso suelto, sin nada que lo envuelva.
+_ANTES = 240
+_DESPUES = 400
+
+
+def _accesos_sin_guarda(html: str) -> list[str]:
+    """Los accesos a almacenamiento que NO parecen envueltos en `try`/`catch`.
+
+    Para cada aparicion se mira hacia atras si hay un `try` cerca y hacia delante si hay un
+    `catch`. No es un parser de JS --- no lo hay en la libreria estandar y este fichero corre en
+    un contenedor pelado--- asi que se elige el error del lado seguro: se avisa del acceso
+    suelto, y un acceso envuelto de forma rara puede colarse. La alternativa (prohibirlo del
+    todo) obligaria a renunciar a recordar una pestana o un filtro por un fallo que tiene
+    arreglo de una linea.
+    """
+    fuera: list[str] = []
+    for api in _ALMACEN:
+        for m in re.finditer(rf"\b{api}\b", html):
+            antes = html[max(0, m.start() - _ANTES) : m.start()]
+            despues = html[m.end() : m.end() + _DESPUES]
+            if "try" in antes and ("catch" in despues or "catch" in antes):
+                continue
+            fuera.append(api)
+            break  # uno por API basta: el mensaje es el mismo
+    return fuera
+
+
+def _host(url: str) -> str | None:
+    """Host de una URL absoluta; None si es relativa, data: o blob:."""
+    url = (url or "").strip()
+    if not url or url.startswith(("data:", "blob:", "#")):
+        return None
+    p = urlparse(url)
+    if p.scheme in ("http", "https") or url.startswith("//"):
+        return (p.netloc or "").lower() or None
+    return None
+
+
+class _Escaner(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.problemas: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        a = {k.lower(): (v or "") for k, v in attrs}
+
+        if tag == "base":
+            self.problemas.append("<base> no esta permitido: reescribe el destino de los enlaces.")
+            return
+
+        if tag == "script":
+            h = _host(a.get("src", ""))
+            if h and h not in CDN_SCRIPT:
+                self.problemas.append(
+                    f"<script src> de '{h}': solo se permiten {sorted(CDN_SCRIPT)}."
+                )
+        elif tag == "link":
+            h = _host(a.get("href", ""))
+            if h and h not in CDN_ESTILO | CDN_FUENTE:
+                self.problemas.append(
+                    f"<link href> de '{h}': solo se permiten {sorted(CDN_ESTILO | CDN_FUENTE)}."
+                )
+        elif tag in ("img", "video", "audio", "source", "embed"):
+            h = _host(a.get("src", ""))
+            if h:
+                self.problemas.append(
+                    f"<{tag} src> de '{h}': usa data: o blob:. Un src externo saca datos "
+                    "por la query string."
+                )
+        elif tag == "iframe":
+            if _host(a.get("src", "")):
+                self.problemas.append("<iframe src> externo no esta permitido.")
+        elif tag == "form":
+            if _host(a.get("action", "")):
+                self.problemas.append("<form action> externo no esta permitido.")
+
+
+#: Etiquetas de mermaid con PARENTESIS sin comillas. Es un error de SINTAXIS, no de estilo, y
+#: rompe el diagrama entero: la pagina carga perfecta y en su sitio sale «Syntax error in text».
+#:
+#: **Medido contra mermaid 10.9.0 en un navegador, con `mermaid.parse` y su control**
+#: (2026-09-01, sobre un panel real que fallo asi):
+#:
+#: | construccion | |
+#: |---|---|
+#: | `A[Uno] --> B[Dos]` | OK |
+#: | `A[Mapeos (mapcol)]` | **ROMPE** |
+#: | `A["Mapeos (mapcol)"]` | OK |
+#: | `subgraph Vistas (contents)` | **ROMPE** |
+#: | `subgraph S1 [Vistas (contents)]` | **ROMPE** |
+#: | `subgraph "Vistas (contents)"` | OK |
+#: | `A[Salida ##EXIT##]`, `A[LoginColl.xne]`, acentos, `:`, `@` | OK |
+#:
+#: **Las almohadillas estan INOCENTES** y es la segunda vez que se acusan en falso: `##EXIT##`
+#: parsea sin problema. Lo que rompe son los parentesis, y en un proyecto XOne salen solos
+#: (`(mapcol)`, `(contents)`), asi que esto no es un caso raro: es el caso normal.
+#: Con que empieza un diagrama de mermaid, para reconocerlo dentro de una plantilla de JS.
+_EMPIEZA_DIAGRAMA = re.compile(
+    r"\s*(?:%%\{.*?\}%%\s*)?"
+    r"(?:graph|flowchart|sequenceDiagram|stateDiagram(?:-v2)?|erDiagram|classDiagram|"
+    r"journey|gantt|pie|mindmap|timeline)\b",
+    re.S,
+)
+
+_MERMAID_NODO = re.compile(r"\[([^\]\n]*)\]")
+_MERMAID_SUBGRAPH = re.compile(r"^[ \t]*subgraph[ \t]+(.*)$", re.M)
+#: Los tramos ENTRE COMILLAS, que es lo que hay que quitar antes de buscar un parentesis.
+#:
+#: **Y esto es el arreglo de un falso positivo, cazado a los diez minutos de escribir el
+#: check**: la primera version exigia la comilla PEGADA al corchete (`\[(?!["\'])`), asi que
+#: `Header ["Cabecera (frmTop)"]` --- con un espacio en medio, que es como lo escribe el modelo
+#: --- se leia como sin comillas y el validador RECHAZABA un panel correcto. Un aviso que
+#: desmiente trabajo bueno hace mas daño que uno que falta: el constructor habria reescrito
+#: tres veces algo que ya estaba bien y habria acabado sin publicar.
+_ENTRE_COMILLAS = re.compile(r"\"[^\"]*\"|'[^']*'")
+
+#: Los delimitadores de FORMA en los bordes de una etiqueta. `A[("x")]` es un cilindro (base de
+#: datos), `A([\"x\"])` un estadio, `A[[\"x\"]]` un subproceso: los parentesis y corchetes de los
+#: extremos son ESTRUCTURA, no texto.
+#:
+#: **Segundo falso positivo de este check, y otra vez habria bloqueado un panel correcto**: sin
+#: quitarlos, `A[("Coleccion Usuarios")]` se leia como una etiqueta con parentesis sin comillas
+#: --- las comillas estaban DENTRO de la forma --- y el validador lo rechazaba. Los dos falsos
+#: positivos han venido de lo mismo: mirar la cadena cruda en vez de la ETIQUETA.
+_BORDES_DE_FORMA = re.compile(r"^[\[\(\{>/\\]+|[\]\)\}/\\]+$")
+
+
+def _solo_la_etiqueta(cruda: str) -> str:
+    """El texto de la etiqueta: sin los delimitadores de forma y sin los tramos citados."""
+    return _ENTRE_COMILLAS.sub("", _BORDES_DE_FORMA.sub("", cruda.strip()))
+
+
+def _sin_lo_citado(texto: str) -> str:
+    """El texto con los tramos entre comillas fuera. Lo que quede es lo NO citado."""
+    return _ENTRE_COMILLAS.sub("", texto)
+
+
+def _bloques_mermaid(html: str) -> list[str]:
+    """El texto de cada diagrama mermaid del HTML.
+
+    Se buscan las DOS formas en que llega: el `<pre class="mermaid">`/`<div class="mermaid">`
+    del render automatico y la cadena que se le pasa a `mermaid.render`/`mermaid.parse` desde
+    JS. Con solo la primera, un panel que construye el diagrama en una constante de JavaScript
+    --- que es lo que hacen la mitad de los que se han visto --- pasaria sin mirar.
+    """
+    fuera: list[str] = []
+    for m in re.finditer(
+        r"<(?:pre|div)[^>]*class=[\"'][^\"']*mermaid[^\"']*[\"'][^>]*>(.*?)</(?:pre|div)>",
+        html,
+        re.S | re.I,
+    ):
+        fuera.append(m.group(1))
+    # **La segunda forma: el diagrama dentro de una PLANTILLA de JS** (`const src = \`graph TD
+    # …\`;`), que es como lo escribe la mitad de los paneles. Se acota a la plantilla completa
+    # —de comilla invertida a comilla invertida— y **eso es el arreglo del TERCER falso positivo
+    # de este check**: la version anterior buscaba `graph TD` y se llevaba hasta 20.000 chars
+    # «hasta la comilla o el `</script>`», asi que cuando el diagrama no estaba en una plantilla
+    # se tragaba el CSS de Tailwind que venia detras y marcaba `rounded-[var(--radius)]` como una
+    # etiqueta con parentesis sin comillas. Rechazaba un panel correcto.
+    #
+    # Los tres falsos positivos de este check han salido de lo mismo: **mirar texto que no es una
+    # etiqueta de mermaid.** Delimitar bien lo que se mira vale mas que afinar el patron.
+    for m in re.finditer(r"`([^`]*)`", html, re.S):
+        cuerpo = m.group(1)
+        if _EMPIEZA_DIAGRAMA.match(cuerpo):
+            fuera.append(cuerpo)
+    return fuera
+
+
+def _mermaid_roto(html: str) -> list[str]:
+    """Etiquetas de mermaid con un parentesis FUERA de comillas, con la culpable delante."""
+    problemas: list[str] = []
+    vistas: set[str] = set()
+    for bloque in _bloques_mermaid(html):
+        candidatas = [m.group(1) for m in _MERMAID_NODO.finditer(bloque)]
+        candidatas += [m.group(1) for m in _MERMAID_SUBGRAPH.finditer(bloque)]
+        for cruda in candidatas:
+            if "(" not in _solo_la_etiqueta(cruda):
+                continue
+            etiqueta = cruda.strip()[:80]
+            if etiqueta in vistas:
+                continue
+            vistas.add(etiqueta)
+            problemas.append(
+                f"Etiqueta de mermaid con parentesis SIN comillas: `{etiqueta}`. mermaid 10.9 "
+                f"no la parsea y el diagrama entero sale como «Syntax error in text» (medido "
+                f"con mermaid.parse). Pon el TEXTO entre comillas dobles: `[\"...\"]` en un "
+                f"nodo, `subgraph \"...\"` en un subgrafo."
+            )
+    return problemas
+
+
+def validar(html: str) -> tuple[bool, list[str]]:
+    """Devuelve (ok, problemas). Cada problema dice que hacer, no solo que pasa."""
+    problemas: list[str] = []
+
+    tam = len(html.encode("utf-8"))
+    if tam > TOPE_BYTES:
+        problemas.append(
+            f"El artifact ocupa {tam / 1024 / 1024:.1f} MB y el tope son 5 MB. "
+            "Reduce los datos horneados o baja la resolucion de las imagenes."
+        )
+
+    for patron, nombre in _RED:
+        if patron.search(html):
+            problemas.append(
+                f"Usa {nombre}: el artifact es autocontenido y no puede hablar con el "
+                "servidor. Hornea los datos dentro del HTML."
+            )
+
+    problemas.extend(_mermaid_roto(html))
+
+    for api in _accesos_sin_guarda(html):
+        problemas.append(
+            f"Usa {api} sin try/catch: en el sandbox del visor LANZA "
+            f"(«The document is sandboxed and lacks the 'allow-same-origin' flag») y se lleva "
+            f"el bloque <script> entero, asi que la pagina se rompe EN SILENCIO. Para el tema "
+            f"basta matchMedia('(prefers-color-scheme: dark)'). Si necesitas guardar algo, "
+            f"envuelve cada acceso: try {{ {api}.getItem(k) }} catch {{}}."
+        )
+
+    escaner = _Escaner()
+    try:
+        escaner.feed(html)
+    except AssertionError as e:  # lo unico que HTMLParser levanta con markup patologico
+        problemas.append(f"El HTML no se puede parsear: {e}")
+    problemas.extend(escaner.problemas)
+
+    return (not problemas), problemas
+
+
+def avisos(html: str) -> list[str]:
+    """Calidad, no rotura: se publica igual y se le dice.
+
+    **La distincion es la que hace que el contrato signifique algo.** Si un `alt` que falta
+    bloqueara la publicacion igual que una pagina que no arranca, el modelo aprenderia a leer la
+    lista entera como ruido. Aqui van las cosas que hacen el panel peor sin hacerlo imposible.
+    """
+    fuera: list[str] = []
+    bajo = html.lower()
+
+    if not re.search(r"<!doctype\s+html", html, flags=re.IGNORECASE):
+        fuera.append("falta el doctype de HTML5: el navegador entra en modo quirks.")
+    if not re.search(r"<html[^>]*\slang=", html, flags=re.IGNORECASE):
+        fuera.append('falta `lang` en <html>: los lectores de pantalla no saben en que idioma leer.')
+    if "name=\"viewport\"" not in bajo and "name='viewport'" not in bajo:
+        fuera.append("falta el meta viewport: en movil se vera reducido al 25%.")
+    if not re.search(r"<title>\s*\S", html, flags=re.IGNORECASE):
+        fuera.append("falta un <title> con contenido: es el nombre del panel en la pestana.")
+
+    sin_alt = [
+        m.group(0)
+        for m in re.finditer(r"<img\b[^>]*>", html, flags=re.IGNORECASE)
+        if not re.search(r"\salt=", m.group(0), flags=re.IGNORECASE)
+    ]
+    if sin_alt:
+        fuera.append(f"{len(sin_alt)} imagen(es) sin `alt`.")
+
+    botones_mudos = len(
+        [m for m in re.finditer(r"<button\b[^>]*>\s*</button>", html, flags=re.IGNORECASE)]
+    )
+    if botones_mudos:
+        fuera.append(
+            f"{botones_mudos} boton(es) sin texto ni etiqueta accesible: usa texto o aria-label."
+        )
+
+    ids = re.findall(r"\sid=[\"']([^\"']+)[\"']", html)
+    repetidos = sorted({i for i in ids if ids.count(i) > 1})
+    if repetidos:
+        fuera.append(f"ids repetidos: {', '.join(repetidos[:5])}.")
+
+    interactivo = "<button" in bajo or "<a " in bajo
+    if interactivo and not re.search(r":focus-visible|:focus\b", html, flags=re.IGNORECASE):
+        fuera.append("ningun estilo de foco visible: con teclado no se ve donde estas.")
+
+    return fuera
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) != 2:
+        print("uso: validate_artifact.py <fichero.html>", file=sys.stderr)
+        return 2
+    with open(argv[1], encoding="utf-8") as fh:
+        ok, problemas = validar(fh.read())
+    if ok:
+        print("OK: el artifact cumple el contrato.")
+        return 0
+    print("El artifact NO cumple el contrato:")
+    for p in problemas:
+        print(f"  - {p}")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/skills/xone-hotswap/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: xone-hotswap
+description: Probar una app XOne en un dispositivo o emulador LOCAL —Android o iOS— a través del servidor hotswap que la propia app host levanta en el dispositivo. Usar al desplegar una app en un móvil o simulador, al reiniciarla para que aplique cambios, al capturar la pantalla o el árbol de controles, al pulsar o rellenar controles desde fuera, al leer el log o consultar la base de datos del dispositivo, y al diagnosticar por qué el dispositivo no responde en el puerto 8443. Cubre las dos plataformas y dice, comando por comando, cuál de las dos lo tiene.
+---
+
+# Probar una app XOne en un dispositivo local (hotswap)
+
+El interlocutor es la **app host ya instalada** en el dispositivo. No se compila ni se instala
+un paquete por iteración: se le suben los ficheros del proyecto, se reinicia y se mira.
+
+| | Android | iOS |
+|---|---|---|
+| App host | **XoneStudio** (`com.xone.android.framework`, o `com.xone.android.developer.framework` en el flavor de Play Store) | **XOneStudioSwift** (`es.xone.studioapp.swift`) |
+| Solo existe en | builds *debuggable* | el runtime en **modo desarrollo** (`XoneAppDeveloment`); en una app de producción no existe |
+
+El servidor vive **dentro del proceso de la app**: si la app no está viva, el puerto no
+responde. Habla dos protocolos por el mismo puerto: **WebSocket** para los comandos
+(`{"command": "..."}` → `{"result": ..., "status": ...}`) y **HTTP(S)** para lo demás.
+
+## Lo que hay que saber antes de tocar nada
+
+- **HTTPS con certificado autofirmado** en las dos plataformas. Todas las URLs son `https://`;
+  con `curl` hace falta `-k`. Solo escucha en `http://` si alguien desactivó la conexión segura.
+- **El puerto 8443 es el POR DEFECTO, no una garantía.** En Android, si está ocupado —otra APK
+  del framework instalada— el servidor coge el siguiente libre, y el real se ve en la pantalla
+  del servidor hotswap (pestaña Información).
+- **Subir NO aplica.** El proceso tiene cargado en memoria lo de antes: hay que reiniciar la app.
+- **La base de datos va cifrada con SQLCipher.** Subir un `.db` en claro termina en
+  `database disk image is malformed (code 11)`.
+- **En iOS, `POST /command` sirve solo los comandos de automatización** — los de los bloques
+  **Ver la pantalla** y **Tocar**. Los comandos legados (`launchApplication`, `setAttribute`,
+  `listAppFiles`…) son **solo WebSocket**: sus manejadores responden escribiendo en el socket, que
+  en una petición HTTP no existe, así que por HTTP contestan `Unknown command '<x>'` aunque el
+  comando exista. Cuál es cuál, comando a comando: la columna **Canal (iOS)** de la
+  [matriz](references/comandos.md#matriz-de-disponibilidad).
+
+## Cómo llegar, según la plataforma
+
+**Android** — por `adb forward`, y entonces la IP es `127.0.0.1` (el localhost del PC, que adb
+tuneliza al dispositivo). Con varios dispositivos, `adb -s <serial>`:
+
+```bash
+adb devices -l
+adb shell am start -n com.xone.android.framework/com.xone.android.hotswap.activities.SetupActivity
+adb forward tcp:8443 tcp:8443          # reaplicar tras cada reconexión del cable
+```
+
+**iOS** — **no hay `adb` ni túnel**. El simulador comparte la pila de red del Mac, así que el
+servidor es alcanzable directamente; en dispositivo físico se llega por la IP de la LAN que
+muestra la propia app:
+
+```bash
+xcrun simctl list devices booted
+xcrun simctl launch <UDID> es.xone.studioapp.swift    # arrancar el host levanta el servidor
+curl -sk -X POST https://localhost:8443/command -d '{"command":"getAllElements"}'
+```
+
+Detalle de despliegue, relanzado y endpoints de fichero: [conexión y despliegue](references/conexion-y-despliegue.md).
+
+## Qué hay en cada plataforma, de un vistazo
+
+| Bloque | Android | iOS |
+|---|---|---|
+| Ver la pantalla (`getAllElements`, `getCurrentScreen`, `getScreenshot`, `getText`, `getUiAttribute`, `getRows`, `isVisible`, `isEnabled`, `waitForElement`) | sí | **sí**, con desviaciones (abajo) |
+| Tocar (`click`, `tap`, `doubleTap`, `longPress`, `openSelector`, `fill`, `clear`, `scroll`, `pressKey`) | sí | **sí**, con desviaciones (abajo) |
+| Ciclo de app (`launchApplication`, `exitApplication`, `directdownload`) | sí | `launchApplication` y `directdownload` sí; `exitApplication` no |
+| Atributos y colecciones (`setAttribute`, `deleteAttribute`, `loadCollection`) | sí | sí |
+| CSS, `replaceProperty`, `refresh`, `relayout`, `loadIncludeFile` | sí | **no** |
+| Ficheros (`/file_upload`, `/file_download`, `uploadFile`, `getFileChecksum`) | sí | **no** (`listappfiles` sí) |
+| Scripts y SQL (`runScript`, `runSql`, `getDatabaseTableNames`, `queryDatabaseTable`) | sí | **no** |
+| Logs (`getLog`, `*DeviceLogging`, `setLog*`) | sí | **no** |
+| Mock de hardware (`setMockData`, `clearMockData`) | sí | **no** |
+| Edición en vivo (`enable/disableLiveEditionMode`) | sí | **no** |
+| Depurador JS (`debug`) | sí | **no** (JavaScriptCore no tiene API pública de depuración) |
+
+**Lo que en 5.0.2.2dev NO existe, medido el 16-sep-2026** (flavor standalone, Android, **con una app
+ya cargada y viva**): `getCurrentScreen` y `status`/`state` contestan `Unknown command`, aunque esta
+tabla los dé por disponibles. Para ver la pantalla, lo que responde es `getAllElements` —el árbol de
+controles— y `getScreenshot` —el PNG en base64—. Y **el nombre de un comando es EXACTO**: no hay
+alias insensible a mayúsculas. `launchApplication`, `setAttribute` y `listAppFiles` existen; sus
+variantes en minúscula contestan `Unknown command`, que es como se descubrió.
+
+Comando por comando, con su contrato y sus desviaciones: [comandos](references/comandos.md).
+
+Los doce comandos que apuntan por nombre (`getText`, `isVisible`, `isEnabled`, `waitForElement`,
+`click`, `tap`, `doubleTap`, `longPress`, `openSelector`, `fill`, `clear`, `scroll`) aceptan
+además **`row` / `content` / `where`** para apuntar a una **fila**: por índice, por content, o por
+**lo que contiene** (`{"ID":"2938733"}`). Solo existen las filas **pintadas**; el índice es el de
+la colección y **no se renumera con el scroll**; y `waitForElement` con `row` espera a que la
+fila **esté pintada**, no a que la colección tenga datos. Para leer las filas que NO están a la
+vista, `getRows` — que lee el modelo, no las vistas.
+
+## Lo que iOS no puede hacer IGUAL, y por qué
+
+No son carencias de implementación: son límites y consecuencias de la plataforma, y el canal las
+responde con un motivo en vez de fingir. **Declarar lo que iOS no puede hacer igual vale más que
+fingir paridad**: con la diferencia delante se puede trabajar; con una promesa falsa, no.
+
+- **No hay inyección de toques ni de teclas.** `click` invoca el manejador del control (como el
+  `performClick()` de Android), así que **`click` y `tap` colapsan** en el mismo efecto, y
+  `doubleTap`/`longPress` **siempre se niegan**: el runtime iOS no tiene eventos XONE de doble
+  toque ni de pulsación larga en props/frames. `pressKey` solo traduce `4`/`back` y `66`/`enter`
+  (con `key` simbólico: `back`, `enter` y `done`).
+  Por eso `has no click handler` va **sin** la coletilla `use 'tap' to send a real touch` de
+  Android: mandaría a repetir la llamada que acaba de fallar.
+- **No hay codificación WebP.** `getScreenshot` devuelve JPEG al 50% (o PNG si se pide) y lo
+  declara en `imageFormat`.
+- **La captura no lo captura todo**: quedan fuera la cámara en vivo, las capas Metal/GL, las
+  teselas de mapa y la barra de estado del sistema (otro proceso).
+- **Los memos multilínea y los campos de fecha/hora no los escribe ESTE CANAL**, y lo dicen así:
+  `Element 'X' is editable, but this channel cannot write a multiline|date/time field`. El usuario
+  sí puede editarlos — no es un control equivocado, es un límite del canal.
+- **Los dos volcados NO son compatibles atributo a atributo.** iOS emite **8** atributos y Android
+  **19**, con solo **5 comunes** (`index`, `class`, `text`, `enabled`, `bounds`). iOS no tiene
+  `resource-id` —con el que Android nombra las piezas de un diálogo— ni `content-desc` ni los
+  booleanos (`checkable`, `clickable`, `scrollable`…), y tiene tres propios (`accessibility-id`,
+  `label`, `visible`). En iOS el canónico es **`uikit`**; `uiautomator` se acepta como **alias**
+  para que una llamada multiplataforma no falle, pero **devuelve datos con forma de iOS**.
+- **La búsqueda mira primero lo que está ENCIMA** (diálogos, toasts) y la pantalla al final.
+  Alcanzar un control tapado **nombrándolo** sigue permitido; lo que cambió es el orden. Los
+  niveles **anteriores** de navegación **no se buscan**: un `not found` sobre un control de la
+  pantalla que dejaste atrás significa que todavía no has navegado.
+
+Las **once divergencias con Android**, con su porqué:
+[comandos → Divergencias](references/comandos.md#divergencias-con-android).
+
+## Dos avisos sobre el host iOS que te vas a encontrar
+
+Ninguno es del hotswap; los dos te van a costar una sesión si no los sabes.
+
+- **`MyAllXOne` crashea al arrancar** en el host (GoogleMaps). Para probar **filas**, el fixture
+  usable es **`FontIconsApp`**.
+- **El host se cae al abrir una lista de menú**: le faltan los `xone_img_*.png`, y
+  `CollectionViewController`/`SortView` meten `UIImage` nil en arrays. Es un defecto **ajeno** al
+  hotswap. Si el puerto deja de responder justo después de abrir un menú, es esto.
+
+## Cómo se prueba, y qué cuenta como evidencia
+
+1. **Reproduce el estado**: lanza la app y espera al control que marca la pantalla lista
+   (`waitForElement`), nunca a un temporizador fijo.
+2. **Pregunta dónde estás** (`getCurrentScreen`, **iOS**) tras cada navegación: dice la pantalla,
+   su colección, qué diálogos hay encima y cuál se lleva los toques. Es una respuesta corta, y
+   evita interpretar un volcado para averiguar lo mismo.
+3. **Mira el árbol antes de tocar** (`getAllElements`). El formato `xone` da los controles con su
+   nombre XOne, que es por el que se pulsa; el otro formato da el volcado de la jerarquía de
+   vistas, útil para distinguir "ese control no existe" de "existe pero el motor no lo indexa".
+   Para el contenido de una **lista**, `getRows`: el volcado solo trae las filas pintadas.
+4. **Actúa por NOMBRE de control** (`click`, `tap`, `fill`, `scroll`), no por coordenadas: las
+   coordenadas cambian con el tamaño de pantalla y no dicen qué se intentaba pulsar.
+5. **Comprueba con un dato, no con una impresión**: `getText`, `isVisible`, `isEnabled`, y el
+   propio `getAllElements` antes y después. Una captura sirve para **enseñar** el fallo, no para
+   afirmar que algo funciona — nadie puede releerla.
+6. **Si algo falla, trae el log** (Android) o la respuesta literal del comando (las dos
+   plataformas) y la línea concreta. «No funciona» no es un hallazgo.
+
+## Reglas que evitan diagnósticos falsos
+
+- **No inventes controles.** Si `getAllElements` no lo lista, no existe en esa pantalla: dilo en
+  vez de probar nombres a ver si suena alguno.
+- **Un `result: false` es el resultado**, no un error del que recuperarse en silencio. Su `status`
+  dice exactamente qué pasó. En iOS, un control **ausente** ya no se confunde con uno
+  **intocable**, y cada mensaje manda a un sitio distinto: `not found` (corrige el nombre) ·
+  `is not enabled` (rellena antes la pantalla) · `has editing disabled` (desbloquéalo en la app).
+  El catálogo entero, con qué arregla cada uno:
+  [comandos → El catálogo de errores](references/comandos.md#el-catálogo-de-errores-desdoblado-ios).
+- **Para saber si un campo se puede escribir, mira `editDisabled`, no `enabled`.** `enabled`
+  devuelve lo mismo en un campo bloqueado y en uno que no se escribe nunca; `editDisabled:true`
+  (que solo se emite cuando es cierto) es el único que los separa. Y su **ausencia no promete**
+  que el `fill` funcione: un memo o un campo de fecha salen sin él y este canal tampoco los
+  escribe.
+- **Distingue «la app no está viva» de «la prueba falla».** Conexión rechazada en el puerto es lo
+  primero. En iOS hay además una distinción propia: `"App is not running"` significa que no hay
+  ninguna app XONE lanzada, mientras que `"Screen '<clase>' is not readable by the 'xone' format"`
+  significa que sí la hay, pero su pantalla es de un camino de render que ese formato no lee.
+- **Después de subir, reinicia.** Un resultado medido sin reiniciar está midiendo la versión
+  anterior, y es el error más caro de todos porque no da ningún síntoma.
+- **No dejes el dispositivo peor de como estaba**: `clearMockData` tras usar datos simulados
+  (Android), y `disableDeviceLogging` / `setLogDisabled` tras acabar.
+
+## Referencias
+
+| Qué | Dónde |
+|---|---|
+| Los comandos, uno a uno: entrada, salida, errores y qué plataforma lo tiene | [references/comandos.md](references/comandos.md) |
+| Llegar al dispositivo, desplegar una app, relanzarla, y los endpoints de fichero | [references/conexion-y-despliegue.md](references/conexion-y-despliegue.md) |