Matrix App Builder

¿Qué hace Matrix App Builder?

Cuándo Usar

Usa esto cuando el usuario pida construir, crear, corregir, rediseñar o publicar una aplicación Matrix OS.

No Negociables

• Construye aplicaciones orientadas al usuario en ~/apps/<slug>/.
• Por defecto, usa Vite, React 19, TypeScript y runtime: "vite".
• Las aplicaciones CRM, roadmap, dashboard, admin y con muchos datos siguen siendo SPAs Vite React por defecto. Usa las APIs puente de Matrix/Postgres para los datos en lugar de crear rutas API de Next.js.
• No crees Next.js, .next/, archivos del router app/, runtime: "node", serve.start o npm start a menos que el usuario solicite explícitamente un tiempo de ejecución de servidor o Next.js.
• No crees aplicaciones HTML plano a menos que el usuario lo pida explícitamente.
• Siempre crea o actualiza matrix.json. Para aplicaciones construidas para el propietario, incluye listingTrust: "first_party" y scope: "personal"; la falta de bloques de confianza impide el lanzamiento incluso si la compilación tiene éxito. Nunca etiquetes incorrectamente aplicaciones descargadas/de la comunidad para eludir la política.
• Siempre ejecuta pnpm install cuando cambien las dependencias y pnpm build antes de decir que la aplicación funciona.
• Verifica que exista dist/index.html.
• Usa las variables de tema Matrix inyectadas y el dimensionamiento seguro para iframes. Las aplicaciones personalizadas deben heredar el tema del shell por defecto; añade marca explícita de la aplicación solo cuando el usuario lo solicite o la aplicación tenga una razón de dominio clara.
• Para la UI, lee matrix-design-system, matrix-app-ui-patterns y App craft. Descubre y lee los archivos SKILL.md de emil-design-eng y apple-design instalados antes de diseñar; usa animate para trabajo de movimiento específico. Conserva las reglas de tema/tiempo de ejecución de Matrix y elige diseño, materiales y movimiento para el propósito real de la aplicación.
• Almacena datos estructurados de la aplicación a través de las APIs puente Matrix/Postgres, no mediante bases de datos locales ad hoc.
• Nunca coloques secretos de proveedores, claves API o tokens OAuth dentro del directorio de la aplicación.
• No uses localStorage del navegador como persistencia de la aplicación en el shell Matrix. Los iframes sandboxed pueden lanzar SecurityError; usa window.MatrixOS.db y mantén las rutas de respaldo local solo para pruebas/sin operación.
• Para aplicaciones predeterminadas o de primera parte bajo home/apps/**, mantén los manifiestos deterministas: runtime: "vite", build.output: "dist", columnas de esquema declaradas en storage.tables e icon apuntando a un activo confirmado en home/system/icons/.

Flujo de trabajo de diseño

Antes de andamiar, lee la referencia de artesanía y las habilidades de diseño instaladas. Elige una dirección de diseño concisa y un flujo de usuario principal. Construye primero la interacción central, añade retroalimentación intencionada, luego inspecciona y refina la aplicación en ejecución en Matrix. Evita un héroe de bienvenida genérico, tarjetas de estadísticas decorativas, contenedores de vidrio repetidos y entradas escalonadas automáticas. Registra qué habilidades y superficies verificaste realmente.

Estructura Estándar

~/apps/<slug>/
  matrix.json
  package.json
  vite.config.ts
  tsconfig.json
  index.html
  src/
    main.tsx
    App.tsx
    App.css
  dist/
    index.html

Manifiesto

Usa esta línea base y ajusta el nombre de la aplicación, descripción, categoría, icono y tablas de almacenamiento:

{
  "name": "Mi Aplicación",
  "description": "Una descripción concisa de la aplicación",
  "slug": "mi-aplicacion",
  "version": "1.0.0",
  "runtime": "vite",
  "runtimeVersion": "^1.0.0",
  "listingTrust": "first_party",
  "scope": "personal",
  "icon": "mi-aplicacion",
  "category": "productividad",
  "build": {
    "command": "pnpm build",
    "output": "dist"
  },
  "storage": {
    "tables": {}
  }
}

Los tipos de columna de almacenamiento válidos incluyen text, boolean, integer, float, timestamptz, jsonb y uuid.

Presentación de aplicaciones y gráficos en el Chat

Después de verificar la aplicación, enlaza su directorio relativo al propietario, por ejemplo [Adopción de IA](~/apps/adopcion-ia). Electron Desktop resuelve los directorios de aplicaciones instaladas contra el catálogo de aplicaciones y las abre a través del comportamiento normal del lanzador. No afirmes que una carpeta arbitraria es una aplicación instalada.

Muestra gráficos o capturas de pantalla guardados con imágenes Markdown y rutas completas relativas al propietario, por ejemplo ![Gráfico de adopción de IA](~/apps/adopcion-ia/chart-light.png). Electron Desktop puede mostrar estas imágenes y abrirlas en Vista Previa de Archivos; no le digas al usuario que las imágenes solo pueden aparecer en la terminal del agente. Usa enlaces Markdown para otros archivos guardados. Las vistas previas HTML estáticas están en sandbox sin scripts; enlaza la aplicación instalada para un gráfico interactivo en lugar de prometer ejecución HTML activa dentro del Chat. Informa la falta de archivos o fallos de vista previa con sinceridad.

Nomenclatura

• name es la etiqueta humana, en Title Case que se muestra en el lanzador, dock y barra de título — p. ej. "Rastreador de Calorías", "Jardín de Hábitos". Hazlo corto y real; nunca muestres el slug a los usuarios.
• slug es el identificador en minúsculas y con guiones utilizado en rutas/URLs (^[a-z0-9][a-z0-9-]{0,63}$). Derívalo del nombre (rastreador-de-calorias). Es interno — no lo uses como cadena de visualización en ningún lugar.

Icono (obligatorio — o la aplicación muestra un mosaico roto)

El lanzador carga el icono de cada aplicación desde ~/system/icons/<icono>.svg (o .png) que coincide con el campo icon del manifiesto. Si no envías ese archivo, /icons/<icono> devuelve 404 y la aplicación obtiene un icono roto/de marcador de posición. Así que siempre:

1. Establece "icon": "<slug>" en matrix.json (usa el slug de la aplicación a menos que tengas un nombre de concepto mejor).
2. Crea ~/system/icons/<slug>.png usando el estilo de icono de aplicación enviado con Matrix OS: ilustración de icono de aplicación skeuomórfica premium ligera al estilo iOS/macOS, representación de producto refinada al estilo Apple, fondo blanco roto cálido o pastel pálido, profundidad cerámica/vidrio sutil, biseles suaves, reflejos brillantes, sombras de estudio realistas y un solo objeto o símbolo 3D grande y táctil que represente claramente la aplicación. Mantén la familia de iconos alineada con los acentos de bosque, crema, brasa y profundos de Matrix OS. No incluyas texto, logotipos, marcas de agua, fondos transparentes, fondos de dock negros/oscuros, relleno vacío o un marco de icono visible separado; el shell Matrix posee el radio de esquina final. Mantén la iluminación y el tratamiento de materiales consistentes con los PNG de iconos de aplicación predeterminados enviados en ~/system/icons/.

Para aplicaciones de primera parte/predeterminadas, prefiere iconos PNG confirmados de home/system/icons/. Los SVG son aceptables solo para cromo del sistema o respaldos de compatibilidad simples, no para logotipos de aplicación recién generados.

Datos (Postgres a través del puente MatrixOS)

Las aplicaciones se ejecutan en un iframe sandboxed de origen nulo (CSP connect-src 'self'), por lo que un fetch() directo a /api/bridge/* está bloqueado y localStorage lanza SecurityError. Persiste SOLO a través del puente inyectado:

• Declara tus tablas en storage.tables de matrix.json (arriba). El gateway aprovisiona el esquema Postgres automáticamente — al inicio para aplicaciones enviadas, y perezosamente en la primera consulta para aplicaciones que construyas ahora, por lo que las llamadas db de una aplicación recién construida funcionan sin necesidad de reinicio.
• En el código, usa window.MatrixOS.db (find/findOne/insert/update/delete/count/onChange). Protege contra undefined (está ausente en pruebas unitarias), envuelve cada llamada en try/catch (registra + muestra error visible al usuario; nunca un catch vacío), actualiza el estado local de forma optimista y reconcilia en onChange.
• Para APIs externas/de terceros, usa window.MatrixOS.proxyFetch(url) (en lista blanca) — nunca un fetch sin procesar.
• NO añadas un fallback de localStorage que se ejecute en el shell; lanza un error en el sandbox. Una ruta try/catch protegida para localStorage es aceptable solo como no operación para el entorno de pruebas unitarias.

Herencia de Tema

El shell inyecta tokens --matrix-* en cada iframe de aplicación puente y los actualiza en cambios de tema. Construye el CSS de la aplicación sobre esos tokens primero, con colores literales solo como respaldos:

:root {
  --app-bg: var(--matrix-bg, #FAFAF9);
  --app-fg: var(--matrix-fg, #32352E);
  --app-card: var(--matrix-card, #FCFCF8);
  --app-primary: var(--matrix-primary, #434E3F);
  --app-primary-fg: var(--matrix-primary-fg, #FAFAF5);
  --app-accent: var(--matrix-accent, #D06F25);
  --app-success: var(--matrix-success, #3A7D44);
  --app-warning: var(--matrix-warning, #E0A12E);
  --app-danger: var(--matrix-destructive, #D74A3A);
  --app-border: var(--matrix-border, #D8D6C7);
}

Usa las fuentes heredadas del shell (var(--matrix-font-sans), var(--matrix-font-mono)) en lugar de cargar hojas de estilo de fuentes remotas. No uses paletas azules, verdes o moradas locales de la aplicación para la UI predeterminada. Si se necesita marca explícita de la aplicación, limítala a tokens de marca nombrados y mantén los controles del sistema, estados de enfoque, colores de estado y paneles en los tokens Matrix.

Reglas de Persistencia

• Declara cada campo persistido en storage.tables de matrix.json, incluidos campos de auditoría como created_at, columnas de mejor puntuación/mejor tiempo y cargas útiles de estado JSONB.
• Carga desde el almacenamiento del puente al inicio; no siembres filas de respaldo duplicadas después de que se carguen filas reales.
• Revierte los cambios de UI optimistas en creaciones, actualizaciones, eliminaciones y reordenamientos fallidos. Mantén las eliminaciones pendientes filtradas del estado visible hasta que el puente confirme o revierta.
• Serializa escrituras dependientes que actualicen ordenamiento, mejores puntuaciones, contadores de estadísticas o filas de historial. Evita que dos escrituras del puente compitan y puedan sobrescribir el estado derivado de la otra.
• Mantén los ayudantes solo para navegador protegidos para pruebas. En los iframes del shell de producción, el acceso directo a localStorage y las llamadas fetch() sin procesar al puente no son una persistencia confiable.

Aplicaciones Predeterminadas de Primera Parte

Al editar aplicaciones predeterminadas empaquetadas en este repositorio:

• Mantén los manifiestos y esquemas de las aplicaciones en home/apps/<slug>/matrix.json.
• Reutiliza la ruta de compilación Vite compartida de aplicaciones predeterminadas; no añadas campos de paquete/tiempo de ejecución obsoletos por aplicación a menos que la aplicación realmente los necesite.
• Ejecuta node scripts/build-default-apps.mjs home/apps antes del trabajo de empaquetado del host cuando cambie el código fuente de las aplicaciones predeterminadas.
• Prefiere el icono compartido game-center para juegos a menos que exista un icono concreto enviado.
• Verifica los slugs de los iconos de las aplicaciones contra home/system/icons/<slug>.svg o .png; nunca confíes en la generación de iconos en tiempo de ejecución.

Comandos de Andamiado

Prefiere copiar la plantilla Vite empaquetada de Matrix cuando exista:

cp -a ~/apps/_template-vite ~/apps/<slug>
cd ~/apps/<slug>
pnpm install --prefer-offline
pnpm build
test -f dist/index.html

Si la plantilla no está presente, crea los archivos Vite estándar directamente con react, react-dom, @vitejs/plugin-react, typescript y vite.

Acceso a Datos

Usa el puente window.MatrixOS.db inyectado para datos estructurados. No llames directamente a /api/bridge/query desde el código de la aplicación; las aplicaciones en tiempo de ejecución se cargan como iframes srcdoc en sandbox, y las búsquedas directas al puente están bloqueadas por el límite CORS/CSP del shell.

Ejemplo CRUD:

const db = window.MatrixOS?.db;
if (!db) throw new Error("El puente de datos Matrix no está disponible");

const tasks = await db.find("tasks", { orderBy: { created_at: "desc" } });
const created = await db.insert("tasks", { title: "Enviar" });
await db.update("tasks", created.id, { done: true });
await db.delete("tasks", created.id);

Integraciones

Si la aplicación necesita Gmail, Calendar, GitHub, Slack, Drive u otro proveedor, usa las APIs de integración de Matrix o la habilidad matrix-integrations. La plataforma posee las credenciales del proveedor. La aplicación nunca almacena secretos del proveedor.

Verificación

Antes de informar que está listo:

cd ~/apps/<slug>
pnpm build
test -f dist/index.html
node <directorio-resuelto-de-habilidad-matrix-app-builder>/scripts/verify-app.mjs "$PWD"

Resuelve el directorio de la habilidad desde el SKILL.md que cargaste; el script se envía junto a él y no necesita dependencias. Ejecútalo en el directorio real de la aplicación, no en la plantilla. Verifica el manifiesto Vite construido por el propietario y la entrada de producción; nunca cambia la confianza ni prueba un inicio de sesión en vivo.

Inicio de sesión y autenticación

Matrix proporciona la autenticación del propietario. No construyas una página de inicio de sesión separada ni leas/copies credenciales de la puerta de enlace en la aplicación. El lanzador nativo obtiene un token de corta duración a través de POST /api/apps/<slug>/session-token; el lanzamiento es /apps/<slug>/. Un listingTrust faltante o desconocido produce 403 install_blocked_by_policy, no un inicio de sesión caducado. Una aplicación existente que acabas de construir para el propietario puede tener sus metadatos faltantes corregidos después de verificar su origen; nunca promuevas silenciosamente una aplicación importada. 401 significa autenticación, 403 política, 409 alcance/reconocimiento, 404 descubrimiento y 5xx un fallo del servidor. Informa los fallos con precisión en lugar de recomendar iniciar sesión para todos ellos. No deshabilites la autenticación, debilites la política, reinicies el VPS ni añadas un servidor para solucionar un fallo de lanzamiento.

Luego abre la aplicación desde el lanzador Matrix usando la sesión autenticada existente. Verifica los activos de la aplicación, el icono, las operaciones del puente, un ciclo de guardar/reabrir y las comprobaciones visuales/de estado de la referencia de artesanía. Si el acceso al navegador no está disponible, informa la verificación de lanzamiento y visual como pendiente en lugar de afirmar que la aplicación funciona. Revisa la consola/red del navegador para:

• needs_build
• 404 para rutas de paquete de aplicación o icono
• Errores CORS de llamadas directas a proveedores
• errores no manejados de React