Saltar al contenido
miblo

SDK

Desarrolla una app del Desk sin un Miblo Desk: el simulador

Crea una app con miblo apps new, mira la pantalla de 240×240 en el simulador, pruébala en tu Miblo con un clic y genera el zip y las capturas de la tienda de apps del Desk.

Tres comandos

No necesitas un Miblo para hacer una app del Desk. El comando miblo, que viene con Miblo instalado en el computador, crea la app, muestra su pantalla en un simulador en tu navegador y lo verifica todo con las reglas propias de la tienda de apps del Desk:

Terminal
miblo apps new "My App" --page  # creates the folder my-app, a page Desk app
miblo apps dev my-app           # the simulator in your browser
miblo apps check my-app         # the store's checks

Y, una vez que la app funciona, tres más, que también son botones en la página del simulador:

Terminal
miblo apps send my-app          # runs the app on your real Miblo
miblo apps pack my-app          # the checks, then my-app.zip for the store
miblo apps shots my-app         # the screenshots for the store

Desde Miblo 1.45, la forma por defecto de empezar es --page: la app del Desk es una página web que dibuja Miblo Hub (apps del Desk de página). Sin --page, la plantilla es la forma antigua, con una tarjeta (obsoleta, pero funcional).

No hay nada que instalar: la app es el paquete de código que recibe la tienda de apps del Desk (manifest.json y main.js, que exporta run(ctx)), y el SDK llega a ella mediante ctx, como a las apps oficiales. miblo apps new "My Alerts" --alerts crea una app que solo envía alertas.

Qué muestra el simulador (1.37.0)

  • La página, en vivo (Miblo 1.45): para una app del Desk de página, el simulador muestra la página junto a la pantalla, con el mismo window.miblo que recibe la página del Miblo Desk, y la carga de nuevo en cada guardado.

  • Cuentas conectadas: un ajuste connect (Google o Microsoft) se convierte en el botón Conectar Google/Microsoft, con el inicio de sesión real en el proveedor, como en una app instalada (miblo apps connect). El acceso queda sellado en la carpeta temporal del simulador y se va cuando este se cierra; Desconectar lo olvida. La página muestra la cuenta, nunca el token.

  • Sesiones de IA: para una app con "sessions": true, el panel Sesiones de IA tiene el interruptor que permite ctx.sessions() y una lista de sesiones falsas en el Miblo virtual (Claude Code o Codex, el proyecto y el estado) que tú editas.

  • Errores con lugar: el log nombra el campo y el motivo de una tarjeta rechazada (error: bad_request (items[1].color must be one of ...)), el archivo y la línea de una excepción o de un error de sintaxis (at main.js:12:5), y el estado HTTP con un extracto de la respuesta, sin claves ni tokens.

  • Valores que parecen credenciales (un ajuste cuyo nombre sugiere una clave o una contraseña, o un valor con forma de token) se muestran como •••• en el simulador, en miblo apps config y en miblo apps show. Solo es visualización: el valor igual se guarda en el computador y la app lo lee. Para una cuenta, usa connect.

  • Capturas de pantalla e ícono: miblo apps shots usa el simulador ya abierto para la carpeta (miblo apps dev), con sus ajustes; si no hay ninguno abierto, dice qué dirección abrir y cuánto espera. Además de las capturas escribe el ícono de la tienda de apps del Desk (icon-128.png, 128 × 128), que miblo apps pack pone en el paquete completo de la tienda cuando la carpeta store/ no tiene un ícono propio. El starter hace lo mismo (node sim.mjs shots).

miblo apps new

Con --page (Miblo 1.45), la carpeta es la de una app del Desk de página: un manifest.json con api: 5, display: "page" y page, un main.js que devuelve { data }, page.html (la plantilla es un reloj con cuánto de la jornada laboral ha pasado) y README.md. --page y --alerts no se mezclan: una app del Desk es de página o solo de alertas. Los detalles están en Apps del Desk de página. El resto de esta sección describe la plantilla sin --page, la forma antigua.

Sin --page, crea una carpeta con el nombre de la app en minúsculas (my-app) con tres archivos:

  • manifest.json: el id, la API de apps para la que está escrita (api, Compatibilidad), el nombre y la promesa en portugués e inglés, un ajuste, las direcciones a las que llega la app (network, vacío: sin conexión), cada cuánto se ejecuta (intervalMs) y la tarjeta de vista previa de la tienda de apps del Desk;

  • main.js: una app real. La pantalla muestra la hora, un anillo con cuánto de la jornada laboral se ha ido (con el efecto sweep), la semana en una barra y un gráfico en vivo alimentado por ctx.screen.push();

  • README.md: los próximos pasos.

El id sale del nombre. La tienda de apps del Desk tiene reglas propias para los ids (de 3 a 32 caracteres, sin miblo- al inicio, sin "13", algunas palabras reservadas: la lista completa), y miblo apps check todavía no las aplica: un nombre como "Miblo Weather" produce miblo-weather, que pasa la verificación y es rechazado por la tienda de apps del Desk. Elige el id antes de empezar, y cambia id en manifest.json si hace falta.

miblo apps dev

Abre una página en http://127.0.0.1:<port>/?t=<code> que solo este computador puede abrir. Detrás corre el Miblo real: el mismo puente, la misma Status API, los mismos límites y validadores, con un Miblo virtual emparejado en lugar del dispositivo. Tu app corre como corre una app instalada desde la tienda de apps del Desk, en el mismo sandbox (lee solo su propia carpeta y llega solo a las direcciones de network). Lo que pasa en el simulador pasa en el Miblo.

El sandbox necesita Node 22.15+, 23.5+ o 24+ (usa el modelo de permisos de Node). Miblo busca uno por su cuenta (el Node que ejecuta Miblo, luego PATH, nvm y fnm); si ninguno sirve, apunta MIBLO_NODE a la ruta de uno (MIBLO_NODE=/opt/homebrew/bin/node miblo apps dev my-app).

A la izquierda, la página tiene el Miblo: la pantalla de 240 × 240 dibujada por el propio espejo de Miblo Hub, con la tarjeta, los efectos (fx), las imágenes de fondo y las animaciones de marcos y tiles. El gráfico en vivo reproduce sus lotes a medida que el Miblo los recibe. Una alerta de la app se muestra sobre la pantalla como en el Miblo: una a la vez, durante los segundos que pidió, con el destello violeta cuando es important. A la derecha hay cinco paneles:

  • Lo que le cuesta la app al Miblo: la RAM, el almacenamiento y el procesamiento que necesita tu pantalla, como bandas (cabe, atención, no cabe) con consejos (la memoria de Miblo);

  • Verificaciones de la tienda: verde cuando la tienda de apps del Desk aceptaría la app; cada rechazo con su archivo y su línea;

  • Ajustes de la app: el formulario que la gente ve en Miblo Hub, con las mismas reglas; guarda y mira cómo cambia la pantalla;

  • Alertas: "Permitir las alertas de esta app" (la primera alerta solo pregunta, como en el Miblo), la alerta en pantalla y las que esperan;

  • Log de la app: lo que la app escribe con ctx.log, sus errores y lo que bloqueó el sandbox.

Cada vez que guardas un archivo de la carpeta, las verificaciones corren de nuevo y la app se reinicia. El botón "Reiniciar la app" hace lo mismo.

Encima de ellos está el panel Herramientas (ver abajo): enviar al Miblo, preparar para la tienda de apps del Desk y hacer las capturas de pantalla, un clic cada uno.

Lo que el simulador no muestra como lo hace el dispositivo: la tarjeta usa las fuentes del computador, no las del Miblo; el Modo 7 y el 3D se quedan quietos (solo se reproducen en el Miblo); el dibujo de la alerta es una aproximación (su orden y su tiempo son los del Miblo); y la pantalla de apps siempre está a la vista, mientras que en el Miblo aparece cuando la persona lo eligió (miblo apps when; por defecto tras 60 s sin actividad).

miblo apps check

Ejecuta en tu computador, sin conexión, las mismas verificaciones que corre el análisis de código de la tienda de apps del Desk cuando envías la app: el análisis del código (módulos prohibidos, eval, direcciones fuera de network, archivos que no acepta, el tamaño) y las reglas de Miblo sobre lo que la app declara (los ajustes y la tarjeta de vista previa, que debe caber en las fuentes e íconos del Miblo). Sale con 0 cuando el análisis la aceptaría; --json da el resultado completo.

Terminal
MIBLO_LANG=en miblo apps check my-app
# my-app: ready to submit (nothing the store refuses).

La tienda de apps del Desk también verifica lo que no está en el código: las reglas del id (arriba), el ícono y los textos del listado (Publicar).

Las herramientas del simulador

Enviar al Miblo

Con un Miblo emparejado con este computador, el botón Enviar al Miblo (o miblo apps send my-app) ejecuta la app en tu Miblo real sin escribir ningún programa: la página dice a qué Miblo va, y la app toma su turno en la pantalla de apps como cualquier app. Corre a través del puente de Miblo de este computador, en el mismo sandbox que una app instalada desde la tienda de apps del Desk (lee solo su propia carpeta y llega solo a las direcciones de network), tras pasar las verificaciones de la tienda de apps del Desk.

  • Cada guardado envía también la versión nueva al Miblo.

  • Mostrar ahora en el Miblo pone la pantalla de la app en el Miblo de inmediato; Detener, Volver a encender y Sacar del Miblo hacen lo que dicen; el log de la app en el Miblo aparece justo debajo.

  • Es temporal: cuando cierras el simulador, la app sale del Miblo. Enviada desde la terminal (miblo apps send), se queda hasta miblo apps remove my-app.

  • Nunca reemplaza una app con el mismo id instalada desde la tienda de apps del Desk, un programa tuyo (miblo apps add) o una app oficial: cambia id en manifest.json.

  • Seguridad: solo la persona frente a este computador puede presionarlo (la página se abre solo en 127.0.0.1, con un código por sesión). Un agente de IA no envía un programa al Miblo por su cuenta: miblo apps send se niega cuando corre dentro de un agente, igual que miblo apps add; el botón es tu clic, y el comando es para tu propia terminal.

Preparar para la tienda de apps del Desk

El botón Preparar para la tienda de apps del Desk (o miblo apps pack my-app) corre las verificaciones de la tienda de apps del Desk y, cuando no se rechaza nada, escribe el paquete de código que recibe la tienda de apps del Desk, my-app.zip, junto a la carpeta de la app (dentro de ella, la siguiente verificación leería el zip). El paquete lo verifica el mismo lector que Miblo usa para instalar las apps de la tienda. Cuando algo se rechaza, no se escribe nada y la página dice qué.

Terminal
MIBLO_LANG=en miblo apps pack my-app
# my-app: store package ready, 3 files, 3 KB.
#   /Users/you/apps/my-app.zip
# Submit this zip at miblo.ai/apps/enviar (the "Code" field), with the screenshots.

Todo el envío en un solo zip (Miblo 1.37.0). Haz una carpeta store/ dentro de la carpeta de la app con lo que pide el formulario de la tienda de apps del Desk además del código; miblo apps pack entonces también escribe my-app-store.zip junto a la carpeta, y soltarlo en el primer paso de la página de envío completa de una vez la versión, los textos, el ícono y las capturas. La carpeta store/ nunca entra en el paquete de código.

my-app/store/
├── store.json      { "version": "1.0.0", "category": "daily", "description": { "pt": "...", "en": "..." }, "link": "https://...", "instructions": "..." }
├── icon.png        a square PNG, up to 64 KB (the store makes it 128 × 128)
└── shot-0.png ...  up to 6 screenshots (without them, the 960 px ones from `miblo apps shots`)

store.json es opcional campo por campo: version como 1.0 o 1.0.0; category una de computer, money, daily, news-dev, sport, delights, other; description una cadena o { pt, en } (hasta 2000 caracteres cada una); link una dirección https://; instructions hasta 2000 caracteres; needsPlus: true cuando la app usa funciones de Miblo+. Toda imagen debe ser un PNG. La tienda de apps del Desk vuelve a verificar todo cuando envías.

Envía en Enviar una app (cómo es el proceso).

Hacer capturas de pantalla

El botón Hacer capturas de pantalla (o miblo apps shots my-app) dibuja, con el mismo espejo que la pantalla del simulador:

  • la pantalla ahora (con la alerta encima, si se muestra una);

  • cada tarjeta que la app declara para la tienda de apps del Desk en manifest.json: preview y, para más, previews (una lista de tarjetas; la tienda de apps del Desk acepta hasta 6).

Las capturas las dibuja la página del simulador, en un navegador. miblo apps shots inicia el simulador, abre la página en tu navegador y la espera hasta 2 minutos; sin ninguna página abierta se detiene con "The simulator page did not open: the screens are drawn there". Con --no-open, abre tú mismo la dirección que imprime.

Cada una sale en 240 × 240 (el tamaño del Miblo) y 960 × 960 (lo más grande que conserva la tienda de apps del Desk, píxel por píxel), en la carpeta my-app-screenshots/ junto a la carpeta de la app, y se muestra en la página. El archivo de la pantalla de ahora lleva la hora en su nombre: cambia los ajustes, haz clic de nuevo y obtén una escena más.

Un SDK nuevo

El simulador verifica, al abrirse y cada hora, si existe un Miblo más nuevo (el SDK viene con él), mediante la lista firmada de versiones de miblo.ai, la misma que verifica cada actualización de Miblo. Cuando lo hay, aparece el aviso Hay un SDK nuevo disponible con el botón Actualizar el SDK: actualiza Miblo por las vías oficiales (el actualizador firmado de Miblo y, cuando Miblo llegó por Claude Code, los propios comandos claude plugin de Claude Code), muestra el resultado y reinicia el simulador en la versión nueva, conservando la página y la app enviada al Miblo. Solo las ventanas de Claude Code que ya estaban abiertas necesitan /reload-plugins. Desde la terminal: miblo sdk update (y miblo sdk update --check solo verifica).

Sin Miblo instalado

Descarga el starter: https://miblo.ai/dl/extras/miblo-app-starter-1.46.2.zip. Contiene los dos ejemplos (examples/meu-app y examples/meus-alertas) y el simulador. new, check y pack corren en cualquier Node reciente; el simulador (dev, shots) necesita Node 22.15+, 23.5+ o 24+ (el sandbox de las apps usa su modelo de permisos; en otro Node apunta MIBLO_NODE a uno que sirva). Los comandos son los mismos:

Terminal
node sim.mjs new "My App"
node sim.mjs dev my-app
node sim.mjs check my-app
node sim.mjs pack my-app
node sim.mjs shots my-app

  • node sim.mjs send solo dice que enviar a un Miblo requiere tener Miblo instalado.

  • El starter 1.36.1 todavía no escribe el paquete -store.zip (eso llegó con Miblo 1.37.0): envía my-app.zip y completa el formulario, o usa un starter más nuevo cuando salga.

  • Sin Miblo instalado no hay nada que actualizar: descarga el starter nuevo cuando salga.