flet-box 1.1.2 → 1.1.3

package/docs/README.md

@@ -18,6 +18,8 @@ This documentation is one continuous book. Start at **Chapter 0** and follow the
 | 11 | [The CLI](cli/README.md) | Create, run, and build projects with `flet-box` | Intermediate |
 | 12 | [Clean UI](guides/clean-ui.md) | The four skills every app ships with, the design system they hold, and the gate that enforces it | Intermediate |
 | 13 | [Accessibility](guides/accessibility.md) | The focus ring, the keyboard pass over every press, the roles the widgets declare, and the overlays that hold the keyboard | Intermediate |
+| 14 | [Migrate an app to a newer FletBox](guides/migration.md) | What changed between releases, and the codemod that writes it for you | Intermediate |
+| 15 | [The AI toolkit](guides/ai-toolkit.md) | The map from a question to the command, the per-file report, and the MCP server | Intermediate |
 | A | [Appendices](guides/minification-and-protection.md) | Minification, mobile, compatibility, embedding, online updates (OTA) | Advanced |
 
 > **Levels.** *Beginner:* start here and read in order. *Intermediate:* continue in order — you are comfortable with widgets. *Advanced:* for when you ship, skip on a first read.
@@ -56,6 +58,8 @@ Front cover (this page)
 → The CLI · cli/README.md
 → Clean UI · guides/clean-ui.md
 → Accessibility · guides/accessibility.md
+→ Migrating · guides/migration.md
+→ The AI toolkit · guides/ai-toolkit.md
 → Appendices (minification → mobile → compatibility → embedding → online updates)
 → The end of the book
 ```
@@ -71,7 +75,7 @@ Front cover (this page)
 
 - [Server toolkit](server/README.md) — Express/SQLite/Redis backend helpers (separate toolkit).
 - [Architecture](arquitectura.md) — how the framework is built inside.
-- [Contributing](CONTRIBUTING.md) — for people who add code or docs to FletBox.
+- [Contributing](../CONTRIBUTING.md) — for people who add code or docs to FletBox.
 
 ## Read this book as an app
 

package/docs/arquitectura.md

@@ -161,4 +161,4 @@ and strips dev warnings from the shipped output. See
 - [Routing](guides/router.md)
 - [Utilities](guides/utilities.md)
 - [Frontend services](guides/frontend-services.md)
-- [Contributing](CONTRIBUTING.md)
+- [Contributing](../CONTRIBUTING.md)

package/docs/cli/README.md

@@ -2,13 +2,13 @@
 
 The FletBox CLI helps you create, run, expand, and build FletBox applications from the terminal.
 
-You do not need to create every folder by hand. The CLI can create a working project, add screens and components, start a development server, and prepare a production bundle.
+You do not need to create every folder by hand. The CLI can create a working project, add screens and components, start a development server, prepare a production bundle, and check the code against the API the installed framework really has.
 
 ## Before you start
 
 Install:
 
-- Node.js 18 or newer.
+- Node.js 20.9 or newer.
 - npm.
 - A terminal such as Terminal, iTerm, PowerShell, or the VS Code terminal.
 
@@ -590,6 +590,156 @@ alongside the app, and that file says so.
 The full contract — the 21 rules, every finding code, and how to fix one — is
 [Chapter 12, Clean UI](../guides/clean-ui.md).
 
+## Look up the API the app really has
+
+`flet-box check-api` reads your own `src/` and reports every name that does not
+belong to the installed package: a widget that does not exist, a prop the real
+widget never reads, a widget called with a positional string instead of a props
+object, an import from another framework, and a broken import between two of your
+own modules — the last two resolved statically, so it works offline and in CI.
+
+It imports the package's barrel for real and reads its own types, so it cannot
+judge your code against an API you do not have.
+
+```bash
+flet-box check-api                      # scan ./src
+flet-box check-api --props Button       # print one widget's real props
+flet-box check-api --list               # print every public export
+flet-box check-api --emit-api           # write .fletbox/api/cheatsheet.md
+flet-box check-api --json               # the findings as data
+flet-box check-api --root ../my-app     # scan another project
+```
+
+Aliases: `flet-box check`, `checkApi`, `doctor`. It exits `1` when it finds an
+error, which is what lets it be the `api` gate inside `flet-box verify` and the
+`npm run check` a created app ships.
+
+`--emit-api` writes the cheatsheet an assistant should read before it writes any
+code for the app: every widget, every prop the package can prove, and a prop that
+has been renamed marked `(deprecated → onPress)` — the old spelling still works,
+so nothing else will tell you it is the one being retired. `flet-box create`
+generates the file at scaffold time; after a version bump, regenerate it with the
+command above. It is the API at that version, not the one you remember.
+
+## Unpack a widget
+
+Every prop lives in four places, and they can disagree: the type declaration, the
+engine's prop registry, the widget's own source, and its doc page.
+`flet-box unpack <Widget>` cross-checks the four and labels each disagreement
+instead of hiding it:
+
+| Label | What it means |
+| --- | --- |
+| `DEAD` | Declared in the interface, routed by the engine nowhere and read by the widget nowhere — writing it has no effect. |
+| `INVENTED` | The widget reads it, and no interface declares it. |
+| `UNDOCUMENTED` | The engine handles it for this widget and the interface hides it — the editor underlines a call that works. |
+| `DOC-ONLY` | The doc page promises it and the code has never heard of it. |
+| `CODE-ONLY` | The code accepts it and the doc page never mentions it. |
+
+```bash
+flet-box unpack Button                  # what Button really accepts, prop by prop
+flet-box unpack Button --example        # a paste-ready call using only verified props
+flet-box unpack Modal --diff            # declared vs real, and what disagrees
+flet-box unpack Button --json           # the same contract as data
+flet-box unpack --all                   # every widget → .fletbox/api/api.json
+flet-box unpack --all --md              # and the readable api.md beside it
+flet-box unpack --all --json            # the whole surface on stdout, writing nothing
+flet-box unpack Button --root ../my-app # read another project's package
+```
+
+`--example` is the answer to "what can I paste". It is built only from props the
+four surfaces agree on, never carries a renamed one, samples no blind `width` or
+`height` (a number pasted into `Switch` collapses it), and never drops a required
+prop — so the call it prints runs.
+
+`--all` writes the whole verified surface to `.fletbox/api/api.json`, the file a
+created app's assistant reads as data; `--md` puts `api.md` beside it and
+`--json` prints the same tree to stdout instead of writing anything. `npm run
+api` in a created app is `unpack --all --md`.
+
+## Verify everything at once
+
+`flet-box verify` is the single command: it parses every module, then runs the
+anti-hallucination check, the type check (the project's own `jsconfig.json`
+through TypeScript — the same service the editor uses, so a widget declared as
+a bare `HTMLElement` and the `widget.update({ … })` call it rejects are a gate
+failure with a line, not a squiggle to be ignored), the clean-UI check, the
+structural check and the prop contract **in parallel**, and then runs whichever
+test scripts the project declares — one report, one exit code. It is the command
+to run after every edit: the report names the gate, the file at `line:column`
+and what to do about it, instead of making you run seven commands and remember
+which one failed.
+
+```bash
+flet-box verify                  # every gate and every suite, one report
+flet-box verify --only syntax    # one gate: syntax | api | types | ui | structure | surface | tests
+flet-box verify --only tests     # the project's own suites, nothing else
+flet-box verify --fix            # the mechanical repair first, then the gates
+flet-box verify --json           # the report as data
+flet-box verify --watch          # re-runs the fast gates on every edit (no suites)
+flet-box verify --no-tests       # the static gates only; run the suites yourself
+flet-box run --verify            # the same, while the dev server runs
+```
+
+Every generated app ships it as `npm run verify`. The gates read the installed
+package, so they cannot judge your code against an API you do not have.
+
+The gates, and what each one owns:
+
+| Gate | What it proves |
+| --- | --- |
+| `syntax` | Every module loads. Each `.js`/`.mjs`/`.cjs` outside `node_modules`, `www` and `dist` is handed to `node --check` — the parser the runtime uses — and a parse error is reported at `file:line:column` with the offending source line, a caret under the character and a hint: an unclosed brace, a backtick that never closes, a smart quote that only looks like a quote. |
+| `api` | The code only names widgets and props that exist, and its own modules resolve each other. |
+| `ui` | The code is on the tokens, on the scale, and every control has a name. |
+| `structure` | Two of your modules do not import each other in a circle, every module lives where the project expects it, and no screen writes the DOM by hand. |
+| `surface` | Every prop a widget reads is declared, and every declared prop is read. |
+| `tests` | The project's own suites run and pass. `test`, `test:browser` and `test:visual` are run one after another when `package.json` declares them; a failing suite's own last output is the finding, which is where the rule is named. A project that declares none — a generated app — gets a skipped step, not a green one. |
+
+The parse gate runs first because the other four read code as text. A file that
+does not load is a line, not a finding about an invented prop, and telling the
+two apart is the difference between one edit and a guess.
+
+Every finding prints the same four things: the file at `line:column`, the code,
+what is wrong and a `→` suggestion. Warnings are printed too, under *what to
+review* — they do not fail the run, but they name the same line, which is the
+only form in which an agent can act on them.
+
+`--fix` runs `flet-box audit-fix` first: it rewrites what it can prove — a
+mistyped prop, a wrong relative path, a missing import — and then the gates
+read the result. A typo is mechanical, and it should never reach you as work
+to do.
+
+## The north metric
+
+Every `flet-box verify` run appends a row to the project's log —
+`.fletbox/metrics/generations.md` for a generated app, `metrics/generations.md`
+for this repository — with the time, the project, whether the gates were green,
+which gates failed and which codes they reported. **Every** run, green or not: a
+log that keeps only the successes cannot tell a correction from a first try.
+
+```bash
+flet-box metrics                  # the metric and the failures that recur
+flet-box metrics --log <file>     # read another log
+```
+
+A **generation** is a run of failing rows closed by the first green one. The
+**north metric** is the share of generations whose *first* run was green — the
+share of code that passed the gate with no correction at all. It is the number
+that moves when the code gets better, not when the report gets softer.
+
+The same command prints the three failures that recur most often and the rule
+each one should belong to, and it **exits non-zero** when a code has come back
+three times with no rule behind it. That is the loop closing: a code that keeps
+coming back is a rule that has not been written yet.
+
+The log also holds a **Gate defects** table. A code written there with its
+window — the first and the last day it explains — is the framework's debt, not
+the project's correction: those runs are left out of the metric, never asked to
+justify a rule, and printed on their own (`fixed`, or `⚠ OPEN`). A run after the
+window's last day counts again, so an old row can never silence the same mistake
+coming back. The table is data in the log, not a list inside the command: a
+project records what it proved, and the next release cannot rewrite its past.
+
 ## Command reference
 
 
@@ -623,6 +773,21 @@ The full contract — the 21 rules, every finding code, and how to fix one — i
 | `flet-box check-ui` | Runs the clean-UI gate over `src/`: tokens, scale, tap targets, labels, contrast. |
 | `flet-box check-ui --tokens` | Prints the measured contrast of every color token, on the background and on the surface. |
 | `flet-box check-ui --strict` | Makes the contrast warnings fail the run, not just the errors. |
+| `flet-box check-api` | Checks that every widget, prop and import your code names really exists. |
+| `flet-box check-api --props <Widget>` | Prints the real props of one widget. |
+| `flet-box check-api --list` | Prints every public export. |
+| `flet-box check-api --emit-api` | Writes `.fletbox/api/cheatsheet.md`, the API an assistant reads first. |
+| `flet-box unpack <Widget>` | Cross-checks a widget's four surfaces and labels what disagrees. |
+| `flet-box unpack <Widget> --example` | Prints a paste-ready call built only from verified props. |
+| `flet-box unpack <Widget> --diff` | Prints the reconciliation alone: declared vs real, and what disagrees. |
+| `flet-box unpack --all` | Writes the whole verified surface to `.fletbox/api/api.json`. |
+| `flet-box unpack --all --md` | Adds the readable `api.md` beside it. |
+| `flet-box verify` | Runs every gate at once: one report, one exit code. |
+| `flet-box verify --no-tests` | The static gates only, for a pipeline that runs the suites in their own jobs. |
+| `flet-box verify --fix` | Runs the mechanical repair first, then the gates. |
+| `flet-box metrics` | Reads the project's log: the north metric and the failures that recur. |
+| `flet-box audit-fix` | Rewrites what it can prove: a broken import, a mistyped prop, a renamed prop. |
+| `flet-box audit-fix --only migrations` | Applies only the renames from [the migration guide](../guides/migration.md). |
 | `flet-box pkg` | Opens the package manager. |
 | `flet-box --version` | Shows the CLI version. |
 | `flet-box --help` | Shows the command list. |
@@ -714,6 +879,7 @@ npm install --save-dev esbuild
 - Learn the basics in [Start here](../widget/START_HERE.md).
 - Learn complete app structures in [Build your first FletBox app](../guides/app-templates.md).
 - Explore every widget in the [widget documentation](../widget/README.md).
+- Ask "where is the work?" with [the AI toolkit](../guides/ai-toolkit.md) — `flet-box report`, `flet-box tools`, `flet-box mcp`.
 
 ---
 

package/docs/guides/README.md

@@ -16,6 +16,12 @@ This directory is the **conceptual index** of FletBox: how to build apps, set up
 - **[Accessibility](accessibility.md)** — Chapter 13 · the focus ring, the
   keyboard pass over every press, the roles and states the widgets declare, and
   the overlays that hold the keyboard.
+- **[Migrate an app to a newer FletBox](migration.md)** — Chapter 14 · what
+  changed between releases, the "de X a Y" table, and the codemod that writes
+  the new names for you.
+- **[The AI toolkit](ai-toolkit.md)** — Chapter 15 · the map from a question to
+  the command (`flet-box tools`), the per-file diagnosis (`flet-box report`), and
+  the same tools over MCP stdio (`flet-box mcp`).
 - **[Widget structure](widget-structure.md)** — the canonical, modular shape every widget follows (and how new ones are added).
 
 ## Appendices (Advanced — for shipping)

package/docs/guides/accessibility.md

@@ -158,6 +158,7 @@ is already in place; the table exists so you know what not to duplicate.
 | `Switch` | `switch` | `aria-checked` |
 | `Checkbox` | `checkbox` | `aria-checked` |
 | `Radio` / `Rating` | `radio` / `radiogroup` | `aria-checked` |
+| `ThemePicker` | `radiogroup` / `radio` | `aria-checked`; one Tab stop per swatch, and Enter or Space picks |
 | `Slider` | `slider` | `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-orientation` |
 | `ProgressBar`, `CircularBar` | `progressbar` | `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-busy` while indeterminate |
 | `Dropdown` | `combobox` | `aria-expanded`, `aria-controls`, `aria-activedescendant`, `aria-invalid`, `aria-labelledby` |
@@ -276,7 +277,7 @@ forbids. The runtime half lives in `/tests/a11y.html`.
 ## Continue reading
 
 - **Previous:** [Clean UI](clean-ui.md) — Chapter 12
-- **Next:** [Minify and protect a FletBox build](minification-and-protection.md) — Appendix A
+- **Next:** [Migrate an app to a newer FletBox](migration.md) — Chapter 14
 - **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
 
 You are reading **Chapter 13 · Accessibility**.

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/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

@@ -212,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

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. |