create-nodebuilderjs 0.2.1 → 0.2.5

package/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// bun create nodebuilderjs [dir] [--title "Meu App"] [--no-install] [--no-git]
+// bun create nodebuilderjs [dir] [--title "My 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, mkdirSync, readdirSync, readFileSync, renameSync, symlinkSync, writeFileSync } from "node:fs";
@@ -22,19 +22,19 @@ const { values: opts, positionals } = parseArgs({
 });
 
 if (opts.help) {
-  console.log(`uso: bun create nodebuilderjs [pasta] [--title "Meu App"] [--no-install] [--no-git]`);
+  console.log(`usage: bun create nodebuilderjs [folder] [--title "My App"] [--no-install] [--no-git]`);
   process.exit(0);
 }
 
 let dir = positionals[0];
 if (!dir) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
-  dir = (await rl.question("Nome do projeto: (meu-app) ")).trim() || "meu-app";
+  dir = (await rl.question("Project name: (my-app) ")).trim() || "my-app";
   rl.close();
 }
 const target = resolve(dir);
 if (existsSync(target) && readdirSync(target).length) {
-  console.error(`A pasta ${dir} já existe e não está vazia.`);
+  console.error(`The folder ${dir} already exists and is not empty.`);
   process.exit(1);
 }
 
@@ -84,8 +84,8 @@ const run = (cmd, args) => spawnSync(cmd, args, { cwd: target, stdio: "inherit"
 const hasBun = spawnSync("bun", ["--version"], { stdio: "ignore" }).status === 0;
 
 if (!opts["no-install"]) {
-  if (!hasBun) console.warn("Bun não encontrado: instale em https://bun.sh e rode `bun install`.");
-  else if (!run("bun", ["install"])) console.warn("`bun install` falhou; rode de novo dentro da pasta.");
+  if (!hasBun) console.warn("Bun not found: install it from https://bun.sh and run `bun install`.");
+  else if (!run("bun", ["install"])) console.warn("`bun install` failed; run it again inside the folder.");
 }
 if (!opts["no-git"] && spawnSync("git", ["--version"], { stdio: "ignore" }).status === 0) {
   run("git", ["init", "-q"]);
@@ -93,10 +93,10 @@ if (!opts["no-git"] && spawnSync("git", ["--version"], { stdio: "ignore" }).stat
 
 const cd = relative(process.cwd(), target) || ".";
 console.log(`
-Pronto! ${title} criado em ${cd}
+Done! ${title} created in ${cd}
 
   cd ${cd}
-  bun run dev        # abre a janela e recarrega ao salvar
-  bun test           # testes sem janela
-  bun run package    # AppImage, .deb, .rpm e .tar.gz em dist/
+  bun run dev        # opens the window and reloads on save
+  bun test           # tests without a window
+  bun run package    # AppImage, .deb, .rpm and .tar.gz in dist/
 `);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-nodebuilderjs",
-  "version": "0.2.1",
-  "description": "Cria um app nodebuilder: bun create nodebuilderjs meu-app",
+  "version": "0.2.5",
+  "description": "Creates a nodebuilder app: bun create nodebuilderjs my-app",
   "type": "module",
   "license": "MIT",
   "repository": {

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

@@ -0,0 +1,87 @@
+---
+name: nodebuilder-charts
+description: Line, area, bar, composed and pie/donut charts in nodebuilder with @nodebuilderjs/core/charts, which uses the same API as Recharts. Use when building dashboards, reports, time series, category comparisons or share breakdowns (pie), and whenever you would reach for Recharts, Chart.js or Victory.
+---
+
+# Charts with `@nodebuilderjs/core/charts`
+
+Already ships with `@nodebuilderjs/core` (install nothing); it only ends up in the app if imported.
+
+```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 [sales] = createSignal([
+  { month: "Jan", revenue: 120, target: 100 },
+  { month: "Feb", revenue: 150, target: 110 },
+  { month: "Mar", revenue: 90, target: 120 },
+]);
+const channels = [{ name: "Store", value: 42 }, { name: "Website", value: 31 }];
+
+export const charts = () => (
+  <>
+    <LineChart data={sales} height={240}>
+      <CartesianGrid vertical={false} />
+      <XAxis dataKey="month" />
+      <YAxis tickFormatter={(v) => `$${v}`} />
+      <Line dataKey="revenue" name="Revenue" />
+      <Line dataKey="target" name="Target" stroke="#e5a50a" type="monotone" dot={false} />
+      <Legend />
+    </LineChart>
+    <BarChart data={sales} height={200}>
+      <XAxis dataKey="month" />
+      <YAxis />
+      <Bar dataKey="revenue" fill={theme.accent.base} radius={3} />
+    </BarChart>
+    <AreaChart data={sales} height={160}>
+      <YAxis domain={[0, 200]} />
+      <Area dataKey="revenue" type="monotone" />
+    </AreaChart>
+    <PieChart height={220}>
+      <Pie data={channels} dataKey="value" nameKey="name" innerRadius="50%" paddingAngle={2}>
+        <Cell fill="#3584e4" />
+        <Cell fill="#26a269" />
+      </Pie>
+      <Legend />
+    </PieChart>
+  </>
+);
+```
+
+## What is supported
+
+| Component | Props |
+|---|---|
+| `LineChart`, `AreaChart`, `BarChart`, `ComposedChart` (mixed) | `data` (array or signal), `height` (240), `width` or `grow`, and the style props |
+| `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 or `(value) => text`) |
+| `XAxis` | `dataKey`, `tickFormatter`, `hide` |
+| `YAxis` | `domain={[min, max]}`, `tickCount`, `tickFormatter`, `hide` |
+| `CartesianGrid` | `horizontal`, `vertical`, `stroke`, `strokeDasharray` |
+| `PieChart` + `Pie` | `data`, `dataKey`, `nameKey`, `innerRadius`, `outerRadius` (px or `"80%"`), `paddingAngle` (degrees), `label` (true or `({ name, value, percent }) => text`); `<Cell fill>` per slice |
+| `Tooltip` | `formatter(value, name)`, `labelFormatter(category)`; guide line at the category under the mouse (on a pie: the slice) |
+| `Legend` | no props (bottom, centered) |
+
+`dataKey` is the field name or a function `(row) => value`.
+
+## Differences from Recharts
+
+- **No `ResponsiveContainer`:** the chart already fills the parent's width; give it a `height`.
+- Series with the same `stackId` stack (bars in a single column, areas on top of each other);
+  the y axis accounts for the totals.
+- The x axis drops labels that would overlap, keeping the last one (like `interval="preserveEnd"`).
+- Not available yet: `Brush`, `ReferenceLine`, `ScatterChart`, `RadarChart`, secondary
+  axes, animations; on `Line`, `label`.
+- Pies start at the top and go clockwise (`startAngle`/`endAngle` do not exist); the
+  labels sit outside the slices, so keep `outerRadius` around 70% for them to fit.
+- Colors: without `stroke`/`fill`, each series takes the next palette color (the first is
+  `theme.accent.base`).
+- For anything beyond this, draw with `<Canvas>` (skill `nodebuilder-drawing`).
+
+## Performance
+
+Changing the `data` signal redraws only that chart. Updating every frame (live data
+with `requestAnimationFrame`) works; hundreds of points per series are fine.

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

@@ -0,0 +1,54 @@
+---
+name: nodebuilder-drawing
+description: Freeform drawing in nodebuilder with the Canvas widget (lines, polygons, arcs, gauges, sparklines, annotations, custom visualizations). Use for non-rectangular shapes and charts that @nodebuilderjs/core/charts does not cover, instead of the browser <canvas> or D3. For regular line, area, bar and pie charts, use the nodebuilder-charts skill.
+---
+
+# Drawing with `<Canvas>`
+
+```tsx
+import { Canvas, createSignal, theme } from "@nodebuilderjs/core";
+
+const [data, setData] = createSignal([12, 40, 33, 70, 55, 90]);
+
+<Canvas height={160} draw={(g) => {
+  const v = data();                                       // signals read here redraw the 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");  // grid
+  const pts = v.flatMap((n, i) => [x(i), y(n)]);
+  g.polygon([0, g.height, ...pts, g.width, g.height], "#3584e433");   // area
+  g.polyline(pts, theme.accent.base, 2);                              // line
+  g.circle(x(v.length - 1), y(v[v.length - 1]!), 4, theme.accent.base);
+  g.text("max 100", 4, 0, theme.text.secondary, 11);
+}} />
+```
+
+## API (`g`)
+
+| Method | What |
+|---|---|
+| `g.width`, `g.height` | canvas size (inside the `padding`) |
+| `rect(x, y, w, h, color, radius?)` | rectangle (bars) |
+| `line(x0, y0, x1, y1, color, width = 1, cap = "round")` | segment; cap `round`, `butt` (flat) or `square` |
+| `polyline(points, color, width = 1, { cap, closed })` | line through several points `[x0, y0, x1, y1, ...]`, round joins |
+| `polygon(points, color)` | filled polygon (concave is fine; self-intersecting is not drawn) |
+| `circle(cx, cy, radius, color)` | disc |
+| `arc(cx, cy, outerRadius, innerRadius, start, sweep, color)` | slice (inner 0) or ring; radians, 0 = top, clockwise |
+| `text(text, x, y, color, size?, bold?)`, `measureText(text, size?)` | labels; `y` is the top of the line |
+
+## Rules
+
+- Give the canvas a size: `width`/`height` or `grow`. Without a size, `draw` does not run.
+- Local coordinates, with `y` pointing down. Flip it for charts: `g.height - value * scale`.
+- `draw` must only draw: do not create signals or effects or call `set` inside it.
+- The canvas redraws when a signal read in `draw` changes or its size changes; the geometry
+  is recorded, so other parts of the window redrawing cost nothing here.
+- Live data: update the signal with `requestAnimationFrame`; thousands of points
+  work (5000 line + area points at ~120 fps).
+- Pie/donut: accumulate the slices in radians (`fraction * 2 * Math.PI`); a small gap
+  (`- 0.03` on the sweep) separates the slices visually.
+- Translucent colors on `polyline` darken at the joins: prefer opaque colors for lines
+  and translucent ones for areas.
+- Interaction (tooltip, clicking a point, dragging): use `onPointerMove`/`onClick` on the
+  `Canvas` itself; `e.localX`/`e.localY` are in the same coordinates as the drawing (the `padding`
+  offsets them: subtract it).

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

@@ -0,0 +1,69 @@
+---
+name: nodebuilder-from-react
+description: Translation of React, DOM, CSS and web library habits to nodebuilder, and which npm packages work. Use before installing any UI, icon, component, state or styling library (lucide-react, MUI, Tailwind, styled-components, react-*, solid-js...), when writing useState/useEffect/className/div/onChange, or when porting React/Solid/HTML code to this app.
+---
+
+# Coming from React (or the web)
+
+nodebuilder draws the interface with the GPU, without a browser: **there is no DOM, CSS, React
+or Solid**. The JSX looks the same as always, but the elements are the widgets from
+`@nodebuilderjs/core`.
+
+## Direct translation
+
+| On the web / React | In nodebuilder |
+|---|---|
+| `useState(0)` | `const [n, setN] = createSignal(0)`; read with `n()` |
+| `useMemo` | `createMemo(() => ...)` |
+| `useEffect(() => ..., [deps])` | `createEffect(() => ...)` (automatic deps) + `onCleanup` |
+| component re-render | does not exist: the component runs **once** |
+| `{count}` in JSX | `{count}` (the function, not `count()`), otherwise it stays fixed |
+| `style={{ padding: 8 }}`, `className` | props: `padding={8}`, `background="#fff"` |
+| `div`, `span`, `p`, `h1` | `Column`, `Row`, `Box`, `Text fontSize={24} bold` |
+| input `onChange` | `TextField value={v} onInput={setV}` |
+| `<input type="range">`, `type="radio"`, MUI switch, `<progress>` | `Slider`, `RadioGroup`, `Toggle`, `ProgressBar`/`Spinner` |
+| `<select>`, Dialog/Modal, Tabs, Tooltip (MUI, Radix, shadcn) | `Select`, `Dialog`, `Tabs` (+ `<Switch>` for the content), `Tooltip` |
+| `disabled` on input/button | `disabled` on any control (value or function) |
+| `list.map(...)` in JSX | `<For each={list}>{(item) => ...}</For>` |
+| `list.map((x, i) => ...)` with `key={i}` (list of primitives) | `<Index each={list}>{(item, i) => ...}</Index>`; `item` is an accessor (`item()`), `i` is a number |
+| `cond && <X/>` | `<Show when={() => cond()}><X/></Show>` |
+| `cond ? <A/> : <B/>`, `switch` that returns JSX | `<Show when={...} fallback={<B/>}><A/></Show>`; several cases: `<Switch fallback={...}><Match when={() => s() === "a"}>...</Match></Switch>` |
+| `user && <X name={user.name}/>` | `<Show when={user}>{(u) => <X name={u().name} />}</Show>` (same as in Solid) |
+| error boundary (`componentDidCatch`, `react-error-boundary`) | `<ErrorBoundary fallback={(error, reset) => ...}>` (as in Solid); catches errors on creation and in effects, not in `onClick` code |
+| `createContext` / `useContext` | the same: `createContext(default)`, `<Ctx.Provider value={...}>`, `useContext(Ctx)`; a value that changes goes as an accessor |
+| `useRef` + `ref={r}` / `el.focus()` | `ref={(el) => ...}` on any widget: `el.focus()`, `el.blur()`, `el.scrollTo(y)`, `el.width` |
+| `overflow-y: auto` / `overflow-x: auto` / `overflow: auto` | `<Scroll>` / `<Scroll horizontal>` / `<Scroll horizontal vertical>` (with `grow={1}` or a size) |
+| `el.scrollIntoView()`, `el.scrollTo({ left, top })`, `scrollLeft`/`scrollTop` | `el.scrollIntoView()` (scrolls the minimum, on the next frame), `el.scrollTo({ x, y })`, `el.scrollX`/`el.scrollY` |
+| `min-height: 0` / `min-width: 0` around what scrolls | unnecessary: the content of a `Scroll` does not hold up the size of its container |
+| `ResizeObserver`, media queries | `onResize={(s) => setWidth(s.width)}` + signal |
+| `createPortal`, `position: fixed`, `z-index`, library modal/dropdown/tooltip | `<Overlay>` (`modal`, `anchor={() => el}`, `onDismiss`); skill `nodebuilder-ui` |
+| CSS `opacity`, `transform: translate(...)` | props `opacity`, `translateX`, `translateY` (no `scale`/`rotate`) |
+| `transition`, framer-motion, react-spring, `AnimatePresence` | `createTween`, `createPresence` (+ `<Show when={p.mounted}>`), `animate` |
+| `prefers-color-scheme`, `ThemeProvider` with a dark theme | `setTheme("dark")`, `colorScheme()`, colors in functions: `() => theme.text.primary` |
+| `white-space: nowrap` / `text-overflow: ellipsis` / `-webkit-line-clamp` | `wrap={false}` / `maxLines={1}` / `maxLines={n}` |
+| CSS `text-align`, `line-height` | `textAlign` (`start`/`center`/`end`), `lineHeight` (multiplier) |
+| CSS `:hover` | `onPointerEnter`/`onPointerLeave` + signal |
+| selectable text (the default on the web) | only with `<Text selectable>`; without the prop it does not select (like `user-select: none`) |
+| `navigator.clipboard.writeText/readText` | `clipboard.writeText(t)` / `await clipboard.readText()` |
+| `fetch`, `fs`, timers | they work (Bun/Node APIs); update signals with the result |
+
+## npm libraries
+
+- **Work:** pure logic without the DOM (date-fns, zod, lodash, HTTP clients, Bun's SQLite,
+  parsers). Plain SVG icons with the `Icon` widget: `lucide-static`, `lucide` (the data,
+  not `createIcons()`) and `@phosphor-icons/core` (skill `nodebuilder-icons`).
+- **Do not work:** anything that renders React/Solid/Vue or touches the DOM: `lucide-react`,
+  `lucide-solid`, `@phosphor-icons/react`, MUI, Chakra, shadcn/ui, Radix, Tailwind,
+  styled-components, react-router, browser canvas/SVG charting libraries.
+- Charts: use `@nodebuilderjs/core/charts` (same API as Recharts; skill
+  `nodebuilder-charts`) or draw with `<Canvas>` (skill `nodebuilder-drawing`). Recharts,
+  Chart.js and D3 need the DOM and do not work.
+- When in doubt: if the package imports `react`, `react-dom`, `solid-js/web` or uses `document`,
+  it will not work here.
+
+## Common mistakes
+
+- Calling `useContext` inside a handler or `setTimeout`: it only works in the component body.
+- Reading the signal in the component body (`const x = count();`) and expecting it to update.
+- Destructuring reactive props (`const { value } = props`) and losing the function.
+- Putting `createSignal` inside an effect to "reset" state: create it outside and use `set`.

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

@@ -0,0 +1,53 @@
+---
+name: nodebuilder-icons
+description: Icons and SVG in nodebuilder with the Icon widget, using Lucide (lucide-static or lucide) and Phosphor (@phosphor-icons/core). Use when adding icons to buttons, menus, sidebars or lists, when choosing an icon library, or when showing any .svg file.
+---
+
+# Icons
+
+```sh
+bun add lucide-static              # Lucide .svg files
+bun add lucide                     # or: the same icons as data (import { Camera } from "lucide")
+bun add @phosphor-icons/core       # Phosphor: assets/<weight>/<name>.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 [active] = createSignal(false);
+
+<Icon svg={camera} />                                  // 20 px, color of the surrounding text
+<Icon svg={heart} size={32} color="#e01b24" />
+<Icon svg={Star} size={16} strokeWidth={1.5} />        // stroke width (outline icons)
+<Button variant="primary"><Icon svg={Star} size={16} /><Text>Favorite</Text></Button>
+<Row color={() => (active() ? theme.accent.base : theme.text.secondary)}>
+  <Icon svg={camera} /><Text>Camera</Text>              {/* icon and text change color together */}
+</Row>
+```
+
+## Rules
+
+- **Never** use `lucide-react`, `lucide-solid`, `@phosphor-icons/react`, `react-icons` or
+  `@heroicons/react`: they require React/DOM. Use the packages above.
+- Import `.svg` files with `with { type: "text" }` (the import becomes the SVG text and
+  `nodebuilder package` embeds it). `with { type: "file" }` (path) also works.
+- `svg` accepts: SVG text, a path to a `.svg`, or data from the `lucide` package. It can be
+  a function (`svg={() => (open() ? chevronUp : chevronDown)}`).
+- `size` is the height in logical px (default 20, `theme.icon.size`); the width follows the
+  `viewBox`. The color comes from `color` on the `Icon` itself or is inherited from a parent, as with `Text`.
+- Changing the color is free (single-color icons are tinted on the GPU); changing the size
+  rasterizes again (~0.5 ms). They stay sharp on HiDPI screens.
+- Phosphor weights: `thin`, `light`, `regular`, `bold`, `fill`, `duotone` (folders in
+  `assets/`; names carry the weight suffix, except `regular`: `heart.svg`, `heart-fill.svg`).
+
+## SVG limits
+
+Supported: `path` (with arcs and curves), `rect`, `circle`, `ellipse`, `line`, `polyline`,
+`polygon`, `g`, `transform`, `fill`/`stroke` (colors, `currentColor`), stroke width, caps,
+joins, `fill-rule`, opacities and inline `style=""`.
+Not supported (the rest of the drawing still shows): gradients, patterns, text, filters, masks,
+clip paths, `<use>`, dashes and `<style>`. For logos and illustrations like that: export a 2x PNG and
+use `Image`.

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

@@ -0,0 +1,50 @@
+---
+name: nodebuilder-images
+description: Show images (PNG, JPEG, WebP, AVIF, HEIC) with nodebuilder's Image widget and include the files in the packaged app. Use when adding photos, logos, avatars, thumbnails or any image file to the UI. For icons and SVG, use the nodebuilder-icons skill.
+---
+
+# Images
+
+```tsx
+import { Image } from "@nodebuilderjs/core";
+import logo from "./assets/logo.png" with { type: "file" };
+
+<Image src={logo} width={64} />                       // height follows the aspect ratio
+<Image src={photo} width={200} height={120} fit="cover" radius={12} />
+<Image src={() => avatarOf(user())} width={32} height={32} radius={16} opacity={0.9} />
+```
+
+## Rules
+
+- **Import files with `with { type: "file" }`.** The import becomes the file path, and
+  `nodebuilder package` embeds the image in the executable. `new URL("./x.png", import.meta.url)`
+  and bare paths work in `bun run dev`, but **break in the packaged app**.
+- `src` accepts: a path (relative to the current directory), a `file:` `URL`, the file bytes
+  (`Uint8Array`, e.g. from a `fetch`) or pixels `{ width, height, data }` (8-bit RGBA).
+  It can be a function: changing `src` releases the old image.
+- Size: without `width`/`height`, it uses the file's pixels (1 pixel = 1 logical px). With only one
+  of the two, the other follows the aspect ratio. For HiDPI screens, use a 2x larger file and fix the
+  size (`width={64}` for a 128 px PNG).
+- `fit`: `contain` (default, whole image centered), `cover` (fills and crops), `fill`
+  (stretches). `radius` rounds the corners; `opacity` goes from 0 to 1.
+- The same file used in several places is decoded once; the memory is released when the
+  last `Image` leaves the screen.
+- A file that fails to load: a warning in the console and nothing drawn (the app does not crash).
+
+## Formats
+
+| Format | How | Notes |
+|---|---|---|
+| PNG, JPEG, WebP | decoded in TypeScript | always work; JPEG honors the EXIF orientation |
+| AVIF, HEIC | `libheif` system library | without it, only these fail ("needs libheif"); the `.deb`/`.rpm` package suggests it but does not install it. Prefer WebP/PNG/JPEG for the app's own images |
+| SVG | through the `Icon` widget (skill `nodebuilder-icons`) | subset for icons; illustrations with gradients/text: export a 2x PNG |
+| Animated GIF, video | not supported | |
+
+## Caveats
+
+- Decoding is synchronous: a 4-megapixel photo takes ~0.1 s and freezes the UI
+  meanwhile. Shrink large images before putting them in the app (e.g. thumbnails).
+- Images scaled down a lot on screen look jagged (no mipmaps): use files close to the
+  displayed size.
+- In `bun test`, `Image` works without a window (textures are simulated); AVIF/HEIC
+  need the native addon and libheif.

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

@@ -0,0 +1,37 @@
+---
+name: nodebuilder-packaging
+description: Build and distribute the nodebuilder app (AppImage, .deb, .rpm, .tar.gz) with nodebuilder package, bundle files (images, data) into the executable and configure name, icon and app id. Use when preparing a release to install, when changing the app's name/icon, or when the packaged app behaves differently from bun run dev.
+---
+
+# Packaging
+
+```sh
+bun run package        # = nodebuilder package src/main.tsx --title "..." --app-id ...
+bunx nodebuilder package src/main.tsx --targets deb,rpm --icon assets/icon.svg --version 1.2.0
+bunx nodebuilder package --help
+```
+
+Produces in `dist/` a single executable (Bun + app + native core, ~31 MB compressed) inside
+an AppImage, `.deb`, `.rpm` and `.tar.gz`, with a menu entry and icon. Runs on distros with glibc
+2.34+ (Ubuntu 22.04+, Debian 12+, Fedora, RHEL 9+).
+
+## Rules
+
+- **App files** (images, JSON, sounds) are bundled into the executable only if imported with
+  `with { type: "file" }` (the import becomes the path). `readFileSync("./data.json")` with a
+  loose path works in dev and **fails in the package**. For JSON, `import data from
+  "./data.json"` also bundles it.
+- The `<Window>`'s `appId` must match `--app-id` (the template already does this); otherwise the
+  icon and taskbar grouping do not work.
+- `--icon`: `.svg` or a 256x256 PNG. `--name` is the executable/package name (lowercase).
+- System libraries (Wayland, X11, EGL, FreeType, HarfBuzz, fontconfig) are declared
+  dependencies of the packages, never bundled. `libheif` (only for AVIF/HEIC) is
+  only suggested.
+- User data: save it in `~/.local/share/<app>` (`process.env.XDG_DATA_HOME`), never
+  next to the executable (`/usr/bin` is not writable).
+
+## Verify
+
+- Run the generated executable outside the project folder (`cd / && path/to/app`) to catch
+  files that only existed on the development disk.
+- AppImage: `chmod +x dist/*.AppImage && ./dist/*.AppImage`.

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

@@ -0,0 +1,40 @@
+---
+name: nodebuilder-performance
+description: Measure and improve the performance of nodebuilder apps (fps, CPU, memory) and avoid slow patterns in large lists, frequent updates and animations. Use when the app is slow, stuttering or freezing, using too much CPU/memory, or when building lists with hundreds of items, live data or animations.
+---
+
+# Performance
+
+## Measure
+
+```sh
+NB_STATS=1 bun src/main.tsx      # per second: fps, ms of state/layout/paint/native, nodes, memory
+NB_MAX_FPS=60 bun src/main.tsx   # fps cap (default 120); also run(app, { maxFps: 60 })
+```
+
+When idle, the app draws nothing (0% CPU). State changes schedule a frame; several changes
+before it go out together in the same frame.
+
+## Patterns
+
+- **Large lists:** always inside `<Scroll>`; whatever is outside the visible area is not
+  positioned or drawn. Even so, each item becomes nodes: with thousands, filter or paginate.
+- **`<For>` is keyed by reference:** recreating the objects (`list.map((x) => ({ ...x }))`)
+  destroys and recreates every row. Keep the references and change only what changed; for
+  fields that change often, store a signal inside the item (`{ id, cpu: createSignal(0) }`).
+  If the data always arrives as new objects (a JSON every second) or is primitive,
+  use `<Index>`: rows stay by position and only the `item()` accessor changes.
+- **Update the minimum:** one signal per changing value, and thin functions in props
+  (`text={() => fmt(item.cpu())}`) instead of one giant signal holding all the state.
+- **Several changes together:** `batch(() => { setA(1); setB(2); })` produces a single frame and
+  runs the effects once.
+- **Animation and live data:** to go from one value to another use `createTween`/`animate`; for
+  a loop, `requestAnimationFrame(cb)` (paced by the display), not a short `setInterval`. To
+  stop, do not request the next frame. `Spinner` and `ProgressBar` without a value request frames while
+  they are on screen: hide them when the wait is over.
+- **Text:** measurements are cached; texts that change every frame (counters, clocks)
+  cost little, but avoid generating thousands of new strings per frame.
+- **Images:** decoding is expensive and synchronous; reuse the same file (it is shared) and
+  use files at the displayed size.
+- Heavy CPU work (parsing large files, computations) freezes the interface: split it into
+  chunks with `setTimeout(..., 0)` or use a `Worker`.

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

@@ -0,0 +1,97 @@
+---
+name: nodebuilder-testing
+description: Write and debug tests for nodebuilder apps with bun test, without opening a window (mount, findByText, click, interact for mouse and keyboard, layout, debugTree). Use when creating tests, when verifying a behavior or layout change, or when a component test fails.
+---
+
+# Tests without a window
+
+`bun test` runs the files in `test/`. Nothing opens a window: `mount` builds the tree with
+fake text metrics (**8 px per character, 20 px line**), so layout is deterministic.
+
+```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("adds a task", () => {
+  const { root, relayout, dispose } = mount(() => <App />, { width: 800, height: 600 });
+  click(findByText(root, "Add")!);                // walks up to the parent with onClick (the Button)
+  expect(findByText(root, /1 task/)).toBeDefined();
+  relayout();                                     // recomputes positions after changes
+  const item = findByText(root, "New task")!;
+  expect(item.y).toBeGreaterThan(0);
+  dispose();                                      // disposes the app's effects and signals
+});
+```
+
+## API (`@nodebuilderjs/core/testing`)
+
+- `mount(view, size?)` → `{ root, relayout, dispose }`. Layout runs once in `mount`;
+  call `relayout()` before checking `x`, `y`, `width`, `height` after changing state.
+- `findByText(root, "text" | /regex/)`: first `Text` whose entire content matches.
+- `findAll(root, (n) => ...)`: free-form search; `n.label` is `"Text \"...\""`, `"Button"`, `"Row"`...
+- `click(node)`: fires the `onClick` of the node or of its nearest ancestor (quick shortcut).
+- `interact(root)`: mouse and keyboard delivered as in the real app (hover, focus, capture
+  while dragging, Tab): `hover(n)`, `press(n)`, `release(n)`, `drag(n, dx, dy)`, `move(x, y)`,
+  `down(x, y)`/`up(x, y)` (button at a window position, e.g. on the scrollbar),
+  `scroll(n, dy, { dx, shift })`, `key("Return")`, `key("c", { ctrl: true })`,
+  `type("text")`, `focused` and `cursor` (the cursor the window would show).
+
+```tsx
+const ui = interact(root);
+ui.press(field);            // focuses the TextField
+ui.type("Ana");             // types into the focused field
+ui.key("Return");           // fires onSubmit
+ui.drag(slider, 80, 0);     // drags 80 px to the right
+```
+- `debugTree(node)` (from `@nodebuilderjs/core`): tree with positions, great for inspecting layout.
+- Animations finish immediately in tests (there is no window): a closed `Dialog` leaves the
+  tree at once. To test the animation, `const clock = frames()` after `mount()` and
+  `clock.advance(ms)` (16 ms frames).
+- `ref={(el) => el.focus()}` (focus on creation) takes effect in a microtask: create
+  `interact(root)` and `await Promise.resolve()` before typing. `onResize` fires on every
+  `relayout()` in which the size changed.
+- Scrolling: `n.scrollY`/`n.scrollX` give the position; `ui.scroll(n, 60)` uses the wheel,
+  `ui.key("Next")` (PageDown; PageUp is `"Prior"`) the keyboard. `scrollTo` and `scrollIntoView()`
+  apply on the next layout: call `relayout()` before checking.
+- Overlays are positioned during layout: after opening or closing one, call `relayout()`.
+  Their content lives in `root.layers` (not in `root.children`); `findByText(root, ...)` searches
+  both.
+
+## Clipboard and selection
+
+In tests, `clipboard` is an in-memory area (no window, no system). To check a copy, read it
+back; reading is asynchronous, so the test becomes `async`:
+
+```tsx
+import { expect, test } from "bun:test";
+import { Column, Text, clipboard } from "@nodebuilderjs/core";
+import { interact, mount } from "@nodebuilderjs/core/testing";
+
+test("copies the id by selecting the text", async () => {
+  const { root } = mount(() => <Column align="start"><Text selectable>id-42</Text></Column>);
+  const ui = interact(root);
+  const id = root.children[0]!.children[0]!;
+  ui.press(id);                 // the click gives focus to the text
+  ui.release(id);
+  ui.key("a", { ctrl: true });  // Ctrl+A: everything (or ui.drag(id, dx, 0) for a range)
+  ui.key("c", { ctrl: true });
+  expect(await clipboard.readText()).toBe("id-42");
+});
+```
+
+To test pasting into a `TextField`, write first with `clipboard.writeText(...)`, focus the
+field, `ui.key("v", { ctrl: true })` and wait one loop turn
+(`await new Promise((r) => setImmediate(r))`) before checking the value. The in-memory area
+is shared within the file: write the expected value at the start of each test.
+
+## Tips
+
+- State changes immediately (signals are synchronous); there is no `await` or `act()` (the
+  exception is reading the clipboard, above).
+- Prefer `interact` over calling handlers by hand: it also tests focus, hover and propagation.
+  After changes that move nodes, call `relayout()` before interacting again.
+- Test layout calculations with fixed sizes (`width`, `height`) so they do not depend on the
+  fake metrics.
+- Before finishing a task: `bun run typecheck && bun test`.