flet-box 1.1.1 → 1.1.3

package/docs/guides/ai-toolkit.md

@@ -0,0 +1,166 @@
+# The AI toolkit
+
+A FletBox project ships with ten checkers, and each one is right about its own
+slice: the API gate knows the prop is invented, the design gate knows the
+spacing is off-scale, the type gate knows the editor is unhappy. What an
+assistant lacks is not another checker — it is a **map from the question in front
+of it to the command that answers it**, and one report that puts every answer on
+the same page.
+
+This chapter is that map. Three commands share one catalogue:
+
+| Command | What it is for |
+| --- | --- |
+| `flet-box tools` | the map: every tool, the question it answers, the exact command |
+| `flet-box report` | the diagnosis: every file of *this* project, its verdict, and what to do next |
+| `flet-box mcp` | the same catalogue over MCP stdio, for an assistant with no shell |
+
+All three are **read-only**. None of them edits a source, renames a prop, runs a
+repair, builds or publishes. The single file they can produce is the report's
+own HTML page, and only when `--html` asks for it.
+
+## The map: `flet-box tools`
+
+```bash
+flet-box tools            # the catalogue, printed as a map
+flet-box tools --json     # the same catalogue on stdout, for a script
+flet-box tools --emit     # write .fletbox/api/tools.json into the project
+```
+
+Each entry carries the question in the words a person uses when they are stuck,
+the command, its arguments, its output formats, whether it writes anything, and
+the moments it applies. The nine tools are:
+
+| id | Question it answers |
+| --- | --- |
+| `report` | Where is the work? Which file is wrong, how wrong, what is missing? |
+| `widget_props` | Which props does this widget really accept, with types and deprecations? |
+| `widget_contract` | Do declaration, engine and docs agree — and which props are dead? |
+| `list_widgets` | What exists in this version of the framework? |
+| `check` | Is any widget, prop or import invented? |
+| `design` | Are the tokens, the scale, tap targets, labels and contrast legal? |
+| `syntax` | Does every module parse? |
+| `types` | What does the editor complain about? |
+| `metrics` | Which mistakes keep coming back, and does a rule own each one? |
+
+The catalogue is one file of pure data (`bin/utils/toolkit.js`). The CLI prints
+it, the report links every finding back to the tool that proves it, and the MCP
+server exposes the same entries — one source, three mouths. A tool that is
+missing from that file does not exist for any of them, which is what keeps the
+three from drifting apart.
+
+## The diagnosis: `flet-box report`
+
+`flet-box verify` answers a yes/no question — *may I say this is done* — gate by
+gate, because that is what an exit code needs. An assistant that is **lost**
+needs the other reading of the same facts: not which gate failed, but which file
+is wrong, how wrong, and which one thing to do next.
+
+```bash
+flet-box report                      # text, in the terminal
+flet-box report --json               # the whole report as data
+flet-box report --md                 # Markdown, to paste or commit
+flet-box report --html               # .fletbox/reports/report.html
+flet-box report --html --out /tmp/report.html
+flet-box report --tests              # also run the project's own suites
+```
+
+The command runs the six static gates once — `syntax`, `api`, `types`, `ui`,
+`structure`, `surface` — and then **re-groups their findings by file**, because
+the file is what the reader opens. Three decisions make it a tool rather than
+another number:
+
+1. **Every file is named**, clean ones included, with its line count, its
+   verdict, and the widgets it imports. A report that lists only the failures
+   cannot tell "this file is fine" from "this file was not read".
+2. **Every finding carries a next step and a rule.** A code with no suggestion
+   is printed with the tool that proves it instead — "something is wrong
+   somewhere" is not a finding.
+3. **It writes no metrics row.** A diagnostic must not change the record it is
+   diagnosing; only `verify` owns
+   `.fletbox/metrics/generations.md`.
+
+The text report reads in this order:
+
+```
+🩺 FletBox report · my-app · flet-box@1.1.2 · read-only
+
+  files: 12 clean · 0 with findings
+  0 error(s), 0 warning(s) · 24 widgets, 0 with contract gaps
+
+  ✓ syntax    clean
+  ✓ api       clean
+  ✓ types     clean
+  ✓ ui        clean
+  ✓ structure clean
+  ✓ surface   clean
+```
+
+When something is wrong, a ranked **next** list follows, one line per finding:
+the file at `line:column`, the code, the message, the fix, and the rule that
+owns it. Then the files that are not clean (with their widgets), any findings
+that name the installed package rather than your code — the framework's own
+debt, kept separate on purpose — the widget contract ledger, and the metrics
+line.
+
+The HTML page carries the same report in one self-contained file: inline CSS,
+no `<script>`, no network request. It opens offline, in any browser, and every
+value is escaped, so a report about code is safe to open even when that code
+contains markup.
+
+The exit code is `1` when the report has errors, so `flet-box report` can stand
+in for `flet-box verify` in a script that only needs the verdict.
+
+## The server: `flet-box mcp`
+
+An assistant with no shell cannot run `flet-box report`. `flet-box mcp` serves
+the same catalogue over MCP stdio — newline-delimited JSON-RPC 2.0 on stdin and
+stdout — so the same nine tools are callable without a terminal:
+
+```bash
+flet-box mcp
+```
+
+It answers `initialize`, `ping`, `tools/list` and `tools/call`. Two request
+lines are enough to see it work:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
+{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"report","arguments":{"root":"."}}}
+```
+
+Every tool result is text (the same text the CLI prints), so an editor or an
+agent reads exactly what a person would read. A missing required argument or a
+directory that does not exist comes back as a result with `isError: true`; an
+unknown tool name is a JSON-RPC error (`-32602`). Neither is a crash, and
+neither can be mistaken for an answer. When stdin closes behind a slow request,
+the server finishes it before exiting — a one-shot client gets its answer.
+
+The server **never** calls the logging path: it runs the gates, not `verify`, so
+asking a question through MCP cannot add a row to the metrics log either.
+
+## Where to plug it in
+
+- In an app's `package.json`, keep the catalogue current next to the API files:
+  `flet-box tools --emit` beside `flet-box unpack --all --md`.
+- Commit `.fletbox/api/tools.json`: it is the map an assistant reads when it
+  cannot run a command.
+- Treat `.fletbox/reports/` as generated output — a page you open, not a file
+  you review. Recreate it with `flet-box report --html`.
+- Register `flet-box mcp` as an MCP server if your editor supports one; the
+  project path is the only argument it needs.
+
+The loop stays the one the other chapters teach: `flet-box report` to find the
+work, the named command to understand it, `npm run verify` to prove the fix.
+The toolkit only removes the guess about **which** command answers the question
+you have.
+
+---
+
+## Continue reading
+
+- **Previous:** [Migrate an app to a newer FletBox](migration.md) — Chapter 14
+- **Next:** [Minify and protect a FletBox build](minification-and-protection.md) — Appendix A
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 15 · The AI toolkit**.

package/docs/guides/compatibility.md

@@ -33,7 +33,7 @@ Private browsing, sandboxed iframes, and strict browser policies may disable som
 
 ### Node.js
 
-Node.js 18 or newer is required for the CLI and build tooling. FletBox widgets themselves are browser-oriented and should not be rendered directly in a Node process without a DOM environment.
+Node.js 20.9 or newer is required for the CLI and build tooling — the floor `package.json` declares in `engines`. FletBox widgets themselves are browser-oriented and should not be rendered directly in a Node process without a DOM environment.
 
 ## Build targets
 

package/docs/guides/first-app.md

@@ -4,24 +4,23 @@ This page is for **absolute beginners**. You do not need to know any trick — y
 
 ## Before you start
 
-FletBox is not published to the npm registry, so first you install the CLI once and link it globally:
+You need Node.js 20.9 or newer and one command, because FletBox is published on npm:
 
 ```bash
-git clone https://github.com/kuko53348/flet-box.git
-cd flet-box
-npm link                          # link the flet-box CLI globally
+npm install -g flet-box           # the CLI, once
 ```
 
-Then create an empty project, link the framework into it, and start the dev server:
+Then create an empty project, install the framework into it, and start the dev server:
 
 ```bash
-cd ..
 flet-box create my-app
 cd my-app
-npm link flet-box                 # or: npm install ../path/to/flet-box
+npm install                       # flet-box itself, from the registry
 npm run dev
 ```
 
+If you would rather not install anything globally, `npx flet-box create my-app` does the same thing.
+
 Open your browser at `http://localhost:8000`. You should see "Hello FletBox" (or a small welcome screen). If you do, everything is working.
 
 ## Step 1: the smallest app

package/docs/guides/migration.md

@@ -0,0 +1,92 @@
+# Migrate an app to a newer FletBox
+
+> **Level: Intermediate.** Read this page when a FletBox release renamed or removed something your app uses. It follows [Accessibility](accessibility.md) — Chapter 13 — in the book's reading path.
+
+FletBox does not break your app on purpose. A prop that gets a better name keeps working under the old one, and the framework keeps both until the next major says otherwise. **But a name you keep writing is a name you keep paying for**: the old spelling disappears at the next major, and the app breaks then, on a machine that is not yours.
+
+So this page exists for two moments:
+
+- **You are upgrading.** The table below says, prop by prop, what changed and what to write instead.
+- **You are publishing a major.** `flet-box release --major` refuses to publish a version that has no section here — a major is exactly the release where an app has to change something, so the guide has to exist before the release does.
+
+## The rule the framework follows
+
+A rename in FletBox is always done in this order:
+
+1. The new name is declared and documented **first**.
+2. The old name keeps working, marked `@deprecated` in `src/index.d.ts`.
+3. The old name lands in `src/widget-factory/deprecations.js` — the one table the guide, the codemod and the contract test all read.
+4. The old name is listed in the table below, with the version that renamed it.
+5. The old name is removed in the next **major**, and that major's section says so.
+
+Nothing here is a breaking change inside the 1.x line. Read the table as a list of names to stop writing, not as a list of things that already broke.
+
+## 1.2.0
+
+Every old name below still works in 1.2.0. Write the new one.
+
+| Widget | From | To | What changed |
+| --- | --- | --- | --- |
+| `Accordion` | `onToggle` | `onPress` | The callback still receives the new expanded state; the name is now the framework-wide one. |
+| `Checkbox` | `onCheck` | `onPress` | The callback still receives the new checked state. |
+| `Dropdown` | `onChange` | `onPress` | The callback still receives the chosen value — and only the value. The second argument the old type promised was never sent. |
+| `Radio` | `onSelect` | `onPress` | The callback still receives the new selected state. |
+| `Slider` | `onChanged` | `onPress` | The callback still receives the new number. |
+| `Switch` | `onToggle` | `onPress` | The callback still receives the new toggled state. |
+| `Tooltip` | `tooltipDelay` | `delay` | Same number, same units: milliseconds. |
+| `Scaffold` | `navSideBar` | `leftNavBar` | The side moved into the name. A call that also says `navSideBarPosition: "right"` becomes `rightNavBar`. |
+| `Scaffold` | `navSideBarWidth` | `leftNavBarWidth` | The old width was accepted and then **ignored** — the panel kept the default width. The new name applies, so the panel finally takes the width you wrote. |
+| `Scaffold` | `navSideBarPosition` | (removed) | The side now lives in the prop name (`leftNavBar` / `rightNavBar`). Nothing reads this prop any more, so the key goes with it. |
+
+Two names that look like the ones above are **not** deprecated: `TreeView` still calls its own selection callback `onSelect` and its own expansion callback `onToggle`, because that is what a tree calls them. The rename was about the framework-wide `onPress`, and a tree's own vocabulary is not a candidate for it. `flet-box audit-fix` knows the difference: the table names a widget, not a spelling.
+
+## Applying the table
+
+The framework ships a codemod for the rows where the answer is mechanical:
+
+```bash
+npx flet-box audit-fix --only migrations
+```
+
+In a project made with `flet-box create` the same command is `npm run fix` (which also repairs imports and mistyped props). The codemod rewrites only the calls it can prove:
+
+- the widget has to declare **both** the old name and the new one;
+- the call must not already carry the new name — two callbacks for one event is a decision, not a rename;
+- for `Scaffold`, the call must not already carry a new sidebar prop, because the legacy one is inert there.
+
+Anything it cannot prove is printed under **"Left for you to decide"** and left untouched. A codemod that guesses is worse than one that stops: a wrong rename changes the screen silently, and the gate would no longer complain about it.
+
+What the codemod will **not** do, on purpose:
+
+- it will not change a callback's *signature* — `Dropdown`'s old `onChange(value, label)` promised a second argument that was never sent, and the codemod renames the prop without inventing the argument;
+- it will not touch a call that spreads another object (`{ ...props }`), because the keys inside are not visible;
+- it will not rename anything that is not a FletBox widget call;
+- it will not edit `docs/`, `skills/` or the framework's own sources.
+
+Run it, then read the diff:
+
+```bash
+npx flet-box audit-fix --only migrations
+git diff
+```
+
+## Before you publish a major
+
+A major release is the one that removes the old names for good. The framework will not let it through without this page saying what it removes:
+
+```bash
+flet-box release --major
+# ❌ the migration guide has no "## 2.0.0" section
+```
+
+To publish it, add the section here first — one row per removed or renamed prop, with the version as the heading — and the release goes through. The rows are read by `scripts/check-migrations.mjs`, which also proves that the table above, the deprecated markers in `src/index.d.ts`, the deprecation table in the framework and this codemod all name the same things. A prop that is deprecated in the types but missing from this page fails CI, not the user's app.
+
+---
+
+## Continue reading
+
+- **Previous:** [Accessibility](accessibility.md) — Chapter 13
+- **Next:** [The AI toolkit](ai-toolkit.md) — Chapter 15
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 14 · Migrating to a newer FletBox**.

package/docs/guides/minification-and-protection.md

@@ -255,6 +255,7 @@ Minification reduces the web payload inside the native application. It does not
 
 ## Continue reading
 
-- **Previous:** [Accessibility](accessibility.md) — Chapter 13
+- **Previous:** [The AI toolkit](ai-toolkit.md) — Chapter 15
 - **Next:** [Build FletBox for mobile and other platforms](mobile-and-platforms.md) — Appendix B
+- **See also:** [Migrate an app to a newer FletBox](migration.md) — Chapter 14
 - **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/mobile-and-platforms.md

@@ -26,7 +26,7 @@ Capacitor packages the compiled web application inside a native shell. You can a
 
 ### For every platform
 
-- Node.js 18 or newer.
+- Node.js 20.9 or newer (the CLI's `engines` floor).
 - npm.
 - A working FletBox project.
 - A production build that creates the directory configured as Capacitor's `webDir`.

package/docs/guides/online-updates.md

@@ -116,7 +116,7 @@ Every bundle ships a small manifest at `www/config.json`. This is what a running
 
 `update.url` is resolved automatically, in this order:
 
-1. `update.url` in `fletbox.config.json` at your project root (explicit wins).
+1. `update.url` in `fletbox.config.json` at your project root (explicit wins) — unless it is still the scaffold placeholder, which is not a choice. See [The Pages address of a generated app](#the-pages-address-of-a-generated-app).
 2. Derived from the `repository` field of `package.json`, mapped to GitHub Pages: `https://<user>.github.io/<repo>/`.
 3. Derived from the **current project's** git remote `origin` (when it is a GitHub URL). This means `flet-box createBundle` always points at the project it is built in, never at the flet-box framework installed as a dependency.
 4. If none of these exist, OTA is **disabled** and the bundle simply runs what shipped in it.
@@ -152,10 +152,22 @@ things at once:
 - writes that address into the header of the generated `.github/workflows/build.yml`;
 - prints it in the closing summary, with the one-time setting Pages needs.
 
-Without `--repo` nothing is invented. `fletbox.config.json` keeps the generic
-placeholder `https://TU-USUARIO.github.io/TU-REPO/`, the workflow header names a
-guess built from the folder name, and the workflow says so in its own comment:
-write the real address in both files that state it.
+Without `--repo` nothing is invented at scaffold time. `fletbox.config.json` keeps
+the generic placeholder `https://TU-USUARIO.github.io/TU-REPO/`, the workflow
+header names a guess built from the folder name, and the workflow says in its own
+comment which part of that address still has to be checked by hand.
+
+The build does not trust that placeholder. `TU-USUARIO` and `TU-REPO` mean "not
+configured yet", so `flet-box createBundle` falls through to rules 2 and 3 and
+writes the address it derived — and prints that it derived, because a manifest
+pointing at a real site next to a file that still says `TU-REPO` is a half-filled
+config you should either finish or leave alone. A project with no GitHub remote
+yet gets `update.url: null`: OTA is off, the bundle runs what shipped in it, and
+nothing polls a host that does not exist.
+
+That matters because the failure used to be silent. The app compares bundle
+**hashes**, and OTA is built never to break the app, so a placeholder URL that
+reached a bundle produced no error, no dialog and no update — ever.
 
 **The workflow log is the authority.** The header names the address you typed at
 scaffold time; the `Where this lives` step prints the address the run *actually*
@@ -200,6 +212,8 @@ Declare those files in `fletbox.config.json` and they become part of every relea
 
 Globs are relative to the project root and support `**`, `*` and `?`. At build time `flet-box createBundle` copies each match into `www/` at the same path, hashes it, and lists it in the manifest's `assets` array — which is also what your CI publishes to GitHub Pages.
 
+A project created by `flet-box create` already declares its own pictures. The scaffold creates `assets/` and puts `assets/logo.png` there, so that folder is where an app keeps its images; the generated `fletbox.config.json` lists `assets/**/*.png`, `.jpg`, `.jpeg`, `.svg` and `.webp`. Without that entry the bundle copied `src/assets` (icons and fonts) and nothing else: the built app served every screen with a broken picture while `npm run dev` — which serves the project root — looked perfect. Other formats, or a file kept outside `assets/`, still need their own glob; a source document parked in `assets/` (the PDF a catalogue was written from) is deliberately not matched.
+
 The app then reads them through the loader instead of `fetch`:
 
 ```js
@@ -274,7 +288,7 @@ Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings →
 | Symptom | Likely cause |
 | --- | --- |
 | Build prints "THIS APP DOES NOT SUPPORT OTA UPDATES" | No public GitHub repo is reachable from the project (no `origin` remote, a non-GitHub remote, or nothing configured). The app still works — it runs the bundle it shipped with. Create the repo, push it, and rebuild. |
-| No dialog, app runs old code | `update.url` missing/incorrect, or no `v*` tag was published — a normal push updates the site but deliberately leaves the manifest out, so there is nothing to compare against. |
+| No dialog, app runs old code | `update.url` wrong — a real address that is not where the bundle is (the scaffold placeholder is not one of those: the build derives the address and prints it). Or no `v*` tag was published — a normal push updates the site but deliberately leaves the manifest out, so there is nothing to compare against. |
 | `hash mismatch` in console | The published `config.json` and bundle are from different builds. Re-run `flet-box release` so both are published together. |
 | Dialog appears but download fails | The Pages site is not reachable/CORS-blocked from the app origin. Pages serves with permissive headers; check you are not behind a proxy that strips them. |
 | Update applies but reverts on next launch | Cache Storage unavailable (private browsing). The bundle runs once but cannot persist. |

package/docs/server/deployment.md

@@ -99,7 +99,7 @@ Queues also require Redis to coordinate jobs between workers.
 
 ## Production checklist
 
-- Use Node.js 18 or newer.
+- Use Node.js 22 or newer — the floor `flet-box-server` declares in `engines` (the FletBox CLI itself needs 20.9).
 - Run `npm ci --omit=dev` in deployment.
 - Set a strong `JWT_SECRET`.
 - Remove hardcoded admin credentials.

package/docs/tools/styling.md

@@ -18,7 +18,7 @@ import { border, margin, padding, gradient, shadow, color } from "flet-box";
 | Function | Signature | Returns | Description |
 | --- | --- | --- | --- |
 | `animation` | `animation(name, duration?, timing?, iteration?)` | `string` | CSS `animation` shorthand. `name` can also be an options object (`{ name, duration, timing, delay, iteration, direction, fillMode }`). |
-| `border` | `border(width = 1, style = "solid", color?)` | `string` | CSS `border` shorthand, e.g. `1px solid #e2e8f0`. |
+| `border` | `border(width = 1, style = "solid", color)` | `string` | CSS `border` shorthand, e.g. `1px solid #e2e8f0`. The colour is required: a border without one is invisible. |
 | `gradient` | `gradient(type, colors, angle = 135)` | `string` | A CSS gradient background. `type` is `"linear"`, `"circle"` (radial), or `"conic"`; `colors` is an array of color strings. |
 | `margin` / `padding` | `margin(value)` / `padding(value)` | `string` | Spacing CSS. `value` can be a number, a string, or `{ all, horizontal, vertical, top, right, bottom, left }`. |
 | `rgba` | `rgba(r, g, b, a = 1)` | `string` | `rgba(r, g, b, a)` with an alpha default of `1`. |
@@ -29,7 +29,7 @@ import { border, margin, padding, gradient, shadow, color } from "flet-box";
 | `flex` | `flex(grow, shrink = 1, basis = "0%")` | `string` | CSS `flex` shorthand. `grow` can also be `{ grow, shrink, basis }`. |
 | `grid` | `grid(options)` | `string` | CSS grid template from `{ columns, rows, gap }`; `gap` can be a number or `{ row, column }`. |
 | `color` | `color(value)` | Color object | A mutable, chainable color. See the Color object below. |
-| `stackPosition` | `stackPosition(widget, props)` | `Widget` | Applies absolute positioning/centering to a widget and returns it. |
+| `stackPosition` | `stackPosition(widget, props)` | `Widget` | Anchors a widget absolutely over its positioned ancestor and returns it. Takes `top`/`right`/`bottom`/`left` (numbers go through the `rem` contract), the logical `start`/`end`, and the shorthands `centerX`, `centerY`, `center`, `fullWidth`, `fullHeight`, `full`. A `false` value means "do not apply". |
 | `toREM` / `toPX` | `toREM(value)` / `toPX(value)` | `string \| undefined` | Convert a value between `rem` and `px`. |
 | `setBaseFontSize` | `setBaseFontSize(px)` | `void` | Change the `rem` base (default `16`). |
 | `getBaseFontSize` | `getBaseFontSize()` | `number` | The current `rem` base. |

package/docs/tools/theme.md

@@ -1,17 +1,31 @@
 # Themes
 
 ## Overview
-FletBox ships a built-in color system: `colors` is the palette of the current theme, `palettes` holds all named palettes, and the theme functions switch between light and dark, subscribe to changes, and follow the system preference. A `ThemeProvider` and the `useTheme()` hook wrap them for component-based apps.
+FletBox ships a built-in color system: `colors` is the palette of the current theme, `palettes` holds all named palettes, and the theme functions switch between light and dark, subscribe to changes, and follow the system preference. On top of that sit the accent presets — selectable hue families that paint `colors.primary`, its ink and its wash over whichever palette is active — and the theme functions carry them too. A `ThemeProvider` and the `useTheme()` hook wrap all of it for component-based apps.
 
 ## When to use
 - Style widgets with semantic tokens (`colors.surface`, `colors.primary`, `colors.error`) instead of hard-coded hex values.
 - Add a light/dark toggle that re-colors the whole app instantly.
 - Follow the OS dark/light setting automatically.
+- Let the reader pick the app's color — buttons, icons and plates and all — with [`ThemePicker`](../widget/ThemePicker.md) and `setAccent`.
 
 ## Import
 
 ```javascript
-import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemeProvider } from "flet-box";
+import {
+  colors,
+  setTheme,
+  registerPalette,
+  toggleTheme,
+  subscribeTheme,
+  ThemeProvider,
+  registerAccent,
+  setAccent,
+  applyAccentPreference,
+  getAccent,
+  getAccentSurfaces,
+  listAccents,
+} from "flet-box";
 ```
 
 ## Functions
@@ -20,6 +34,13 @@ import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemePr
 | --- | --- | --- | --- |
 | `setTheme` | `setTheme('light' \| 'dark')` | `Record<string, string>` | Switch the active palette. |
 | `registerPalette` | `registerPalette(themeName, palette)` | `Record<string, string>` | Merge brand tokens into a named palette and repaint the page. |
+| `registerAccent` | `registerAccent({ id, label?, light, dark })` | `Accent \| null` | Add or replace one selectable accent. Each end of the pair is a hex or a five-stop ramp; `null` means the argument was unusable. |
+| `setAccent` | `setAccent(id \| null, { surfaces? })` | `Record<string, string>` | Lay an accent over the live palette and store the choice. `surfaces: true` paints the page and its panels from the same ramp. `null`, or an id nothing registered, takes it back off. |
+| `applyAccentPreference` | `applyAccentPreference(id, { surfaces? })` | `string \| null` | Paint the app's own brand at boot, and only when the reader has never picked one. Never stores anything. |
+| `getAccent` | `getAccent()` | `string \| null` | The accent id on screen, or `null` while the palette's own `primary` shows. |
+| `getAccentSurfaces` | `getAccentSurfaces()` | `boolean` | Whether the live accent also paints the surfaces, or only the brand. |
+| `listAccents` | `listAccents()` | `Accent[]` | Every selectable family, in registration order — `{ id, label, light, dark }`. |
+| `listAccentRamps` | `listAccentRamps()` | `Array` | The same families with all five stops of each theme beside them, for a swatch that shows the whole ramp. |
 | `getTheme` | `getTheme()` | `string` | The active theme name. |
 | `toggleTheme` | `toggleTheme()` | `string` | Flip light/dark and return the new name. |
 | `getColor` | `getColor(name, opacity?)` | `string` | Resolve a token (optionally with alpha). |
@@ -27,7 +48,7 @@ import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemePr
 | `applySystemTheme` | `applySystemTheme()` | `string` | Apply light/dark from the OS preference. |
 | `watchSystemTheme` | `watchSystemTheme()` | `() => void` | Follow the OS preference live; returns an unsubscribe function. |
 | `ThemeProvider` | `ThemeProvider({ children, theme? })` | `Widget` | Provide a theme (defaults to system) for a subtree. |
-| `useTheme` | `useTheme()` | object | `{ colors, setTheme, getTheme, toggleTheme, getColor, applySystemTheme }`. |
+| `useTheme` | `useTheme()` | object | `{ colors, setTheme, getTheme, toggleTheme, getColor, applySystemTheme, setAccent, getAccent, listAccents }`. |
 
 Plus the constants: `colors` (current palette) and `palettes` (all named palettes, keyed by name).
 
@@ -36,9 +57,10 @@ Plus the constants: `colors` (current palette) and `palettes` (all named palette
 Every token is available on `colors`:
 
 - **Brand:** `primary`, `secondary`, `info`, `success`, `warning`, `danger`, `error`.
+- **On a fill:** `onPrimary` — the ink the theme puts on a `primary` plate. Ask the theme for it; a literal `#ffffff` is a bug the moment the reader picks a pale accent.
 - **Surfaces:** `background`, `surface`, `card`, `overlay`.
 - **Text:** `text`, `textSecondary`, `textDisabled`, `divider`, `border`, `shadow`.
-- **Tints:** `gray50` … `gray900`, plus the soft backgrounds `errorBg`, `successBg`, `warningBg`, `infoBg`.
+- **Tints:** `gray50` … `gray900`, plus the soft backgrounds `primaryBg`, `errorBg`, `successBg`, `warningBg`, `infoBg`.
 - **Glass:** `glass` (the translucent surface) and `glassBorder` (its rim), meant to pair with `backdropFilter`. Light is white glass, dark is a slate pane with a light rim.
 
 The `dark` palette overrides the surface/text tokens; `gray*` and brand colors also shift to keep contrast. Read [the palette walkthrough](../guides/utilities.md) for usage patterns.
@@ -80,6 +102,118 @@ it at the bottom of `src/database/themes.js` — the same file that declares
 `lightColors` and `darkColors` — so a project that edits its brand colors is
 already correct without touching `src/app.js`.
 
+## Accent presets: `setAccent`
+
+`registerPalette` says what a theme is. An **accent** is what the reader picks
+inside it: one hue family painted over the palette's `primary`, its ink and its
+wash, so every button, icon and selected plate on the screen moves together.
+Twelve families ship (`listAccents()`), and each is a *pair* — the stop that hue
+wears on a light page and the stop it wears on a dark one — which is why a
+[`ThemePicker`](../widget/ThemePicker.md) swatch is split down the middle.
+Worn with `surfaces: true`, the same family paints the page and its panels too,
+and the picker is choosing a **theme** rather than a brand color; see
+[Worn as a theme](#worn-as-a-theme) below.
+
+```javascript
+import { ThemePicker, applyAccentPreference, listAccents } from "flet-box";
+
+// At boot: the app's own brand, and only if the reader has never chosen.
+applyAccentPreference("teal");
+
+// In a settings sheet: the reader's choice, which paints and persists.
+ThemePicker({
+  accents: listAccents().filter((a) => ["teal", "blue", "rose", "orange"].includes(a.id)),
+  size: 48,
+  onChange: (id) => console.log("accent:", id),
+});
+```
+
+What it does:
+
+- **It is a layer, not a second palette.** The one repaint funnel lays the
+  accent's `primary`, `onPrimary` and `primaryBg` over the theme's own tokens, so
+  a toggle, an OS flip or a `setTheme` from anywhere keeps the choice instead of
+  writing the brand back over it. The `--color-*` properties and the PWA status
+  bar move with it because they read the same tokens. Worn with `surfaces: true`
+  the same funnel lays five more tokens down — `background`, `surface`, `card`,
+  `border`, `divider` — and nothing else changes hands.
+- **`setAccent` is the reader's verb, `applyAccentPreference` is the app's.** The
+  first stores `"fletbox-accent"`, so the picker opens on the answer the reader
+  gave; the second paints without storing, so it is a default the reader can
+  overrule and never a choice written into their name. An unknown id changes
+  nothing, and `setAccent(null)` gives the palette its own brand back.
+- **A created app opens on `neutral`.** `flet-box create` writes
+  `applyAccentPreference("neutral")` at the bottom of `src/database/themes.js`,
+  beside the `registerPalette` calls that carry the same three values, so a new
+  project reads as paper and type rather than as somebody else's brand: the
+  accent is the page's own ink, near-black on a light page and near-white on a
+  dark one. The first thing a designer changes is that id — and the Preferences
+  screen already ships a `ThemePicker`, so a reader can change it without them.
+- **A family is measured before it ships.** Each pair clears the numbers a
+  hand-built palette has to as well: white or near-black words on the accent at
+  4.5:1, the accent as text on the page at 4.5:1 and as a glyph on a card at 3:1,
+  page ink, secondary ink and the accent itself on its wash at 4.5:1, and the
+  wash lifting off the background by 1.04 to 1.5. `#3b82f6` fails the first one —
+  white words measure 3.15:1 on it — which is why an accent is a stop on a ramp
+  and never the middle of one.
+- **A brand the list lacks is registered, not typed.**
+  `registerAccent` takes an `id`, a `label` and a `light`/`dark` pair: one hex
+  each, and the wash and `colors.onPrimary` are derived, or a five-stop ramp whose
+  stop 0 (light) and stop 1 (dark) are the ones painted. The call belongs in
+  `src/database/themes.js`, beside the palette it feeds.
+
+### Worn as a theme
+
+`setAccent(id, { surfaces: true })` is how an app lets the reader pick the color
+of the *page* and not only of its buttons. Five more tokens arrive off the same
+five stops the swatch paints, in the order a designer would build them by hand:
+
+| Token | Light, from the ramp | Dark, from the ramp |
+| --- | --- | --- |
+| `background` | `ramp[4]` — the palest stop | `ramp[3]` scaled to 10% |
+| `surface` | `ramp[3]` — the measured wash stop | `ramp[3]` scaled to 18% |
+| `card` | `#ffffff`, the way it lifts off `#fafafa` today | `ramp[3]` scaled to 28% |
+| `border`, `divider` | `ramp[3]` darkened 6% | `ramp[3]` scaled to 45% |
+
+Teal, measured: a light page `#f0fdfa` with `#ccfbf1` panels, white cards and
+`#c0ece3` hairlines; a dark page `#010c0b` with `#031514` panels, `#04211f`
+cards and `#073531` hairlines. `applyAccentPreference("teal", { surfaces: true })`
+boots an app in that theme for a reader who has never chosen.
+
+Three rules the derivation keeps, and every one of them is measured by
+`tests/regression.test.js` ("an accent worn as a theme keeps every ink on the
+surfaces it paints") for all twelve families in both themes:
+
+- **Only the surfaces move.** `text`, `textSecondary`, `textDisabled`, the brand
+  trio and every semantic signal — `success`, `danger`, their plates and alert
+  tints — answer the same values they had worn as a brand-only accent. The neutral
+  ink scale was measured against a near-white and a near-black page, and a tinted
+  stop of a saturated family sits within a few percent of both, so the text needs
+  re-measuring rather than re-deriving; and a tinted theme still has to be able to
+  say "this failed" in a hue that is not its own.
+- **Dark scales toward black, never toward white.** Multiplying a channel keeps the
+  hue exactly; mixing toward white washes it out, and `#042f2e` stops reading as
+  teal at all. The steps also have to be *visible*, and a WCAG ratio cannot see
+  them — near black, every pair compresses to about 1.0 — so the three dark depths
+  are separated in CIELAB `L*`: blue's land at 2.3, 4.5 and 8.6, which is the range
+  the shipped neutral dark palette already occupies (`#09090b` at 2.5, `#18181b` at
+  8.4).
+- **The plate keeps its own stop.** `primaryBg` still comes from the wash stop the
+  family was measured against, and on a light page that is now also the panel. A
+  selected row inside a panel is therefore the same color as its container, exactly
+  as it is in the neutral palette, where `#f4f4f5` sits on `#fafafa` at 1.05 — the
+  one place a tinted theme buys its tint by spending a layer.
+
+An accent registered as a bare pair of hexes has no lightness to walk, so it paints
+brand only: `{ surfaces: true }` is accepted and ignored, and the surfaces keep the
+palette's own values.
+
+The choice rides in one stored string — `"teal"` for a brand, `"teal+surfaces"`
+for a theme — which is why `getAccent()` and `getAccentSurfaces()` answer together.
+A bare id is what every app wrote before surfaces existed, so it still parses; and
+a picker needs both answers, because the family already on screen means two
+different things and moving between them is a repaint, not a no-op.
+
 ## Examples
 
 ### Everyday example
@@ -131,6 +265,7 @@ runApp(ThemeProvider({ children: ThemedApp() }), "root");
 - [Device & environment](device.md) — previous chapter.
 - [Markdown, code & HTML](markdown.md) — next chapter.
 - [Colors and utilities guide](../guides/utilities.md) — palette walkthrough.
+- [ThemePicker](../widget/ThemePicker.md) — the swatch grid that calls `setAccent`.
 
 ---