flet-box 1.1.1 → 1.1.3

package/AGENTS_FOR_CODE_GEN.md

@@ -0,0 +1,284 @@
+# AGENTS_FOR_CODE_GEN.md
+
+The contract for an agent that **writes FletBox code**. It holds in an app built
+with `flet-box create` and in the framework's own source.
+
+`AGENTS.md` is the contract for *maintaining the framework*. This one is for
+*producing code with it*: what may be written, what may not, and how it is
+proved.
+
+---
+
+## 0. The golden rule
+
+> **If a widget or a prop is not in `.fletbox/api/cheatsheet.md`, it does not
+> exist.**
+
+An invented prop throws nothing. The engine ignores it, the layout breaks
+quietly, and nobody finds it for weeks. If the cheatsheet does not hold what
+the task needs, **ask** — do not invent.
+
+| What I need | Where it lives | How it is produced |
+| --- | --- | --- |
+| Which widgets exist and which props each one takes | `.fletbox/api/cheatsheet.md` | `flet-box check-api --emit-api` — runs before `npm run dev` |
+| The same surface as data: one entry per prop, with its engine target, default, aliases and a sample value | `.fletbox/api/api.json` | `flet-box unpack --all --md` |
+| Everything one widget accepts, and whether each prop is really wired | `flet-box unpack <Widget>` | — |
+| A call I can paste as-is | `flet-box unpack <Widget> --example` | — |
+| The real props of one widget | `npm run check -- --props <Widget>` | — |
+
+Both files are **generated output**: never hand-edit them, regenerate after
+upgrading `flet-box`.
+
+---
+
+## 1. Five things you may never do
+
+1. **No runtime dependency.** FletBox has zero runtime dependencies and the app
+   is offline: no `react`, `vue`, `svelte`, `lit`, `jquery`, `tailwindcss`, no
+   CDN `<script>`, no `.jsx`/`.tsx`. Plain ESM `.js`, with the `.js` extension
+   in every import.
+2. **No hardcoded color.** Every fill, ink and border is a `colors.*` token.
+   A hex literal in a screen is reported as `RAW_COLOR`.
+3. **No hand-written DOM.** Build with widgets and props — never with
+   `innerHTML`, `createElement` or a template string. (The engine uses
+   `innerHTML` internally for rich text; app code does not.)
+4. **No widget or prop outside the cheatsheet**, and no positional arguments:
+   `Text({ text: "Hi" })`, never `Text("Hi")`.
+5. **No API change without deprecation.** Renaming or removing a prop is a
+   breaking change: keep the old name working, mark it, and write the
+   "from X to Y" line in the migration guide.
+
+---
+
+## 2. Ten rules that survive a review
+
+Each cites the numbered rule in `skills/fletbox-design/SKILL.md`, which is
+where the longer argument lives.
+
+1. **Numbers, not pixels.** `padding: 16` is a framework unit and scales with
+   the reader's font; `padding: "16px"` does not. (03, 07)
+2. **Tokens, not colors.** `bgColor: colors.surface`. One brand color per
+   screen; the accent is the reader's to choose, never a hex in a widget. (03, 28)
+3. **Hierarchy in three seconds.** One type size per element, one weight per
+   role. A label and its value that look alike mean the hierarchy is broken. (08)
+4. **Space carries meaning.** 16 inside a card, 16 or 24 between cards, 24
+   between sections. Never mix padding and gap on the same list. (07)
+5. **Depth is a scale.** `elevation` picks the level; a hand-written shadow is
+   noise. (10)
+6. **Every control has a name.** An icon-only button needs `aria-label`, a
+   field needs a label. The gate reports `ICON_ONLY_CONTROL` and
+   `UNLABELED_FIELD`. (11)
+7. **Tap targets are 40 or more**, reached with `height`, not with padding. (11)
+8. **Every interaction has four states.** hover, focus, active and disabled
+   come from the engine's props — do not re-implement them per widget. (12)
+9. **The phone range is the test device.** From 320×568 to 430×932 nothing
+   overflows, nothing is clipped, nothing scrolls sideways. (16)
+10. **One screen per file, one component per file.** A file exporting two
+    widgets is a file nobody finds later.
+
+---
+
+## 3. Examples
+
+### Good
+
+```js
+import { Button, Container, Row, Text, colors, useState } from "flet-box";
+
+export const StatsScreen = () => {
+  const [period, setPeriod] = useState("stats-period", "week");
+
+  return Container({
+    direction: "column",
+    gap: 16,
+    padding: 24,
+    bgColor: colors.background,
+    children: [
+      Text({ text: "This week", size: 24, weight: 600, color: colors.text }),
+      Row({
+        gap: 12,
+        children: [
+          Button({ text: "Week", onPress: () => setPeriod("week"), variant: "outlined" }),
+          Button({ text: "Month", onPress: () => setPeriod("month"), variant: "outlined" }),
+        ],
+      }),
+      Button({
+        icon: "refresh",
+        "aria-label": "Refresh stats",
+        onPress: refresh,
+        bgColor: colors.primary,
+        height: 40,
+      }),
+    ],
+  });
+};
+```
+
+Every widget and prop there is in the cheatsheet, every length is a number, and
+every color is a token.
+
+### Bad
+
+```js
+import { Card } from "react";                       // 1. foreign framework
+```
+
+```js
+import { Button, Text } from "flet-box";
+
+const el = document.createElement("div");           // 3. hand-written DOM
+el.innerHTML = `<b>${name}</b>`;
+
+Text({ text: "Total", color: "#4f46e5", size: 13 }); // 2. hex + off-scale size
+Text("Total");                                       // 4. positional argument
+Button({ icon: "save", onPress: save });             // 6. a control with no name
+Button({ text: "Save", onPress: save, bgColor: "#4f46e5" }); // 2. hardcoded color
+```
+
+---
+
+## 4. The verification protocol
+
+```bash
+npm run verify     # every gate, one report, one exit code
+```
+
+1. Run it after every edit, before saying the task is done.
+2. Fix **only** the error the report names. Do not rewrite the file to make it
+   pass — a check that fails on line 12 is a line 12 problem.
+3. **At most two attempts.** If the same error survives the second attempt,
+   revert the change and hand the report back with what you tried.
+4. A warning may stay only when you can justify it in one sentence.
+
+`npm run verify` is `flet-box verify`: it parses every module first (`node
+--check`, the parser the runtime uses — a missing `)` is reported as
+`file:line:column` with the offending line, a caret under the character and a
+hint), then runs the anti-hallucination gate (invented widgets, positional
+arguments, foreign imports, broken imports), the type gate (the app's own
+`jsconfig.json` through TypeScript: a widget declared as a bare `HTMLElement`
+makes the documented `widget.update()` an error, and a prop the declaration
+forgot is one too), the design gate (tokens, the scale,
+tap targets, labels, contrast), the structural gate (a cycle between two of the
+app's own modules, a module outside the project's folders, markup written by
+hand) and the prop contract (a prop the widget reads but nothing declares), and
+prints one report with one exit code. A project that declares its own `test`,
+`test:browser` or `test:visual` script gets those run too; a generated app
+declares none, so that step is skipped there. `flet-box verify --watch` re-runs
+the fast gates on every edit, and `flet-box run --verify` does the same while the
+dev server runs.
+
+A mistyped name is mechanical, not creative: `npm run fix` rewrites what it
+can prove (`chilldren` → `children`, `bgColr` → `bgColor`, a relative path that
+does not resolve) and leaves anything ambiguous for you to decide. Read the
+diff.
+
+Lost before the first gate answers? `flet-box report` names every file of the
+project with its verdict and a ranked next step, and `flet-box tools` is the
+catalogue that maps a question to the command. Both read; neither repairs, and
+neither appends a metrics row.
+
+Then look at it: `npm run dev` and use the screen. A green report proves the
+code is legal, not that it is right.
+
+---
+
+## 5. The surgical protocol
+
+The report names a line. The edit touches that line, and nothing else.
+
+1. **Fix only what is named.** Every finding carries a file, a line and a code.
+   Change that line. A file that fails on three lines gets three edits — not a
+   rewrite of the file, and never a rewrite of the screen around it.
+2. **Let the tool repair first.** A mistyped prop, a wrong relative path and a
+   missing import are mechanical, and the repair is the tool's job:
+   `npm run verify -- --fix` rewrites what it can prove and re-runs the gates
+   on the result. Read the diff it prints before you write anything.
+3. **Do not widen the blast radius.** No reformatting, no renaming, no
+   "while I was here". A diff that touches a line the report did not name is a
+   diff you have to justify — and usually it is one you should not make.
+4. **A new finding is a decision, not noise.** If the fix makes a gate report
+   somewhere else, that is the next thing to look at. Do not silence it by
+   loosening the value that caused it.
+5. **Two attempts, then revert.** The same error surviving the second attempt
+   means the diagnosis was wrong, not that the third attempt will be luckier.
+   Revert and hand back the report with what you tried.
+6. **Say what you did not touch.** The handoff names the files you changed and
+   the ones the report named but you left alone, with one sentence of why.
+
+---
+
+## 6. What gets rejected, and why
+
+A change comes back when it breaks one of these. Each row names who says so,
+so "it was rejected" is never a matter of taste.
+
+| It comes back when | Who says so | What to write instead |
+| --- | --- | --- |
+| A widget, a prop or an export that does not exist | `UNKNOWN_EXPORT`, `UNKNOWN_PROP` | look it up in the cheatsheet; if it is not there, ask |
+| A positional call | `POSITIONAL_ARG` | `Text({ text: "Hi" })` |
+| An import that does not resolve | `MODULE_NOT_FOUND`, `MISSING_EXPORT` | `npm run fix`, or the path the file really has |
+| A prop the widget reads but no type declares | `INVENTED_PROP` | declare it, so an editor finds it |
+| A prop that no type declares and nothing reads | `DEAD_PROP` | wire it in the widget, or drop the declaration |
+| A hex where a token belongs | `RAW_COLOR` | `colors.primary` |
+| A length that is not on the scale | `OFF_SCALE_SPACING`, `OFF_SCALE_RADIUS`, `OFF_SCALE_TYPE` | the number the scale holds |
+| A control smaller than the tap target | `SMALL_TAP_TARGET` | `height: 40` |
+| A control with no name | `UNLABELED_FIELD`, `ICON_ONLY_CONTROL` | a label, or an `aria-label` |
+| A cycle, a file from outside the project, markup written by hand | `CIRCULAR_IMPORT`, `SOURCE_OUTSIDE_ROOT`, `HAND_WRITTEN_DOM` | import the file that owns it; build with widgets |
+| A rename or a removal with no deprecation | a review | keep the old name working, mark it, write the "from X to Y" line |
+| A diff that touches lines the report did not name | a review | revert the extra lines |
+| A claim with no measurement | a review | measure it, or say that it is unmeasured |
+| A baseline moved to quiet a gate | a review | a baseline moves when the framework moves |
+
+The last four rows are not gates: no tool can prove them, and a reader has to.
+A machine can say that a prop does not exist; only a person can say that a
+diff does more than the task asked.
+
+And two things are **not** a reason to send anything back: a warning you can
+justify in one sentence, and a fix that lands exactly on the line the report
+named. Both are in the two sections above.
+
+---
+
+## 7. The log of what keeps coming back
+
+Every `npm run verify` run appends a row to `.fletbox/metrics/generations.md` —
+when it happened, whether the gates were green, which gates failed, 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
+npm run metrics      # the north metric and the failures that recur
+```
+
+A **generation** is a run of failing rows closed by the first green one, and 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. That is the number
+worth raising, and it moves only when the code changes, 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. **That list is the loop.** A code that keeps coming
+back and has no rule behind it is a rule that has not been written yet — and the
+command fails when it finds one, so the gap cannot be forgotten.
+
+A code that keeps coming back *with* a rule behind it is a different problem,
+and the command names it: the rule is not landing. That is a stronger rule, a
+stronger place to put it, or an agent that did not read it.
+
+So when you see the same code twice in the log, do not only fix the line it
+names: write the rule that would have prevented it, where it belongs (the
+design skill, the rules skill, or the gate itself), and prove it with a check
+that fails without the fix.
+
+---
+
+## 8. If you are working on the framework itself
+
+`AGENTS.md` in the framework root is the contract for engine work: one
+rendering engine, the rem contract, the widget structure, the gates that guard
+each of them. This file still applies to anything you write there: real APIs
+only, tokens only, no new rendering system, and every rule you break gets a
+guard that fails before the fix.
+
+When you find a defect in the framework, fix it **upstream** and prove it with
+a check that fails without the fix. Never patch `node_modules`.

package/CONTRIBUTING.md

@@ -0,0 +1,238 @@
+# Contributing to FletBox
+
+FletBox is a vanilla-JS UI framework: ESM only, zero runtime dependencies, no
+build step. This file is the map of the repository for whoever adds code to it.
+
+Two contracts live next to it, and they are not the same document:
+
+| File | It is the contract for |
+| --- | --- |
+| [AGENTS.md](AGENTS.md) | **maintaining the framework** — the architecture, the rem contract, the widget structure, the gates that guard each of them |
+| [AGENTS_FOR_CODE_GEN.md](AGENTS_FOR_CODE_GEN.md) | **producing code with it** — what may be written, what gets rejected, how the work is proved. It ships inside every app `flet-box create` builds |
+
+## The branch, the commits, the release
+
+The work happens on `refactory`. A commit message is one line: a conventional
+prefix, a scope, an imperative subject — `feat(theme): …`, `fix(stack): …`,
+`docs(widget): …`, `chore(release): …`. The body carries the *why* when the
+subject cannot: the measurement that decided a value, the defect a fix closes.
+
+Never publish by hand. `npm run release -- --patch` bumps the version,
+rebuilds the bundle, commits and tags; CI publishes the tag. `npm publish` in a
+terminal is the one command that must never appear in a handoff.
+
+## The gates
+
+| Command | What it proves | When |
+| --- | --- | --- |
+| `npm run verify` | one report, one exit code: every module is parsed first, then the anti-hallucination gate, the design gate, the structural gate and the prop contract run, and then the project's own suites (`test`, `test:browser`, `test:visual`) | after every edit |
+| `npm test` | the static checkers: the widget contract, the scale, the shared helpers, accessibility, the error boundary, the API contract, the bundle budget, the image tooling, the docs, the skills, **the gates' own selftest** and the snippets | before you commit |
+| `npm run selftest` | the gates bite: each of the seven gates runs on a clean fixture and on one with a known defect, and must name the exact code on the exact line | after changing a checker |
+| `npm run test:browser` | the behavioural harnesses in `tests/`, driven in a real Chrome | when the change touches runtime behaviour |
+| `npm run test:visual` | the gallery measured in light and dark against `scripts/visual-baseline.json` | when the change touches how a widget paints |
+| `npm run metrics` | the north metric: the share of generations whose first run was already green | to know whether the rules are landing |
+
+CI runs the first three on every pull request and on every push to `refactory`
+and `main`, as three parallel jobs. Nothing is published from a pull request:
+the publish workflow reacts to a version tag and to nothing else.
+
+## Prove it twice
+
+Every rule in this repository is proven twice: once by breaking it and once by
+obeying it. A check that only proves the happy path proves nothing — a gate
+that stopped matching would report a clean repository forever. So a new gate
+arrives with a mutation that makes it fail and a case that makes it pass, and
+`npm test` is where both live.
+
+The same is true of a baseline. `scripts/visual-baseline.json` and
+`scripts/bundle-budget.json` are promises about how the framework paints and
+how heavy it is. They move when the framework moves, never to quiet a gate. A
+baseline that shrinks is a good day; a baseline that moves because a
+measurement was wrong is a defect.
+
+## What gets rejected
+
+The full list is in
+[AGENTS_FOR_CODE_GEN.md §6](AGENTS_FOR_CODE_GEN.md#6-what-gets-rejected-and-why),
+and it is short: a widget or a prop that does not exist, a positional call, an
+import that does not resolve, a hex where a token belongs, a length off the
+scale, a tap target under 40, a control with no name, a cycle, markup written
+by hand, an API change without a deprecation, a diff wider than the task, and
+a claim with no measurement.
+
+## Fix it upstream
+
+When an app cannot do what the contract says, the defect is in the framework.
+Fix it here, prove it with a check that fails without the fix, and never patch
+`node_modules`.
+
+## Project areas
+
+```text
+src/core/           Runtime, mounting, PWA, and HMR
+src/widgets/        UI widgets
+src/widget-factory/ Widget creation and prop processing
+src/navigations/    Scaffold, drawer, tabs, and router
+src/services/       Browser storage and HTTP helpers
+src/tools/          State and general-purpose tools
+src/utils/          Themes, parsing, effects, units, and validation
+src/helpers/        Shared helpers — one home per behaviour, and no imports
+bin/                CLI and project generators
+scripts/            The static checkers and the browser drivers (dev only)
+skills/             What the framework knows about designing an app
+tests/              The browser harnesses
+docs/               User and API documentation
+```
+
+## Before changing code
+
+1. Read the owning module and its nearest tests or examples.
+2. Check `src/index.js` to understand the public export.
+3. Check `src/index.d.ts` when changing public types.
+4. Search for existing aliases and related widgets.
+5. Keep unrelated refactors out of the change.
+
+## Adding a widget
+
+A widget should normally include:
+
+- A file under `src/widgets/`.
+- An export in `src/widgets/index.js`.
+- An export in `src/index.js`.
+- A prop interface and function declaration in `src/index.d.ts`.
+- Basic, everyday, and full examples.
+- A documentation page under `docs/widget/`.
+- Accessibility notes when it is interactive.
+- Cleanup for timers, listeners, observers, and subscriptions.
+
+Use the existing `WidgetFactory` patterns instead of creating a second
+rendering system, and follow
+[docs/guides/widget-structure.md](docs/guides/widget-structure.md): one factory
+root, `widgetName` on it, `composeUpdate()` instead of overwriting
+`container.update`, and every resource released through an idempotent
+`onUnmount` disposer.
+
+## Adding a prop
+
+When adding a public prop:
+
+1. Implement it in the widget.
+2. Add its TypeScript type.
+3. Add its default value and behavior documentation.
+4. Add an example that proves the behavior.
+5. Check whether it should have a friendly alias.
+6. Test both the preferred name and aliases when aliases are intentional.
+
+FletBox supports developer-friendly aliases, but each alias must have one
+clear meaning. **An alias is a feature, not a duplicate**: never "dedupe" two
+names that both work.
+
+## The generated files — never hand-edited
+
+| File | Regenerate it with |
+| --- | --- |
+| `docs/widget/*.md` | `python3 scripts/generate_widget_docs.py` |
+| `tools/snippets-creator-flet-box/*.json` | `python3 tools/snippets-creator-flet-box/build_snippets.py` |
+| `.fletbox/api/cheatsheet.md` and `api.json` | `flet-box check-api --emit-api`, `flet-box unpack --all --md` |
+| `www/` and `dist/` | `npm run build` |
+
+The shape of a widget page is the generator's, not yours: the page is built
+from `src/index.d.ts` and the curated examples in `scripts/_docdata/`.
+
+## Runtime and types must agree
+
+A public API is not complete until these three surfaces agree:
+
+```text
+runtime implementation
+src/index.js exports
+src/index.d.ts declarations
+```
+
+If a function is declared but not exported, or exported but not typed, do not
+ship it as stable: fix the source of truth. `scripts/check-api-surface.mjs`
+enforces it — it imports `src/index.js` for real, so it fails when a runtime
+export has no declaration, when a declared value does not exist at runtime,
+when an `interface`/`type` is not `export`ed (a consumer could not
+`import type` it), or when the barrel re-exports a name that no longer
+exists. It also fails when the package stops being importable in Node, so
+never touch `window` / `document` at module scope — guard with
+`typeof window !== "undefined"`.
+
+## Deprecating a prop
+
+A rename is not a breaking change, and it is not a silent one either. It has
+five parts, and they belong in the same change:
+
+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 migration guide](docs/guides/migration.md) as
+   a "de X a Y" row, under the version that renamed it.
+5. The old name is removed in the next **major**, and that major's section says
+   so.
+
+`scripts/check-migrations.mjs` proves the four surfaces agree, and
+`flet-box release --major` refuses to publish a version the guide does not
+cover. The codemod that applies the table is `flet-box audit-fix --only
+migrations`: it renames a key only when the widget declares both names and the
+call does not already carry the new one, and it removes a key the table marks as
+removed. Anything it cannot prove stays untouched, under "Left for you to
+decide".
+
+The guide is a chapter of the book, so a rename also touches the book's
+indexes and the neighbouring chapter's links.
+
+## Cleanup rules
+
+Components that register resources must release them:
+
+- `window` and `document` listeners.
+- Timers and animation frames.
+- `ResizeObserver` and `MutationObserver`.
+- Router subscriptions.
+- Storage subscriptions.
+- WebSocket connections.
+
+Use the widget cleanup lifecycle when available.
+
+## Validation checklist
+
+Before you open the pull request:
+
+```bash
+npm run verify
+npm test
+npm run test:browser
+node --check path/to/changed-file.js
+python3 -m py_compile scripts/generate_widget_docs.py
+```
+
+`npm run test:browser` drives the harnesses in `tests/` in a real Chrome:
+
+- `/tests/index.html` — the widget-factory regression contract
+- `/tests/smoke.html` — instantiates every widget
+- `/tests/motion.html` — the motion contract
+- `/tests/a11y.html` — the accessibility contract
+- `/tests/regression.html` — a guard for every bug this repository has fixed
+- `/tests/errorboundary.html` — a throw never takes the screen with it
+- `/tests/doccheck.html` and `/tests/doccheck-all.html` — documented behavior
+
+Each harness writes a global (`window.__TESTS`, `window.__SMOKE`,
+`window.__MOTION`, `window.__A11Y`, `window.__REGRESSION`) and must pass with 0
+failures. Serve the repo with `npm run dev` to open one by hand.
+
+## Pull request guidance
+
+A good pull request explains:
+
+- What user problem it solves.
+- Which files changed.
+- Which public API changed.
+- Whether types and docs were updated.
+- Which commands or tests were run.
+- Any remaining compatibility or migration concern.
+
+Avoid committing generated output, secrets, local databases, APKs, logs, or
+credentials.

package/README.md

@@ -38,21 +38,24 @@ Real DOM · No Virtual DOM · No build config to learn.
 
 ## Installation
 
-FletBox isn't on the npm registry, so clone it and link the CLI locally:
+FletBox is on npm, and it drags nothing in with it — `"dependencies": {}`:
 
 ```bash
-brew install node                 # macOS/Linux: ensure Node >= 18
-
-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 (Node >= 20.9)
 
 flet-box create appName           # scaffold your first app
 cd appName
-npm link flet-box                 # link FletBox into the new project
-flet-box run-spa                  # run as SPA with hot reload
+npm install                       # pulls flet-box itself from the registry
+flet-box run                      # dev server with hot reload
 ```
 
+Nothing to install at all: `npx flet-box create appName` runs the same scaffolder
+straight from the registry, and the project it writes declares `flet-box` as a
+normal dependency.
+
+Cloning the repository and `npm link`ing it is still how you *develop the framework
+itself* — see [CONTRIBUTING](CONTRIBUTING.md).
+
 ## Quick start
 
 ```javascript
@@ -80,7 +83,7 @@ runApp(App);
 ## Features
 
 - Declarative, widget-based UI · reactive state with `useState` · router for SPAs
-- Zero runtime dependencies; ESM only, Node >= 18 · real DOM, no Virtual DOM
+- Zero runtime dependencies; ESM only, Node >= 20.9 · real DOM, no Virtual DOM
 - Local storage, HTTP services, theme, PWA, and production builds
 - Android & iOS from the CLI (APK, simulator `.app`, `.xcarchive`)
 - Utility API for layout, text, color, animation, and more
@@ -137,12 +140,11 @@ invent against.
 
 ## Android and iOS
 
-`flet-box create` ships the Capacitor config, so the same SPA builds for both platforms. FletBox isn't on the npm registry — link it before installing:
+`flet-box create` ships the Capacitor config, so the same SPA builds for both platforms. The generated project already declares `flet-box` as a dependency, so one install covers everything:
 
 ```bash
 flet-box create my-app && cd my-app
-npm link flet-box              # or: npm install ../path/to/flet-box
-npm install                    # Capacitor CLI, sharp, platform package
+npm install                    # flet-box from the registry, plus the Capacitor toolchain
 ```
 
 - **Android** — Node >= 20.9, a JDK, and the Android SDK. `flet-box build android` → debug APK; `flet-box build android --release [--aab]` → unsigned release artifact to sign yourself (`apksigner` / Play App Signing).
@@ -160,6 +162,8 @@ They are **one continuous book** — the cover maps every page: [The FletBox Boo
 
 Rather than read, click: **[the live widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/)** gives every widget its own page, renders each example in the browser it was written for, and prints the exact call underneath it. The theme toggle in the corner shows the same screen in light and dark, which is the honest way to judge a default color.
 
+And the book itself is an app: **[`flet-box-docs`](https://www.npmjs.com/package/flet-box-docs)** (`npm install flet-box-docs`) renders these same pages with the framework's own `Markdown` widget, with an index, a theme toggle, an offline cache and Android/iOS wrappers.
+
 - [Your first app](docs/guides/first-app.md) — build a working todo app in 20 minutes
 - [The widget book](docs/widget/README.md) — every widget with property tables and examples
 - [State, Router & Services](docs/guides/state.md) — shared state, routing, storage, and HTTP
@@ -169,7 +173,7 @@ Rather than read, click: **[the live widget gallery](https://kuko53348.github.io
 - [SQLite and the API server](docs/server/data-services.md) — where your data lives + a full SQLite API example
 - [Mobile and platforms](docs/guides/mobile-and-platforms.md) — Android, iOS, PWA, and desktop
 - [Architecture](docs/arquitectura.md) — the widget contract and the single rendering engine
-- [Contributing](docs/CONTRIBUTING.md) — how to add code and docs
+- [Contributing](CONTRIBUTING.md) — how to add code and docs
 
 ## Support & sponsorship