create-nodebuilderjs 0.2.1 → 0.2.5

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

@@ -1,72 +1,299 @@
 ---
 name: nodebuilder-ui
-description: Widgets, props de estilo e layout do nodebuilder (Window, Column, Row, Scroll, Text, Button, TextField, Checkbox, Card, For, Show, theme). Use ao criar ou mudar qualquer tela, formulário, lista, barra lateral ou layout de um app nodebuilder, ou quando um elemento não aparece, não cresce ou não rola como esperado.
+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.
 ---
 
-# Interface com nodebuilder
+# UI with nodebuilder
 
-Tudo vem de `@nodebuilderjs/core`. Não há DOM nem CSS: widgets são funções e o estilo são
-props planas. Reatividade estilo SolidJS: **só funções são reativas** (veja o AGENTS.md).
+Everything comes from `@nodebuilderjs/core`. There is no DOM and no CSS: widgets are functions and
+style is flat props. SolidJS-style reactivity: **only functions are reactive** (see AGENTS.md).
 
 ## Widgets
 
-| Widget | Para quê | Props principais |
+| Widget | What for | Main props |
 |---|---|---|
-| `Window` | raiz, uma por app, com barra de título própria | `title`, `width`, `height` (tamanho inicial), `appId`, `onClose` (retorne `false` para não fechar) |
-| `Column` / `Row` / `Box` | contêiner flex (coluna, linha; `Box` é coluna) | estilo + eventos |
-| `Scroll` | coluna com rolagem vertical | precisa de `grow={1}` ou `height`; filhos podem ser maiores |
-| `Text` | texto de uma linha (sem quebra automática) | filhos (`{count}`, `"a"`) ou `text={() => ...}` |
-| `Image` | PNG, JPEG, WebP, AVIF | veja a skill `nodebuilder-imagens` |
-| `Icon` | ícone SVG (Lucide, Phosphor), cor herdada como texto | `svg`, `size` (20), `color`, `strokeWidth`; skill `nodebuilder-icones` |
-| `Canvas` | desenho livre: linhas, polígonos, arcos, texto | `draw={(g) => ...}` + tamanho; skill `nodebuilder-desenho` |
-| `Button` | botão com foco e teclado | `label` ou filhos, `variant` (`default`, `primary`, `danger`, `flat`), `disabled`, `onClick` |
-| `TextField` | campo de texto controlado | `value` (accessor), `onInput(valor)`, `onSubmit`, `placeholder` |
-| `Checkbox` | caixa de seleção | `checked` (accessor), `onChange(marcado)`, `label` |
-| `Card` | coluna com fundo, borda, raio 12, padding 16, gap 8 | estilo |
-| `Divider` / `Spacer` | linha de 1 px / espaço flexível (`size` fixo opcional) | |
-| `<For each={lista}>{(item, i) => ...}</For>` | lista keyed por referência; `i` é um accessor | `fallback` |
-| `<Show when={() => ...} fallback={...}>` | condicional | |
+| `Window` | root, one per app, with its own title bar | `title`, `width`, `height` (initial size), `appId`, `onClose` (return `false` to keep it open) |
+| `Column` / `Row` / `Box` | flex container (column, row; `Box` is a column) | style + events |
+| `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` |
+| `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` |
+| `Button` | button with focus and keyboard | `label` or children, `variant` (`default`, `primary`, `danger`, `flat`), `disabled`, `onClick` |
+| `TextField` | controlled text field | `value` (accessor), `onInput(value)`, `onSubmit`, `placeholder`, `disabled` |
+| `Checkbox` | checkbox | `checked` (accessor), `onChange(checked)`, `label`, `disabled` |
+| `Toggle` | on/off switch (`Switch` is the control-flow component) | `checked` (accessor), `onChange(on)`, `label`, `disabled` |
+| `RadioGroup` | one option among several; a single Tab stop, arrows switch | `value` (accessor), `onChange(v)`, `options=[{ value, label, disabled? }]`, `disabled` |
+| `Slider` | number by dragging or with arrows/PageUp/Home/End | `value` (accessor), `onChange(n)`, `min` (0), `max` (100), `step` (1), `width` (200), `disabled` |
+| `Select` | dropdown list anchored to the field; full keyboard support | `value` (accessor, may be `undefined`), `onChange(v)`, `options=[{ value, label, disabled? }]`, `placeholder`, `width`, `disabled` |
+| `Tabs` | tab bar (the content is yours, with `<Switch>`) | `value` (accessor), `onChange(v)`, `tabs=[{ value, label, disabled? }]` |
+| `Tooltip` | hint when the pointer rests over the child | `text`, `placement` (`"top"`), `delay` (500 ms), child |
+| `Dialog` | ready-made modal dialog: title, body, actions | `open` (accessor), `onClose`, `title`, `actions`, `width` (420), `dismissible` (true) |
+| `ProgressBar` | progress bar, 6 px | `value` from 0 to 1 (without it: indeterminate) |
+| `Spinner` | busy, no measure of progress | `size` (20), `color` |
+| `Card` | column with background, border, radius 12, padding 16, gap 8 | style |
+| `Divider` / `Spacer` | 1 px line / flexible space (optional fixed `size`) | |
+| `<For each={list}>{(item, i) => ...}</For>` | list keyed by reference; `i` is an accessor | `fallback` |
+| `<Index each={list}>{(item, i) => ...}</Index>` | list by position (primitives); `item` is an accessor, `i` a number | `fallback` |
+| `<Show when={() => ...} fallback={...}>` | conditional; a `{(v) => ...}` child gets the value as an accessor | |
+| `<Switch fallback={...}><Match when={...}>...</Match></Switch>` | several cases: the first true `Match` | `Match` accepts `{(v) => ...}` |
+| `<ErrorBoundary fallback={(error, reset) => ...}>` | replaces children that threw with the `fallback` | `reset()` tries again |
 
 ```tsx
-const [nome, setNome] = createSignal("");
-<TextField value={nome} onInput={setNome} onSubmit={salvar} placeholder="Nome" />
-<Checkbox checked={ativo} onChange={setAtivo} label="Ativo" />
-<Button label="Salvar" variant="primary" disabled={() => !nome()} onClick={salvar} />
+const [name, setName] = createSignal("");
+<TextField value={name} onInput={setName} onSubmit={save} placeholder="Name" />
+<Checkbox checked={active} onChange={setActive} label="Active" />
+<Button label="Save" variant="primary" disabled={() => !name()} onClick={save} />
+<Toggle checked={wifi} onChange={setWifi} label="Wi-Fi" />
+<Slider value={volume} onChange={setVolume} max={100} step={5} />
 ```
 
-## Props de estilo (qualquer widget)
+`disabled` (value or function) on any control: dims it, removes it from Tab order and focus, and
+ignores clicks and keys. Do not fake it with `opacity` + an empty `onClick`.
 
-- Layout: `direction` (`"row"`/`"column"`), `gap`, `padding` (`8`, `[v, h]` ou
+## 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`.
-- Visual: `background`, `radius`, `borderWidth`, `borderColor`, `shadow={{ color, blur, y }}`.
-- Texto (herdados pelos filhos): `color`, `fontSize`, `bold`. Cursor: `cursor="pointer"`.
-- Cores são strings hex (`"#3584e4"`, `"#00000010"` com alfa) ou `"transparent"`.
-- Eventos em qualquer contêiner: `onClick`, `onPointerDown/Up/Enter/Leave`,
-  `onPointerMove`, `onScroll`, `onKeyDown`, `onFocus`, `onBlur`. Eventos de ponteiro trazem
-  `x`/`y` (janela) e `localX`/`localY` (relativos ao nó); enquanto o botão está pressionado,
-  `onPointerMove` continua chegando ao nó onde o clique começou, mesmo fora dele (arrastar,
-  sliders). `onKeyDown` só chega pelo caminho do elemento focado.
-- Qualquer prop aceita valor fixo ou função: `background={() => (sel() ? a : b)}`.
-
-## Regras do layout (flexbox simplificado)
-
-- `align` padrão é **stretch**: filhos ocupam toda a largura de uma coluna. Use
-  `align="start"`/`"center"` para encolher ao conteúdo.
-- `justify`: `start`, `center`, `end`, `space-between`. Não existe `space-around`/`evenly`.
-- `grow={1}` divide o espaço que sobra. Sem `grow`, o tamanho é o do conteúdo.
-- Um filho **não encolhe abaixo do próprio conteúdo** (como `min-size: auto` do CSS), exceto
-  `Scroll`, `clip` ou `minWidth/minHeight` explícito. Lista longa dentro de uma coluna
-  que cresce sem parar? Envolva em `<Scroll grow={1}>`.
-- Para um `Scroll` dentro de uma coluna com `grow`, a coluna também precisa de `minHeight={0}`.
-- Não há porcentagens, `flex-wrap`, grid nem quebra de linha de texto: monte linhas com `Row`
-  e larguras fixas (veja tabelas: `Text width={110}`) ou `grow`.
-
-## Tema e janela
-
-- Cores e tamanhos padrão em `theme` (`theme.text.secondary`, `theme.accent.base`,
-  `theme.danger.base`, `theme.divider`...). Mude `theme` antes de `run()` para personalizar.
+- 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"`.
+- 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,
+  `onPointerMove` keeps reaching the node where the press started, even outside it (dragging,
+  sliders). `onKeyDown` only arrives along the path of the focused element.
+- 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.
+- `ref={(el) => ...}` on any widget: `el.focus()`, `el.blur()`, `el.scrollIntoView()`,
+  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).
+
+## Conditions, lists and errors
+
+```tsx
+import { Button, ErrorBoundary, Index, Match, Show, Switch, Text, createSignal } from "@nodebuilderjs/core";
+
+const [order, setOrder] = createSignal<{ id: number } | null>(null);
+const [step, setStep] = createSignal<"cart" | "payment" | "done">("cart");
+const [grades] = createSignal([7, 9, 10]);
+
+<Show when={order} fallback={<Text>No order</Text>}>
+  {(o) => <Text>{() => `Order ${o().id}`}</Text>}
+</Show>;
+
+<Switch fallback={<Text>Thank you!</Text>}>
+  <Match when={() => step() === "cart"}><Text>Your cart</Text></Match>
+  <Match when={() => step() === "payment"}><Text>Payment</Text></Match>
+</Switch>;
+
+<Index each={grades}>{(grade, i) => <Text>{() => `Test ${i + 1}: ${grade()}`}</Text>}</Index>;
+
+<ErrorBoundary fallback={(error, reset) => <Button label="Try again" onClick={reset} />}>
+  <Text>{() => `Order ${order()!.id}`}</Text>
+</ErrorBoundary>;
+```
+
+- `<For>` vs `<Index>`: `For` tracks each **object** (the row survives reordering; recreating
+  the objects recreates the rows). `Index` tracks each **position**: the row stays and the
+  `item()` accessor changes; good for lists of numbers/strings or data that always arrives as new
+  objects.
+- A function child of `Show`/`Match` gets the value only when it takes a parameter: `{(o) => ...}`
+  gets the value as an accessor; `{() => ...}` (no parameter) is a plain reactive child.
+- `Switch` only accepts `Match` children, written in JSX (not generated by a function).
+- `ErrorBoundary` catches errors while creating the children and later in their effects (e.g. a click
+  changes a signal and a text throws). It disposes everything the children created and shows the
+  `fallback`; `reset()` recreates the children. What the `onClick` itself throws is not caught:
+  handle it with `try/catch` in the handler.
+
+## Context, ref and size
+
+```tsx
+import { Column, Scroll, TextField, Text, createContext, createSignal, useContext } from "@nodebuilderjs/core";
+import type { Accessor, ElementRef } from "@nodebuilderjs/core";
+
+// Value shared through the tree (theme, language, logged-in user), without passing props.
+const User = createContext<Accessor<string>>(() => "anonymous");
+function Greeting() {
+  const user = useContext(User);
+  return <Text>{() => `Hello, ${user()}`}</Text>;
+}
+const [user, setUser] = createSignal("Ana");
+<User.Provider value={user}><Greeting /></User.Provider>;
+
+// Focus a field on open and scroll a list to the end.
+const [search, setSearch] = createSignal("");
+let list: ElementRef | undefined;
+<Column grow={1}>
+  <TextField ref={(el) => el.focus()} value={search} onInput={setSearch} />
+  <Scroll ref={(el) => (list = el)} grow={1}>{/* ... */}</Scroll>
+</Column>;
+const scrollToEnd = () => list?.scrollTo(Infinity);
+```
+
+- The context value is read once, when the component runs. For a value that changes, pass
+  an accessor (signal) and call it inside a reactive function, as above.
+- `useContext` only works in the component body (not inside an `onClick` or `setTimeout`):
+  read it there and keep it in a variable.
+
+## Scrolling
+
+```tsx
+import { Button, Card, For, Row, Scroll, Text } from "@nodebuilderjs/core";
+import type { ElementRef } from "@nodebuilderjs/core";
+
+const items = Array.from({ length: 200 }, (_, i) => `Item ${i}`);
+const rows: ElementRef[] = [];
+<>
+  {/* Strip that scrolls sideways: children keep their width. */}
+  <Scroll horizontal gap={12} padding={[0, 0, 14, 0]}>
+    <For each={items}>{(t) => <Card width={160}><Text>{t}</Text></Card>}</For>
+  </Scroll>
+  <Button label="Go to 150" onClick={() => rows[150]?.scrollIntoView()} />
+  <Scroll grow={1}>
+    <For each={items}>{(t, i) => <Row ref={(el) => (rows[i()] = el)} padding={8}><Text>{t}</Text></Row>}</For>
+  </Scroll>
+  {/* Wide and long table: scrolls on both axes. */}
+  <Scroll horizontal vertical height={300}>{/* rows with fixed widths */}</Scroll>
+</>;
+```
+
+- `<Scroll>` scrolls vertically. `horizontal`: a row whose children keep their width (text
+  inside does not wrap, unless given `width`/`maxWidth`). `horizontal vertical`: a column
+  that scrolls on both axes; each child is at least the visible width and grows if the
+  content asks for it.
+- The user scrolls with the wheel (Shift+wheel goes sideways; touchpad on both axes), by dragging
+  the scrollbar thumb, by clicking the track (one page) and with the keyboard: PageUp/PageDown,
+  Home/End and the arrows scroll the `Scroll` around the focused element (with no focus, the one under
+  the mouse), unless an `onKeyDown` calls `e.stop()`. `TextField` keeps Home/End and ←/→;
+  ↑/↓ scroll.
+- Scrollbars sit **on top of** the content, in a 14 px strip along the right edge (and the
+  bottom one), and only exist when there is something to scroll: leave `padding` on that edge if
+  buttons touch it (like the `padding={[0, 0, 14, 0]}` above).
+- `el.scrollIntoView()` (on any element, via `ref`) scrolls the surrounding `Scroll`s the minimum
+  needed for it to show; it takes effect on the next frame, even for a just-created or off-screen
+  element. `el.scrollTo({ x, y })` accepts just one of the axes.
+- An open `<Overlay modal>` blocks the wheel, keys and scrollbars of what is behind it.
+
+## Dialogs, menus and hints: `<Overlay>`
+
+For the common cases use the ready-made widgets (`Dialog`, `Select`, `Tooltip`), which already handle
+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>`.
+
+```tsx
+import { Button, Card, Overlay, Row, Show, Text, createSignal, theme } from "@nodebuilderjs/core";
+import type { ElementRef } from "@nodebuilderjs/core";
+
+const [menu, setMenu] = createSignal(false);
+const [confirm, setConfirm] = createSignal(false);
+let button: ElementRef | undefined;
+<>
+  <Button ref={(el) => (button = el)} label="Options" onClick={() => setMenu((m) => !m)} />
+  <Show when={menu}>
+    <Overlay anchor={() => button} matchWidth onDismiss={() => setMenu(false)}>
+      <Card padding={4} shadow={{ color: "#00000030", blur: 16, y: 4 }}>
+        <Button label="Delete" variant="flat" onClick={() => (setMenu(false), setConfirm(true))} />
+      </Card>
+    </Overlay>
+  </Show>
+  <Show when={confirm}>
+    <Overlay modal background="#00000059" align="center" justify="center" onDismiss={() => setConfirm(false)}>
+      <Card width={320} gap={12}>
+        <Text bold>Delete file?</Text>
+        <Row gap={8} justify="end">
+          <Button label="Cancel" variant="flat" onClick={() => setConfirm(false)} />
+          <Button label="Delete" variant="danger" onClick={() => setConfirm(false)} />
+        </Row>
+      </Card>
+    </Overlay>
+  </Show>
+</>;
+```
+
+- `anchor={() => el}` (always as a function): sits next to the element, `placement`
+  `"bottom"` (default), `"top"`, `"right"` or `"left"`, flips side if it does not fit, never leaves the
+  window; `offset` (4) and `matchWidth` (same width, for menus).
+- Without `anchor`: covers the window; position it with `align`/`justify`/`padding` or with
+  `position="absolute"` + `left`/`top`. Empty space lets clicks through (toasts, hints).
+- `modal`: blocks clicks and Tab on what is behind; `background` dims the backdrop.
+- `onDismiss`: click outside (when modal, on the dimmed backdrop; never on the anchor) or Esc. Close the
+  `<Show>` there.
+- Declare the `<Overlay>` **outside** a `Button` (next to it, as above): events inside
+  the overlay bubble up through the parents of the place where it was declared.
+- Transition: animate `opacity` and `translateY` with a signal updated in
+  `requestAnimationFrame` (see `examples/overlays.tsx` in the nodebuilder repository).
+
+## 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.
+- `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
+  `Scroll`, `clip` or an explicit `minWidth/minHeight`. A long list inside a column
+  that keeps growing? Wrap it in `<Scroll grow={1}>`.
+- The content of a `Scroll` does not count toward that minimum: the column (or row) around it
+  shrinks without needing `minHeight={0}`/`minWidth={0}`. A `Scroll horizontal` does not
+  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.
+- 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`.
+
+## Theme and window
+
+- Default colors and sizes in `theme` (`theme.text.secondary`, `theme.accent.base`,
+  `theme.danger.base`, `theme.divider`...). Dark theme: `setTheme("dark")` (or `"light"`, or
+  `{ ...darkTheme, accent: {...} }`), at any time; `colorScheme()` tells which one is active.
+- **Theme colors always inside a function** (`color={() => theme.text.secondary}`): that way they
+  follow theme changes. `color={theme.text.secondary}` keeps the color of that moment.
 - `windowControls.close()`, `.minimize()`, `.toggleMaximize()`, `.setTitle(t)`;
-  `windowState.width()`, `.height()`, `.maximized()`, `.activated()` são accessors.
-- Ainda não existem: tema escuro, animações, quebra de linha, seleção de texto, IME,
-  várias janelas.
+  `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.
+- Not available yet: theme following the system, `scale`/`rotate`, selection in `TextField`
+  (and Ctrl+C in it), IME, multiple windows.
+
+## Selecting and copying text
+
+Plain text **does not select**, on purpose (labels, buttons, titles). Text the user
+may want to copy (ids, links, paths, error messages, results) gets `selectable`:
+
+```tsx
+<Text selectable>{order.id}</Text>
+<Text selectable color={theme.danger.base}>{error}</Text>
+```
+
+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
+(it does not span several) and there is no Shift+click or Shift+arrows yet.
+
+The system clipboard (text only) is in `clipboard`:
+
+```tsx
+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())} />
+```
+
+- `readText()` is asynchronous (another program holds the content) and returns `""` if there
+  is no text.
+- Copy from a click or key press (as above): on Wayland the system ignores copies that
+  do not come right after a user interaction (a `setTimeout` will not do).
+- `TextField` already pastes with Ctrl+V / Shift+Insert (line breaks become spaces), but
+  does not select or copy yet.

package/template/AGENTS.md

@@ -1,34 +1,37 @@
 # AGENTS.md
 
-App nodebuilder: UI nativa para Linux em TSX, **sem DOM e sem React**. Leia antes de mudar código.
+nodebuilder app: native Linux UI in TSX, **no DOM and no React**. Read this before changing code.
 
-## Comandos
-- `bun run dev` abre o app; `bun test` roda os testes sem janela; `bun run typecheck` checa tipos.
-- Antes de concluir: `bun run typecheck && bun test`.
+## 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`.
 
-## Modelo (igual ao SolidJS, não ao React)
-- **Componentes rodam uma vez.** Não há re-render nem hooks. Estado é `createSignal`;
-  derivados são `createMemo`; efeitos são `createEffect` (+ `onCleanup`).
-- **Só funções são reativas.** `<Text>{count}</Text>` ou `text={() => ...}` atualizam;
-  `<Text>{count()}</Text>` é lido uma vez e nunca muda. O mesmo vale para estilo:
-  `background={() => (ativo() ? "#3584e4" : "#0000")}`.
-- Listas: `<For each={lista}>{(item) => ...}</For>` (chave por referência). Condicional:
-  `<Show when={() => ...} fallback={...}>`.
-- Estilo são props planas (`padding`, `gap`, `grow`, `background`...), não CSS. Não existem
-  `className`, `style={{}}`, `div`, `useState` nem bibliotecas de React (ex.: `lucide-react`).
+## Model (like SolidJS, not React)
+- **Components run once.** There is no re-render and there are no hooks. State is `createSignal`;
+  derived values are `createMemo`; effects are `createEffect` (+ `onCleanup`).
+- **Only functions are reactive.** `<Text>{count}</Text>` or `text={() => ...}` update;
+  `<Text>{count()}</Text>` is read once and never changes. The same goes for styles:
+  `background={() => (active() ? "#3584e4" : "#0000")}`, and for theme colors:
+  `color={() => theme.text.secondary}` follows a switch to the dark theme.
+- Lists: `<For each={list}>{(item) => ...}</For>` (keyed by reference) or
+  `<Index each={list}>{(item) => ...}</Index>` (by position; `item` is an accessor).
+  Conditions: `<Show when={() => ...} fallback={...}>`; several cases: `<Switch>` with
+  `<Match when={...}>`. Errors: `<ErrorBoundary fallback={(error, reset) => ...}>`.
+- Styles are flat props (`padding`, `gap`, `grow`, `background`...), not CSS. There is no
+  `className`, `style={{}}`, `div` or `useState`, and React libraries (e.g. `lucide-react`) don't work.
 
-## Skills (detalhes por assunto)
-Em `.agents/skills/<nome>/SKILL.md` (com links em `.claude/skills/` para o Claude Code). Agentes
-que suportam skills as carregam sozinhos; os outros devem ler a skill do assunto antes de começar:
+## Skills (details by topic)
+In `.agents/skills/<name>/SKILL.md` (linked from `.claude/skills/` for Claude Code). Agents
+that support skills load them on their own; others should read the topic's skill before starting:
 
-| Skill | Quando |
+| Skill | When |
 |---|---|
-| `nodebuilder-ui` | telas, widgets, props de estilo, layout, `For`/`Show`, tema |
-| `nodebuilder-sem-react` | antes de instalar bibliotecas ou portar código React/web |
-| `nodebuilder-imagens` | imagens (PNG, JPEG, WebP, AVIF), arquivos no app |
-| `nodebuilder-icones` | ícones (Lucide, Phosphor) e SVG com `Icon` |
-| `nodebuilder-graficos` | gráficos prontos (`@nodebuilderjs/core/charts`, API do Recharts) |
-| `nodebuilder-desenho` | desenho livre com `Canvas` |
-| `nodebuilder-testes` | testes sem janela (`mount`, `findByText`, `click`) |
-| `nodebuilder-empacotar` | AppImage/.deb/.rpm, arquivos embutidos, ícone e app id |
-| `nodebuilder-desempenho` | lentidão, listas grandes, dados ao vivo, animação |
+| `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-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-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-packaging` | AppImage/.deb/.rpm, embedded files, icon and app id |
+| `nodebuilder-performance` | slowness, long lists, live data, animation |

package/template/README.md

@@ -1,32 +1,32 @@
 # {{title}}
 
-App desktop nativo para Linux feito com [nodebuilder](https://www.npmjs.com/package/@nodebuilderjs/core):
-componentes TSX com reatividade estilo SolidJS, desenhados por um núcleo nativo (Wayland/X11 + GLES).
+Native Linux desktop app made with [nodebuilder](https://www.npmjs.com/package/@nodebuilderjs/core):
+TSX components with SolidJS-style reactivity, drawn by a native core (Wayland/X11 + GLES).
 
 ```sh
-bun run dev        # abre a janela e reinicia ao salvar
-bun start          # roda uma vez
-bun test           # testes sem janela (test/)
+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 package    # AppImage, .deb, .rpm e .tar.gz em dist/
+bun run package    # AppImage, .deb, .rpm and .tar.gz in dist/
 ```
 
-## Estrutura
+## Structure
 
 ```
 src/
-  main.tsx             abre a janela: run(() => <App />)
-  App.tsx              layout da tela; cria o estado e o passa aos componentes
-  estado.ts            signals e ações do app (contador, tarefas, histórico)
-  icones.ts            ícones SVG usados pelo app
-  componentes/
-    Contador.tsx       botões e texto reativo
-    Tarefas.tsx        campo de texto, lista com For/Checkbox, Show
-    Atividade.tsx      gráfico (@nodebuilderjs/core/charts) que acompanha o estado
+  main.tsx             opens the window: run(() => <App />)
+  App.tsx              screen layout and dark mode toggle; creates the state and passes it down
+  state.ts             app signals and actions (counter, tasks, history)
+  icons.ts             SVG icons used by the app
+  components/
+    Counter.tsx        buttons, reactive text and a tooltip
+    Tasks.tsx          text field, list with For/Checkbox, Show and a confirmation Dialog
+    Activity.tsx       chart (@nodebuilderjs/core/charts) that follows the state
 test/
-  App.test.tsx         testes sem janela: mount + interact (clicar, digitar)
+  App.test.tsx         tests without a window: mount + interact (click, type)
 ```
 
-Para apagar o exemplo e começar do zero, deixe só a `<Window>` em `App.tsx`.
+To remove the example and start from scratch, keep only the `<Window>` in `App.tsx`.
 
-Requisitos: Linux com Wayland ou X11, [Bun](https://bun.sh) 1.4+.
+Requirements: Linux with Wayland or X11, [Bun](https://bun.sh) 1.4+.

package/template/src/App.tsx

@@ -1,29 +1,32 @@
-import { Column, Icon, Row, Scroll, Text, Window, theme } from "@nodebuilderjs/core";
-import { Atividade } from "./componentes/Atividade.js";
-import { Contador } from "./componentes/Contador.js";
-import { Tarefas } from "./componentes/Tarefas.js";
-import { criarEstado } from "./estado.js";
-import { brilho } from "./icones.js";
+import { Column, Icon, Row, Scroll, Spacer, Text, Toggle, Window, colorScheme, setTheme, theme } from "@nodebuilderjs/core";
+import { Activity } from "./components/Activity.js";
+import { Counter } from "./components/Counter.js";
+import { Tasks } from "./components/Tasks.js";
+import { sparkle } from "./icons.js";
+import { createState } from "./state.js";
 
 export function App() {
-  const estado = criarEstado();
+  const state = createState();
   return (
     <Window title="{{title}}" appId="{{appId}}" width={720} height={760}>
       <Scroll grow={1} padding={20} gap={16}>
         <Row gap={12} align="center">
-          <Icon svg={brilho} size={32} color={theme.accent.base} />
-          <Column gap={2}>
+          {/* Theme colors go inside functions, so they follow a theme switch. */}
+          <Icon svg={sparkle} size={32} color={() => theme.accent.base} />
+          <Column gap={2} grow={1}>
             <Text fontSize={22} bold>{"{{title}}"}</Text>
-            <Text color={theme.text.secondary}>Edite src/App.tsx e salve: o bun run dev reabre a janela.</Text>
+            <Text color={() => theme.text.secondary}>Edit src/App.tsx and save: bun run dev reopens the window.</Text>
           </Column>
+          <Spacer size={8} />
+          <Toggle checked={() => colorScheme() === "dark"} onChange={(on) => setTheme(on ? "dark" : "light")} label="Dark" />
         </Row>
         <Row gap={16} align="start">
           <Column grow={1} gap={16}>
-            <Contador estado={estado} />
-            <Atividade estado={estado} />
+            <Counter state={state} />
+            <Activity state={state} />
           </Column>
           <Column grow={1}>
-            <Tarefas estado={estado} />
+            <Tasks state={state} />
           </Column>
         </Row>
       </Scroll>

package/template/src/components/Activity.tsx

@@ -0,0 +1,24 @@
+import { Card, Icon, Row, Text, theme } from "@nodebuilderjs/core";
+import { Area, AreaChart, CartesianGrid, Legend, Line, Tooltip, YAxis } from "@nodebuilderjs/core/charts";
+import { chart } from "../icons.js";
+import type { State } from "../state.js";
+
+export function Activity(props: { state: State }) {
+  return (
+    <Card gap={8}>
+      <Row gap={8} align="center" color={() => theme.text.secondary}>
+        <Icon svg={chart} size={16} />
+        <Text bold>Activity</Text>
+      </Row>
+      {/* data is a signal: the chart follows every click and every task. */}
+      <AreaChart data={props.state.history} height={180}>
+        <CartesianGrid vertical={false} strokeDasharray="3 3" />
+        <YAxis />
+        <Area dataKey="clicks" name="Clicks" type="monotone" />
+        <Line dataKey="pending" name="Pending" stroke="#e5a50a" dot={false} />
+        <Tooltip />
+        <Legend />
+      </AreaChart>
+    </Card>
+  );
+}

package/template/src/components/Counter.tsx

@@ -0,0 +1,24 @@
+import { Button, Card, Icon, Row, Text, Tooltip, theme } from "@nodebuilderjs/core";
+import { pointer } from "../icons.js";
+import type { State } from "../state.js";
+
+export function Counter(props: { state: State }) {
+  const { clicks, click, reset } = props.state;
+  // Only functions are reactive: Text reads `times` again whenever `clicks` changes.
+  const times = () => `You clicked ${clicks()} ${clicks() === 1 ? "time" : "times"}`;
+  return (
+    <Card gap={12}>
+      <Row gap={8} align="center" color={() => theme.text.secondary}>
+        <Icon svg={pointer} size={16} />
+        <Text bold>Counter</Text>
+      </Row>
+      <Text fontSize={20}>{times}</Text>
+      <Row gap={8}>
+        <Tooltip text="Back to zero">
+          <Button label="Reset" variant="flat" onClick={reset} disabled={() => clicks() === 0} />
+        </Tooltip>
+        <Button label="Click me" variant="primary" onClick={click} />
+      </Row>
+    </Card>
+  );
+}