xonecode 0.1.0

package/skills/xone-development/references/javascript/motor-js-y-contexto-de-ejecucion.md

@@ -0,0 +1,319 @@
+# XOne JavaScript — Motor, contexto de ejecución y escape XML
+
+> Fuente: `xone/v2/xone-help-docs/topics/03a-js-self.md` §1. Referencia de la skill; el índice está en [../../SKILL.md](../../SKILL.md).
+
+Contenido: §1 motor JS embebido, objetos globales disponibles, cómo se ejecuta el JS desde eventos XML, diferencias con JS web, archivos JS del proyecto, alcance y persistencia de variables, buenas prácticas y escape XML/CDATA dentro de .xne
+
+---
+
+## 1. Introduccion al JavaScript de XOne
+
+### 1.1 Motor JS Embebido
+
+El JavaScript de XOne **NO se ejecuta en un navegador web ni en Node.js**. Se ejecuta dentro de un motor JavaScript nativo embebido en la aplicación móvil (Rhino/V8 según la plataforma). Esto implica limitaciones fundamentales que todo desarrollador debe conocer.
+
+Los scripts se colocan dentro de nodos `<script>` en archivos `.xne`, vinculados a eventos del ciclo de vida de la pantalla:
+
+```xml
+<coll name="MiPantalla" title="Mi Pantalla" class="xnCollBase">
+
+    <!-- Se ejecuta UNA sola vez al crear el objeto (primera apertura) -->
+    <create>
+        <action name="runscript">
+            <script language="javascript">
+                inicializar();
+            </script>
+        </action>
+    </create>
+
+    <!-- Al abrir el objeto para edicion — evento principal para inicializar la pantalla -->
+    <before-edit>
+        <action name="runscript">
+            <script language="javascript">
+                cargarDatos();
+            </script>
+        </action>
+    </before-edit>
+
+    <!-- Al pulsar el botón atrás -->
+    <onback>
+        <action name="runscript">
+            <script language="javascript">
+                manejarAtras();
+            </script>
+        </action>
+    </onback>
+
+</coll>
+```
+
+> **Crítico**: `<load>` NO se ejecuta al mostrar la pantalla — se dispara **por cada DataObject** al cargarse desde la BD: tanto al recorrer la coleccion (`startBrowse()`/`loadAll()`) como al hidratar items de un `<contents>` o cargas individuales. **NO se recomienda usarlo** porque el rendimiento puede verse seriamente afectado (se ejecuta una vez por item cargado). Para inicializar una pantalla usar `<before-edit>` (al abrir para editar) o `<create>` (primera apertura).
+
+> **Referencia cruzada:** Para la estructura completa de eventos en nodos XML, consultar el tópico 02 - Estructura XML. Para los estilos CSS aplicables a controles manipulados desde JS, ver el tópico 04 - Estilos CSS.
+
+### 1.2 Objetos Globales Disponibles
+
+XOne expone los siguientes objetos globales accesibles desde cualquier script:
+
+| Objeto | Descripción |
+|--------|-------------|
+| `ui` | Interfaz de usuario: dialogos, toasts, navegación, GPS, camara |
+| `appData` | Datos de la aplicación: colecciones, autenticación, macros, rutas |
+| `self` | Objeto de datos actual (DataObject) en el contexto del script |
+| `crypto` | Funciones criptograficas: hashing, cifrado AES, firma digital, encoding |
+| `$http` | Cliente HTTP asíncrono: GET, POST, PUT, DELETE, PATCH, download |
+| `console` | Logging WHATWG completo: `console.{log,info,debug,warn,error,trace,assert,group,groupCollapsed,groupEnd,time,timeLog,timeEnd,count,countReset,dir,dirxml,clear,table}` con formato `%s/%d/%j/...` |
+| `biometricsManager` | Autenticación biometrica (huella, face) y firma biometrica |
+| `fingerprintManager` | Huella dactilar (API legacy, preferir `biometricsManager`) |
+| `bluetoothSerial` | Comunicación por puerto serie Bluetooth |
+| `replica` | Control de sincronización/replica con servidor |
+| `systemSettings` | Singleton global: brillo, permisos, memoria, MDM, batería, rutas, Intune |
+| `deviceInfo` | Singleton global: batería, red móvil, trafico de bytes |
+
+### 1.3 Como se Ejecuta el JS: Eventos XML a Acciones a Script
+
+El flujo de ejecución en XOne sigue este patron:
+
+```
+1. Usuario interactua con la UI (pulsa boton, cambia campo, etc.)
+         |
+2. El framework detecta el evento asociado al nodo XML
+         |
+3. Se ejecuta el bloque <script> vinculado al evento
+         |
+4. El script accede a objetos globales (self, ui, appData)
+         |
+5. Las acciones del script modifican datos y/o la interfaz
+```
+
+**Eventos disponibles en nodos XML:**
+
+| Evento | Momento de Ejecución | Ubicación |
+|--------|---------------------|-----------|
+| `<create>` | Una sola vez al crear el objeto (primera apertura) | Dentro de `<coll>` |
+| `<before-edit>` | Al abrir un objeto para edición — **el más usado para inicializar la pantalla** | Dentro de `<coll>` |
+| `<after-edit>` | Después de entrar en modo edición, con la UI ya montada | Dentro de `<coll>` |
+| `<load>` | Se dispara **por cada DataObject** al cargarse desde la BD (startBrowse/loadAll/`<contents>`/cargas individuales). **NO es evento de pantalla** y **NO recomendado** por impacto en rendimiento | Dentro de `<coll>` |
+| `<onchange>` | Cuando cambia el valor de una propiedad | Dentro de `<coll>`, nodo `<field>` |
+| `<selecteditem>` | Cuando se selecciona un item en una lista | Dentro de `<coll>` |
+| `<onlongpressitem>` | Pulsacion larga en un item de lista | Dentro de `<coll>` |
+| `<onback>` | Cuando el usuario pulsa el botón atrás | Dentro de `<coll>` |
+| `<miNodo>` | Nodo custom invocado con `ExecuteNode(miNodo())` o `method="executenode(miNodo)"` | Dentro de `<coll>` |
+
+### 1.4 Diferencias con JS Web
+
+**APIs que NO están disponibles en XOne:**
+
+| API Web | Alternativa XOne |
+|---------|------------------|
+| `document`, `window` (DOM) | `ui.getView(self)` para acceder a controles |
+| `localStorage` / `sessionStorage` | `appData.getGlobalMacro()` / `appData.setGlobalMacro()` |
+| `XMLHttpRequest` | `$http.get()`, `$http.post()`, etc. (también existe `fetch` custom). |
+| `navigator.geolocation` | `ui.startGps()` / `ui.checkGpsStatus()` |
+| `alert()` / `confirm()` / `prompt()` | `ui.msgBox()` / `ui.showToast()` |
+| `require()` / `import` | No hay sistema de módulos; todo va en `functions.js` |
+| `async` / `await` | Callbacks o `Promise` (sí soportado vía implementación custom). |
+
+**Sintaxis ES6+ NO soportada:**
+
+| Sintaxis | Estado | Alternativa |
+|----------|--------|-------------|
+| Template literals `` `${var}` `` | Parse error (*illegal character*) sobre el backtick | Concatenación con `+` |
+| `async` / `await` | Parse error (reservadas) | Callbacks o `Promise` |
+| Spread/rest `...args`, default params `function f(x=1)` | Parse error | `arguments` / chequeo `=== undefined` |
+| Computed keys en object literals `{[k]: v}` | Parse error (sí en class body) | `var o = {}; o[k] = v;` |
+| Optional chaining `?.` / nullish coalescing `??` | Parse error | Chequeos manuales |
+| Private fields `#name` en class | Parse error (requiere runtime) | Convención `_name` |
+| Static blocks `static { ... }` en class | Parse error | Sentencias `ClassName.x = ...;` tras la clase |
+
+**SÍ funciona:** `let`, `const`, arrow functions `() => {}`, destructuring (`var {a, b} = o`), `for...of` sobre arrays/strings, generadores con `yield` (runtime SpiderMonkey legacy — usar `try { while (true) v = iter.next(); } catch (e) {}`), Symbol, typed arrays, **`class` ES6+ con `extends`/`super`/`static`/getters/setters/computed keys/field declarations/generator methods (`*method()`)**, **`Promise` ES2024 completo** (`.then`/`.catch`/`.finally`/`Promise.all`/`allSettled`/`race`/`any`/`withResolvers`), `fetch`, `setTimeout`/`setInterval`, `URL`, `AbortController`, `TextEncoder`/`TextDecoder`, `console.{log,info,warn,error,debug,trace,...}`, `performance.now()`, métodos modernos de `String` (`padStart`, `replaceAll`, `at`, `matchAll`...) y de `Array` (`map`, `filter`, `reduce`, `find`...), `JSON`. Detalle completo en 01-xone-fundamentals.md §6.7.
+
+### 1.5 Archivos JavaScript en el Proyecto
+
+```
+MiProyecto/
+  functions.js          <- Funciones globales (siempre presente, carga automatica)
+  scripts/              <- Scripts adicionales organizados (opcional)
+    ubicacion.js
+    viajes.js
+    mensajeria.js
+```
+
+El archivo `functions.js` es el punto de entrada global. Se carga automáticamente al iniciar la aplicación y sus funciones están disponibles en todos los scripts `.xne` del proyecto. Para proyectos grandes, se recomienda organizar la lógica en archivos adicionales dentro de `scripts/` y cargarlos con `appData.loadIncludeFile()`.
+
+### 1.6 Alcance de Variables
+
+```javascript
+// Variables globales: accesibles desde cualquier script del proyecto
+// Se definen en functions.js
+var MI_CONSTANTE = "valor";
+var ESTADOS = { ACTIVO: 1, INACTIVO: 0 };
+
+// Variables locales: solo dentro de la funcion
+function miFuncion() {
+    let variableLocal = "solo existe aquí";
+}
+
+// IMPORTANTE: 'self' puede cambiar de contexto en callbacks asincronos
+// Guardar referencia ANTES de cualquier operación asincrona
+function operacionAsincrona() {
+    let contexto = self;  // Guardar referencia
+    $http.get(url, request,
+        function(sData) {
+            // Aquí 'self' puede NO ser el mismo objeto
+            // Usar 'contexto' en su lugar
+            contexto.MAP_RESULTADO = sData;
+        },
+        function(nError, sDesc) {
+            ui.showToast("Error: " + sDesc);
+        }
+    );
+}
+```
+
+### 1.7 Ambitos de ejecución y persistencia de variables
+
+Entender en que **ambito** se ejecuta cada script es fundamental para usar correctamente `This` / `self`, `ThisDataColl` y las variables globales.
+
+**Ambitos posibles:**
+
+| Ambito | Cuando | `This` / `self` | `ThisDataColl` |
+| --- | --- | --- | --- |
+| **Objeto** | Acción disparada desde un objeto (p.ej. `<create>`, `<onchange>` de un prop) | El objeto en cuestion | `Nothing` / `null` |
+| **Coleccion** | Acción en nodo `<coll-action>` (p.ej. `<onlogon>`) | `Nothing` / `null` | La coleccion que dispara el script |
+| **Local** | Dentro de una `function()` | — | — |
+
+**Reglas de visibilidad:**
+
+- `appData` es siempre visible desde cualquier ambito.
+- `self` / `This` y `ThisDataColl` son visibles durante la ejecución del script y de todas las funciones que se llamen desde el. **No** son visibles dentro de acciones anidadas (p.ej. un `Save` que dispara otro script tiene su propio ambito).
+- `user` es visible cuando hay usuario logueado.
+- Una variable declarada en el bloque principal del script es visible para todas las funciones llamadas desde ese mismo script, pero **no** para acciones anidadas.
+
+**Intercambio de datos entre scripts anidados:** como las variables locales no sobreviven al anidamiento, hay que usar mecanismos persistentes:
+
+- Propiedades del objeto (`self.MAP_FLAG = 1`)
+- Variables de la coleccion (`coll.setVariable(...)`)
+- Colecciones globales (`appData.getCollection("...")`)
+- Macros globales (`appData.setGlobalMacro("##KEY##", valor)` / `appData.getGlobalMacro("##KEY##")`)
+- Objeto `user` (persiste durante la sesión)
+
+### 1.8 Buenas prácticas al programar en XOne
+
+Patrones que evitan bugs sutiles y problemas de rendimiento:
+
+**1. No uses `LoadAll()` sin motivo.** Cargar todos los objetos en memoria es caro. Si solo necesitas recorrer una coleccion, usa `startBrowse()` / `endBrowse()`. Para contar, `startBrowse(true)`.
+
+**2. No filtres colecciones globales sin restaurar.** Si haces `coll.setFilter(...)` sobre una coleccion global y no la restauras, afectara a todas las vistas que usen esa coleccion.
+
+```javascript
+// MAL: filtra la coleccion global y afecta la UI
+let coll = appData.getCollection("Clientes");
+coll.setFilter("CODIGO=1");
+coll.startBrowse();
+// ... al salir, la lista de clientes solo muestra el cliente 1
+
+// BIEN: trabajar sobre una copia
+let coll = appData.getCollection("Clientes").createClone();
+coll.setFilter("CODIGO=1");
+// ... usar coll ...
+coll = null;  // liberar
+```
+
+**3. Anula las referencias en orden inverso.** Si creas una coleccion y sacas objetos de ella, anula primero los objetos y luego la coleccion. Nunca al reves (la coleccion puede destruir los objetos antes).
+
+**4. Guarda una marca para evitar reentradas.** Si un `Save` puede dispararse desde dentro de un `<onchange>` que a su vez puede llamarse otra vez al modificar el mismo campo, usa una propiedad centinela:
+
+```xml
+<onchange field="MAP_IMPORTE">
+    <action name="runscript">
+        <script language="javascript">
+            if (self.MAP_SAVING == 0) {
+                self.MAP_SAVING = 1;
+                // ... calcular cosas ...
+                self.save();        // dispara este mismo evento
+                self.MAP_SAVING = 0;
+            }
+        </script>
+    </action>
+</onchange>
+```
+
+**5. No modifiques `CurrentItem` con cursores abiertos.** Algunas bases de datos no permiten modificar una tabla con cursores activos. Si tienes que modificar muchos objetos, mejor hazlo con `executeSql` o carga los IDs, cierra el cursor, y modifica uno a uno.
+
+**6. En callbacks asíncronos, captura `self` antes.** Ver sección 1.6.
+
+---
+
+### 1.9 JavaScript dentro de XNE: escape XML o CDATA
+
+Cuando el JavaScript va embebido dentro de un fichero `.xne` (en `<script language="javascript">` o en atributos como `onclick`, `disablevisible`, `value`, etc.), el bloque JS forma parte del XML y **debe respetar las reglas de XML**.
+
+**Regla preferida — JS no trivial debe vivir fuera del `.xne`:** declarar una función en `functions.js` (o un fichero `.js` incluido) y llamarla desde el XML con `miFuncion();`. Así el JS se escribe normal (sin entidades, sin CDATA) y el XML solo invoca. Es lo más mantenible, lo más legible y evita por completo el problema del escape.
+
+Cuando aun así necesitas escribir JS inline (snippets cortos), hay dos formas válidas de evitar que los caracteres especiales rompan el parseo XML:
+
+1. **Entidades XML** dentro del JavaScript — funciona en cualquier sitio (nodo y atributo).
+2. **`<![CDATA[...]]>` envolviendo el bloque** — funciona solo dentro de nodos `<script>`. NO es válido dentro de atributos XML (`onclick="..."`, `disablevisible="..."`).
+
+Las dos son equivalentes en cuanto al resultado: el motor JS recibe el mismo código.
+
+**Tabla de entidades:**
+
+| Carácter JS | Entidad XML | Cuando aparece |
+|-------------|-------------|----------------|
+| `&`         | `&amp;`     | Operador `&&` se escribe `&amp;&amp;` |
+| `<`         | `&lt;`      | Comparación `<` se escribe `&lt;` |
+| `>`         | `&gt;`      | Comparación `>` se escribe `&gt;` |
+| `"`         | `&quot;`    | Solo si el JS está dentro de un atributo XML con delimitador `"` |
+| `'`         | `&apos;`    | Solo si el JS está dentro de un atributo XML con delimitador `'` |
+
+**Ejemplo comparativo — el mismo JS escrito de las dos formas:**
+
+(fence sin lenguaje para que las entidades se rendericen literales y se vean como tendrías que teclearlas en el `.xne`)
+
+```
+<!-- OPCIÓN A: entidades XML dentro del JS (válido en nodo o atributo) -->
+<before-edit>
+    <action name="runscript">
+        <script language="javascript">
+            if (a &gt; 0 &amp;&amp; b &lt; 10) {
+                self.MAP_RES = a + b;
+            }
+        </script>
+    </action>
+</before-edit>
+
+<!-- OPCIÓN B: envolver en CDATA (solo válido en nodo <script>) -->
+<before-edit>
+    <action name="runscript">
+        <script language="javascript"><![CDATA[
+            if (a > 0 && b < 10) {
+                self.MAP_RES = a + b;
+            }
+        ]]></script>
+    </action>
+</before-edit>
+```
+
+**JS dentro de un atributo XML** (CDATA no aplica — solo entidades):
+
+```
+<!-- Atributo onclick (delimitador "): comillas internas con &quot; o usa '.
+     onclick es un script JS inline en modo estricto: cada sentencia debe acabar en ';'. -->
+<prop name="MAP_BTN" type="B" title="Buscar"
+      onclick="if (self.MAP_TEXTO &amp;&amp; self.MAP_TEXTO.length &gt; 0) { hacerBusqueda(self.MAP_TEXTO); };" />
+
+<!-- disablevisible con comparaciones también usa entidades -->
+<prop name="MAP_AVISO" type="L"
+      disablevisible="MAP_TOTAL &gt;= 100 &amp;&amp; MAP_ACTIVO=1" />
+```
+
+**Regla de oro:**
+
+| Donde vive el JS | Cómo se escribe |
+|-------------------|-----------------|
+| Fichero `.js` separado (`functions.js`, `scripts/*.js`) — **forma preferida para JS no trivial** | JavaScript puro, sin entidades, sin CDATA. |
+| Atributo XML (`onclick=`/`disablevisible=`/…) | Con entidades XML (`&amp;`, `&lt;`, `&gt;`, etc.). CDATA no es válido dentro de atributos. |
+| Nodo `<script>` dentro de un `.xne` (snippets cortos) | Entidades XML o `<![CDATA[…]]>`. Ambas formas funcionan. |
+

package/skills/xone-development/references/javascript/objeto-ai-llm-en-dispositivo.md

@@ -0,0 +1,358 @@
+# XOne JavaScript — Objeto ai: LLM generativo en el dispositivo
+
+> Fuente: `xone/v2/xone-help-docs/topics/08-objeto-ai.md` §1–§13. Referencia de la skill; el índice está en [../../SKILL.md](../../SKILL.md).
+
+Contenido: §1 flujo típico · §2 downloadModel · §3 canLoadModel · §4 getModelInfo · §5 loadModel/unload · §6 generate · §7 chat con streaming · §8 cancelar y reiniciar · §9 herramientas y function calling · §10 loadSkills · §11 formatos de imagen y audio · §12 parámetros recomendados Gemma 4 y decodificación especulativa · §13 buenas prácticas y problemas comunes
+
+---
+
+## 1. Flujo típico
+
+```js
+// 1) Descargar el modelo (una vez; queda guardado en el dispositivo)
+ai.downloadModel({
+    repository: "litert-community/gemma-4-E2B-it-litert-lm",
+    file: "gemma-4-E2B-it.litertlm",
+    onProgress: function (percent) { ui.showToast("Descargando: " + percent + "%"); },
+    onComplete: function (file) { cargarModelo(file); },
+    onError: function (msg) { ui.msgBox(msg); }
+});
+
+function cargarModelo(file) {
+    // 2) Cargar en memoria
+    ai.loadModel({ path: file, backend: "GPU" });
+    // 3) Generar
+    var respuesta = ai.generate({ prompt: "Resume en una frase qué es XOne." });
+    ui.msgBox(respuesta);
+    // 4) Liberar memoria cuando se termine
+    ai.unload();
+}
+```
+
+**Todos los ficheros (modelo, imágenes, audio) se referencian por su nombre simple**, no por ruta. El modelo vive en una carpeta interna `models/` que gestiona el framework: `downloadModel` lo coloca ahí y `loadModel`/`getModelInfo` lo encuentran con el mismo nombre. No se aceptan rutas con `/`, `\`, `.` ni `..`.
+
+---
+
+## 2. Descargar un modelo (`downloadModel`)
+
+Descarga **asíncrona** de un fichero de modelo desde HuggingFace. No bloquea la pantalla.
+
+```js
+ai.downloadModel({
+    repository: "litert-community/gemma-4-E2B-it-litert-lm",  // requerido: <usuario>/<repo>
+    file: "gemma-4-E2B-it.litertlm",                          // requerido: nombre de fichero
+    revision: "main",                                          // opcional: rama/tag/commit (def. "main")
+    token: "hf_xxx",                                           // opcional: solo para repos protegidos
+    resume: true,                                              // opcional: reanudar descarga parcial (def. true)
+    onProgress: function (percent) { },                       // porcentaje entero 0-100
+    onComplete: function (file) { },                          // nombre del fichero descargado
+    onError: function (msg) { }
+});
+```
+
+- **`onProgress`** recibe un porcentaje entero y solo se llama cuando ese porcentaje cambia (no en cada bloque). Si el servidor no informa del tamaño total, no se emite progreso.
+- **`onComplete`** recibe el **nombre del fichero**, listo para pasar tal cual a `loadModel({ path: file })`.
+- **`resume: true`** reanuda una descarga cortada (útil para modelos de varios GB y redes inestables).
+- **`token`**: algunos repos exigen aceptar una licencia y un token de acceso de HuggingFace. Sin él, el servidor responde con error (llega a `onError`). Los repos de la comunidad `litert-community` suelen ser abiertos y no necesitan token.
+
+---
+
+## 3. Comprobar el dispositivo (`canLoadModel`)
+
+Indica si el dispositivo tiene recursos para cargar un modelo. Devuelve `true`/`false`.
+
+```js
+// Comprobación básica (arquitectura del dispositivo + memoria no crítica)
+if (ai.canLoadModel()) { /* ... */ }
+
+// Comprobación con el modelo concreto: además valida que el fichero existe
+// y que hay RAM total suficiente (tamaño del fichero × factor)
+if (ai.canLoadModel({ path: "gemma-4-E2B-it.litertlm", memoryFactor: 1.5 })) {
+    ai.loadModel({ path: "gemma-4-E2B-it.litertlm" });
+}
+```
+
+`memoryFactor` (por defecto `1.5`) se compara contra la RAM **total** del dispositivo, no la libre: si el dispositivo no tiene RAM total suficiente, no podrá cargar el modelo aunque ahora haya algo libre.
+
+---
+
+## 4. Inspeccionar el modelo (`getModelInfo`)
+
+Lee los **parámetros de inferencia** del modelo **sin cargarlo** (es instantáneo, solo lee la cabecera del fichero). Acepta el nombre del fichero o un objeto `{ file }`.
+
+```js
+var info = ai.getModelInfo("gemma-4-E2B-it.litertlm");
+// info = {
+//   formatVersion: "1.5.0",
+//   modelType: "gemma4",                // gemma4 | gemma3 | gemma3n | qwen3 | qwen2p5 | fastvlm | generic | unknown
+//   fileSize: 2598123456,               // bytes
+//   supportsVision: true,               // admite imágenes
+//   supportsAudio: true,                // admite audio
+//   supportsSpeculativeDecoding: true,  // trae acelerador MTP (ver §12)
+//   maxNumTokens: 4096                  // OPCIONAL: solo si el modelo lo declara
+// }
+```
+
+Útil para decidir antes de cargar. Por ejemplo, no intentar pasar imágenes a un modelo de solo texto:
+
+```js
+var info = ai.getModelInfo(file);
+if (info.supportsVision) {
+    ai.generate({ prompt: "¿Qué hay en la foto?", images: ["foto.jpg"] });
+}
+```
+
+- Todos los campos están **siempre presentes** salvo `maxNumTokens`, que se omite cuando el modelo no lo declara. Muchos modelos (incluido Gemma 4 E2B) no fijan el tamaño de contexto en la cabecera; en ese caso lo controla el parámetro `maxTokens` de `loadModel`.
+- `supportsSpeculativeDecoding` indica si tiene sentido activar `enableSpeculativeDecoding` al cargar (ver §12).
+
+---
+
+## 5. Cargar y descargar de memoria
+
+### `loadModel`
+
+```js
+ai.loadModel({
+    path,                       // requerido: nombre del fichero (en models/)
+    backend: "GPU",             // "GPU" (def.) | "CPU"
+    visionBackend: "GPU",       // requerido para usar imágenes; omitir en modelos de solo texto
+    audioBackend: "GPU",        // requerido para usar audio; omitir en modelos de solo texto
+    maxImages: 1,               // nº máximo de imágenes (junto con visionBackend en multimodales)
+    maxTokens: 4096,            // tamaño de contexto (prompt + respuesta). Ver nota
+    topK: 64,                   // recomendado Gemma 4
+    topP: 0.95,                 // recomendado Gemma 4
+    temperature: 1.0,           // recomendado Gemma 4 (creatividad; 0 = determinista)
+    randomSeed: 0,
+    enableSpeculativeDecoding: false, // activa MTP si el modelo lo soporta (ver §12)
+    onModelLoaded: function () { },      // opcional: si se pasa, la carga es asíncrona (ver abajo)
+    onModelLoadError: function (msg) { } // opcional: OBLIGATORIO junto con onModelLoaded
+});
+```
+
+- **`backend`**: `"GPU"` por defecto (más rápido). Si un modelo no arranca o falla en GPU en cierto dispositivo, probar `"CPU"`.
+- **`visionBackend` / `audioBackend`**: son los **activadores** de imagen/audio. Si no se indican, pasar `images`/`audio` a `generate`/`chat` da error. En modelos de solo texto, omitirlos.
+- **`maxTokens`**: es el contexto **total** (entrada + salida). En móvil conviene mantenerlo moderado (p. ej. `4096`); valores muy altos consumen mucha memoria y pueden desestabilizar la carga.
+- **`onModelLoaded` / `onModelLoadError` (carga asíncrona)**: dos callbacks opcionales que van **juntos** — o los dos o ninguno; pasar solo uno da error. Si se pasan, `loadModel` **no bloquea**: vuelve enseguida y carga el modelo en segundo plano, y al terminar llama a `onModelLoaded()` si fue bien o a `onModelLoadError(mensaje)` si falló. Es la forma recomendada de cargar el modelo **al arrancar** sin congelar la pantalla. Sin estos callbacks `loadModel` es **síncrono** (bloquea hasta cargar), por lo que en ese caso debe ejecutarse desde un nodo de acción/script en segundo plano.
+
+```js
+// Cargar al arrancar sin bloquear la interfaz (p. ej. si el modelo ya está descargado):
+ai.loadModel({
+    path: "gemma-4-E2B-it.litertlm",
+    backend: "GPU",
+    onModelLoaded: function () { ui.showToast("IA lista."); },
+    onModelLoadError: function (msg) { ui.showToast("No se pudo cargar la IA: " + msg); }
+});
+```
+
+### `unload` / `isLoaded`
+
+```js
+ai.isLoaded();   // true si hay un modelo cargado e inicializado
+ai.unload();     // libera el modelo de memoria (libéralo cuando termines: ocupa mucha RAM)
+```
+
+Cargar un modelo es **costoso** (varios segundos y mucha RAM). Cárgalo una vez y reutilízalo; no lo cargues y descargues en cada interacción.
+
+---
+
+## 6. Generación sin historial (`generate`)
+
+Genera una respuesta **de una sola vez**, sin recordar mensajes anteriores. Es **síncrona** (bloquea hasta terminar) y devuelve el texto como `String`.
+
+```js
+var texto = ai.generate({
+    prompt: "Traduce al inglés: Buenos días",
+    system: "Eres un traductor profesional.",   // opcional: instrucción de sistema
+    images: ["recibo.jpg"],                      // opcional: array de imágenes
+    audio: "nota.wav",                           // opcional: un audio
+    tools: []                                    // opcional: herramientas (function calling) — ver §9
+});
+```
+
+> **No la llames desde el hilo de interfaz** (p. ej. directamente en un `onclick` que bloquee la pantalla): lanza error si detecta que corre en el hilo de UI. Ejecútala desde un nodo de acción/script en segundo plano, o usa `chat` (asíncrono) si quieres no bloquear.
+
+Para imágenes hace falta `visionBackend` en `loadModel`; para audio, `audioBackend`.
+
+---
+
+## 7. Chat multi-turno con streaming (`chat`)
+
+Mantiene **historial** entre llamadas y entrega la respuesta **token a token** mediante callbacks (no bloquea la pantalla).
+
+```js
+ai.chat({
+    prompt: "¿Y cuál es su capital?",
+    system: "Responde de forma breve.",      // opcional
+    images: ["mapa.png"],                     // opcional
+    audio: "pregunta.wav",                    // opcional
+    tools: [],                                // opcional: herramientas (function calling) — ver §9
+    onToken: function (token) {               // se llama por cada fragmento de texto
+        // acumular y refrescar la vista
+    },
+    onComplete: function (full) {             // texto completo al terminar
+        ui.refresh();
+    },
+    onError: function (msg) {
+        ui.msgBox(msg);
+    }
+});
+```
+
+- La conversación se conserva entre llamadas sucesivas a `chat`. Para empezar de cero, usar `clearChat()`.
+- Si cambias el `system` —o el conjunto de herramientas (`tools`)— entre llamadas, la conversación se reinicia automáticamente.
+- Los callbacks se ejecutan preservando el contexto del objeto activo (`self`), igual que cualquier callback asíncrono del framework — pero si vas a usar `self` dentro, guárdalo en una variable antes de llamar a `chat`.
+
+---
+
+## 8. Cancelar y reiniciar
+
+```js
+ai.cancel();      // cancela la generación de chat en curso (si la hay)
+ai.clearChat();   // borra el historial de la conversación y la instrucción de sistema
+```
+
+---
+
+## 9. Herramientas / function calling (`tools`)
+
+Permite que el modelo **invoque funciones JavaScript** cuando lo considere necesario (function calling). Cada herramienta se describe en un fichero JSON (estilo OpenAI) y se asocia a una función JS que recibe los parámetros. Las herramientas se pasan en el parámetro `tools` de `chat` o `generate` — un array de objetos `{ jsonDescriptorPath, callback }`:
+
+```js
+// "tools/clima.json" describe la herramienta (nombre, descripción, parámetros)
+ai.chat({
+    prompt: "¿Qué tiempo hace en Madrid?",
+    tools: [
+        {
+            jsonDescriptorPath: "tools/clima.json",
+            callback: function (params) {
+                var ciudad = params.ciudad;
+                // ... obtener el dato ...
+                return JSON.stringify({ temperatura: 21, ciudad: ciudad });
+            }
+        }
+    ],
+    onComplete: function (full) { /* ... */ }
+});
+```
+
+La función recibe los parámetros como un mapa `clave → valor` y debe devolver una cadena (normalmente JSON). Las herramientas funcionan tanto en `chat` como en `generate`. En `chat`, si cambias el conjunto de herramientas entre llamadas, la conversación se reinicia automáticamente.
+
+---
+
+## 10. Skills automáticas (`loadSkills`)
+
+Las **skills** son comportamientos especializados que el modelo **detecta y aplica automáticamente** según el mensaje del usuario. No son function calling: son instrucciones de comportamiento que se inyectan en el contexto. Cada skill es un fichero Markdown.
+
+```js
+ai.loadSkills("skills/");        // carga todos los .md de la carpeta (cada fichero = una skill)
+ai.removeSkill("traductor");     // elimina una skill por nombre
+ai.clearSkills();                // elimina todas las skills
+```
+
+**Formato del fichero `.md` — encabezado obligatorio:**
+
+```
+---
+name: traductor
+description: Traduce texto entre idiomas
+---
+Instrucciones de comportamiento de la skill...
+```
+
+- `name` y `description` son obligatorios; el cuerpo (las instrucciones) no puede quedar vacío. Los ficheros que no cumplan el formato se ignoran.
+- Con **2 o más skills**, el modelo elige automáticamente la más adecuada a cada mensaje antes de responder (añade algo de latencia). Con **una sola**, se aplica siempre. Con **ninguna**, comportamiento normal.
+
+---
+
+## 11. Multimedia: formatos soportados
+
+> **No hay soporte de vídeo.** Las entradas multimedia son **imagen** y **audio**. Si necesitas analizar un vídeo, extrae fotogramas como imágenes.
+
+### Imagen
+
+| Formato | Soporte |
+|---|---|
+| JPEG / JPG | ✅ |
+| PNG | ✅ |
+| BMP | ✅ |
+| GIF | ✅ (solo primer fotograma) |
+| TGA, HDR, PSD, PNM/PPM/PGM | ✅ |
+| WebP | ❌ |
+| HEIC / AVIF | ❌ |
+
+**Recomendado:** JPEG para fotos, PNG para capturas. Atención: **HEIC** es el formato por defecto de muchas cámaras de móvil modernas y **no se admite** — convertir a JPEG/PNG antes.
+
+### Audio
+
+| Formato | Soporte |
+|---|---|
+| WAV | ✅ |
+| MP3 | ✅ |
+| FLAC | ✅ |
+| Ogg / Opus | ❌ |
+| AAC / M4A | ❌ |
+
+**Recomendado:** WAV mono 16 kHz 16-bit. Atención: **AAC/M4A** (grabaciones de voz típicas del móvil) **no se admiten**.
+
+> **Para grabar ese WAV desde el micrófono** usa `ui.startAudioRecord({ outputFormat: "wav", timeout: 30, onComplete: ... })`: produce justo WAV PCM 16 bits / 16 kHz / mono y respeta el máximo de 30 s de audio del modelo. **Ojo:** su formato por defecto es `mp4` (AAC) y **no sirve** para la IA; hay que pedir `outputFormat: "wav"` explícitamente. Pasa la ruta del `onComplete` directamente como `audio`. Ver `topics/03b-js-ui.md` §3.10.
+
+### Validar la extensión antes de enviar
+
+```js
+function getMediaType(fileName) {
+    if (!fileName) { return null; }
+    var nDot = fileName.lastIndexOf(".");
+    if (nDot < 0) { return null; }
+    switch (fileName.substring(nDot + 1).toLowerCase()) {
+        case "jpg": case "jpeg": case "png": case "bmp":
+        case "gif": case "tga": case "hdr": case "psd":
+        case "pnm": case "ppm": case "pgm":
+            return "image";
+        case "wav": case "mp3": case "flac":
+            return "audio";
+        default:
+            return null;   // webp, heic, m4a, aac, vídeo, etc.
+    }
+}
+```
+
+---
+
+## 12. Parámetros recomendados (Gemma 4)
+
+Google publica una configuración de muestreo estándar para Gemma 4, que son **los valores por defecto** del objeto `ai`:
+
+| Parámetro | Gemma 4 (por defecto) |
+|---|---|
+| `temperature` | `1.0` |
+| `topP` | `0.95` |
+| `topK` | `64` |
+
+**MTP (Multi-Token Prediction / decodificación especulativa):** algunos modelos Gemma 4 traen un "acelerador" que puede **duplicar la velocidad** de generación sin perder calidad. Se activa con `enableSpeculativeDecoding: true` en `loadModel`, y solo tiene efecto si:
+
+- El modelo lo soporta — compruébalo con `getModelInfo(file).supportsSpeculativeDecoding`.
+- Se usa `backend: "GPU"` (es donde está validado).
+
+```js
+var info = ai.getModelInfo(file);
+ai.loadModel({
+    path: file,
+    backend: "GPU",
+    enableSpeculativeDecoding: info.supportsSpeculativeDecoding
+});
+```
+
+---
+
+## 13. Buenas prácticas y problemas comunes
+
+| Situación | Recomendación |
+|---|---|
+| `generate` lanza error de "hilo de UI" | No la llames en un `onclick` que bloquee; usa un nodo de acción en segundo plano o `chat` (asíncrono). |
+| El modelo tarda mucho o no arranca en GPU | Probar `backend: "CPU"`. La primera carga siempre es lenta (compila en el dispositivo). |
+| Falta de memoria al cargar | Bajar `maxTokens`; comprobar antes con `canLoadModel({ path, memoryFactor })`; llamar a `unload()` cuando termines. |
+| Pasar imagen/audio da error | Falta `visionBackend`/`audioBackend` en `loadModel`, o el modelo no es multimodal (`getModelInfo`). |
+| Imagen/audio no reconocidos | Formato no soportado (HEIC, M4A, WebP, vídeo). Convertir a JPEG/PNG o WAV. |
+| Recargas el mismo modelo una y otra vez | Cárgalo una vez y reutilízalo; cargar es costoso en tiempo y RAM. |
+| `maxNumTokens` no aparece en `getModelInfo` | Normal: el modelo no lo declara. El contexto lo fija tú con `maxTokens` en `loadModel`. |
+