create-nodebuilderjs 0.2.1 → 0.3.0

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);
 }
 
@@ -73,6 +73,8 @@ const pkg = {
     dev: "bun --watch src/main.tsx",
     test: "bun test",
     typecheck: "tsc --noEmit",
+    screenshot: "nodebuilder screenshot src/main.tsx screenshot.png",
+    "icons:add": "nodebuilder icons add --out src/icons.ts",
     package: `nodebuilder package src/main.tsx --title "${title}" --app-id ${appId}`,
   },
   dependencies: { "@nodebuilderjs/core": `^${version}` },
@@ -84,8 +86,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 +95,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.3.0",
+  "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,89 @@
+---
+name: nodebuilder-drawing
+description: Freeform drawing in nodebuilder with the Canvas widget (lines, dashed lines, gradient fills, polygons, arcs, gauges, sparklines, annotations, labels cut to a width with an ellipsis, custom visualizations); the draw function is reactive. 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", dash?)` | segment; cap `round`, `butt` (flat) or `square`; `dash` like `[4, 3]` (dash, gap...) |
+| `polyline(points, color, width = 1, { cap, closed, dash })` | 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?, { maxWidth, ellipsis, weight, italic, letterSpacing })` | one line of text; `y` is the top of the line. With `maxWidth`, text that does not fit is cut and ends in "…" (`ellipsis: false` just cuts; nothing is drawn if not even "…" fits). `weight` (1..1000) wins over `bold`. No wrapping |
+| `measureText(text, size?, bold?, { weight, italic, letterSpacing })` | `{ width, height }` of that text, to align it |
+| `linearGradient(x0, y0, x1, y1, stops)` | a gradient usable in place of `color` in `rect`, `line`, `polyline`, `polygon`, `circle`, `arc` (not `text`): offset 0 at `(x0, y0)`, 1 at `(x1, y1)`, end colors beyond; stops are colors or `[color, offset]` |
+
+Gradient area under a line (fades out toward the bottom):
+
+```tsx
+import { Canvas, createSignal, mixColor, theme } from "@nodebuilderjs/core";
+
+const [points] = createSignal([0, 120, 80, 40, 160, 90, 240, 20]);
+<Canvas height={160} draw={(g) => {
+  const pts = points();
+  const fade = g.linearGradient(0, 0, 0, g.height, [mixColor(theme.accent.base, "transparent", 0.6), "transparent"]);
+  g.polygon([pts[0]!, g.height, ...pts, pts[pts.length - 2]!, g.height], fade);
+  g.polyline(pts, theme.accent.base, 2);
+}} />;
+```
+
+Sizes default to the theme's font size (14). Text that must fit a width:
+
+```tsx
+import { Canvas, createSignal, theme } from "@nodebuilderjs/core";
+
+const [title] = createSignal("A very long track title that does not fit");
+<Canvas width={180} height={40} draw={(g) => {
+  const { height } = g.measureText(title(), 13);
+  g.text(title(), 4, (g.height - height) / 2, theme.text.primary, 13, false, { maxWidth: g.width - 8 }); // "A very long track…", centered vertically
+  g.line(0, g.height - 1, g.width, g.height - 1, theme.divider, 1, "butt", [4, 3]); // dashed
+}} />;
+```
+
+For wrapping paragraphs, a `<Text>` next to the canvas (or over it: an absolute sibling in a
+`Box`, declared after the `Canvas`) is simpler than drawing text.
+
+## 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.
+- `draw` is **reactive**: it runs inside an effect, so every signal it reads (the data, a
+  hovered index, `theme.*` colors) is tracked, and changing one redraws the canvas, once per
+  change. It also redraws when its size changes. Do not wrap it in `createEffect` and do not
+  read the data outside `draw` (that reads it once). 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,80 @@
+---
+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 |
+| `z-index` among siblings (badge over a card's content) | `zIndex={1}` (siblings only: no global stacking context; ties keep child order) |
+| `createPortal`, `position: fixed`, `z-index` above everything, library modal/dropdown/tooltip | `<Overlay>` (`modal`, `anchor={() => el}`, `onDismiss`); skill `nodebuilder-ui` |
+| CSS `display: grid; grid-template-columns: repeat(4, 1fr); gap: 8px; row-gap: 12px` | `<Grid columns={4} gap={8} rowGap={12}>` (equal columns only; no spans or named areas) |
+| CSS `margin: 8px 16px`, `margin-top`, negative margins | `margin={[8, 16]}`, `margin={[12, 0, 0, 0]}`, `margin={[0, -16]}` (no collapsing, no `auto`; adds to `gap`) |
+| CSS `flex-wrap: wrap` (chips, tags), `row-gap` | `<Row wrap gap={6} rowGap={8}>` (lines start at the top: no `align-content`) |
+| CSS `flex: 1 1 0` (equal or 1:1:2 columns in one row) | `width={0} grow={1}` (`grow={2}`...) on each child |
+| CSS `aspect-ratio: 16 / 9`, square thumbnails | `aspectRatio={16 / 9}`; `aspectRatio={1}` in `Grid` cells gives square cells |
+| CSS `align-self`, `position: absolute; inset: 0` / `right: 8px` | `alignSelf`, `position="absolute" left={0} top={0} right={0} bottom={0}` / `right={8}` (inside a `Scroll` it scrolls with the content) |
+| CSS `background: linear-gradient(180deg, #1db954, #121212 60%)` | `background={{ linear: ["#1db954", ["#121212", 0.6]], angle: 180 }}` (linear only; on `<canvas>`: `g.linearGradient(x0, y0, x1, y1, stops)`) |
+| 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`, `text-decoration: underline` | `textAlign` (`start`/`center`/`end`), `lineHeight` (multiplier), `underline` (inherited) |
+| CSS `font-weight: 600`, `font-weight: bold` | `fontWeight={600}`, `bold` (= 700); inherited |
+| CSS `font-style: italic` | `italic` (inherited) |
+| CSS `letter-spacing: 0.08em` / `2px` | `letterSpacing={2}` (px only: multiply `em` by the `fontSize`); inherited |
+| CSS `:hover` / `:active`, `.card:hover .play` | `hoverStyle={{ background: "#..." }}` / `pressStyle={{...}}` on any widget; state read elsewhere: `const card = createInteraction()`, `<Box {...card.props}>`, `<Show when={card.hovered}>` |
+| 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,95 @@
+---
+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 (generate the imports with `nodebuilder icons add`), 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, Column, 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 { Heart, Play, Star } from "lucide";
+import starFill from "@phosphor-icons/core/assets/fill/star-fill.svg" with { type: "text" };
+
+const [active] = createSignal(false);
+const [liked, setLiked] = createSignal(false);
+
+<Column gap={8}>
+  <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>
+  <Icon svg={Play} fill />                             {/* solid Lucide icon (icon color) */}
+  <Icon svg={Heart} fill={() => liked() && "#e01b24"} onClick={() => setLiked(!liked())} />
+  <Icon svg={starFill} />                              {/* Phosphor ships solid icons as "fill" */}
+  <Row color={() => (active() ? theme.accent.base : theme.text.secondary)}>
+    <Icon svg={camera} /><Text>Camera</Text>            {/* icon and text change color together */}
+  </Row>
+</Column>
+```
+
+## Adding icons: `nodebuilder icons add`
+
+For more than one or two icons, **generate the imports** instead of writing them:
+
+```sh
+bun run icons:add play pause heart arrow-left                  # lucide-static -> src/icons.ts
+bun run icons:add heart-fill house --from @phosphor-icons/core # Phosphor: weight by suffix
+nodebuilder icons list arrow                                   # names that contain "arrow"
+```
+
+<!-- no-check -->
+```tsx
+import { Icon } from "@nodebuilderjs/core";
+import { arrowLeft, heartFill } from "./icons.js"; // camelCase of the file name
+
+<Icon svg={arrowLeft} />;
+<Icon svg={heartFill} color="#e01b24" />;
+```
+
+- Install the package first (`bun add lucide-static`). `--out <file>` picks another module.
+- One sorted, deduplicated line per icon; the rest of `src/icons.ts` (hand-drawn icons) stays.
+  A name already used in the file is an error (rename yours, or pick another icon).
+- An unknown name fails with close matches (`did you mean heart-crack?`) and writes nothing:
+  run `nodebuilder icons list <part>` to find the right one.
+- Writing them by hand: `import x from "lucide-static/icons/x.svg" with { type: "text" };`.
+  **Never** `export { default as x } from "....svg" with { type: "text" }`: Bun drops the
+  attribute on re-exports, so `x` becomes the file's path, not its text (`Icon` happens to
+  read paths too, anything expecting SVG text breaks); `icons add` rewrites those lines into
+  `import x from "....svg" with { type: "text" }; export { x };`.
+
+## 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`.
+- Solid icons: Lucide is outline only; `fill` (`true` = the icon's color, or a color) makes
+  it solid, like Lucide's own `fill` prop: it replaces the root `<svg>`'s `fill="none"`, so the
+  shapes get filled and keep their stroke. A fill a shape or group sets itself (`none`
+  included) still wins. It can be a function. **Never** patch the SVG text
+  (`svg.replace('fill="none"', ...)`). Phosphor has ready-made solid icons in the `fill` weight.
+- 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,56 @@
+---
+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 { Column, Image, createSignal } from "@nodebuilderjs/core";
+import logo from "./assets/logo.png" with { type: "file" };
+import photo from "./assets/photo.jpg" with { type: "file" };
+
+const [user] = createSignal({ name: "Ana", avatar: logo });
+
+<Column gap={8}>
+  <Image src={logo} width={64} />                     {/* height follows the aspect ratio */}
+  <Image src={photo} width={200} height={120} fit="cover" radius={12} />
+  <Image src={() => user().avatar} width={32} height={32} radius={16} opacity={0.9} />
+</Column>
+```
+
+## 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). A shape of your own that follows the space:
+  `aspectRatio={1} fit="cover"` (square covers; in a `<Grid columns={4}>` they fill each cell).
+- `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,59 @@
+---
+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 (also while idle), 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, why, nodes, memory
+NB_TRACE=frames bun src/main.tsx    # per frame: what asked for it, with the top of its stack
+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) and `NB_STATS` prints nothing. State changes
+schedule a frame; several changes before it go out together in the same frame.
+
+## The app never goes idle
+
+`NB_STATS` shows why frames happen: `why: inv 3 ev 2 raf 0` counts frames requested by
+`invalidate()` (a signal changed something on screen), by native events (resize, hover,
+scroll) and by `requestAnimationFrame`/animations. While nothing moves on screen it should
+print nothing at all. If lines keep coming, run with `NB_TRACE=frames` to see who asks:
+
+```
+frame 41: inv [in frame]
+    at <anonymous> (src/components/clock.tsx:12:7)
+    at paintTree (node_modules/@nodebuilderjs/core/src/render/paint.ts:140:8) x3
+```
+
+`[in frame]` means the request came while that frame was being laid out or painted: usually
+code that runs there (an `onResize` handler, a custom `paint`) and writes a signal every
+time, even when the value did not change. Write only when the value really changes. In
+development, the app also warns once (`frame loop: ...`) after 30 such frames in a row.
+
+## 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`.