xonecode 0.1.0

package/skills/xone-development/references/javascript/ui-navegacion-mensajes-y-vista.md

@@ -0,0 +1,422 @@
+# XOne JavaScript — ui: navegación, mensajes y vista
+
+> Fuente: `xone/v2/xone-help-docs/topics/03b-js-ui.md` §3.1–§3.4. Referencia de la skill; el índice está en [../../SKILL.md](../../SKILL.md).
+
+Contenido: §3.1 navegación (openEditView, openMenu) · §3.2 mensajes y diálogos (msgBox, showToast, showSnackbar) · §3.3 refrescar y acceder a controles, showcase · §3.4 date/time pickers
+
+---
+
+### 3.1 Navegación
+
+`ui.openEditView()` es el mecanismo principal de navegación en XOne. Sirve tanto para "abrir una pantalla" como para "editar un objeto existente":
+
+```javascript
+// === Abrir una pantalla (la forma habitual) ===
+// Firma: ui.openEditView(target, [exit])
+//   target : dataObject | string — un dataObject ya preparado, o el nombre de la coll destino
+//   exit   : boolean — si true, cierra la vista origen al abrir la nueva (default false)
+
+// Forma corta: pasar el nombre de la coll. XOne crea internamente un dataObject
+// vacío de esa coll (createObject + addItem) y abre su vista de edición.
+ui.openEditView("Productos");
+
+// Pasar un objeto NUEVO con datos pre-rellenados
+let coll = appData.getCollection("Productos");
+let obj = new Productos({ MAP_CATEGORIA_ID: idCategoria });
+coll.addItem(obj);
+ui.openEditView(obj);
+
+// Abrir un objeto EXISTENTE recuperado de la BD
+let producto = appData.getCollection("Productos").findObject("ID = " + nId);
+if (producto) {
+    ui.openEditView(producto);
+}
+
+// Cerrar la vista origen al abrir la nueva (flujos lineales sin botón atrás)
+ui.openEditView(obj, true);
+
+// === Obtener la ventana actual ===
+let window = ui.getView(self);   // Ventana del objeto actual
+let window = ui.getView();       // Ventana actual sin parametro
+
+// === Cerrar ventana actual ===
+let window = ui.getView(self);
+if (window) {
+    window.exit();
+}
+
+// === Cerrar la aplicación ===
+appData.exit();
+
+// === Mostrar/ocultar grupos (tabs) ===
+ui.showGroup(2);  // Mostrar grupo por indice
+
+// Con animacion
+ui.showGroup(2, "##ALPHA_IN##", 200, "##ALPHA_OUT##", 200);
+
+// Ejemplo real: navegacion entre paginas con animacion
+function mostrarGrupo(nGroup, sAnimIn, sAnimOut) {
+    sAnimIn = sAnimIn || "##ALPHA_IN##";
+    sAnimOut = sAnimOut || "##ALPHA_OUT##";
+    ui.showGroup(nGroup, sAnimIn, 200, sAnimOut, 200);
+}
+```
+
+**Animaciones predefinidas disponibles:**
+
+| Constante | Descripción |
+|-----------|-------------|
+| `##ALPHA_IN##` / `##ALPHA_OUT##` | Entrada/salida con fundido |
+| `##ZOOM_IN##` / `##ZOOM_OUT##` | Entrada/salida con zoom |
+| `##LEFT_IN##` / `##LEFT_OUT##` | Deslizar desde/hacia la izquierda |
+| `##RIGHT_IN##` / `##RIGHT_OUT##` | Deslizar desde/hacia la derecha |
+| `##TOP_IN##` / `##TOP_OUT##` | Deslizar desde/hacia arriba |
+| `##BOTTOM_IN##` / `##BOTTOM_OUT##` | Deslizar desde/hacia abajo |
+
+#### Caso especial — abrir la LISTA de una coll directamente
+
+`ui.openEditView()` siempre abre el EditView de un dataObject. Si lo que se necesita es lanzar directamente la **lista** de una coll como pantalla independiente (`MainListCollectionActivity` o `MainCalendarViewActivity` si tiene `viewmode="calendar"`), hay que recurrir al método legacy `ui.openMenu(collName, mask, mode)` con `mode=0`:
+
+```javascript
+// Lista con todas las opciones del menú (mode=0, mask=0xFFFFFF)
+ui.openMenu("Productos", 0xFFFFFF, 0);
+
+// Lista en modo sólo lectura (mask = MENU_MASK_VIEW)
+ui.openMenu("Productos", 0x000200, 0);
+```
+
+Constantes `mask` (combinables con OR — JavaScript NO expone los nombres, usar el valor numérico): `ADD=0x01`, `EDIT=0x02`, `DELETE=0x04`, `EXIT=0x08`, `FILTRAR=0x10`, `SAVE=0x40`, `SORT=0x80`, `REFRESH=0x100`, `VIEW=0x200`, `FULLMASK=0xFFFFFF`.
+
+> Para el resto de necesidades de navegación (abrir una pantalla nueva, abrir un objeto existente, abrir un detalle desde un `<selecteditem>`) usar siempre `ui.openEditView()`. Habitualmente las "listas" en XOne se muestran como `<contents>` embebido en una pantalla padre, no como activity independiente — por eso `mode=0` se necesita poco.
+
+### 3.2 Mensajes y Dialogos
+
+```javascript
+// === Message Box clasico ===
+// Tipo 0 = Solo botón OK
+// Tipo 4 = Botones Si/No (retorna 6=Si, 7=No)
+let nResult = ui.msgBox("Desea continuar?", "Confirmar", 4);
+if (nResult == 6) {
+    // Usuario pulso Si
+}
+
+// === Toast simple ===
+ui.showToast("Mensaje rápido");
+
+// === Toast personalizado ===
+ui.showToast({
+    color    : "#4CAF50",          // Color de fondo
+    duration : "short",            // "short" o "long"
+    text     : "Guardado correctamente",
+    textColor: "#FFFFFF",          // Color del texto
+    textFont : "Roboto-Regular.ttf",  // Fuente (debe estar en fonts/)
+    textSize : 14,                 // Tamano de fuente
+    rounded  : true                // Esquinas redondeadas
+});
+
+// === Snackbar simple (solo texto) ===
+ui.showSnackbar("Registro eliminado");   // duración "long", texto blanco por defecto
+
+// === Snackbar con acción ===
+ui.showSnackbar({
+    text           : "Registro eliminado", // OBLIGATORIO (vacío => excepción)
+    color          : "#323232",
+    duration       : "long",        // "short" | "long" | "indefinite" (otro valor => excepción)
+    width          : "80%",         // "100%" => ancho completo
+    textColor      : "#FFFFFF",
+    actionText     : "Deshacer",    // solo se muestra si TAMBIÉN hay actionMethod
+    actionTextColor: "#FFEB3B",
+    maxLines       : 1,             // solo aplica si > 1
+    align          : "center|bottom",
+    height         : "10%",         // Altura del snackbar (opcional)
+    actionMethod   : function() {   // se ejecuta en un hilo aparte, no en el de UI
+        deshacerEliminacion();
+    }
+});
+
+// Ocultar snackbar manualmente (oculta el último mostrado; false si no hay ninguno visible)
+ui.hideSnackbar();
+
+// NOTA: showSnackbar solo funciona dentro de una pantalla de edición.
+// En otros contextos lanza una excepción.
+
+// === msgBox con DataObject (dialogo completamente personalizado) ===
+
+// Variante SINCRONA: bloquea hasta que el usuario pulsa
+// La coll debe tener botones con button-option="N"
+// ui.msgBox() devuelve el valor del button-option del botón pulsado
+let msgBoxObj  = new MessageBoxNormal();
+let nResult    = ui.msgBox(msgBoxObj);
+// nResult == 1 -> pulsó Cancel (button-option="1")
+// nResult == 2 -> pulsó OK     (button-option="2")
+
+// Variante ASINCRONA con callbacks (no bloquea)
+// La coll debe tener: hardware-accelerated="false", bgcolor="#00000000"
+// y campos type="O" para los callbacks
+function showMsgBoxAsync(callbackOk, callbackCancel) {
+    let obj = new MessageBoxAsync({ MAP_CALLBACK_OK: callbackOk, MAP_CALLBACK_CANCEL: callbackCancel });
+    ui.openEditView(obj);
+}
+
+// Uso:
+showMsgBoxAsync(
+    function() { ui.showToast("OK pulsado");     ui.getView(self).exit(); },
+    function() { ui.showToast("Cancel pulsado"); ui.getView(self).exit(); }
+);
+
+// === Wait Dialog (indicador de carga) ===
+ui.showWaitDialog("Cargando datos...");
+ui.setWaitDialogText("Procesando registros...");
+ui.hideWaitDialog();
+
+// === Notificaciones ===
+// Notificación simple
+ui.showNotification(1, "Titulo", "Texto de la notificación");
+
+// Notificación con ticker
+ui.showNotification(2, "Titulo", "Texto", "Texto en barra de estado");
+
+// Notificación con callback al pulsar
+ui.showNotification(3, "Titulo", "Texto", "Ticker", self, "miNodoCallback");
+
+// Notificación avanzada con botones
+ui.showNotification({
+    id             : 5000,
+    title          : "Nueva tarea asignada",
+    text           : "Tiene una nueva tarea pendiente",
+    textHtml       : "<b>Tarea urgente</b>: Revision de inventario",
+    icon           : "app_icon1",       // app_icon1 a app_icon10
+    largeIcon      : "app_icon4",
+    backgroundColor: "#1976D2",
+    sound          : "notification.wav",
+    cancelable     : true,
+    dataObject     : self,
+    nodeName       : "callbackNotificacion",
+    parameters     : '{ "tareaId": "123" }',
+    buttons        : [{
+        id              : 5001,
+        title           : "Responder",
+        directReply     : true,
+        directReplyLabel: "Escriba su respuesta...",
+        dataObject      : self,
+        nodeName        : "respuestaCallback"
+    }]
+});
+
+// LED de notificación (solo Android)
+ui.setNotificationLed("#00FF00", 1000, 1000);  // color, onMs, offMs
+```
+
+#### msgBox con DataObject (Dialogos Personalizados)
+
+`ui.msgBox(dataObject)` permite abrir una coleccion XOne como dialogo completamente personalizado.
+
+**Variante sincrona** — Los botones usan `button-option`. `ui.msgBox()` bloquea hasta que el usuario pulsa y devuelve el valor del `button-option` pulsado:
+
+```javascript
+let msgBoxObj  = new MessageBoxNormal();
+let nResult    = ui.msgBox(msgBoxObj);
+// nResult == 1 -> pulsó Cancel (button-option="1")
+// nResult == 2 -> pulsó OK     (button-option="2")
+```
+
+La coll `MessageBoxNormal` requiere: `notab="true"`, `show-toolbar="false"`, `check-owner="false"`, `dependent="false"`, y botones con `button-option="N"`.
+
+**Variante asíncrona con callbacks** — Los botones invocan `self.MAP_CALLBACK_OK()`. Usa campos `type="O"` para las funciones callback:
+
+```javascript
+function showMessageBoxDataObject(callbackOk, callbackCancel) {
+    let newMsgBox = new MessageBoxAsync({ MAP_CALLBACK_OK: callbackOk, MAP_CALLBACK_CANCEL: callbackCancel });
+    ui.openEditView(newMsgBox);
+}
+
+// Uso
+showMessageBoxDataObject(
+    function() { ui.showToast("OK pulsado");     ui.getView(self).exit(); },
+    function() { ui.showToast("Cancel pulsado"); ui.getView(self).exit(); }
+);
+```
+
+La coll `MessageBoxAsync` requiere además: `hardware-accelerated="false"` y `bgcolor="#00000000"` para fondo transparente sin fondo negro.
+
+### 3.3 Vista - Refrescar y Acceder a Controles
+
+```javascript
+// === Obtener la ventana actual ===
+let window = ui.getView(self);
+let window = ui.getView();    // Sin parametro = ventana activa actual
+
+// === Acceder a un control por nombre ===
+let control = window["MAP_BOTON"];
+
+// === getControl(name, [dataObject]) - función NATIVA global (recomendado) ===
+// Disponible directamente, NO hace falta declarar el helper. Devuelve el control
+// resuelto en la ventana destino:
+//   - getControl(name)             → última ventana visible.
+//   - getControl(name, dataObject) → ventana asociada a ese DataObject.
+//
+// Semántica ESTRICTA: lanza error si el nombre está vacío, el control no
+// existe, no hay ventana destino, o el dataObject no es válido.
+//
+// Si un proyecto ya tiene "function getControl(...)" propia, esa sombrea a la
+// nativa en su scope local (compatibilidad hacia atrás preservada).
+let control = getControl("MAP_BOTON");
+let controlEnOtraVentana = getControl("MAP_TITULO", objPadre);
+
+// === Refrescar campos de la interfaz ===
+ui.refresh();                           // Refrescar TODO (costoso, evitar)
+ui.refresh("MAP_NOMBRE");              // Refrescar un campo específico
+ui.refresh("MAP_NOMBRE,MAP_ESTADO");   // Refrescar multiples campos
+
+// Solo actualizar el valor (sin reconstruir la vista del control)
+ui.refreshValue("MAP_CAMPO");
+// Multiples campos (cada uno como argumento)
+let ventana = ui.getView(self);
+ventana.refreshValue("MAP_CAMPO1", "MAP_CAMPO2", "MAP_CAMPO3");
+
+// Refrescar una fila específica de un content
+ui.refreshContentRow("MAP_CONTENT", 0);
+
+// Refrescar la fila seleccionada de un content
+ui.refreshContentSelectedRow("MAP_CONTENT");
+
+// Refrescar usando la ventana directamente
+window.refresh("MAP_CAMPO");
+window.refreshAll("frmMiFrame");       // Refresca el frame y todos sus hijos
+
+// === Grupos (tabs) y Drawers ===
+// Mostrar un grupo por indice
+ui.showGroup(2);
+ui.showGroup(2, "##ALPHA_IN##", 300, "##ALPHA_OUT##", 300);  // Con animacion
+
+// Comprobar si un grupo esta abierto (util para drawers)
+if (window.isGroupOpen(999)) {
+    window.hideGroup(999);  // Cerrar el drawer
+}
+
+// Patron: botón atrás cierra drawer antes de salir
+function doOnBack() {
+    let window = ui.getView();
+    if (!window) return;
+    if (window.isGroupOpen(999)) {
+        window.hideGroup(999);
+        return;
+    }
+    window.exit();
+}
+
+// === Nombre de la coleccion activa ===
+function getCurrentCollectionName() {
+    let window = ui.getView();
+    if (!window) return "";
+    let dataObject = window.getDataObject();
+    if (!dataObject) return "";
+    let coll = dataObject.getOwnerCollection();
+    if (!coll) return "";
+    return coll.getName();
+}
+
+// === Traer app al primer plano (desde handler de notificación) ===
+ui.returnToForeground();
+
+// === Scroll de Frames ===
+let frame = window["frmScroll"];
+frame.scrollToTop(true);     // true = animado
+frame.scrollToBottom(true);
+
+// === Bottom Sheet ===
+// sFrame: nombre del frame con behavior="bottom-sheet"
+// sState: "expanded" / "collapsed" / "hidden"
+// bLockDrag: true = impedir que el usuario lo arrastre
+window.setBottomSheetState("mi_panel", "expanded", false);
+window.setBottomSheetState("mi_panel", "collapsed", true);  // Bloqueado
+let sEstado = window.getBottomSheetState("mi_panel");
+
+// === Progress Bar JS ===
+let control = window["MAP_PROGRESS_BAR"];
+control.setIndeterminate(true);    // Activar animacion continua
+control.setIndeterminate(false);   // Desactivar, mostrar valor actual
+control.toggleIndeterminate();     // Alternar estado
+let bIndet = control.isIndeterminate();
+
+// === Efectos visuales en frame: setBlur / setSaturation ===
+// NO son API de XOne: los expone la vista nativa de Android/iOS que hay por debajo.
+// Se llaman sobre el frame o el control, nunca sobre ui, y no hay ui.setBlur.
+// Documentados en metodos-nativos-de-la-vista.md, con el envoltorio y el patron de slider.
+
+// === Color de la barra de estado ===
+window.setStatusBarColor("#1565C0");  // Color RRGGBB
+window.setStatusBarColor(null);       // Restaurar color por defecto
+
+// === Showcase (tutorial interactivo) ===
+window.startShowcase({
+    continueOnCancel: true,     // Si cancela un paso, ir al siguiente
+    tapTargets: [{
+        target              : "MAP_CAMPO1",
+        title               : "Paso 1",
+        description         : "Descripción del primer paso",
+        cancelable          : true,
+        transparentTarget   : true,
+        targetRadius        : 90,
+        outerCircleOpacity  : 96,
+        outerCircleColor    : "#1565C0",
+        targetCircleColor   : "#FF0000",
+        dimColor            : "#CC000000",
+        titleTextSize       : 20,
+        descriptionTextSize : 15,
+        textColor           : "#FFFFFF",
+        titleTextColor      : "#FFFF00",
+        descriptionTextColor: "#FFFFFF",
+        textFont            : "MiFuente.ttf",
+        drawShadow          : true
+    }, {
+        target     : "MAP_CAMPO2",
+        title      : "Paso 2",
+        description: "Segundo paso del tutorial",
+        cancelable : true
+    }]
+});
+```
+
+### 3.4 Date/Time Pickers
+
+```javascript
+// Date Picker con callback
+ui.showDatePicker({
+    initialYear : 2024,
+    initialMonth: 6,
+    initialDay  : 15,
+    title       : "Seleccione fecha",
+    theme       : "holo_light",           // Tema visual del picker
+    onDateSet   : function(nYear, nMonth, nDay) {
+        self.MAP_FECHA = nDay + "/" + nMonth + "/" + nYear;
+        ui.refresh("MAP_FECHA");
+    }
+});
+
+// Date Picker que escribe directamente en un campo (sin callback)
+ui.showDatePicker({
+    targetProperty: "MAP_FECHA"           // El picker escribe aquí al confirmar
+});
+
+// Time Picker con callback
+ui.showTimePicker({
+    initialHour  : 17,
+    initialMinute: 30,
+    is24HoursMode: true,
+    title        : "Seleccione hora",
+    theme        : "holo_light",
+    onTimeSet    : function(nHours, nMinutes) {
+        let h = ("0" + nHours).slice(-2);
+        let m = ("0" + nMinutes).slice(-2);
+        self.MAP_HORA = h + ":" + m;
+        ui.refresh("MAP_HORA");
+    }
+});
+
+// Time Picker que escribe directamente en un campo
+ui.showTimePicker({
+    targetProperty: "MAP_HORA"
+});
+```
+

package/skills/xone-development/references/resumen-js-datos-dispositivo.md

@@ -0,0 +1,80 @@
+# Resumen por capa: JavaScript, datos y dispositivo
+
+> Referencia de `xone-development`. Sale del `SKILL.md` para que las reglas
+> duras quepan en una lectura por omisión (100 líneas).
+
+## JavaScript
+
+JavaScript ejecutado en bloques `<script>` de los `.xne` y en `functions.js`. No es JavaScript de navegador ni de Node: no hay módulos (`require`/`import`) y el código compartido es global. Los LLMs inventan sistemáticamente `self.lock()`, `ui.startChronometer()` y variantes de `setCircularReveal` que no existen.
+
+**Objetos globales.** `self` (DataObject actual, alias `dataobject`) · `selfDataColl` (su colección, alias `datacollection`) · `ui` · `appData` (alias `appdata`) · `err` (alias `error`) · `user`.
+
+Singletons de acceso directo, **sin `new`**: `$http`, `crypto`, `clipboard`, `deviceInfo`, `systemSettings`, `packageManager`, `biometricsManager`, `fingerprintManager`, `bleManager`, `sensorManager`, `paymentManager`, `pushMessage`, `appBroadcastManager`, `replica`, `live`, `smsService`, `serial`, `bluetoothSerial`, `bleSerial`, `ml`, `ai`.
+
+Objetos que se crean con `new` (o `createObject`): `FileManager`, `GpsTools`, `SqlManager`, `IniParser`, `EncodingUtils`, `AndroidIntent`, `DeviceManager`, `WifiManager`, `BluetoothSerialPort`, `OAuth2`, `Worker`, `Animation`, `Socket`, `WebSocket`, `DebugTools`, `IrManager`, `SoundManager`, `VibrationManager`, `WearableConnection`, `AccountManager`, `XOneNFC`, `ImageDrawing`, `BarcodeGenerator`, `XOnePrinter`, `XOnePDF`, `XOneOCR`, `XOneSigner` y los demás de la lista canónica.
+
+**Acceso a datos.** `self.CAMPO`, `self["CAMPO"]` y `self.getValue("CAMPO")` son válidos. **`self("CAMPO")` no existe**: la notación de `self` como función no es parte del motor.
+
+**Controles.** `getControl(name, [dataObject])` es una **función nativa global** del motor (Rhino y V8), no un método de `ui`. Con un solo argumento usa la última ventana visible; con `dataObject`, la ventana asociada a ese objeto. Lanza error si el nombre está vacío, si el control no existe en la ventana destino, si no hay ventana o si el `dataObject` no es válido. Si el proyecto define su propia `function getControl(...)`, esa sombrea a la nativa en su ámbito local.
+
+Los métodos específicos (`getValue`/`setValue`/`setMin`/`setMax`/`setStepSize` de un stepper, `getOtpValue`/`clearOtp`/`focusOtp` de un OTP, `startChronometer`/`stopChronometer`) son métodos **del control**, no de `ui`.
+
+**Patrones críticos.** Modifica colecciones dentro de `unlock()` y devuelve el estado con `lock()` en `finally`. `lock()` activa el modo solo lectura: con la bandera activa, `clear()` y `loadAll()` son no-op. Las colecciones nacen desbloqueadas, pero el convenio es dejarlas bloqueadas tras operar para que código posterior no las mute por accidente.
+
+- `lock()`/`unlock()` son métodos de la **colección**, nunca de `self`. Para bloquear la de un contents: `self.getContents("X").unlock()`.
+- Navega con `startBrowse()` y `endBrowse()` en `finally`. Para contents: `getContents(nombre)` → `unlock` → `createObject`/`addItem` → `lock` → `saveAll`. Cierra siempre cursores y conexiones SQL. Un `WaitDialog` abierto va dentro de `try/finally`.
+- En callbacks asíncronos (`$http`, WebSocket, GPS) guarda el contexto **antes** de la llamada: `var miSelf = self;`.
+- Para crear objetos, el patrón preferido es `new NombreColeccion({ PROP: valor })` (el parámetro es opcional). `coll.createObject()` queda para contents anidados —vincula al padre— o cuando el nombre de la colección es dinámico.
+
+**APIs web y sus equivalentes.**
+
+| API web | Equivalente XOne |
+|---|---|
+| `document.getElementById("X")` | `ui.getView(self)["X"]` o `getControl("X")` |
+| `window.location` / `window.history` | `ui.openEditView("Coll")`, `ui.getView(self).exit()` |
+| `localStorage` | `appData.getGlobalMacro("##X##")` / `setGlobalMacro` |
+| `sessionStorage` | `coll.setVariable`/`getVariable` o variables de empresa |
+| `new XMLHttpRequest()` | `$http.get(url, request, success, error)` |
+| `alert` / `confirm` / `prompt` | `ui.msgBox(msg, título, 0)` o `ui.showToast(msg)` |
+| `navigator.geolocation.getCurrentPosition` | `ui.startGps({nodeName: "callbackgps"})` |
+| `require()` / `import` | `<include file="..."/>` o `<script src="..."/>` en `<app>`; dinámico solo con `appData.loadIncludeFile(...)` |
+
+## Datos e integración
+
+**Modelo local.** La BD es `gestion.db`, normalmente bajo `bd/`, y las tablas suelen llevar prefijo `gen_` en minúsculas. Usa siempre `##PREF##`, nunca el prefijo literal. Cada registro replicable tiene `ROWID` como GUID hexadecimal de 32 caracteres sin guiones, declarado `type="T" fieldsize="32"`. Las colecciones con `objname`/`updateobj` generan tabla; si falta, regenera con `python3 -m xone_db_generator mi_proyecto --overwrite`.
+
+Macros habituales: `##PREF##`, `##ENTID##`, `##USERID##`, `##NOW##`, `##NOW_DATE##`, `##NOW_TIME##`, `##FLD_CAMPO##`. Guarda y restaura filtros con `try/finally` y limpia la colección antes de recargar.
+
+**Seguridad.**
+
+- Parametriza SQL: `sqlManager.doRawQuery("… WHERE ID=?", id)`. Nunca concatenes entrada de usuario. Si un filtro exige texto, escapa `'` como `''`; valida los numéricos antes de concatenar.
+- Cierra cursor y conexión en `finally`.
+- HTTPS siempre, con `allowUnsafeCertificates: false` en producción. Pinning con `enablePinning`/`allowedRootCas`; mTLS con `privateKey`/`certificateChain`.
+- No hardcodees ni registres credenciales. Cifra los tokens antes de guardarlos en macros globales y límpialos al cerrar sesión.
+- Valida obligatorios, longitud, rangos y formato antes de `save()`: un obligatorio vacío produce `-8100`.
+
+**Integración y réplica.** `$http` devuelve respuestas string y futures cancelables: parsea con `try/catch`, preserva `self` antes del callback y cancela la búsqueda anterior antes de lanzar otra. OAuth2 se usa con `new OAuth2()`. `replica.processReplicatorQueue` sincroniza por `ROWID`; la configuración programada vive en el evento `maintenance` de `Empresas`. El error `-11888` con `##EXIT##` cierra la pantalla y con `##EXITAPP##` cierra la aplicación.
+
+Para almacenamiento clave-valor, el equivalente de `localStorage` es `appData.setGlobalMacro`/`getGlobalMacro`; para datos de sesión, variables de colección (`setVariable`/`getVariable`).
+
+Los **eventos** implicados en la sincronización y el provisionamiento (`maintenance`, `sys-message` con sus códigos detallados, eventos de réplica) están documentados en [eventos de sistema, login y personalizados](references/xml-ui/eventos-sistema-login-y-personalizados.md), porque se declaran en el XML.
+
+Para probar integraciones sin backend, usa `mock/http.json` con `xone-simulator` (skill `xone-review`).
+
+## Dispositivo
+
+`xone-simulator` reproduce muchas capacidades con `mock/device.json` (skill `xone-review`).
+
+- Pide y comprueba permisos antes de GPS, cámara, micrófono o biometría. Los permisos se solicitan con `systemSettings.requestPermissions`, que devuelve un future. En el simulador se conceden automáticamente.
+- Declara los permisos que use la app en el nodo `<permissions>`: `location-foreground`, `location-background`, `camera`, `notifications`, `contacts`…
+- GPS: `ui.startGps()` antes de leer la colección de GPS; recórrela con `startBrowse`/`endBrowse`, comprueba `STATUS == 1` y que `LONGITUD` no esté vacío. `ui.checkGpsStatus()` devuelve `0` sin hardware, `1` solo GPS, `2` solo redes, `3` ninguno y `4` GPS y redes.
+- La colección de GPS (`GPSColl`/`GpsCollection`) **la declara el proyecto** con el connector GPS: no es built-in de XOne.
+- En callbacks de cámara, GPS y escáner conserva `self` antes de la operación y refresca solo los campos modificados.
+- Cierra Bluetooth y WebSocket al terminar. Prefiere `ui.executeActionAfterDelay()` (segundos) a una espera bloqueante.
+- `biometricsManager` es el singleton actual; `fingerprintManager` es legacy.
+- La firma se hace con `<prop type="DR">` (`stroke-color`, `stroke-width`, `apply-format-to-file`, `ui.saveDrawing`, `ui.clearDrawing`). `type="IMG" readonly="false"` es la forma **obsoleta**.
+- En archivos, comprueba `fileExists(...) === 0`; `saveFile(..., false)` sobrescribe.
+
+Del registro de GPS se leen `LATITUD`, `LONGITUD`, `ALTITUD`, `VELOCIDAD`, `RUMBO`, `FGPS`, `HGPS`, `STATUS`, `SATELITES`, `FUENTE`, `PRECISION` y el campo `FAKE`. Para cálculos hay `GpsTools` (`distanceBetweenCoordinates`, `getPositionFromAddress`, encode/decode, `simplifyPolyline`, `addExifLocationToFile`, `routeTo`).
+
+Los métodos de los controles de cámara, vídeo, dibujo y escáner están en [métodos de los controles](references/javascript/metodos-de-los-controles.md). Los atributos XML de esos props, en [atributos-prop.md](references/xml-ui/atributos-prop.md).

package/skills/xone-development/references/resumen-xml-y-css.md

@@ -0,0 +1,74 @@
+# Resumen por capa: XML y CSS
+
+> Referencia de `xone-development`. Sale del `SKILL.md` para que las reglas
+> duras quepan en una lectura por omisión (100 líneas).
+
+## Estructura XML
+
+Capa declarativa de XOne: ficheros `.xne`, jerarquía `coll > group > frame > prop`, `contents`, macros, eventos y permisos. Antes de proponer código, inspecciona los `.xne` y el CSS del proyecto para respetar sus convenciones.
+
+- Jerarquía: `coll > group > frame > prop`. Un `<prop>` vive dentro de un `<group>` o de un `<frame>`.
+- Una coll de datos lleva `sql`, `objname` y `updateobj`, y usa `##PREF##` como prefijo de tabla: `sql="SELECT ID, NOMBRE FROM ##PREF##Clientes"`.
+- Una pantalla sin datos (menú, login) usa `special="true"` y **no** lleva `sql`. Son excluyentes.
+- `<prop>` tiene dos atributos obligatorios: `name` y `type`.
+- `notab="true"` cuando solo hay un grupo visible.
+- El splash es un **fichero estático en la raíz** (`splash.png`/`.jpg`/`.gif`/`.webp`/`.apng`/`.mp4`/`.3gp`) que carga el framework. No es una `<coll>`, no es `EntradaApp` (pantalla post-login), y no es `load-imgbk` del `<app>` (fondo del EditView).
+
+**Combo y selector.** Un combo **no tiene tipo propio**: son dos props vinculados, uno oculto con el ID y otro visible con la descripción. Para valores fijos sin tabla, `mapcol-values` en el prop oculto. `mapcol` debe apuntar a una coll existente, y `mapfld`/`linkedfield` a campos reales de esa coll: `xone-simulator` lo valida.
+
+**Contents y listas.**
+
+- El `name` del contents lleva prefijo `@`; sin él no vincula.
+- `src` es obligatorio y apunta a una coll existente. `filter` y `sort` son opcionales.
+- Filtros dinámicos por el objeto padre con `##FLD_CAMPO##`, p. ej. `filter="IDPADRE=##FLD_IDPADRE##"`.
+- Un mapa es `type="Z" viewmode="mapview"` vinculado a un `<contents>`, no un tipo inventado.
+
+**Layout.** Los elementos son `newline="true"` por defecto y se apilan. Para ponerlos en la misma fila, `newline="false"` va en el **segundo y siguientes**; el primero de la fila nunca lo lleva. Si el primer elemento de un `<frame>` lleva `newline="false"`, el frame entero puede no montarse y sus controles desaparecen de la pantalla. Dimensiones en `p` o `%`, nunca `px`/`em`/`rem`.
+
+**Macros.** `##PREF##` prefijo de tablas · `##FLD_CAMPO##` valor del campo del objeto padre en un contents · macros del sistema como `##NOW_TIME##`, `##USERID##`, `##DEVICE_OS##`, `##DEVICE_TYPE##`, `##CURRENT_ORIENTATION##`, `##FRAME_VERSION_CODE##`.
+
+Una macro de colección debe declararse en el XML antes de usarla: `<macro name="##NOMBRE##" value="..." default="true" />` como hijo directo de `<coll>`, al mismo nivel que los `<group>`. Sin esa declaración, `setMacro` no inyecta nada en el SQL. La API es `setMacro`/`getMacro`; `coll.macro(...)` no existe.
+
+## CSS
+
+Sistema de estilos propietario, con sintaxis parecida a CSS web pero atributos propios. Antes de editar, lee el `default.css` del proyecto y respeta sus convenciones de nombres de clase.
+
+**Archivos.** `default.css` en la raíz del proyecto es obligatorio y es el único que se declara en `app.xml`: `<style url="default.css" encoding="UTF-8" />`. Las variantes se cargan automáticamente por convención de nombre.
+
+Si el atributo `compatibility-mode` del nodo `<app>` vale `true`, **el CSS se ignora por completo** — compruébalo antes de diagnosticar cualquier estilo que «no se aplica».
+
+> **El TEMA OSCURO está sin definir, y hasta que se defina no se genera.** El corpus escribe el
+> nombre del fichero de variante de dos formas incompatibles —con guion bajo
+> (`default_night.css`) y con punto (`default.night.css`)—, y en los proyectos reales de
+> referencia no existe ninguno de los dos: lo que hay son variantes con guion normal
+> (`default-ios.css`, `default-colors.css`). Como el framework carga estas variantes **por
+> convención de nombre**, un nombre equivocado no da error: el fichero no se carga y la app
+> se ve en claro sin que nada lo diga. **Decisión del proyecto (2026-08-29): no proponer ni
+> generar el fichero de tema oscuro hasta fijar su nombre.** Los ejemplos de tema que quedan
+> en las referencias de CSS ilustran la CASCADA, no el nombre — no los copies como ruta.
+
+**Cascada.** De menor a mayor prioridad: `default.css` → plataforma → orientación → tema → condiciones combinadas → **atributos inline en XML** (máxima prioridad). Lo más específico gana atributo por atributo, no bloque por bloque.
+
+**Selectores.** Solo estos: `coll`, `prop`, `prop:TYPE` (`prop:T`, `prop:N`, `prop:B`, `prop:NC`, `prop:Z`, `prop:IMG`, `prop:D`…), `group`, `frame` y `.clase`. Las clases se asignan con `class="..."` en el XML.
+
+**Unidades.**
+
+- `p` para dimensiones absolutas, `%` relativo al contenedor.
+- Sin unidad: `fontsize`, `border-corner-radius`, `border-width`, `labelwidth`, `lines`, `visible`, `gallery-columns`, `img-width`, `img-height`.
+- Prohibidas: `px`, `em`, `rem`, `vw`, `vh`, `vmin`, `vmax`.
+
+**Colores.** `#RRGGBB` o ARGB `#AARRGGBB`. **El alpha va primero**, al contrario que el `#RRGGBBAA` de CSS web.
+
+**Herencia.** Dos mecanismos equivalentes: el atributo `extends: .claseBase;` y la at-rule `@extend selector;`. Diferencia relevante: `@extend` detecta ciclos en tiempo de parseo (auto-referencia, 2 vías y N vías) y admite referencias adelantadas; `extends:` no detecta ciclos automáticamente. En un proyecto que ya usa `extends:`, mantén `extends:` por consistencia.
+
+**Funciones del parser.**
+
+**Sí soportadas:** comentarios `/* */` y `//`; `@import "ruta";` (solo al inicio del archivo); variables CSS en `:root` o locales de bloque, con `var(--nombre)` y `var(--nombre, fallback)`; `calc()` con `+ - * /`, paréntesis y `-` unario sobre números puros; `!important`; `!default`; selectores múltiples `a, b, c { }`.
+
+**No soportadas:** `min()`, `max()`, `clamp()`, `@media`, pseudo-clases (`:hover`, `:focus`, `:active`, `:nth-child`), pseudo-elementos (`::before`, `::after`), selectores de atributo (`[data-attr]`), combinadores (`>`, `+`, `~`, descendiente), `transition`, `transform`, Flexbox, CSS Grid, `box-shadow`, `text-shadow` y gradientes.
+
+Para sombras usa `elevation` y `shadow-color`. No hay abreviados `margin` ni `padding`: usa `tmargin`, `bmargin`, `lmargin`, `rmargin` y sus equivalentes `*padding`.
+
+**Estilos dinámicos.** No existe selector condicional puro. Dos vías: tokens `##FLD_CAMPO##` en el valor (funcionan en CSS y en atributos inline XML) y cambio de clase desde JavaScript en tiempo de ejecución.
+
+Si un estilo no se aplica, empieza por `compatibility-mode`; el resto de síntomas está en la skill `xone-debugging`.

package/skills/xone-development/references/tipos-de-prop.md

@@ -0,0 +1,28 @@
+# Tipos de `prop` válidos
+
+> Referencia de `xone-development`. Sale del `SKILL.md` para que las reglas
+> duras quepan en una lectura por omisión (100 líneas).
+
+## Tipos de prop válidos
+
+| Tipo | Descripción |
+|---|---|
+| `T` | Texto editable |
+| `TN` / `TN2`…`TN6` | Texto numérico; el sufijo son los decimales visibles |
+| `L` | Etiqueta de solo lectura. Sin `title`, muestra el valor del campo |
+| `TL` | Alias legacy de `L` |
+| `THTML` | Texto con formato HTML |
+| `N` / `N2`…`N6` | Número; el sufijo son los decimales visibles |
+| `D` / `DT` / `TT` | Fecha / fecha y hora / solo hora |
+| `B` | Botón |
+| `NC` | Checkbox, toggle, radio o switch |
+| `X` | Password enmascarado |
+| `IMG` / `PH` | Imagen referenciada / foto capturable |
+| `VD` | Vídeo o escáner QR/barcode |
+| `DR` | Dibujo o firma digital |
+| `Z` | Contenedor de lista embebida |
+| `WEB` | WebView |
+| `AT` | Adjunto |
+| `O` | Sub-objeto JavaScript, no persiste |
+
+Los combos **no tienen tipo propio**: se hacen con `type="T"` (o `type="N"`) más `mapcol` y `mapfld`. No existen `type="C"`, `"M"`, `"A"`, `"F"`, `"S"`, `"P"`, `"E"`, `"R"`, `"H"`, `"W"`, `"CAM"`, `"ARRAY"`, `"STRING"`, `"N1"` ni `"BT"`.