create-nodebuilderjs 0.2.5 → 0.3.0

package/index.js

@@ -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}` },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nodebuilderjs",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Creates a nodebuilder app: bun create nodebuilderjs my-app",
   "type": "module",
   "license": "MIT",

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

@@ -1,6 +1,6 @@
 ---
 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.
+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>`
@@ -29,20 +29,55 @@ const [data, setData] = createSignal([12, 40, 33, 70, 55, 90]);
 |---|---|
 | `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 |
+| `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?)`, `measureText(text, size?)` | labels; `y` is the top of the line |
+| `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.
-- 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.
+- `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

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

@@ -36,13 +36,24 @@ or Solid**. The JSX looks the same as always, but the elements are the widgets f
 | `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` |
+| `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` | `textAlign` (`start`/`center`/`end`), `lineHeight` (multiplier) |
-| CSS `:hover` | `onPointerEnter`/`onPointerLeave` + signal |
+| 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 |

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

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -12,22 +12,59 @@ bun add @phosphor-icons/core       # Phosphor: assets/<weight>/<name>.svg
 ```
 
 ```tsx
-import { Button, Icon, Row, Text, createSignal, theme } from "@nodebuilderjs/core";
+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 { Star } from "lucide";
+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);
 
-<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>
+<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
@@ -38,6 +75,11 @@ const [active] = createSignal(false);
   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

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

@@ -6,12 +6,17 @@ description: Show images (PNG, JPEG, WebP, AVIF, HEIC) with nodebuilder's Image
 # Images
 
 ```tsx
-import { Image } from "@nodebuilderjs/core";
+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" };
 
-<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} />
+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
@@ -24,7 +29,8 @@ import logo from "./assets/logo.png" with { type: "file" };
   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).
+  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

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

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -8,12 +8,31 @@ description: Measure and improve the performance of nodebuilder apps (fps, CPU,
 ## 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 })
+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). State changes schedule a frame; several changes
-before it go out together in the same frame.
+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
 

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

@@ -1,12 +1,13 @@
 ---
 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.
+description: Write and debug tests for nodebuilder apps with bun test, without opening a window (mount, findByText, findByLabel, click, interact for mouse and keyboard, layout, debugTree, layoutWarnings for hidden overflow, real text metrics), and look at the UI with screenshots (nodebuilder screenshot, screenshot()). Use when creating tests, when verifying a behavior, layout or visual 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.
+fake text metrics (**8 px per character, 20 px line**), so layout is deterministic (real
+fonts on request: `useRealTextMetrics()`, below).
 
 ```tsx
 import { expect, test } from "bun:test";
@@ -27,11 +28,23 @@ test("adds a task", () => {
 
 ## 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.
+- `mount(view, size?)` → `{ root, relayout, dispose, layoutWarnings }`. Layout runs once in
+  `mount`; call `relayout()` before checking `x`, `y`, `width`, `height` after changing state.
+- `layoutWarnings()` (from `mount`, or `layoutWarnings(root)`): overflow warnings of the last
+  layout, e.g. `layout: Row > Text("Artists") overflows Box(panel) by 42px (children need
+  342px, 300px available)`: children that need more room than they get, cut off by a `clip`
+  ancestor or the window (past a `Scroll` on its scrolling axis does not count). `mount` does
+  not fail on them; assert `expect(layoutWarnings()).toEqual([])` in screen tests so a hidden
+  chip fails right away instead of when a click finds it.
+- `findByText(root, "text" | /regex/)`: first `Text` whose entire content matches;
+  `findAllByText` returns every match (e.g. a title repeated in a list and in a player bar).
+- `findByLabel(root, "label" | /regex/)` / `findAllByLabel`: by `ariaLabel`, for elements
+  without text (`<Button ariaLabel="Play">` with only an icon). Built-in labels: the window's
+  title-bar buttons (`"Minimize"`, `"Maximize"` or `"Restore"`, `"Close"`), and a `Tooltip`'s
+  trigger gets the tip text when it has no `ariaLabel` of its own.
 - `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).
+- `click(node)`: fires the `onClick` of the node or of its nearest ancestor (quick shortcut),
+  at the node's center.
 - `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),
@@ -45,7 +58,63 @@ 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.
+- **Hidden targets throw.** `click(n)` and the node helpers of `interact` (`hover`, `press`,
+  `release`, `drag`, `scroll`) throw when a user could not reach the node: it is `culled`
+  (it, or an ancestor, is outside the visible area of the last layout, e.g. a chip that
+  overflowed a `clip` panel or a row far down a `Scroll`), or its center is cut off by a
+  clipping/scrolling ancestor or the window. The message names the node and the ancestor.
+  Fix the test (or the layout): `n.scrollIntoView()` then `relayout()`, give it room (a
+  bigger `mount` size, `width`), or `relayout()` if the tree changed since the last layout.
+  `down(x, y)`/`up(x, y)`/`move(x, y)` take window positions and are never checked.
+
+```tsx
+import { expect, test } from "bun:test";
+import { Button, For, Row, Scroll } from "@nodebuilderjs/core";
+import { click, findAllByText, findByLabel, findByText, mount } from "@nodebuilderjs/core/testing";
+
+test("plays a genre that starts off screen", () => {
+  const played: string[] = [];
+  const genres = ["Rock", "Jazz", "Pop", "Funk", "Soul"];
+  const { root, relayout } = mount(() => (
+    <Row>
+      <Button ariaLabel="Play" label="▶" onClick={() => played.push("all")} />
+      <Scroll horizontal width={300}>
+        <For each={genres}>{(g) => <Button label={g} width={100} onClick={() => played.push(g)} />}</For>
+      </Scroll>
+    </Row>
+  ));
+  click(findByLabel(root, "Play")!);
+  const soul = findByText(root, "Soul")!;
+  expect(() => click(soul)).toThrow(/culled/); // past the 300 px Scroll
+  soul.scrollIntoView();
+  relayout();
+  click(soul);
+  expect(played).toEqual(["all", "Soul"]);
+  expect(findAllByText(root, /o/)).toHaveLength(3); // Rock, Pop, Soul
+});
+```
+- **Real text metrics:** `useRealTextMetrics()` makes this and every later `mount` measure
+  text with the installed fonts (no window) and returns a function that restores the previous
+  metrics; `useFakeTextMetrics({ charWidth, lineHeight })` sets fake ones (the default is 8
+  and 20). Use real metrics to check that a label really fits (`layoutWarnings()` empty with
+  a `clip` panel); numbers depend on the machine's fonts, so assert relations, not exact
+  pixels. Guard with `test.skipIf(!canUseRealTextMetrics())` and restore in `afterEach`.
+
+```tsx
+import { afterEach, expect, test } from "bun:test";
+import { Row, Text } from "@nodebuilderjs/core";
+import { canUseRealTextMetrics, layoutWarnings, mount, useFakeTextMetrics, useRealTextMetrics } from "@nodebuilderjs/core/testing";
+
+afterEach(() => useFakeTextMetrics());
+
+test.skipIf(!canUseRealTextMetrics())("the header fits with real fonts", () => {
+  useRealTextMetrics();
+  const { root } = mount(() => <Row width={240} clip><Text>Recently played</Text></Row>);
+  expect(layoutWarnings(root)).toEqual([]);
+});
+```
+- `debugTree(node)` (from `@nodebuilderjs/core`): tree with positions, great for inspecting
+  layout; a container whose children overflow a clip is marked `[overflow +42]`.
 - 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).
@@ -59,6 +128,39 @@ ui.drag(slider, 80, 0);     // drags 80 px to the right
   Their content lives in `root.layers` (not in `root.children`); `findByText(root, ...)` searches
   both.
 
+## Look at the UI: screenshots
+
+Tests check boxes, not looks. **After a visual change, take a screenshot and look at it**
+(read the PNG): wrong colors, clipped text, misalignment and missing icons show up at once.
+No window or display server is needed (it renders with the GPU through EGL):
+
+```sh
+bun run screenshot                      # screenshot.png: src/main.tsx at the <Window>'s size
+nodebuilder screenshot src/main.tsx dark.png --theme dark --scale 2 --width 1024 --height 700
+```
+
+Animations run to their end on a simulated clock (`--wait-frames <n>` stops earlier). In a
+test, `screenshot()` gives the real pixels of a mounted tree, with real fonts:
+
+```tsx
+import { expect, test } from "bun:test";
+import { Box } from "@nodebuilderjs/core";
+import { canScreenshot, mount, savePNG, screenshot } from "@nodebuilderjs/core/testing";
+
+test.skipIf(!canScreenshot())("the banner is red", () => {
+  const { root } = mount(() => <Box height={40} background="#e01b24" />, { width: 200, height: 40 });
+  const shot = screenshot(root, { scale: 2 });         // 400x80 pixels
+  expect(shot.pixel(10, 10)).toEqual([0xe0, 0x1b, 0x24, 255]); // [r, g, b, a], straight alpha
+  savePNG(shot, "banner.png");                         // to look at it
+});
+```
+
+- `screenshot(root | () => view, { width, height, scale, background })` →
+  `{ width, height, scale, rgba, pixel(x, y), toPNG() }`; size in device pixels. Uncovered
+  areas stay transparent. The test's text metrics (fake by default) come back after the shot.
+- Pixels depend on the machine's fonts and GPU: assert colors at chosen points, not whole
+  images. `canScreenshot()` is false without a GPU driver (e.g. some CI runners).
+
 ## Clipboard and selection
 
 In tests, `clipboard` is an in-memory area (no window, no system). To check a copy, read it
@@ -94,4 +196,4 @@ is shared within the file: write the expected value at the start of each test.
   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`.
+- Before finishing a task: `bun run typecheck && bun test`, and a screenshot if anything visual changed.

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

@@ -1,6 +1,6 @@
 ---
 name: nodebuilder-ui
-description: nodebuilder widgets, style props and layout (Window, Column, Row, Scroll, Text, Button, TextField, Checkbox, Toggle, RadioGroup, Slider, Select, Tabs, Tooltip, Dialog, ProgressBar, Spinner, Card, For, Index, Show, Switch/Match, ErrorBoundary, theme), scrolling (vertical, horizontal, scrollbars, keyboard, scrollIntoView), context (createContext), ref (focus, scroll, measure), onResize, dark theme (setTheme), animations (createTween, createPresence), overlays (modal dialog, dropdown menu, hint/tooltip), opacity and translate, selectable text and clipboard (copy/paste). Use when creating or changing any screen, form, list, sidebar or layout of a nodebuilder app, when the user needs to copy text from the screen, or when an element does not show up, grow or scroll as expected.
+description: nodebuilder widgets, style props and layout (gradient backgrounds, Window, custom title bar with dragRegion and WindowControls, Column, Row, Scroll, Text, Button, TextField, Checkbox, Toggle, RadioGroup, Slider, Select, Tabs, Tooltip, Dialog, ProgressBar, Spinner, Card, For, Index, Show, Switch/Match, ErrorBoundary, theme), scrolling (vertical, horizontal, scrollbars, keyboard, scrollIntoView), context (createContext), ref (focus, scroll, measure), onResize, dark theme (setTheme), animations (createTween, createPresence, animate, easing, mixColor), equal-width columns, absolute positioning and stacking (zIndex), clip with rounded corners, shadows, events (double/right click, key names), reusable components (MaybeAccessor, read, batch), overlays (modal dialog, dropdown menu, hint/tooltip), opacity and translate, selectable text and clipboard (copy/paste). Use when creating or changing any screen, form, list, sidebar or layout of a nodebuilder app, when the user needs to copy text from the screen, or when an element does not show up, grow or scroll as expected.
 ---
 
 # UI with nodebuilder
@@ -12,10 +12,12 @@ style is flat props. SolidJS-style reactivity: **only functions are reactive** (
 
 | Widget | What for | Main props |
 |---|---|---|
-| `Window` | root, one per app, with its own title bar | `title`, `width`, `height` (initial size), `appId`, `onClose` (return `false` to keep it open) |
+| `Window` | root, one per app, with its own title bar | `title`, `width`, `height` (initial size), `appId`, `onClose` (return `false` to keep it open), `decorations={false}` (your own title bar, see "Theme and window") |
+| `WindowControls` | minimize, maximize/restore and close buttons, for a custom title bar | style (`gap`...) |
 | `Column` / `Row` / `Box` | flex container (column, row; `Box` is a column) | style + events |
+| `Grid` | children in rows of equal-width cells (cards, covers, galleries) | `columns`, `gap`, `rowGap` (default `gap`); see "Layout rules" |
 | `Scroll` | scrolling: vertical (default), `horizontal` or `horizontal vertical` (both) | needs `grow={1}` or a size; see "Scrolling" below |
-| `Text` | text; wraps at spaces to fit the width | children (`{count}`, `"a"`) or `text={() => ...}`, `wrap` (default `true`), `maxLines` (truncates with "…"), `textAlign`, `lineHeight`, `selectable` |
+| `Text` | text; wraps at spaces to fit the width | children (`{count}`, `"a"`) or `text={() => ...}`, `wrap` (default `true`), `maxLines` (truncates with "…"), `textAlign`, `lineHeight`, `underline`, `selectable` |
 | `Image` | PNG, JPEG, WebP, AVIF | see the `nodebuilder-images` skill |
 | `Icon` | SVG icon (Lucide, Phosphor), color inherited like text | `svg`, `size` (20), `color`, `strokeWidth`; skill `nodebuilder-icons` |
 | `Canvas` | free drawing: lines, polygons, arcs, text | `draw={(g) => ...}` + size; skill `nodebuilder-drawing` |
@@ -54,18 +56,55 @@ ignores clicks and keys. Do not fake it with `opacity` + an empty `onClick`.
 ## Style props (any widget)
 
 - Layout: `direction` (`"row"`/`"column"`), `gap`, `padding` (`8`, `[v, h]` or
-  `[top, right, bottom, left]`), `width`, `height`, `minWidth`, `minHeight`, `maxWidth`,
-  `maxHeight`, `grow`, `align`, `justify`, `position: "absolute"` + `left`/`top`, `clip`.
+  `[top, right, bottom, left]`), `margin` (same forms, negative allowed), `width`, `height`, `minWidth`, `minHeight`, `maxWidth`,
+  `maxHeight`, `grow`, `aspectRatio` (width / height), `align`, `alignSelf`, `justify`,
+  `wrap` (on a `Row`/`Column`: lines; on a `Text`: word wrapping), `rowGap`,
+  `position: "absolute"` + `left`/`top`/`right`/`bottom`, `zIndex`, `clip`.
 - Visual: `background`, `radius`, `borderWidth`, `borderColor`, `shadow={{ color, blur, y }}`,
   `opacity` (0 to 1, applies to children), `translateX`/`translateY` (shifts after
   layout, without pushing siblings; for animation).
-- Text (inherited by children): `color`, `fontSize`, `bold`. Cursor: `cursor="pointer"`.
+- **Gradient background** (CSS `linear-gradient`): `background={{ linear: ["#1db954", "#121212"], angle: 180 }}`.
+  `angle` in degrees (0 = to top, 90 = to right, default 180 = to bottom); stops are colors or
+  `[color, offset]` (0..1, missing ones spread evenly). Works with `radius`, borders, `opacity`,
+  `hoverStyle`, and reactively: `background={() => ({ linear: [theme.accent.base, "transparent"] })}`.
+  Interpolated premultiplied (fading to `"transparent"` stays the same hue). Linear only (no
+  radial/conic); `borderColor`, `color` and `shadow` take solid colors only.
+- `clip` cuts the children to the inside of the border, **rounded** (radius `radius - borderWidth`):
+  `<Card clip padding={0}>` + an `Image` or a colored header gets the card's rounded corners.
+- `shadow` is the node's rounded box, blurred `blur` px on each side of its edge and moved down
+  by `y` (no x offset, no spread). It is drawn even without `background`: then the whole blurred
+  shape shows (a soft glow), and a translucent background lets it show through.
+- Text (inherited by children): `color`, `fontSize`, `bold`, `fontWeight` (1..1000 like CSS:
+  300 light, 500 medium, 700 bold, 900 black; `bold` is 700 and `fontWeight` wins on the same
+  widget), `italic`, `letterSpacing` (px after every character, may be negative: `letterSpacing={1.5}`
+  on small uppercase labels), `underline` (a line under each line of text, in its color;
+  `underline={false}` turns it off below; `TextField` ignores it). Weights come from the
+  system font (the closest it has).
+  Symbols, CJK and emoji the UI font lacks come from the system's fallback fonts; emoji are in
+  color (`color` does not tint them, `opacity` fades them). Cursor: `cursor="pointer"`. A link that underlines on hover:
+
+  ```tsx
+  import { Text, createSignal, theme } from "@nodebuilderjs/core";
+
+  const [hovered, setHovered] = createSignal(false);
+  <Text color={() => theme.accent.base} underline={hovered} cursor="pointer"
+    onPointerEnter={() => setHovered(true)} onPointerLeave={() => setHovered(false)}
+    onClick={() => console.log("open docs")}>Read the docs</Text>;
+  ```
 - Colors are hex strings (`"#3584e4"`, `"#00000010"` with alpha) or `"transparent"`.
 - Events on any container: `onClick`, `onPointerDown/Up/Enter/Leave`,
   `onPointerMove`, `onScroll`, `onKeyDown`, `onFocus`, `onBlur`. Pointer events carry
-  `x`/`y` (window) and `localX`/`localY` (relative to the node); while the button is held,
+  `x`/`y` (window), `localX`/`localY` (relative to the node), `button` (0 left, 1 middle,
+  2 right) and `clicks` (2 = double click); while the button is held,
   `onPointerMove` keeps reaching the node where the press started, even outside it (dragging,
-  sliders). `onKeyDown` only arrives along the path of the focused element.
+  sliders). `onKeyDown` only arrives along the path of the focused element; it gets `key`
+  (xkb names: `"Return"`, `"Escape"`, `"Tab"`, `"BackSpace"`, `"space"`, `"Up"`, `"Left"`, `"a"`),
+  `text`, `ctrl`, `shift`, `alt`, `repeat`. `onScroll` gets `dx`/`dy`. `onClick` is the left button only
+  (context menu: `onPointerDown` with `e.button === 2`) and runs only on the innermost node that
+  has one (a button inside a clickable card clicks only the button); the other events go up
+  through the parents until a handler calls `e.stop()`, also past nodes with `onClick` (a
+  list's `onPointerDown` with `e.button === 2` sees a right press on any of its clickable
+  rows; on keys and the wheel, `stop()` also keeps the surrounding `Scroll` still).
 - Any prop accepts a fixed value or a function: `background={() => (sel() ? a : b)}`.
 - `onResize={(s) => ...}`: the node's size (`s.width`, `s.height`) after layout, the first
   time and whenever it changes. Use it to adapt the screen to the available width.
@@ -73,6 +112,47 @@ ignores clicks and keys. Do not fake it with `opacity` + an empty `onClick`.
   on a `Scroll` `el.scrollTo(y)` / `el.scrollTo({ x, y })` and `el.scrollX`/`el.scrollY`, and
   `el.x`/`y`/`width`/`height` from the last layout. It is called on creation, before layout:
   keep the `el` and read the box later (in a click, for example).
+- `ariaLabel="Play"` on any widget names an element without text (an icon-only button);
+  tests find it with `findByLabel`. A `Tooltip` gives its tip to a trigger that has none.
+
+## Hover and press
+
+Do not write `onPointerEnter`/`onPointerLeave` + a signal for hover effects. Use
+`hoverStyle`/`pressStyle` (any widget, any style prop, values fixed or functions), and
+`createInteraction()` when something else depends on the state (a child shown while its
+parent is hovered):
+
+```tsx
+import { Box, Button, Column, Show, Text, createInteraction } from "@nodebuilderjs/core";
+
+function SongCard(props: { title: string; onPlay: () => void }) {
+  const card = createInteraction();
+  return (
+    <Box {...card.props} direction="row" align="center" gap={12} padding={12} radius={8}
+      background="#181818" hoverStyle={{ background: "#282828" }} pressStyle={{ opacity: 0.85 }}>
+      <Column grow={1}>
+        <Text color="#ffffff">{props.title}</Text>
+      </Column>
+      <Show when={card.hovered}>
+        <Button label="Play" variant="primary" onClick={props.onPlay} />
+      </Show>
+    </Box>
+  );
+}
+```
+
+- `pressStyle` wins over `hoverStyle`; on leave the base values come back (a base given as a
+  function keeps updating underneath). They win over a widget's own hover colors (`Button`);
+  a `disabled` control ignores them.
+- `createInteraction()` returns `hovered`, `pressed`, `focused` (accessors) and `props`.
+  `{...card.props}` adds to the widget's handlers and to your own `onPointerEnter`... written
+  before or after it (nothing is overwritten); the card stays hovered while the pointer is
+  over its children. `focused` only changes on focusable widgets (`Button`, `TextField`).
+- `hoverStyle` alone does not take the press; `pressStyle` and `card.props` do, so inside a
+  window's drag region (title bar) such a widget no longer drags the window.
+- Like CSS `:active`, a parent's `pressStyle` (and `pressed()`) also turns on while a child
+  inside it (a button in the card) is pressed; `onPointerDown={(e) => e.stop()}` on the child
+  (or on a `Box` around a `Button`) keeps the press to the child.
 
 ## Conditions, lists and errors
 
@@ -141,6 +221,35 @@ const scrollToEnd = () => list?.scrollTo(Infinity);
 - `useContext` only works in the component body (not inside an `onClick` or `setTimeout`):
   read it there and keep it in a variable.
 
+## Your own components
+
+```tsx
+import { Column, Row, Text, batch, createSignal, read } from "@nodebuilderjs/core";
+import type { Child, MaybeAccessor } from "@nodebuilderjs/core";
+
+// A prop that may be fixed or reactive: MaybeAccessor + read() inside a function.
+function Stat(props: { label: string; value: MaybeAccessor<number>; children?: Child }) {
+  return (
+    <Row gap={8} align="center">
+      <Text>{props.label}</Text>
+      <Text bold>{() => read(props.value).toLocaleString()}</Text>
+      {props.children}
+    </Row>
+  );
+}
+
+const [plays, setPlays] = createSignal(0);
+const [likes, setLikes] = createSignal(0);
+<Column>
+  <Stat label="Plays" value={plays} />
+  <Stat label="Year" value={2024} />
+</Column>;
+batch(() => { setPlays(1200); setLikes(80); }); // several writes, effects run once at the end
+```
+
+- `untrack(() => ...)` reads signals without subscribing; `createMemo(() => ...)` caches a
+  derived value; `StyleProps` (type) is every style prop, to accept and pass them on.
+
 ## Scrolling
 
 ```tsx
@@ -186,8 +295,8 @@ For the common cases use the ready-made widgets (`Dialog`, `Select`, `Tooltip`),
 focus, keyboard and closing. `<Overlay>` is for what they do not cover (options menu, toast,
 custom popover):
 
-No `zIndex` and no `position: fixed`: whatever must stay on top of everything (outside the
-clipping of a `Scroll` or `Card`) goes in an `<Overlay>`, almost always inside a `<Show>`.
+No `position: fixed`, and `zIndex` only orders siblings: whatever must stay on top of everything
+(outside the clipping of a `Scroll` or `Card`) goes in an `<Overlay>`, almost always inside a `<Show>`.
 
 ```tsx
 import { Button, Card, Overlay, Row, Show, Text, createSignal, theme } from "@nodebuilderjs/core";
@@ -235,7 +344,8 @@ let button: ElementRef | undefined;
 ## Layout rules (simplified flexbox)
 
 - Default `align` is **stretch**: children take the full width of a column. Use
-  `align="start"`/`"center"` to shrink them to their content.
+  `align="start"`/`"center"` to shrink them to their content. `alignSelf` on one child
+  overrides its parent's `align` (e.g. one centered button in a stretched form).
 - `justify`: `start`, `center`, `end`, `space-between`. There is no `space-around`/`evenly`.
 - `grow={1}` splits the leftover space. Without `grow`, the size is the content's.
 - A child **does not shrink below its own content** (like CSS `min-size: auto`), except
@@ -246,10 +356,98 @@ let button: ElementRef | undefined;
   lose height (only what scrolls vertically gives up height).
 - In a `Row` without room, whoever has `grow` shrinks first: the long text gets
   `grow={1}` (and `maxLines={1}` to become "…"), the short labels next to it stay whole.
+- **Something does not show up?** In development the app prints an overflow warning once per
+  node when children need more room than they get and a `clip` ancestor or the window cuts
+  them off: `layout: Row > Text("Artists") overflows Box(panel) by 42px (children need 342px,
+  300px available)`; `debugTree(root)` marks the container `[overflow +42]` and tests read the
+  list with `layoutWarnings()` (see the testing skill). Fix: a `Scroll horizontal`, wrapping
+  text, `grow` with `width={0}`, `minWidth={0}` plus `clip` on what may be cut, or more room.
 - Text wraps by itself at the width it gets (`\n` also breaks); a word longer than the line
   overflows. A single line: `wrap={false}` (overflows) or `maxLines={1}` (truncates with "…").
-- There are no percentages, `flex-wrap` or grid: build rows with `Row` and fixed widths (see
-  tables: `Text width={110}`) or `grow`.
+- There are no percentages: build rows with `Row` and fixed widths (see tables:
+  `Text width={110}`), `grow`, proportional columns (below), `wrap` or a `Grid`.
+- **`<Row wrap gap={6}>`** (CSS `flex-wrap: wrap`) for chips and tags: children that do not fit
+  start a new line, `rowGap` (default `gap`) between lines. Each line is its own row (`grow`,
+  `justify`, `alignSelf` apply inside it) and is as tall as its tallest child. The Row wraps at
+  whatever width it gets (stretched in a column, `grow`, a fixed `width`) and its height follows;
+  it can shrink down to its widest child. `<Column wrap height={...}>` breaks into columns at
+  its height.
+- **`margin`** is space outside the border that the parent keeps free: it counts in every size
+  around the child (natural size, `grow`, `Grid` cells, `wrap` lines) and a stretched child
+  gets the room minus its margins. Prefer `gap`/`padding` on the parent for regular spacing;
+  use `margin` for one child (extra space above a section title) or negative values (a divider
+  that cancels the card's padding: `margin={[8, -16]}`). Not painted, not clickable, never
+  collapses, adds to `gap`. On an absolute child it adds to `left`/`top`/`right`/`bottom`.
+- **`<Grid columns={3} gap={8}>`** (CSS `repeat(3, 1fr)`): children flow into rows of equal
+  cells, whatever their content; the last row keeps its empty cells. A row is as tall as its
+  tallest cell and cells stretch to it (`align`/`alignSelf` change that). `rowGap` sets the
+  space between rows (default `gap`). Use it with `<For>` too: adding an item reflows.
+- **`aspectRatio={16 / 9}`** (width / height), like CSS `aspect-ratio`: in a column or a `Grid`
+  cell the height follows the width; with a fixed `height` (or stretched in a `Row` with a
+  height) the width follows the height. `min/max` still clamp, and children taller than the
+  ratio make the box taller. In a `Grid`, `aspectRatio={1}` gives square cells (covers,
+  thumbnails) that do not stretch to a taller neighbor.
+- **Equal (or proportional) columns in one row:** `width={0} grow={1}` on each child, like CSS
+  `flex: 1 1 0`. The fixed width is the base `grow` adds to, so the widths follow only the
+  `grow` values (1:1:2...), not the content; text inside wraps to the column. Plain `grow={1}`
+  only shares the *leftover* space, so wider content makes a wider column. Rows of equal height
+  in a `Column` with a height: `height={0} grow={1}`. Content wider than its column overflows
+  into the next one (`clip` cuts it), and the row's own natural width is just its gaps: give it
+  room (stretched in a column, or `grow`).
+- **`position="absolute"`** takes the child out of the flow: `left`/`top`/`right`/`bottom`
+  count from the parent's content box (inside its `padding`; negative values work), as in CSS.
+  It keeps its natural size, unless both `left` and `right` (or `top` and `bottom`) are set and
+  no `width` (`height`): then it stretches between them, within `min`/`max`. `right` (or
+  `bottom`) alone places it from that edge. It does not take space or change the parent's size.
+  Siblings are drawn and hit in child order (a later one covers an earlier one) unless they
+  have a **`zIndex`** (default 0; higher is above, ties keep child order). It only orders
+  siblings: a raised node stays inside its parent's place in the order (no global stacking
+  context; for that, an `<Overlay>`). What sticks out of the parent's box is drawn and clicked
+  there too, unless the parent clips (`clip`, `Scroll`).
+- Inside a `Scroll`, an absolute child **scrolls with the content** (like CSS). For something
+  pinned to the visible area, put it next to the `Scroll` in a parent that does not scroll.
+
+```tsx
+import { Box, Column, For, Grid, Image, Row, Text, createSignal } from "@nodebuilderjs/core";
+
+// Square album covers, four per row, following the window width.
+const [albums] = createSignal([{ title: "Blue", cover: "blue.jpg" }]);
+<Grid columns={4} gap={12} rowGap={16}>
+  <For each={albums}>
+    {(a) => (
+      <Column gap={6}>
+        <Image src={a.cover} aspectRatio={1} fit="cover" radius={8} />
+        <Text maxLines={1}>{a.title}</Text>
+      </Column>
+    )}
+  </For>
+</Grid>;
+
+// Three columns in one row: 1 : 1 : 2, whatever their content (the manual alternative).
+<Row gap={12}>
+  <Column width={0} grow={1}><Text>Now playing</Text></Column>
+  <Column width={0} grow={1}><Text>Up next, a much longer title that wraps</Text></Column>
+  <Column width={0} grow={2}><Text>Lyrics (twice as wide)</Text></Column>
+</Row>;
+
+// A layer over the whole cover and badges on its corners (declared last: on top).
+<Box width={160} radius={12} clip background="#1f1f24">
+  <Column padding={16} gap={4}><Text color="#ffffff">Album</Text></Column>
+  <Box position="absolute" left={0} top={0} right={0} bottom={0} background="#00000066" />
+  <Text position="absolute" left={8} top={8} padding={[2, 6]} radius={8} background="#e01b24" color="#ffffff">NEW</Text>
+  <Text position="absolute" right={8} bottom={8} color="#ffffff">3:45</Text>
+</Box>;
+
+// A count badge sticking out of a card's corner (no `clip`, so it is drawn and clicked
+// outside too); `zIndex` keeps it above the content even though it is declared first.
+<Box width={160} padding={12} radius={10} background="#e8eaf2">
+  <Text position="absolute" right={-22} top={-22} zIndex={1} padding={[2, 8]} radius={10} background="#e5484d" color="#ffffff">3</Text>
+  <Box padding={8} radius={6} background="#3e63dd"><Text color="#ffffff">Inbox</Text></Box>
+</Box>;
+```
+
+Keep the `padding` on an inner child (as above) when an absolute layer must cover the padding
+too: the edges count from inside the parent's `padding`.
 
 ## Theme and window
 
@@ -260,12 +458,64 @@ let button: ElementRef | undefined;
   follow theme changes. `color={theme.text.secondary}` keeps the color of that moment.
 - `windowControls.close()`, `.minimize()`, `.toggleMaximize()`, `.setTitle(t)`;
   `windowState.width()`, `.height()`, `.maximized()`, `.activated()` are accessors.
-- Animation: `createTween(() => target)` (a number that moves smoothly), `createPresence(when)`
-  (`mounted` for `<Show>`, `progress` 0→1 for `opacity`/`translateY`), `animate(...)`.
-  `Dialog`, `Select`, `Tooltip` and `Toggle` already animate on their own.
+- **Custom title bar** (navigation or search merged with the window buttons): `<Window
+  decorations={false}>` drops the built-in bar (border, corners and edge resizing stay);
+  `dragRegion` on any widget makes it move the window, and a double click maximizes. Plain
+  text and empty space inside it drag; buttons, fields and anything clickable, focusable or
+  with `onPointerDown` keep their press.
+
+```tsx
+import { Row, Spacer, Text, TextField, Window, WindowControls, createSignal, theme, windowState } from "@nodebuilderjs/core";
+
+const [query, setQuery] = createSignal("");
+<Window title="Player" decorations={false}>
+  <Row dragRegion height={56} align="center" gap={12} padding={[0, 12]}>
+    <Text bold color={() => (windowState.activated() ? theme.text.primary : theme.text.secondary)}>Player</Text>
+    <TextField width={280} value={query} onInput={setQuery} placeholder="Search" />
+    <Spacer />
+    <WindowControls />
+  </Row>
+  {/* the rest of the screen */}
+</Window>
+```
+- Animation: see the next section.
 - Not available yet: theme following the system, `scale`/`rotate`, selection in `TextField`
   (and Ctrl+C in it), IME, multiple windows.
 
+## Animation
+
+```tsx
+import { Box, animate, createInteraction, createSignal, createTween, easing, mixColor, theme } from "@nodebuilderjs/core";
+
+const row = createInteraction();
+// Moves smoothly toward its source; a new target starts from wherever it is now.
+const t = createTween(() => (row.hovered() ? 1 : 0), { duration: 150, easing: easing.easeInOut });
+<Box
+  {...row.props} height={56} radius={8}
+  background={() => mixColor(theme.card.background, "#1db954", t() * 0.2)}
+  translateY={() => -2 * t()}
+/>;
+
+// One-off: calls back once per frame; returns a function that stops it.
+const [x, setX] = createSignal(0);
+const stop = animate(0, 300, setX, { duration: 400, easing: easing.linear, onDone: () => console.log("done") });
+<Box width={40} height={40} translateX={x} />;
+```
+
+- `createTween(source, { duration, easing })`: an accessor that follows `source` (a function
+  returning a number). `animate(from, to, onUpdate, { duration, easing, onDone })`.
+  `duration` in ms (default 200), `easing` default `easing.easeOut`.
+- `createPresence(when, { enter, exit, easing })` (ms, defaults 180/120): `mounted` stays true
+  until the exit ends (use it in `<Show when={p.mounted}>`), `progress` goes 0→1→0 (for
+  `opacity`, `translateY`).
+- `easing.linear`, `.easeIn`, `.easeOut`, `.easeInOut`, or any `(t: number) => number`.
+- `mixColor(a, b, t)`: `a` blended toward `b` (t 0..1), as `"#rrggbbaa"`; any hex form works.
+  Premultiplied like CSS: `mixColor("#1db954", "transparent", 0.5)` is the same green at half alpha.
+- Animate numbers only (`opacity`, `translateX/Y`, `width`, colors via `mixColor`). For a
+  custom loop, `requestAnimationFrame((time) => ...)` runs right before the next frame.
+- `Dialog`, `Select`, `Tooltip` and `Toggle` already animate on their own. Without a window
+  (tests) every animation jumps to its end; `frames()` (skill `nodebuilder-testing`) moves time.
+
 ## Selecting and copying text
 
 Plain text **does not select**, on purpose (labels, buttons, titles). Text the user
@@ -278,7 +528,7 @@ may want to copy (ids, links, paths, error messages, results) gets `selectable`:
 
 With `selectable`: dragging selects, double-click takes the word, triple-click the line,
 Ctrl+A everything and Ctrl+C copies; the cursor becomes the text cursor. It is not in the Tab order, and inside
-the title bar it selects instead of dragging the window. Selection is one `Text` at a time
+the title bar (or any `dragRegion`) it selects instead of dragging the window. Selection is one `Text` at a time
 (it does not span several) and there is no Shift+click or Shift+arrows yet.
 
 The system clipboard (text only) is in `clipboard`:
@@ -287,8 +537,8 @@ The system clipboard (text only) is in `clipboard`:
 import { Button, clipboard, createSignal } from "@nodebuilderjs/core";
 
 const [link, setLink] = createSignal("https://example.com");
-<Button label="Copy link" onClick={() => clipboard.writeText(link())} />
-<Button label="Paste" onClick={async () => setLink(await clipboard.readText())} />
+<Button label="Copy link" onClick={() => clipboard.writeText(link())} />;
+<Button label="Paste" onClick={async () => setLink(await clipboard.readText())} />;
 ```
 
 - `readText()` is asynchronous (another program holds the content) and returns `""` if there

package/template/AGENTS.md

@@ -4,7 +4,11 @@ nodebuilder app: native Linux UI in TSX, **no DOM and no React**. Read this befo
 
 ## Commands
 - `bun run dev` opens the app; `bun test` runs the tests without a window; `bun run typecheck` checks types.
-- Before finishing: `bun run typecheck && bun test`.
+- `bun run icons:add play pause` adds icon imports to `src/icons.ts` (after `bun add lucide-static`).
+- `bun run screenshot` renders the app to `screenshot.png` without a window (also with no
+  display server); add `-- --theme dark` or `-- --scale 2`.
+- Before finishing: `bun run typecheck && bun test`. **After a visual change, take a screenshot
+  and look at it** (open the PNG): tests check boxes, not colors, alignment or clipping.
 
 ## Model (like SolidJS, not React)
 - **Components run once.** There is no re-render and there are no hooks. State is `createSignal`;
@@ -26,12 +30,12 @@ that support skills load them on their own; others should read the topic's skill
 
 | Skill | When |
 |---|---|
-| `nodebuilder-ui` | screens, widgets (incl. `Toggle`, `RadioGroup`, `Slider`, `Select`, `Tabs`, `Tooltip`, `Dialog`, `ProgressBar`, `disabled`), style props, layout, `For`/`Index`/`Show`/`Switch`, `ErrorBoundary`, scrolling (horizontal, scrollbars, keyboard, `scrollIntoView`), context, `ref` (focus, scroll), `onResize`, `Overlay` (dialog, menu, tooltip), `opacity`/`translate`, theme (light/dark, `setTheme`), animations, selectable text, copy/paste |
+| `nodebuilder-ui` | screens, widgets (incl. custom title bar with `dragRegion`/`WindowControls`, `Toggle`, `RadioGroup`, `Slider`, `Select`, `Tabs`, `Tooltip`, `Dialog`, `ProgressBar`, `disabled`), style props (incl. gradient `background={{ linear, angle }}`), hover/press (`hoverStyle`, `pressStyle`, `createInteraction`), layout (`Grid` of equal columns, `wrap` rows of chips, `margin`, `aspectRatio`, equal columns in a row with `width={0} grow={1}`, `position="absolute"`, `zIndex`, `clip`, `shadow`, overflow warnings), events, own components, `For`/`Index`/`Show`/`Switch`, `ErrorBoundary`, scrolling (horizontal, scrollbars, keyboard, `scrollIntoView`), context, `ref` (focus, scroll), `onResize`, `Overlay` (dialog, menu, tooltip), `opacity`/`translate`, theme (light/dark, `setTheme`), animations (`createTween`, `animate`, `easing`, `mixColor`), selectable text, copy/paste |
 | `nodebuilder-from-react` | before installing libraries or porting React/web code |
 | `nodebuilder-images` | images (PNG, JPEG, WebP, AVIF), files in the app |
-| `nodebuilder-icons` | icons (Lucide, Phosphor) and SVG with `Icon` |
+| `nodebuilder-icons` | icons (Lucide, Phosphor) and SVG with `Icon`; `bun run icons:add <names...>` writes their imports into `src/icons.ts` |
 | `nodebuilder-charts` | ready-made charts (`@nodebuilderjs/core/charts`, Recharts API) |
-| `nodebuilder-drawing` | freehand drawing with `Canvas` |
-| `nodebuilder-testing` | tests without a window (`mount`, `findByText`, `click`, `interact`, `frames`, clipboard) |
+| `nodebuilder-drawing` | freehand drawing with `Canvas` (reactive `draw`, dashed lines, gradient fills with `g.linearGradient`, text cut to a width with "…") |
+| `nodebuilder-testing` | tests without a window (`mount`, `findByText`/`findAllByText`, `findByLabel` (`ariaLabel`), `click`, `interact`, hidden targets that throw, `layoutWarnings()`, real text metrics (`useRealTextMetrics`), `frames`, clipboard), screenshots (`nodebuilder screenshot`, `screenshot()`) |
 | `nodebuilder-packaging` | AppImage/.deb/.rpm, embedded files, icon and app id |
-| `nodebuilder-performance` | slowness, long lists, live data, animation |
+| `nodebuilder-performance` | slowness, long lists, live data, animation, CPU use while idle (`NB_STATS`, `NB_TRACE=frames`) |

package/template/README.md

@@ -8,6 +8,7 @@ bun run dev        # opens the window and restarts on save
 bun start          # runs once
 bun test           # tests without a window (test/)
 bun run typecheck  # TypeScript 7
+bun run screenshot # screenshot.png of the app, without opening a window
 bun run package    # AppImage, .deb, .rpm and .tar.gz in dist/
 ```
 

package/template/_gitignore

@@ -1,2 +1,3 @@
 node_modules/
 dist/
+screenshot.png

package/template/src/icons.ts

@@ -1,6 +1,5 @@
-// SVG icons (drawn for this template). For more icons, `bun add lucide-static` and
-// `import x from "lucide-static/icons/x.svg" with { type: "text" }`: see the
-// nodebuilder-icons skill.
+// SVG icons (drawn for this template). For more: `bun add lucide-static`, then
+// `bun run icons:add play pause` adds their imports below (see the nodebuilder-icons skill).
 const svg = (body: string) =>
   `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">${body}</svg>`;