Communitygithub.com

Matrix App Builder

Créez des applications Matrix OS sous forme de projets Vite React TypeScript avec des manifests matrix.json, l'intégration du thème Matrix, des données d'application basées sur Postgres et une vérification de la build de production.

Qu'est-ce que Matrix App Builder ?

Matrix App Builder est une compétence d'agent spécialisée pour construire et déployer des applications web dans l'écosystème Matrix OS. Elle utilise un stack technique moderne avec Vite, React 19 et TypeScript, tout en imposant des règles strictes pour garantir la compatibilité avec le shell Matrix. La compétence gère la persistance des données via une passerelle Postgres injectée dans l'iframe, évitant les limitations de sécurité du navigateur comme le CORS et le localStorage. Elle intègre automatiquement le thème Matrix via des variables CSS personnalisées et fournit des workflows de design, de construction, de vérification et de lancement. Les développeurs peuvent créer des applications telles que des CRM, des tableaux de bord ou des outils de productivité, avec des manifests déclaratifs, une interface utilisateur basée sur les tokens et des icônes système. La compétence s'applique à Claude Code, Cursor et d'autres agents compatibles, et prend en charge la génération d'icônes, les tests de build et le dépannage des erreurs de lancement.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/HamedMP/matrix-os/tree/HEAD/skills/matrix/app-builder

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Aperçu

Depuis le README du skill

Graphique d'adoption IA

Documentation

Que fait Matrix App Builder ?

Quand l'utiliser

Utilisez cette compétence lorsque l'utilisateur demande de construire, créer, corriger, reconcevoir ou publier une application Matrix OS.

Non-négociables

  • Construire des applications destinées aux utilisateurs dans ~/apps/<slug>/.
  • Par défaut, utiliser Vite, React 19, TypeScript et runtime: "vite".
  • Les applications CRM, roadmap, tableau de bord, admin et celles avec beaucoup de données restent des SPA Vite React par défaut. Utilisez les API de pont Matrix/Postgres pour les données au lieu de créer des routes API Next.js.
  • Ne créez pas de fichiers Next.js, .next/, app/ router, runtime: "node", serve.start ou npm start sauf si l'utilisateur demande explicitement un serveur d'exécution ou Next.js.
  • Ne créez pas d'applications HTML simples sauf si l'utilisateur demande explicitement une application HTML simple.
  • Créez ou mettez toujours à jour matrix.json. Pour les applications construites pour le propriétaire, incluez listingTrust: "first_party" et scope: "personal" ; les blocs de confiance manquants empêchent le lancement même si la construction réussit. Ne renommez jamais les applications téléchargées/communautaires pour contourner la politique.
  • Exécutez toujours pnpm install lorsque les dépendances changent et pnpm build avant de dire que l'application fonctionne.
  • Vérifiez que dist/index.html existe.
  • Utilisez les variables de thème Matrix injectées et un dimensionnement sûr pour les iframes. Les applications personnalisées doivent hériter du thème du shell par défaut ; ajoutez une marque explicite uniquement lorsque l'utilisateur le demande ou que l'application a une raison de domaine claire.
  • Pour l'interface utilisateur, lisez matrix-design-system, matrix-app-ui-patterns et App craft. Découvrez et lisez les fichiers SKILL.md installés emil-design-eng et apple-design avant de concevoir ; utilisez animate pour un travail de mouvement spécifique. Respectez les règles du thème/de l'exécution Matrix et choisissez la disposition, les matériaux et le mouvement en fonction de l'objectif réel de l'application.
  • Stockez les données structurées de l'application via les API de pont Matrix/Postgres, pas via des bases de données locales ad hoc.
  • Ne mettez jamais de secrets de fournisseur, de clés API ou de jetons OAuth dans le répertoire de l'application.
  • N'utilisez pas le localStorage du navigateur comme persistance d'application dans le shell Matrix. Les iframes sandboxées peuvent lever SecurityError ; utilisez window.MatrixOS.db et gardez les chemins de repli locaux en mode test uniquement / sans opération.
  • Pour les applications par défaut ou first-party sous home/apps/**, gardez les manifests déterministes : runtime: "vite", build.output: "dist", les colonnes de schéma déclarées dans storage.tables, et icon pointant vers un asset commité dans home/system/icons/.

Workflow de conception

Avant l'échafaudage, lisez la référence de conception et les compétences de conception installées. Choisissez une direction de conception concise et un flux utilisateur principal. Construisez d'abord l'interaction de base, ajoutez des retours intentionnels, puis inspectez et affinez l'application en cours d'exécution dans Matrix. Évitez un héros de bienvenue générique, des cartes de statistiques décoratives, des conteneurs en verre répétés et des entrées échelonnées automatiques. Enregistrez les compétences et les surfaces que vous avez effectivement vérifiées.

Structure standard

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

Manifeste

Utilisez cette base et ajustez le nom, la description, la catégorie, l'icône et les tables de stockage de l'application :

{
  "name": "Mon Application",
  "description": "Une description concise de l'application",
  "slug": "mon-application",
  "version": "1.0.0",
  "runtime": "vite",
  "runtimeVersion": "^1.0.0",
  "listingTrust": "first_party",
  "scope": "personal",
  "icon": "mon-application",
  "category": "productivity",
  "build": {
    "command": "pnpm build",
    "output": "dist"
  },
  "storage": {
    "tables": {}
  }
}

Les types de colonnes de stockage valides incluent text, boolean, integer, float, timestamptz, jsonb et uuid.

Présentation des applications et des graphiques dans le Chat

Après avoir vérifié l'application, liez son répertoire relatif au propriétaire, par exemple [Adoption IA](~/apps/ai-adoption). Electron Desktop résout les répertoires d'applications installées par rapport au catalogue d'applications et les ouvre via le comportement normal du lanceur. Ne prétendez pas qu'un dossier arbitraire est une application installée.

Affichez les graphiques ou captures d'écran enregistrés avec des images Markdown et des chemins complets relatifs au propriétaire, par exemple ![Graphique d'adoption IA](~/apps/ai-adoption/chart-light.png). Electron Desktop peut afficher ces images et les ouvrir dans l'aperçu de fichier ; ne dites pas à l'utilisateur que les images ne peuvent apparaître que dans le terminal de l'agent. Utilisez des liens Markdown pour les autres fichiers enregistrés. Les aperçus HTML statiques sont sandboxés sans scripts ; liez l'application installée pour un graphique interactif plutôt que de promettre une exécution HTML active dans le Chat. Signalez honnêtement les fichiers manquants ou les échecs d'aperçu.

Nommage

  • name est l'étiquette humaine en casse de titre affichée dans le lanceur, le dock et la barre de titre — par exemple "Calorie Tracker", "Habit Garden". Rendez-la courte et réelle ; ne montrez jamais le slug aux utilisateurs.
  • slug est l'identifiant en minuscules avec traits d'union utilisé dans les chemins/URLs (^[a-z0-9][a-z0-9-]{0,63}$). Dérivez-le du nom (calorie-tracker). Il est interne — ne l'utilisez pas comme chaîne d'affichage nulle part.

Icône (obligatoire — sinon l'application affiche une vignette cassée)

Le lanceur charge l'icône de chaque application depuis ~/system/icons/<icon>.svg (ou .png) correspondant au champ icon du manifeste. Si vous ne livrez pas ce fichier, /icons/<icon> génère une 404 et l'application obtient une icône cassée/placeholder. Donc toujours :

  1. Définissez "icon": "<slug>" dans matrix.json (utilisez le slug de l'application sauf si vous avez un meilleur nom de concept).
  2. Créez ~/system/icons/<slug>.png en utilisant le style d'icône livré avec Matrix OS : artwork d'icône d'application skeuomorphique iOS/macOS premium et léger, rendu de produit raffiné à l'Apple, fond blanc cassé clair ou pastel pâle, profondeur subtile en céramique/verre, biseaux doux, reflets brillants, ombres de studio réalistes et un seul grand objet ou symbole tactile en 3D qui représente clairement l'application. Gardez la famille d'icônes alignée avec les accents forêt, crème, braise et profonds de Matrix OS. N'incluez pas de texte, logos, filigranes, fonds transparents, fonds de dock noirs/foncés, remplissage vide ou un cadre d'icône visible séparé ; le shell Matrix possède le rayon de coin final. Gardez l'éclairage et le traitement des matériaux cohérents avec les PNG d'icônes par défaut livrés dans ~/system/icons/.

Pour les applications first-party/par défaut, préférez les icônes PNG commitées de home/system/icons/. Les SVG sont acceptables uniquement pour le chrome système ou les retours de compatibilité simples, pas pour les logos d'application nouvellement générés.

Données (Postgres via le pont MatrixOS)

Les applications s'exécutent dans une iframe sandboxée à origine nulle (CSP connect-src 'self'), donc un fetch() direct vers /api/bridge/* est bloqué et localStorage lève SecurityError. Persistez UNIQUEMENT via le pont injecté :

  • Déclarez vos tables dans matrix.json storage.tables (ci-dessus). La passerelle provisionne le schéma Postgres automatiquement — au démarrage pour les applications livrées, et paresseusement à la première requête pour les applications que vous construisez maintenant, donc les appels db d'une application fraîchement construite fonctionnent sans redémarrage.
  • Dans le code, utilisez window.MatrixOS.db (find/findOne/insert/update/delete/count/onChange). Protégez contre undefined (absent dans les tests unitaires), enveloppez chaque appel dans try/catch (log + erreur visible par l'utilisateur ; jamais un catch nu), mettez à jour l'état local de manière optimiste et réconciliez via onChange.
  • Pour les API externes/tierces, utilisez window.MatrixOS.proxyFetch(url) (liste blanche) — jamais un fetch brut.
  • N'ajoutez PAS de fallback localStorage qui s'exécute dans le shell ; cela lève une erreur dans le sandbox. Un chemin localStorage avec try/catch protégé est acceptable uniquement comme no-op pour l'environnement de test unitaire.

Héritage du thème

Le shell injecte les tokens --matrix-* dans chaque iframe d'application pontée et les met à jour lors des changements de thème. Construisez le CSS de l'application sur ces tokens en premier, avec des couleurs littérales uniquement comme fallbacks :

: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);
}

Utilisez les polices héritées du shell (var(--matrix-font-sans), var(--matrix-font-mono)) au lieu de charger des feuilles de style de polices distantes. N'utilisez pas de palettes de couleurs bleues, vertes ou violettes locales pour l'interface utilisateur par défaut. Si une marque explicite est nécessaire, limitez-la aux tokens de marque nommés et gardez les contrôles système, les états de focus, les couleurs de statut et les panneaux sur les tokens Matrix.

Règles de persistance

  • Déclarez chaque champ persisté dans matrix.json storage.tables, y compris les champs d'audit tels que created_at, les colonnes de meilleur score/meilleur temps et les payloads JSONB d'état.
  • Chargez depuis le stockage du pont au démarrage ; ne semez pas de lignes de fallback en double après le chargement des lignes réelles.
  • Annulez les modifications optimistes de l'interface utilisateur en cas d'échec des créations, mises à jour, suppressions et réorganisations. Gardez les suppressions en attente filtrées de l'état visible jusqu'à ce que le pont confirme ou annule.
  • Sérialisez les écritures dépendantes qui mettent à jour l'ordre, les meilleurs scores, les compteurs de statistiques ou les lignes d'historique. Évitez de faire deux écritures pontées qui peuvent se chevaucher.
  • Gardez les aides uniquement pour le navigateur protégés pour les tests. Dans les iframes de production du shell, l'accès direct au localStorage et les appels fetch() bruts vers le pont ne sont pas une persistance fiable.

Applications par défaut First-Party

Lors de l'édition d'applications par défaut groupées dans ce dépôt :

  • Gardez les manifests et schémas d'application dans home/apps/<slug>/matrix.json.
  • Réutilisez le chemin de build Vite partagé des applications par défaut ; n'ajoutez pas de champs de package/runtime périmés par application sauf si l'application en a vraiment besoin.
  • Exécutez node scripts/build-default-apps.mjs home/apps avant le travail de bundle hôte lorsque le code source de l'application par défaut a changé.
  • Préférez l'icône partagée game-center pour les jeux sauf si une icône concrète livrée existe.
  • Vérifiez les slugs d'icônes d'application par rapport à home/system/icons/<slug>.svg ou .png ; ne comptez jamais sur la génération d'icônes au moment de l'exécution.

Commandes d'échafaudage

Préférez copier le modèle Vite groupé de Matrix lorsqu'il existe :

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

Si le modèle n'est pas présent, créez directement les fichiers Vite standard avec react, react-dom, @vitejs/plugin-react, typescript et vite.

Accès aux données

Utilisez le pont window.MatrixOS.db injecté pour les données structurées. N'appelez pas /api/bridge/query directement depuis le code de l'application ; les applications d'exécution se chargent comme des iframes srcdoc sandboxées, et les appels directs au pont sont bloqués par la limite CORS/CSP du shell.

Exemple CRUD :

const db = window.MatrixOS?.db;
if (!db) throw new Error("Pont de données Matrix indisponible");

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

Intégrations

Si l'application a besoin de Gmail, Calendar, GitHub, Slack, Drive ou d'un autre fournisseur, utilisez les API d'intégration Matrix ou la compétence matrix-integrations. La plateforme possède les identifiants des fournisseurs. L'application ne stocke jamais de secrets de fournisseur.

Vérification

Avant de signaler comme terminé :

cd ~/apps/<slug>
pnpm build
test -f dist/index.html
node <chemin-résolu-du-répertoire-de-la-compétence-matrix-app-builder>/scripts/verify-app.mjs "$PWD"

Résolvez le répertoire de la compétence à partir du SKILL.md que vous avez chargé ; le script est livré à côté et n'a besoin d'aucune dépendance. Exécutez-le sur le répertoire réel de l'application, pas sur le modèle. Il vérifie le manifeste Vite construit par le propriétaire et le point d'entrée de production ; il ne modifie jamais la confiance et ne prouve pas une connexion en direct.

Lancement et authentification

Matrix fournit l'authentification du propriétaire. Ne construisez pas de page de connexion séparée et ne lisez/copiez pas les identifiants de la passerelle dans l'application. Le lanceur natif obtient un jeton de courte durée via POST /api/apps/<slug>/session-token ; le lancement est /apps/<slug>/. Un listingTrust manquant ou inconnu donne 403 install_blocked_by_policy, pas une connexion expirée. Une application existante que vous venez de construire pour le propriétaire peut voir ses métadonnées manquantes corrigées après avoir vérifié son origine ; ne promouvez jamais silencieusement une application importée. 401 signifie authentification, 403 politique, 409 portée/accusé de réception, 404 découverte, et 5xx une défaillance du serveur. Signalez les erreurs avec précision au lieu de recommander la connexion pour toutes. Ne désactivez pas l'authentification, n'affaiblissez pas la politique, ne redémarrez pas le VPS, et n'ajoutez pas de serveur pour contourner un échec de lancement.

Ouvrez ensuite l'application depuis le lanceur Matrix en utilisant la session authentifiée existante. Vérifiez les assets de l'application, l'icône, les opérations du pont, un aller-retour sauvegarde/réouverture, et les vérifications visuelles/d'état de la référence de conception. Si l'accès au navigateur est indisponible, signalez le lancement et la vérification visuelle comme en attente plutôt que de prétendre que l'application fonctionne. Vérifiez la console/réseau du navigateur pour :

  • needs_build
  • 404 pour les chemins du bundle de l'application ou de l'icône
  • erreurs CORS provenant d'appels directs au fournisseur
  • erreurs React non gérées

Skills associés