Communitygithub.com

Matrix App Builder

Crie aplicativos Matrix OS como projetos Vite React TypeScript com manifestos matrix.json, integração de tema Matrix, dados de aplicativo com Postgres e verificação de build de produção.

O que é Matrix App Builder?

Esta skill capacita um agente de IA a construir, modificar e publicar aplicativos para o sistema operacional Matrix OS utilizando Vite, React 19 e TypeScript. Ela impõe uma estrutura padronizada de projeto, incluindo um manifesto `matrix.json`, e garante que os aplicativos sejam construídos como SPAs Vite que rodam em iframes sandboxados. A skill gerencia a persistência de dados através de uma ponte Postgres/Matrix, utilizando `window.MatrixOS.db`, evitando o uso de `localStorage` ou chamadas diretas à API. Além disso, ela integra o tema do Matrix via variáveis CSS, gerencia a criação de ícones de aplicativo e realiza verificações de build para garantir que o aplicativo funcione corretamente no launcher do Matrix OS. A habilidade é adequada para construir aplicativos de produtividade, dashboards, CRMs e outras ferramentas de dados, sempre seguindo as regras de runtime "vite" e evitando arquiteturas Next.js, a menos que solicitado explicitamente.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Prévia

Do README da skill

AI adoption chart

Documentação

O que Matrix App Builder faz?

Quando Usar

Use esta skill quando o usuário pedir para construir, criar, corrigir, redesenhar ou publicar um aplicativo Matrix OS.

Inegociáveis

  • Construa aplicativos voltados para o usuário em ~/apps/<slug>/.
  • Padrão: Vite, React 19, TypeScript e runtime: "vite".
  • CRM, roadmap, dashboard, admin e aplicativos com muitos dados ainda são SPAs Vite React por padrão. Use APIs de ponte Matrix/Postgres para dados em vez de criar rotas de API Next.js.
  • Não crie Next.js, .next/, arquivos de rota app/, runtime: "node", serve.start ou npm start a menos que o usuário solicite explicitamente um runtime de servidor ou Next.js.
  • Não crie aplicativos HTML simples a menos que o usuário peça explicitamente por um aplicativo HTML simples.
  • Sempre crie ou atualize matrix.json. Para aplicativos construídos para o proprietário, inclua listingTrust: "first_party" e scope: "personal"; blocos de confiança ausentes impedem o lançamento mesmo se o build for bem-sucedido. Nunca renomeie aplicativos baixados/da comunidade para contornar a política.
  • Sempre execute pnpm install quando as dependências mudarem e pnpm build antes de afirmar que o aplicativo funciona.
  • Verifique se dist/index.html existe.
  • Use variáveis de tema Matrix injetadas e dimensionamento seguro para iframe. Aplicativos personalizados devem herdar o tema do shell por padrão; adicione branding explícito do aplicativo apenas quando o usuário solicitar ou o aplicativo tiver um motivo claro de domínio.
  • Para UI, leia matrix-design-system, matrix-app-ui-patterns e App craft. Descubra e leia os arquivos SKILL.md instalados de emil-design-eng e apple-design antes de projetar; use animate para trabalhos de movimento específicos. Preserve as regras de tema/runtime do Matrix e escolha layout, materiais e movimento para o propósito real do aplicativo.
  • Armazene dados estruturados do aplicativo através de APIs de ponte Matrix/Postgres, não bancos de dados locais ad hoc.
  • Nunca coloque segredos de provedores, chaves de API ou tokens OAuth dentro do diretório do aplicativo.
  • Não use localStorage do navegador como persistência de aplicativo no shell Matrix. Iframes com sandbox podem lançar SecurityError; use window.MatrixOS.db e mantenha caminhos de fallback locais apenas para teste/sem operação.
  • Para aplicativos padrão ou de primeira parte em home/apps/**, mantenha manifestos determinísticos: runtime: "vite", build.output: "dist", colunas de esquema declaradas em storage.tables e icon apontando para um asset commitado em home/system/icons/.

Fluxo de Trabalho de Design

Antes de criar a estrutura, leia a referência de craft e as skills de design instaladas. Escolha uma direção de design concisa e o fluxo de usuário principal. Construa a interação central primeiro, adicione feedback proposital, depois inspecione e refine o aplicativo em execução no Matrix. Evite um banner de boas-vindas genérico, cartões de estatística decorativos, containers de vidro repetidos e entradas escalonadas automáticas. Registre quais skills e superfícies você realmente verificou.

Estrutura Padrão

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

Manifesto

Use esta base e ajuste o nome do aplicativo, descrição, categoria, ícone e tabelas de armazenamento:

{
  "name": "My App",
  "description": "A concise app description",
  "slug": "my-app",
  "version": "1.0.0",
  "runtime": "vite",
  "runtimeVersion": "^1.0.0",
  "listingTrust": "first_party",
  "scope": "personal",
  "icon": "my-app",
  "category": "productivity",
  "build": {
    "command": "pnpm build",
    "output": "dist"
  },
  "storage": {
    "tables": {}
  }
}

Tipos de coluna de armazenamento válidos incluem text, boolean, integer, float, timestamptz, jsonb e uuid.

Apresentação de aplicativos e gráficos no Chat

Após verificar o aplicativo, vincule seu diretório relativo ao proprietário, por exemplo [AI Adoption](~/apps/ai-adoption). O Electron Desktop resolve diretórios de aplicativos instalados em relação ao catálogo de aplicativos e os abre através do comportamento normal do launcher. Não afirme que uma pasta arbitrária é um aplicativo instalado.

Exiba gráficos ou capturas de tela salvos com imagens Markdown e caminhos completos relativos ao proprietário, por exemplo ![AI adoption chart](~/apps/ai-adoption/chart-light.png). O Electron Desktop pode exibir essas imagens e abri-las na Visualização de Arquivos; não diga ao usuário que as imagens só podem aparecer no terminal do agente. Use links Markdown para outros arquivos salvos. Pré-visualizações HTML estáticas são isoladas sem scripts; vincule o aplicativo instalado para um gráfico interativo em vez de prometer execução HTML ativa dentro do Chat. Relate arquivos ausentes ou falhas de pré-visualização com veracidade.

Nomenclatura

  • name é o rótulo legível por humanos, em Title Case, mostrado no launcher, dock e barra de título — ex. "Calorie Tracker", "Habit Garden". Torne-o curto e real; nunca mostre o slug para os usuários.
  • slug é o identificador em letras minúsculas, hifenizado, usado em caminhos/URLs (^[a-z0-9][a-z0-9-]{0,63}$). Derive-o do nome (calorie-tracker). É interno — não o use como string de exibição em lugar nenhum.

Ícone (obrigatório — ou o aplicativo mostra um tile quebrado)

O launcher carrega o ícone de cada aplicativo de ~/system/icons/<icon>.svg (ou .png) correspondente ao campo icon do manifesto. Se você não enviar esse arquivo, /icons/<icon> retorna 404 e o aplicativo fica com um ícone quebrado/substituto. Portanto, sempre:

  1. Defina "icon": "<slug>" em matrix.json (use o slug do aplicativo a menos que tenha um nome de conceito melhor).
  2. Crie ~/system/icons/<slug>.png usando o estilo de ícone enviado do Matrix OS: arte de ícone de aplicativo skeuomórfico premium iOS/macOS claro, renderização de produto refinada ao estilo Apple, fundo off-white claro ou pastel pálido, profundidade sutil de cerâmica/vidro, chanfros suaves, realces brilhantes, sombras de estúdio realistas e um único objeto ou símbolo 3D tátil grande que represente claramente o aplicativo. Mantenha a família de ícones alinhada com os acentos floresta, creme, brasa e profundos do Matrix OS. Não inclua texto, logotipos, marcas d'água, fundos transparentes, fundos de dock pretos/escuros, preenchimento vazio ou uma moldura de ícone visível separada; o shell Matrix é dono do raio de canto final. Mantenha a iluminação e o tratamento de material consistentes com os PNGs de aplicativo padrão enviados em ~/system/icons/.

Para aplicativos de primeira parte/padrão, prefira ícones PNG commitados de home/system/icons/. SVGs são aceitáveis apenas para chrome do sistema ou fallbacks de compatibilidade simples, não para logotipos de aplicativo recém-gerados.

Dados (Postgres via ponte MatrixOS)

Os aplicativos são executados em um iframe com sandbox e origem nula (CSP connect-src 'self'), portanto um fetch() direto para /api/bridge/* é bloqueado e localStorage lança SecurityError. Persista SOMENTE através da ponte injetada:

  • Declare suas tabelas em storage.tables do matrix.json (acima). O gateway provisiona o esquema Postgres automaticamente — na inicialização para aplicativos enviados, e lazy na primeira consulta para aplicativos que você construir agora, portanto, chamadas db de um aplicativo recém-construído funcionam sem qualquer reinicialização.
  • No código, use window.MatrixOS.db (find/findOne/insert/update/delete/count/onChange). Proteja contra undefined (está ausente em testes de unidade), envolva cada chamada em try/catch (log + erro visível ao usuário; nunca um catch vazio), atualize o estado local de forma otimista e reconcilie em onChange.
  • Para APIs externas/de terceiros, use window.MatrixOS.proxyFetch(url) (na lista de permissões) — nunca um fetch bruto.
  • NÃO adicione um fallback de localStorage que execute no shell; ele lança no sandbox. Um caminho try/catch protegido para localStorage é aceitável apenas como uma operação nula para o ambiente de teste de unidade.

Herança de Tema

O shell injeta tokens --matrix-* em cada iframe de aplicativo com ponte e os atualiza em alterações de tema. Construa o CSS do aplicativo nesses tokens primeiro, com cores literais apenas como 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);
}

Use as fontes do shell herdadas (var(--matrix-font-sans), var(--matrix-font-mono)) em vez de carregar folhas de estilo de fonte remotas. Não use paletas azul, verde ou roxo locais do aplicativo para UI padrão. Se for necessário branding explícito do aplicativo, escope-o a tokens de marca nomeados e mantenha controles do sistema, estados de foco, cores de status e painéis nos tokens Matrix.

Regras de Persistência

  • Declare cada campo persistido em storage.tables do matrix.json, incluindo campos de auditoria como created_at, colunas de melhor pontuação/melhor tempo e payloads de estado JSONB.
  • Carregue do armazenamento da ponte na inicialização; não propague linhas de fallback duplicadas após o carregamento de linhas reais.
  • Reverta alterações otimistas de UI em criações, atualizações, exclusões e reordenações com falha. Mantenha exclusões pendentes filtradas do estado visível até que a ponte confirme ou reverta.
  • Serialize gravações dependentes que atualizam ordenação, melhores pontuações, contadores de estatísticas ou linhas de histórico. Evite que duas gravações da ponte corram e possam sobrescrever o estado derivado uma da outra.
  • Mantenha ajudantes apenas do navegador protegidos para testes. Em iframes de shell de produção, o acesso direto a localStorage e chamadas fetch() brutas da ponte não são persistência confiável.

Aplicativos Padrão de Primeira Parte

Ao editar aplicativos padrão agrupados neste repositório:

  • Mantenha manifestos e esquemas de aplicativos em home/apps/<slug>/matrix.json.
  • Reutilize o caminho de build Vite do aplicativo padrão compartilhado; não adicione campos de pacote/runtime desatualizados por aplicativo a menos que o aplicativo realmente precise deles.
  • Execute node scripts/build-default-apps.mjs home/apps antes do trabalho de pacote do host quando o código-fonte do aplicativo padrão mudar.
  • Prefira o ícone compartilhado game-center para jogos, a menos que exista um ícone concreto enviado.
  • Verifique slugs de ícones de aplicativos em relação a home/system/icons/<slug>.svg ou .png; nunca confie na geração de ícones em tempo de execução.

Comandos de Scaffold

Prefira copiar o template Vite agrupado do Matrix quando ele existir:

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

Se o template não estiver presente, crie os arquivos Vite padrão diretamente com react, react-dom, @vitejs/plugin-react, typescript e vite.

Acesso a Dados

Use a ponte window.MatrixOS.db injetada para dados estruturados. Não chame /api/bridge/query diretamente do código do aplicativo; aplicativos em tempo de execução carregam como iframes srcdoc com sandbox, e fetches diretos da ponte são bloqueados pelo limite CORS/CSP do shell.

Exemplo CRUD:

const db = window.MatrixOS?.db;
if (!db) throw new Error("Ponte de dados Matrix indisponível");

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

Integrações

Se o aplicativo precisar de Gmail, Agenda, GitHub, Slack, Drive ou outro provedor, use APIs de integração Matrix ou a skill matrix-integrations. A plataforma gerencia as credenciais do provedor. O aplicativo nunca armazena segredos de provedores.

Verificação

Antes de relatar como concluído:

cd ~/apps/<slug>
pnpm build
test -f dist/index.html
node <caminho-resolvido-do-diretório-da-skill-matrix-app-builder>/scripts/verify-app.mjs "$PWD"

Resolva o diretório da skill a partir do SKILL.md que você carregou; o script é enviado junto a ele e não precisa de dependências. Execute-o no diretório real do aplicativo, não no template. Ele verifica o manifesto Vite construído pelo proprietário e a entrada de produção; nunca altera a confiança ou prova um login ativo.

Lançamento e autenticação

O Matrix fornece autenticação do proprietário. Não construa uma página de login separada nem leia/copie credenciais de gateway para o aplicativo. O launcher nativo obtém um token de curta duração através de POST /api/apps/<slug>/session-token; o lançamento é /apps/<slug>/. listingTrust ausente ou desconhecido resulta em 403 install_blocked_by_policy, não em um login expirado. Um aplicativo existente que você acabou de construir para o proprietário pode ter seus metadados ausentes corrigidos após verificar sua origem; nunca promova silenciosamente um aplicativo importado. 401 significa autenticação, 403 política, 409 escopo/reconhecimento, 404 descoberta e 5xx uma falha de servidor. Relate falhas com precisão em vez de recomendar login para todas elas. Não desabilite a autenticação, enfraqueça a política, reinicie o VPS ou adicione um servidor para contornar uma falha de lançamento.

Em seguida, abra o aplicativo a partir do launcher Matrix usando a sessão autenticada existente. Verifique ativos do aplicativo, ícone, operações da ponte, um ciclo de ida e volta salvar/reabrir e as verificações visuais/de estado da referência de craft. Se o acesso ao navegador não estiver disponível, relate a verificação de lançamento e visual como pendente em vez de afirmar que o aplicativo funciona. Verifique o console/rede do navegador para:

  • needs_build
  • 404s para pacotes de aplicativos ou caminhos de ícone
  • erros CORS de chamadas diretas de provedores
  • erros React não tratados

Habilidades Relacionadas