create-nodebuilderjs 0.1.0 → 0.2.0

package/index.js

@@ -2,7 +2,7 @@
 // bun create nodebuilderjs [dir] [--title "Meu App"] [--no-install] [--no-git]
 // Plain JS (not TS) so it runs under both `bun create` and `npm create`.
 import { spawnSync } from "node:child_process";
-import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, symlinkSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
@@ -46,6 +46,17 @@ cpSync(join(here, "template"), target, { recursive: true });
 // npm drops .gitignore from published packages, so the template ships it as _gitignore.
 renameSync(join(target, "_gitignore"), join(target, ".gitignore"));
 
+// Skills live in .agents/skills (read by Codex, Cursor, OpenCode, Gemini CLI, Copilot). Claude
+// Code only reads .claude/skills, where each skill may be a symlink. Made here, relative,
+// because npm packs and cpSync don't keep relative symlinks.
+const skills = join(target, ".agents", "skills");
+if (existsSync(skills)) {
+  mkdirSync(join(target, ".claude", "skills"), { recursive: true });
+  for (const skill of readdirSync(skills)) {
+    symlinkSync(join("..", "..", ".agents", "skills", skill), join(target, ".claude", "skills", skill), "dir");
+  }
+}
+
 const fill = (file) => {
   const path = join(target, file);
   writeFileSync(path, readFileSync(path, "utf8").replaceAll("{{title}}", title).replaceAll("{{appId}}", appId));

package/package.json

@@ -1,13 +1,23 @@
 {
   "name": "create-nodebuilderjs",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Cria um app nodebuilder: bun create nodebuilderjs meu-app",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felipebrgs1/nodebuilderjs.git",
+    "directory": "packages/create-nodebuilderjs"
+  },
+  "homepage": "https://github.com/felipebrgs1/nodebuilderjs#readme",
+  "bugs": "https://github.com/felipebrgs1/nodebuilderjs/issues",
   "bin": {
     "create-nodebuilderjs": "./index.js"
   },
-  "files": ["index.js", "template"],
+  "files": [
+    "index.js",
+    "template"
+  ],
   "engines": {
     "node": ">=20"
   },

package/template/.agents/skills/nodebuilder-desempenho/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: nodebuilder-desempenho
+description: Medir e melhorar o desempenho de apps nodebuilder (fps, CPU, memória) e evitar padrões lentos em listas grandes, atualizações frequentes e animações. Use quando o app estiver lento, travando, usando muita CPU/memória, ou ao criar listas com centenas de itens, dados ao vivo ou animações.
+---
+
+# Desempenho
+
+## Medir
+
+```sh
+NB_STATS=1 bun src/main.tsx      # por segundo: fps, ms de estado/layout/pintura/nativo, nós, memória
+NB_MAX_FPS=60 bun src/main.tsx   # teto de fps (padrão 120); também run(app, { maxFps: 60 })
+```
+
+Parado, o app não desenha nada (0% de CPU). Mudanças de estado agendam um frame; várias
+mudanças antes dele saem juntas no mesmo frame.
+
+## Padrões
+
+- **Listas grandes:** sempre dentro de `<Scroll>`; o que está fora da área visível não é
+  posicionado nem desenhado. Mesmo assim cada item vira nós: com milhares, filtre ou pagine.
+- **`<For>` é keyed por referência:** recriar os objetos (`lista.map((x) => ({ ...x }))`)
+  destrói e recria todas as linhas. Mantenha as referências e mude só o que mudou; para
+  campos que mudam muito, guarde um signal dentro do item (`{ id, cpu: createSignal(0) }`).
+- **Atualize o mínimo:** um signal por valor que muda, e funções finas nos props
+  (`text={() => fmt(item.cpu())}`) em vez de um signal gigante com o estado todo.
+- **Várias mudanças juntas:** `batch(() => { setA(1); setB(2); })` gera um único frame e
+  roda os effects uma vez.
+- **Animação e dados ao vivo:** use `requestAnimationFrame(cb)` (ritmado pela tela), não
+  `setInterval` curto. Para parar, simplesmente não peça o próximo frame.
+- **Texto:** medidas ficam em cache; textos que mudam todo frame (contadores, relógios)
+  custam pouco, mas evite gerar milhares de strings novas por frame.
+- **Imagens:** decodificar é caro e síncrono; reutilize o mesmo arquivo (é compartilhado) e
+  use arquivos do tamanho exibido.
+- Trabalho pesado de CPU (parse de arquivos grandes, cálculos) trava a interface: divida em
+  pedaços com `setTimeout(..., 0)` ou use um `Worker`.

package/template/.agents/skills/nodebuilder-desenho/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: nodebuilder-desenho
+description: Desenho livre no nodebuilder com o widget Canvas (linhas, polígonos, arcos, medidores, sparklines, anotações, visualizações sob medida). Use para formas que não são retângulos e gráficos que @nodebuilderjs/core/charts não cobre, no lugar do <canvas> do navegador ou D3. Para gráficos de linha, área, barra e pizza comuns, use a skill nodebuilder-graficos.
+---
+
+# Desenho com `<Canvas>`
+
+```tsx
+import { Canvas, createSignal, theme } from "@nodebuilderjs/core";
+
+const [dados, setDados] = createSignal([12, 40, 33, 70, 55, 90]);
+
+<Canvas height={160} draw={(g) => {
+  const v = dados();                                      // signals lidos aqui redesenham o canvas
+  const x = (i: number) => (i / (v.length - 1)) * g.width;
+  const y = (n: number) => g.height - (n / 100) * g.height;
+  for (let n = 0; n <= 100; n += 25) g.line(0, y(n), g.width, y(n), "#0000001a", 1, "butt");  // grade
+  const pts = v.flatMap((n, i) => [x(i), y(n)]);
+  g.polygon([0, g.height, ...pts, g.width, g.height], "#3584e433");   // área
+  g.polyline(pts, theme.accent.base, 2);                              // linha
+  g.circle(x(v.length - 1), y(v[v.length - 1]!), 4, theme.accent.base);
+  g.text("máx 100", 4, 0, theme.text.secondary, 11);
+}} />
+```
+
+## API (`g`)
+
+| Método | O quê |
+|---|---|
+| `g.width`, `g.height` | tamanho do canvas (dentro do `padding`) |
+| `rect(x, y, w, h, cor, raio?)` | retângulo (barras) |
+| `line(x0, y0, x1, y1, cor, largura = 1, ponta = "round")` | segmento; ponta `round`, `butt` (reta) ou `square` |
+| `polyline(pontos, cor, largura = 1, { cap, closed })` | linha por vários pontos `[x0, y0, x1, y1, ...]`, junções redondas |
+| `polygon(pontos, cor)` | polígono preenchido (côncavo pode; cruzando a si mesmo não desenha) |
+| `circle(cx, cy, raio, cor)` | disco |
+| `arc(cx, cy, raioExterno, raioInterno, início, varredura, cor)` | fatia (interno 0) ou anel; radianos, 0 = cima, sentido horário |
+| `text(texto, x, y, cor, tamanho?, negrito?)`, `measureText(texto, tamanho?)` | rótulos; `y` é o topo da linha |
+
+## Regras
+
+- Dê tamanho ao canvas: `width`/`height` ou `grow`. Sem tamanho, `draw` não roda.
+- Coordenadas locais, com `y` para baixo. Inverta para gráficos: `g.height - valor * escala`.
+- `draw` deve só desenhar: nada de criar signals, effects ou chamar `set` lá dentro.
+- O canvas redesenha quando um signal lido em `draw` muda ou o tamanho muda; a geometria
+  fica gravada, então outras partes da janela redesenhando não custam nada aqui.
+- Dados ao vivo: atualize o signal com `requestAnimationFrame`; milhares de pontos
+  funcionam (5000 pontos de linha + área a ~120 fps).
+- Pizza/rosca: some as fatias em radianos (`fração * 2 * Math.PI`); um pequeno vão
+  (`- 0.03` na varredura) separa as fatias visualmente.
+- Cores translúcidas em `polyline` escurecem nas junções: prefira cores opacas para linhas
+  e translúcidas para áreas.
+- Interação (tooltip, clique num ponto, arrastar): use `onPointerMove`/`onClick` no próprio
+  `Canvas`; `e.localX`/`e.localY` estão nas mesmas coordenadas do desenho (o `padding`
+  desloca: subtraia-o).

package/template/.agents/skills/nodebuilder-empacotar/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: nodebuilder-empacotar
+description: Gerar e distribuir o app nodebuilder (AppImage, .deb, .rpm, .tar.gz) com nodebuilder package, incluir arquivos (imagens, dados) no executável e configurar nome, ícone e app id. Use ao preparar uma versão para instalar, ao mudar o nome/ícone do app ou quando o app empacotado se comporta diferente do bun run dev.
+---
+
+# Empacotar
+
+```sh
+bun run package        # = nodebuilder package src/main.tsx --title "..." --app-id ...
+bunx nodebuilder package src/main.tsx --targets deb,rpm --icon assets/icone.svg --version 1.2.0
+bunx nodebuilder package --help
+```
+
+Gera em `dist/` um executável único (Bun + app + núcleo nativo, ~31 MB compactado) dentro de
+AppImage, `.deb`, `.rpm` e `.tar.gz`, com atalho no menu e ícone. Roda em distros com glibc
+2.34+ (Ubuntu 22.04+, Debian 12+, Fedora, RHEL 9+).
+
+## Regras
+
+- **Arquivos do app** (imagens, JSON, sons) entram no executável só se forem importados com
+  `with { type: "file" }` (o import vira o caminho). `readFileSync("./dados.json")` com
+  caminho solto funciona no dev e **falha no pacote**. Para JSON, `import dados from
+  "./dados.json"` também embute.
+- O `appId` da `<Window>` precisa ser igual ao `--app-id` (o template já faz isso); senão o
+  ícone e o agrupamento na barra de tarefas não funcionam.
+- `--icon`: `.svg` ou PNG 256x256. `--name` é o nome do executável/pacote (minúsculas).
+- Bibliotecas do sistema (Wayland, X11, EGL, FreeType, HarfBuzz, fontconfig) são
+  dependências declaradas dos pacotes, nunca embutidas. `libheif` (só para AVIF/HEIC) é
+  apenas sugerida.
+- Dados do usuário: salve em `~/.local/share/<app>` (`process.env.XDG_DATA_HOME`), nunca
+  ao lado do executável (em `/usr/bin` não dá para escrever).
+
+## Verificar
+
+- Rode o executável gerado fora da pasta do projeto (`cd / && caminho/do/app`) para pegar
+  arquivos que só existiam no disco do desenvolvimento.
+- AppImage: `chmod +x dist/*.AppImage && ./dist/*.AppImage`.

package/template/.agents/skills/nodebuilder-graficos/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: nodebuilder-graficos
+description: Gráficos de linha, área, barra, composto e pizza/rosca no nodebuilder com @nodebuilderjs/core/charts, que usa a mesma API do Recharts. Use ao criar dashboards, relatórios, séries temporais, comparações por categoria ou participação (pizza), e sempre que pensaria em usar Recharts, Chart.js ou Victory.
+---
+
+# Gráficos com `@nodebuilderjs/core/charts`
+
+Já vem no `@nodebuilderjs/core` (não instale nada); só entra no app se for importado.
+
+```tsx
+import { createSignal, theme } from "@nodebuilderjs/core";
+import {
+  Area, AreaChart, Bar, BarChart, CartesianGrid, Cell, Legend, Line, LineChart, Pie, PieChart, XAxis, YAxis,
+} from "@nodebuilderjs/core/charts";
+
+const [vendas] = createSignal([
+  { mes: "jan", receita: 120, meta: 100 },
+  { mes: "fev", receita: 150, meta: 110 },
+  { mes: "mar", receita: 90, meta: 120 },
+]);
+const canais = [{ nome: "Loja", valor: 42 }, { nome: "Site", valor: 31 }];
+
+export const graficos = () => (
+  <>
+    <LineChart data={vendas} height={240}>
+      <CartesianGrid vertical={false} />
+      <XAxis dataKey="mes" />
+      <YAxis tickFormatter={(v) => `R$ ${v}`} />
+      <Line dataKey="receita" name="Receita" />
+      <Line dataKey="meta" name="Meta" stroke="#e5a50a" type="monotone" dot={false} />
+      <Legend />
+    </LineChart>
+    <BarChart data={vendas} height={200}>
+      <XAxis dataKey="mes" />
+      <YAxis />
+      <Bar dataKey="receita" fill={theme.accent.base} radius={3} />
+    </BarChart>
+    <AreaChart data={vendas} height={160}>
+      <YAxis domain={[0, 200]} />
+      <Area dataKey="receita" type="monotone" />
+    </AreaChart>
+    <PieChart height={220}>
+      <Pie data={canais} dataKey="valor" nameKey="nome" innerRadius="50%" paddingAngle={2}>
+        <Cell fill="#3584e4" />
+        <Cell fill="#26a269" />
+      </Pie>
+      <Legend />
+    </PieChart>
+  </>
+);
+```
+
+## O que é suportado
+
+| Componente | Props |
+|---|---|
+| `LineChart`, `AreaChart`, `BarChart`, `ComposedChart` (mistura) | `data` (array ou signal), `height` (240), `width` ou `grow` e as props de estilo |
+| `Line` | `dataKey`, `name`, `stroke`, `strokeWidth` (2), `strokeDasharray` (`"6 4"`), `dot` (true), `type` (`linear`/`monotone`) |
+| `Area` | `dataKey`, `name`, `stroke`, `fill`, `fillOpacity` (0,25), `type`, `stackId` |
+| `Bar` | `dataKey`, `name`, `fill`, `radius`, `stackId`, `label` (true ou `(valor) => texto`) |
+| `XAxis` | `dataKey`, `tickFormatter`, `hide` |
+| `YAxis` | `domain={[min, max]}`, `tickCount`, `tickFormatter`, `hide` |
+| `CartesianGrid` | `horizontal`, `vertical`, `stroke`, `strokeDasharray` |
+| `PieChart` + `Pie` | `data`, `dataKey`, `nameKey`, `innerRadius`, `outerRadius` (px ou `"80%"`), `paddingAngle` (graus), `label` (true ou `({ name, value, percent }) => texto`); `<Cell fill>` por fatia |
+| `Tooltip` | `formatter(valor, nome)`, `labelFormatter(categoria)`; linha-guia na categoria sob o mouse (na pizza: a fatia) |
+| `Legend` | sem props (embaixo, centralizada) |
+
+`dataKey` é o nome do campo ou uma função `(linha) => valor`.
+
+## Diferenças do Recharts
+
+- **Sem `ResponsiveContainer`:** o gráfico já ocupa a largura do pai; dê `height`.
+- Séries com o mesmo `stackId` se empilham (barras numa coluna só, áreas uma sobre a outra);
+  o eixo y considera os totais.
+- O eixo x omite rótulos que se sobreporiam, mantendo o último (como `interval="preserveEnd"`).
+- Não existem ainda: `Brush`, `ReferenceLine`, `ScatterChart`, `RadarChart`, eixos
+  secundários, animações; em `Line`, o `label`.
+- Pizza começa no topo e gira no sentido horário (`startAngle`/`endAngle` não existem); os
+  rótulos ficam fora das fatias, então deixe `outerRadius` em ~70% para caberem.
+- Cores: sem `stroke`/`fill`, cada série pega a próxima cor da paleta (a primeira é
+  `theme.accent.base`).
+- Para algo fora disso, desenhe com `<Canvas>` (skill `nodebuilder-desenho`).
+
+## Desempenho
+
+Mudar o signal de `data` redesenha só aquele gráfico. Atualizar a cada frame (dados ao
+vivo com `requestAnimationFrame`) funciona; centenas de pontos por série são tranquilos.

package/template/.agents/skills/nodebuilder-icones/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: nodebuilder-icones
+description: Ícones e SVG no nodebuilder com o widget Icon, usando Lucide (lucide-static ou lucide) e Phosphor (@phosphor-icons/core). Use ao adicionar ícones a botões, menus, barras laterais ou listas, ao escolher uma biblioteca de ícones, ou ao mostrar qualquer arquivo .svg.
+---
+
+# Ícones
+
+```sh
+bun add lucide-static              # arquivos .svg do Lucide
+bun add lucide                     # ou: os mesmos ícones como dados (import { Camera } from "lucide")
+bun add @phosphor-icons/core       # Phosphor: assets/<peso>/<nome>.svg
+```
+
+```tsx
+import { Button, Icon, Row, Text, createSignal, theme } from "@nodebuilderjs/core";
+import camera from "lucide-static/icons/camera.svg" with { type: "text" };
+import heart from "@phosphor-icons/core/assets/duotone/heart-duotone.svg" with { type: "text" };
+import { Star } from "lucide";
+
+const [ativo] = createSignal(false);
+
+<Icon svg={camera} />                                  // 20 px, cor do texto ao redor
+<Icon svg={heart} size={32} color="#e01b24" />
+<Icon svg={Star} size={16} strokeWidth={1.5} />        // espessura do traço (ícones de contorno)
+<Button variant="primary"><Icon svg={Star} size={16} /><Text>Favoritar</Text></Button>
+<Row color={() => (ativo() ? theme.accent.base : theme.text.secondary)}>
+  <Icon svg={camera} /><Text>Câmera</Text>              {/* ícone e texto mudam de cor juntos */}
+</Row>
+```
+
+## Regras
+
+- **Nunca** use `lucide-react`, `lucide-solid`, `@phosphor-icons/react`, `react-icons` ou
+  `@heroicons/react`: eles exigem React/DOM. Use os pacotes acima.
+- Importe arquivos `.svg` com `with { type: "text" }` (o import vira o texto do SVG e o
+  `nodebuilder package` o embute). `with { type: "file" }` (caminho) também funciona.
+- `svg` aceita: texto do SVG, caminho de um `.svg` ou os dados do pacote `lucide`. Pode ser
+  uma função (`svg={() => (aberto() ? chevronUp : chevronDown)}`).
+- `size` é a altura em px lógicos (padrão 20, `theme.icon.size`); a largura segue o
+  `viewBox`. A cor vem de `color` no próprio `Icon` ou é herdada de um pai, como no `Text`.
+- Trocar a cor é de graça (ícones de uma cor são tingidos na GPU); trocar o tamanho
+  rasteriza de novo (~0,5 ms). Ficam nítidos em telas HiDPI.
+- Pesos do Phosphor: `thin`, `light`, `regular`, `bold`, `fill`, `duotone` (pastas em
+  `assets/`; nomes com o sufixo do peso, exceto `regular`: `heart.svg`, `heart-fill.svg`).
+
+## Limites do SVG
+
+Suportado: `path` (com arcos e curvas), `rect`, `circle`, `ellipse`, `line`, `polyline`,
+`polygon`, `g`, `transform`, `fill`/`stroke` (cores, `currentColor`), espessura, pontas,
+junções, `fill-rule`, opacidades e `style=""` inline.
+Não suportado (o resto do desenho aparece): gradientes, padrões, texto, filtros, máscaras,
+recortes, `<use>`, tracejado e `<style>`. Logos e ilustrações assim: exporte um PNG 2x e
+use `Image`.

package/template/.agents/skills/nodebuilder-imagens/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: nodebuilder-imagens
+description: Mostrar imagens (PNG, JPEG, WebP, AVIF, HEIC) com o widget Image do nodebuilder e incluir os arquivos no app empacotado. Use ao adicionar fotos, logos, avatares, miniaturas ou qualquer arquivo de imagem à interface. Para ícones e SVG, use a skill nodebuilder-icones.
+---
+
+# Imagens
+
+```tsx
+import { Image } from "@nodebuilderjs/core";
+import logo from "./assets/logo.png" with { type: "file" };
+
+<Image src={logo} width={64} />                       // altura segue a proporção
+<Image src={foto} width={200} height={120} fit="cover" radius={12} />
+<Image src={() => avatarDe(usuario())} width={32} height={32} radius={16} opacity={0.9} />
+```
+
+## Regras
+
+- **Importe arquivos com `with { type: "file" }`.** O import vira o caminho do arquivo, e o
+  `nodebuilder package` embute a imagem no executável. `new URL("./x.png", import.meta.url)`
+  e caminhos soltos funcionam no `bun run dev`, mas **quebram no app empacotado**.
+- `src` aceita: caminho (relativo ao diretório atual), `URL` `file:`, bytes do arquivo
+  (`Uint8Array`, ex.: de um `fetch`) ou pixels `{ width, height, data }` (RGBA 8 bits).
+  Pode ser uma função: trocar o `src` libera a imagem antiga.
+- Tamanho: sem `width`/`height`, usa os pixels do arquivo (1 pixel = 1 px lógico). Com só um
+  dos dois, o outro segue a proporção. Para telas HiDPI, use um arquivo 2x maior e fixe o
+  tamanho (`width={64}` para um PNG de 128 px).
+- `fit`: `contain` (padrão, imagem inteira centralizada), `cover` (preenche e corta), `fill`
+  (estica). `radius` arredonda; `opacity` vai de 0 a 1.
+- O mesmo arquivo em vários lugares é decodificado uma vez; a memória é liberada quando o
+  último `Image` sai da tela.
+- Arquivo que não carrega: aviso no console e nada desenhado (o app não quebra).
+
+## Formatos
+
+| Formato | Como | Observação |
+|---|---|---|
+| PNG, JPEG, WebP | decodificados em TypeScript | sempre funcionam; JPEG respeita a orientação do EXIF |
+| AVIF, HEIC | biblioteca do sistema `libheif` | sem ela, só esses dão erro ("needs libheif"); o pacote `.deb`/`.rpm` a sugere, mas não instala. Prefira WebP/PNG/JPEG para imagens do próprio app |
+| SVG | pelo widget `Icon` (skill `nodebuilder-icones`) | subconjunto para ícones; ilustrações com gradiente/texto: exporte PNG 2x |
+| GIF animado, vídeo | não suportado | |
+
+## Cuidados
+
+- A decodificação é síncrona: uma foto de 4 megapixels leva ~0,1 s e trava a interface
+  nesse meio-tempo. Reduza imagens grandes antes de colocar no app (ex.: miniaturas).
+- Imagens muito reduzidas na tela ficam serrilhadas (sem mipmaps): use arquivos perto do
+  tamanho exibido.
+- Em `bun test`, `Image` funciona sem janela (as texturas são simuladas); AVIF/HEIC
+  precisam do addon nativo e da libheif.

package/template/.agents/skills/nodebuilder-sem-react/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: nodebuilder-sem-react
+description: Tradução de hábitos de React, DOM, CSS e bibliotecas web para o nodebuilder, e quais pacotes npm funcionam. Use antes de instalar qualquer biblioteca de UI, ícones, componentes, estado ou estilo (lucide-react, MUI, Tailwind, styled-components, react-*, solid-js...), ao escrever useState/useEffect/className/div/onChange, ou ao portar código React/Solid/HTML para este app.
+---
+
+# Vindo do React (ou da web)
+
+O nodebuilder desenha a interface com a GPU, sem navegador: **não existe DOM, CSS, React
+nem Solid**. O JSX parece o de sempre, mas os elementos são os widgets do
+`@nodebuilderjs/core`.
+
+## Tradução direta
+
+| Na web / React | No nodebuilder |
+|---|---|
+| `useState(0)` | `const [n, setN] = createSignal(0)`; leia com `n()` |
+| `useMemo` | `createMemo(() => ...)` |
+| `useEffect(() => ..., [deps])` | `createEffect(() => ...)` (deps automáticas) + `onCleanup` |
+| re-render do componente | não existe: o componente roda **uma vez** |
+| `{count}` em JSX | `{count}` (a função, não `count()`), senão fica fixo |
+| `style={{ padding: 8 }}`, `className` | props: `padding={8}`, `background="#fff"` |
+| `div`, `span`, `p`, `h1` | `Column`, `Row`, `Box`, `Text fontSize={24} bold` |
+| `onChange` de input | `TextField value={v} onInput={setV}` |
+| `list.map(...)` em JSX | `<For each={list}>{(item) => ...}</For>` |
+| `cond && <X/>` | `<Show when={() => cond()}><X/></Show>` |
+| `useContext` | módulos com signals exportados (estado global simples) |
+| CSS `:hover` | `onPointerEnter`/`onPointerLeave` + signal |
+| `fetch`, `fs`, timers | funcionam (APIs do Bun/Node); atualize signals com o resultado |
+
+## Bibliotecas npm
+
+- **Funcionam:** lógica pura sem DOM (date-fns, zod, lodash, clientes HTTP, SQLite do Bun,
+  parsers). Ícones em SVG puro com o widget `Icon`: `lucide-static`, `lucide` (os dados,
+  não o `createIcons()`) e `@phosphor-icons/core` (skill `nodebuilder-icones`).
+- **Não funcionam:** tudo que renderiza React/Solid/Vue ou mexe no DOM: `lucide-react`,
+  `lucide-solid`, `@phosphor-icons/react`, MUI, Chakra, shadcn/ui, Radix, Tailwind,
+  styled-components, react-router, bibliotecas de gráficos em canvas/SVG do navegador.
+- Gráficos: use `@nodebuilderjs/core/charts` (mesma API do Recharts; skill
+  `nodebuilder-graficos`) ou desenhe com `<Canvas>` (skill `nodebuilder-desenho`). Recharts,
+  Chart.js e D3 precisam do DOM e não funcionam.
+- Na dúvida: se o pacote importa `react`, `react-dom`, `solid-js/web` ou usa `document`,
+  ele não serve aqui.
+
+## Erros comuns
+
+- Ler o signal no corpo do componente (`const x = count();`) e esperar que atualize.
+- Desestruturar props reativas (`const { value } = props`) e perder a função.
+- Colocar `createSignal` dentro de um effect para "resetar" estado: crie fora e use `set`.

package/template/.agents/skills/nodebuilder-testes/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: nodebuilder-testes
+description: Escrever e depurar testes de apps nodebuilder com bun test, sem abrir janela (mount, findByText, click, interact para mouse e teclado, layout, debugTree). Use ao criar testes, ao verificar uma mudança de comportamento ou layout, ou quando um teste de componente falha.
+---
+
+# Testes sem janela
+
+`bun test` roda os arquivos de `test/`. Nada abre janela: `mount` monta a árvore com
+métricas de texto falsas (**8 px por caractere, linha de 20 px**), então o layout é
+determinístico.
+
+```tsx
+import { expect, test } from "bun:test";
+import { click, findAll, findByText, mount } from "@nodebuilderjs/core/testing";
+import { debugTree } from "@nodebuilderjs/core";
+import { App } from "../src/App.js";
+
+test("adiciona uma tarefa", () => {
+  const { root, relayout, dispose } = mount(() => <App />, { width: 800, height: 600 });
+  click(findByText(root, "Adicionar")!);          // sobe até o pai com onClick (o Button)
+  expect(findByText(root, /1 tarefa/)).toBeDefined();
+  relayout();                                     // recalcula posições após mudanças
+  const item = findByText(root, "Nova tarefa")!;
+  expect(item.y).toBeGreaterThan(0);
+  dispose();                                      // descarta effects e signals do app
+});
+```
+
+## API (`@nodebuilderjs/core/testing`)
+
+- `mount(view, size?)` → `{ root, relayout, dispose }`. Layout feito uma vez no `mount`;
+  chame `relayout()` antes de checar `x`, `y`, `width`, `height` depois de mudar estado.
+- `findByText(root, "texto" | /regex/)`: primeiro `Text` cujo conteúdo inteiro bate.
+- `findAll(root, (n) => ...)`: busca livre; `n.label` é `"Text \"...\""`, `"Button"`, `"Row"`...
+- `click(node)`: dispara o `onClick` do nó ou do ancestral mais próximo (atalho rápido).
+- `interact(root)`: mouse e teclado entregues como no app de verdade (hover, foco, captura
+  ao arrastar, Tab): `hover(n)`, `press(n)`, `release(n)`, `drag(n, dx, dy)`, `move(x, y)`,
+  `scroll(n, dy)`, `key("Return")`, `type("texto")` e `focused`.
+
+```tsx
+const ui = interact(root);
+ui.press(campo);            // foca o TextField
+ui.type("Ana");             // digita no campo focado
+ui.key("Return");           // dispara o onSubmit
+ui.drag(slider, 80, 0);     // arrasta 80 px para a direita
+```
+- `debugTree(node)` (de `@nodebuilderjs/core`): árvore com posições, ótimo para ver o layout.
+
+## Dicas
+
+- Estado muda na hora (signals são síncronos); não há `await` nem `act()`.
+- Prefira `interact` a chamar handlers à mão: ele testa também foco, hover e propagação.
+  Depois de mudanças que movem nós, chame `relayout()` antes de interagir de novo.
+- Teste cálculos de layout com tamanhos fixos (`width`, `height`) para não depender das
+  métricas falsas.
+- Antes de concluir uma tarefa: `bun run typecheck && bun test`.

package/template/.agents/skills/nodebuilder-ui/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: nodebuilder-ui
+description: Widgets, props de estilo e layout do nodebuilder (Window, Column, Row, Scroll, Text, Button, TextField, Checkbox, Card, For, Show, theme). Use ao criar ou mudar qualquer tela, formulário, lista, barra lateral ou layout de um app nodebuilder, ou quando um elemento não aparece, não cresce ou não rola como esperado.
+---
+
+# Interface com nodebuilder
+
+Tudo vem de `@nodebuilderjs/core`. Não há DOM nem CSS: widgets são funções e o estilo são
+props planas. Reatividade estilo SolidJS: **só funções são reativas** (veja o AGENTS.md).
+
+## Widgets
+
+| Widget | Para quê | Props principais |
+|---|---|---|
+| `Window` | raiz, uma por app, com barra de título própria | `title`, `width`, `height` (tamanho inicial), `appId`, `onClose` (retorne `false` para não fechar) |
+| `Column` / `Row` / `Box` | contêiner flex (coluna, linha; `Box` é coluna) | estilo + eventos |
+| `Scroll` | coluna com rolagem vertical | precisa de `grow={1}` ou `height`; filhos podem ser maiores |
+| `Text` | texto de uma linha (sem quebra automática) | filhos (`{count}`, `"a"`) ou `text={() => ...}` |
+| `Image` | PNG, JPEG, WebP, AVIF | veja a skill `nodebuilder-imagens` |
+| `Icon` | ícone SVG (Lucide, Phosphor), cor herdada como texto | `svg`, `size` (20), `color`, `strokeWidth`; skill `nodebuilder-icones` |
+| `Canvas` | desenho livre: linhas, polígonos, arcos, texto | `draw={(g) => ...}` + tamanho; skill `nodebuilder-desenho` |
+| `Button` | botão com foco e teclado | `label` ou filhos, `variant` (`default`, `primary`, `danger`, `flat`), `disabled`, `onClick` |
+| `TextField` | campo de texto controlado | `value` (accessor), `onInput(valor)`, `onSubmit`, `placeholder` |
+| `Checkbox` | caixa de seleção | `checked` (accessor), `onChange(marcado)`, `label` |
+| `Card` | coluna com fundo, borda, raio 12, padding 16, gap 8 | estilo |
+| `Divider` / `Spacer` | linha de 1 px / espaço flexível (`size` fixo opcional) | |
+| `<For each={lista}>{(item, i) => ...}</For>` | lista keyed por referência; `i` é um accessor | `fallback` |
+| `<Show when={() => ...} fallback={...}>` | condicional | |
+
+```tsx
+const [nome, setNome] = createSignal("");
+<TextField value={nome} onInput={setNome} onSubmit={salvar} placeholder="Nome" />
+<Checkbox checked={ativo} onChange={setAtivo} label="Ativo" />
+<Button label="Salvar" variant="primary" disabled={() => !nome()} onClick={salvar} />
+```
+
+## Props de estilo (qualquer widget)
+
+- Layout: `direction` (`"row"`/`"column"`), `gap`, `padding` (`8`, `[v, h]` ou
+  `[top, right, bottom, left]`), `width`, `height`, `minWidth`, `minHeight`, `maxWidth`,
+  `maxHeight`, `grow`, `align`, `justify`, `position: "absolute"` + `left`/`top`, `clip`.
+- Visual: `background`, `radius`, `borderWidth`, `borderColor`, `shadow={{ color, blur, y }}`.
+- Texto (herdados pelos filhos): `color`, `fontSize`, `bold`. Cursor: `cursor="pointer"`.
+- Cores são strings hex (`"#3584e4"`, `"#00000010"` com alfa) ou `"transparent"`.
+- Eventos em qualquer contêiner: `onClick`, `onPointerDown/Up/Enter/Leave`,
+  `onPointerMove`, `onScroll`, `onKeyDown`, `onFocus`, `onBlur`. Eventos de ponteiro trazem
+  `x`/`y` (janela) e `localX`/`localY` (relativos ao nó); enquanto o botão está pressionado,
+  `onPointerMove` continua chegando ao nó onde o clique começou, mesmo fora dele (arrastar,
+  sliders). `onKeyDown` só chega pelo caminho do elemento focado.
+- Qualquer prop aceita valor fixo ou função: `background={() => (sel() ? a : b)}`.
+
+## Regras do layout (flexbox simplificado)
+
+- `align` padrão é **stretch**: filhos ocupam toda a largura de uma coluna. Use
+  `align="start"`/`"center"` para encolher ao conteúdo.
+- `justify`: `start`, `center`, `end`, `space-between`. Não existe `space-around`/`evenly`.
+- `grow={1}` divide o espaço que sobra. Sem `grow`, o tamanho é o do conteúdo.
+- Um filho **não encolhe abaixo do próprio conteúdo** (como `min-size: auto` do CSS), exceto
+  `Scroll`, `clip` ou `minWidth/minHeight` explícito. Lista longa dentro de uma coluna
+  que cresce sem parar? Envolva em `<Scroll grow={1}>`.
+- Para um `Scroll` dentro de uma coluna com `grow`, a coluna também precisa de `minHeight={0}`.
+- Não há porcentagens, `flex-wrap`, grid nem quebra de linha de texto: monte linhas com `Row`
+  e larguras fixas (veja tabelas: `Text width={110}`) ou `grow`.
+
+## Tema e janela
+
+- Cores e tamanhos padrão em `theme` (`theme.text.secondary`, `theme.accent.base`,
+  `theme.danger.base`, `theme.divider`...). Mude `theme` antes de `run()` para personalizar.
+- `windowControls.close()`, `.minimize()`, `.toggleMaximize()`, `.setTitle(t)`;
+  `windowState.width()`, `.height()`, `.maximized()`, `.activated()` são accessors.
+- Ainda não existem: tema escuro, animações, quebra de linha, seleção de texto, IME,
+  várias janelas.

package/template/AGENTS.md

@@ -14,16 +14,21 @@ App nodebuilder: UI nativa para Linux em TSX, **sem DOM e sem React**. Leia ante
   `background={() => (ativo() ? "#3584e4" : "#0000")}`.
 - Listas: `<For each={lista}>{(item) => ...}</For>` (chave por referência). Condicional:
   `<Show when={() => ...} fallback={...}>`.
+- Estilo são props planas (`padding`, `gap`, `grow`, `background`...), não CSS. Não existem
+  `className`, `style={{}}`, `div`, `useState` nem bibliotecas de React (ex.: `lucide-react`).
 
-## Widgets e estilo
-- `Window` (raiz, uma por app), `Column`/`Row`/`Box`, `Scroll`, `Text`, `Button`, `TextField`,
-  `Checkbox`, `Card`, `Divider`, `Spacer`. Tudo vem de `@nodebuilderjs/core`.
-- Estilo são props planas, não CSS: `padding`, `gap`, `grow`, `align`, `justify`, `width`,
-  `height`, `background`, `radius`, `borderWidth`, `borderColor`, `color`, `fontSize`, `bold`.
-  Layout é flexbox; `align` padrão é `stretch`. `color`, `fontSize` e `bold` são herdados.
-- Cores padrão em `theme` (`theme.text.secondary`, `theme.accent.base`...).
-- Não existem `className`, `style={{}}`, `div`, `span`, `onChange` de DOM nem `useState`.
+## Skills (detalhes por assunto)
+Em `.agents/skills/<nome>/SKILL.md` (com links em `.claude/skills/` para o Claude Code). Agentes
+que suportam skills as carregam sozinhos; os outros devem ler a skill do assunto antes de começar:
 
-## Testes
-- `@nodebuilderjs/core/testing`: `mount(() => <App />)`, `findByText(root, "texto")`,
-  `click(node)` (sobe até o pai clicável). Métricas de texto falsas: 8 px por caractere.
+| Skill | Quando |
+|---|---|
+| `nodebuilder-ui` | telas, widgets, props de estilo, layout, `For`/`Show`, tema |
+| `nodebuilder-sem-react` | antes de instalar bibliotecas ou portar código React/web |
+| `nodebuilder-imagens` | imagens (PNG, JPEG, WebP, AVIF), arquivos no app |
+| `nodebuilder-icones` | ícones (Lucide, Phosphor) e SVG com `Icon` |
+| `nodebuilder-graficos` | gráficos prontos (`@nodebuilderjs/core/charts`, API do Recharts) |
+| `nodebuilder-desenho` | desenho livre com `Canvas` |
+| `nodebuilder-testes` | testes sem janela (`mount`, `findByText`, `click`) |
+| `nodebuilder-empacotar` | AppImage/.deb/.rpm, arquivos embutidos, ícone e app id |
+| `nodebuilder-desempenho` | lentidão, listas grandes, dados ao vivo, animação |