flet-box 1.0.6 → 1.0.8

package/docs/README.md

@@ -14,6 +14,7 @@ This documentation is one continuous book. Start at **Chapter 0** and follow the
 | 9 | [State, Router & Services](guides/state.md) | Shared state, navigation routes, storage, and HTTP | Intermediate |
 | 10 | [Tools & Utilities](tools/README.md) | The helper functions that ship with the framework | Intermediate |
 | 11 | [The CLI](cli/README.md) | Create, run, and build projects with `flet-box` | Intermediate |
+| 12 | [Clean UI](guides/clean-ui.md) | The design system every app ships with and the gate that enforces it | 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.
@@ -50,6 +51,7 @@ Front cover (this page)
 → Animation helpers · tools/animation.md
 → Utilities guide · guides/utilities.md
 → The CLI · cli/README.md
+→ Clean UI · guides/clean-ui.md
 → Appendices (minification → mobile → compatibility → embedding → online updates)
 → The end of the book
 ```

package/docs/cli/README.md

@@ -62,6 +62,33 @@ http://localhost:8000
 
 The default project includes screens, an app bar, a drawer, routing, and the files needed to start experimenting.
 
+### Pointing the project at its repository
+
+`flet-box create` writes a GitHub Pages workflow into every project. Pass the
+repository with `--repo` and the same address is filled in everywhere it is
+needed:
+
+```bash
+flet-box create my-app --repo kuko53348/my-app
+```
+
+That sets `update.url` in `fletbox.config.json` (what an installed app polls for
+an over-the-air update), names the site at the top of
+`.github/workflows/build.yml`, and prints the address in the closing summary:
+
+```text
+⬆️  OTA updates: https://kuko53348.github.io/my-app/
+CI:      .github/workflows/build.yml publishes the web to GitHub Pages on every push.
+         It goes live at: https://kuko53348.github.io/my-app/
+         Enable it once: Settings → Pages → Source: GitHub Actions. The job prints the URL.
+```
+
+The first positional argument is always the project name; a flag that arrives
+before it is read as the name. Without `--repo` nothing is invented — the
+placeholder stays in both files and the workflow says which two to edit. The
+reason the workflow log, not the header, is the authority on the live address is
+explained in [The Pages address of a generated app](../guides/online-updates.md).
+
 ## Project templates
 
 FletBox provides four project templates.
@@ -423,8 +450,116 @@ Capacitor template with different slots keeps working. It:
 The script is idempotent: running it twice leaves identical files. The brand
 color `#1a1a2e` is defined at the top of the script.
 
+## Convert asset images to PNG
+
+Screens need PNG, and a `logo.jpg` dropped into `assets/` still works — until an
+Android or iOS build asks for a format the source photo cannot give it.
+`flet-box to-png` converts a folder of images to PNG using nothing but Node
+itself, so it works on a machine where no image library is installed.
+
+```bash
+flet-box to-png                 # converts ./assets, ./public/assets or ./src/assets
+flet-box to-png assets          # converts one folder
+flet-box to-png assets --dry-run
+```
+
+It recognises a file by its leading bytes, never by its extension, so a
+`logo.jpg` that is really a PNG is treated as the PNG it is. What it converts:
+
+| Format | Notes |
+| --- | --- |
+| JPEG | Baseline and extended sequential, greyscale or colour, any sampling factor (4:4:4, 4:2:2, 4:2:0, 4:1:1), restart intervals. Progressive, arithmetic-coded, lossless, 12-bit and CMYK files are refused with the reason. |
+| PNG | Colour types grey/RGB/palette/grey+alpha/RGBA at 1–16 bits, all five row filters, `tRNS` transparency. Already a PNG, so it is left alone unless you ask with `--optimize` or `--force`. Interlaced (Adam7) files are refused. |
+| GIF | First frame, with or without interlacing and transparency. An animated file converts with a note saying how many frames were dropped. |
+| BMP | Uncompressed 1/4/8/24/32-bit, top-down or bottom-up. Run-length (RLE) files are refused. |
+
+These need a codec or a rasteriser that a zero-dependency package cannot carry,
+so they are reported as declined rather than quietly skipped: WebP, AVIF/HEIF,
+TIFF, ICO and SVG.
+
+Nothing is overwritten. `assets/logo.jpg` becomes `assets/logo.png` beside it and
+the source stays; if `logo.png` already exists the file is kept and reported as a
+name clash, because that collision usually means someone already converted it by
+hand. `--replace` deletes each source, and only after the PNG it replaces has been
+read back and checked:
+
+```bash
+flet-box to-png assets --out build/img   # write the PNGs somewhere else
+flet-box to-png assets --force           # replace an existing logo.png
+flet-box to-png assets --replace         # delete the source once its PNG is verified
+flet-box to-png assets --optimize        # re-pack the PNGs already in the folder
+flet-box to-png assets --flat            # top level only, no sub-folders
+```
+
+The summary counts the outcomes apart — converted, declined, already a PNG, name
+clashes, and with `--optimize` also optimized, already optimal and the bytes saved
+— and only a file whose bytes could not be decoded counts as a failure, which is
+the one case that exits non-zero.
+
+### The PNG it writes is the smallest one that holds the picture
+
+A converted file is not written in one fixed layout. The writer looks at the
+pixels first and keeps whichever arrangement is smallest: a palette when the
+frame really does hold 256 colours or fewer (an exact address per pixel, not a
+quantisation), greyscale when every channel already agrees, three bytes per pixel
+when no pixel uses alpha. It then deflates the five row filters and keeps the
+shortest result. Nothing is approximated, so the file reads back as the same
+picture — and the command checks that before it calls the conversion a success.
+
+`--optimize` asks the same question about files that already are PNG, which is
+how a hand-made asset gets its turn:
+
+```bash
+flet-box to-png assets --optimize
+```
+
+It replaces a PNG only when the new bytes are smaller *and* every pixel matches,
+so running it twice is free: the second pass reports each file as already optimal
+and touches nothing. The repo's own icons lose 13 KB on the 1024 maskable and 3 KB
+on the logo, and the other four come back as already optimal. A 16-bit PNG is left
+alone either way — rewriting it would trade someone else's bit depth for a smaller
+file, and "smaller without losing quality" does not cover that.
+
+What this cannot do is make a photograph small. PNG stores every pixel, and a
+camera JPEG has already thrown most of them away, so the PNG of a photo comes out
+three to four times the file it came from (a 3.5 MB picture writes as 12 MB). The
+command converts it anyway and says so in the report: keep the JPEG — or a WebP
+from a tool that carries a codec — for that picture, and let `to-png` do the flat
+art, the logos and the icons.
+
+## Check the UI
+
+`flet-box check-ui` reads your app's own `src/` and reports the design mistakes a
+static pass can prove: a hand-typed color literal instead of a token, a size that
+is not on the 8-based scale, a tap target below the Fitts floor, a form field with
+no label, and text whose contrast against the fill it sits on is below WCAG AA.
+
+```bash
+flet-box check-ui                  # scan ./src
+flet-box check-ui --root ../my-app # scan another project
+flet-box check-ui --tokens         # print the measured token contrast table
+flet-box check-ui --strict         # contrast warnings fail too
+flet-box check-ui --json           # machine-readable findings
+```
+
+Aliases: `flet-box ui`, `flet-box checkUi`. The command exits `1` when it finds an
+error, or when it finds a warning with `--strict`, so it works as a CI gate.
+
+Every prop name the checker uses comes from the installed package's own prop
+registry, so it cannot invent an API while judging yours. The scale, the radii and
+the tap minimum are the framework's own numbers, read from its `scale` module —
+the same table the widget defaults are drawn from.
+
+What it deliberately does not judge: taste, hierarchy, and whether the screen
+solves the user's problem. `flet-box create` writes the rules as a skill file
+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).
+
 ## Command reference
 
+
 | Command | What it does |
 | --- | --- |
 | `flet-box create <name>` | Creates a default project. |
@@ -432,6 +567,7 @@ color `#1a1a2e` is defined at the top of the script.
 | `flet-box create <name> --full` | Creates a project with drawer and bottom navigation. |
 | `flet-box create <name> --sidebar` | Creates a desktop sidebar project. |
 | `flet-box create <name> --adaptive` | Creates a mobile and desktop project. |
+| `flet-box create <name> --repo <user>/<repo>` | Sets the GitHub Pages address, the OTA URL and the workflow header from the repo. |
 | `flet-box screen <name>` | Creates one screen. |
 | `flet-box screen <number>` | Creates up to ten screens. |
 | `flet-box component <name>` | Creates one component. |
@@ -447,6 +583,13 @@ color `#1a1a2e` is defined at the top of the script.
 | `flet-box run-native <android\|ios>` | Compiles and launches the app on an emulator/simulator or connected device. |
 | `flet-box run-native <android\|ios> --device` | Forces a physical device instead of the emulator. |
 | `flet-box run-native <android\|ios> --livereload` | Launches the app with hot reload on the device. |
+| `flet-box to-png [dir]` | Converts JPEG, GIF, BMP and non-PNG-precision images in a folder to PNG. |
+| `flet-box to-png --dry-run` | Reports what would happen, writes nothing. |
+| `flet-box to-png --replace` | Deletes each source after its PNG was written and read back. |
+| `flet-box to-png --optimize` | Re-packs the PNGs already in the folder, and only when that makes them smaller. |
+| `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 pkg` | Opens the package manager. |
 | `flet-box --version` | Shows the CLI version. |
 | `flet-box --help` | Shows the command list. |
@@ -536,7 +679,7 @@ npm install --save-dev esbuild
 ## Continue reading
 
 - **Previous:** [FletBox utilities](../guides/utilities.md)
-- **Next:** [Minify and protect a FletBox build](../guides/minification-and-protection.md) — Appendix A
+- **Next:** [Clean UI](../guides/clean-ui.md) — Chapter 12
 - **Index:** [Guides index](../guides/README.md) · [The FletBox Book](../README.md)
 
 You are reading **Chapter 11 · The CLI**.

package/docs/guides/README.md

@@ -9,6 +9,8 @@ This directory is the **conceptual index** of FletBox: how to build apps, set up
 - **[Routing with FletBox](router.md)** — Chapter 9 · fixed paths, dynamic parameters, queries, history, and route subscriptions.
 - **[Frontend services](frontend-services.md)** — Chapter 9 · the practical walkthrough of the three storage layers (`RamStore`, `Session`, `Storage`) and the HTTP client.
 - **[FletBox utilities](utilities.md)** — Chapter 10 · layout/theme/format helpers and validator tools.
+- **[The CLI](../cli/README.md)** — Chapter 11 · create, run, and build projects with `flet-box`.
+- **[Clean UI](clean-ui.md)** — Chapter 12 · the token scale, the 21 rules, and the `flet-box check-ui` gate that enforces them.
 - **[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/clean-ui.md

@@ -0,0 +1,211 @@
+# Clean UI — the system contract
+
+A FletBox screen is not decorated, it is extended: every app copies the widget
+defaults, and every later screen copies the screen before it. This page is the
+contract that makes the copy look like one product — the numbers, the tokens,
+and the two commands that prove a screen obeys them.
+
+It is the published version of the rule file that ships inside every generated
+app, so the app's agent and the framework's documentation cannot disagree.
+
+## The two gates
+
+A generated project has two checks, and they answer different questions:
+
+```bash
+npm run check      # is the API real? widgets, props, imports
+npm run ui         # does the screen follow these rules?
+npm run ui -- --tokens   # measured contrast of every token, on both surfaces
+npm run dev        # then look at it: the checker has no eyes
+```
+
+`npm run check` (`flet-box check-api`) is about correctness — an invented prop
+fails the build. `npm run ui` (`flet-box check-ui`) is about the system — a
+`padding: 21` is valid JavaScript and a design defect at the same time. Neither
+one replaces opening the page.
+
+## Where the rules live
+
+| Home | What it holds |
+| --- | --- |
+| `.claude/skills/fletbox-clean-ui/SKILL.md` | The 21 numbered rules below, written for the agent that builds the screen. Mirrored to `.qoder/skills/…` and `.cursor/rules/fletbox-clean-ui.mdc`. |
+| `AGENTS.md` §4 of the app | The short version: one brand color per screen, no hex literals, spacing and radius only from the scale. |
+| `src/tools/scale.js` in the framework | The tables themselves — `SPACING_SCALE`, `RADIUS_SCALE`, `TYPE_SCALE`, `TAP_MINIMUM`, `PILL`, `LABEL_TEXT`. |
+| `bin/commands/checkUi.js` | The gate. It re-exports those same tables instead of keeping its own copy. |
+
+That last line matters more than it looks. A gate that carries its own numbers
+drifts from the widgets, and the app then gets told to be clean by values the
+components it uses do not follow. The defaults and the checker read one table.
+
+## The scale
+
+| Dimension | Allowed values |
+| --- | --- |
+| Spacing | `0 · 4 · 8 · 12 · 16 · 18 · 24 · 32 · 40 · 48 · 64 · 96` |
+| Radius | `0 · 4 · 8 · 12 · 16 · 999` — `999` is a pill, `0` a flush edge; both are decisions |
+| Type | `12 · 14 · 16 · 18 · 24 · 32 · 40 · 48` |
+| Tap minimum | `40` — Fitts: the smallest pressable box a finger reliably hits |
+| Label text | `14` — the reading size a control's own label may not fall under |
+
+Type steps are two apart on purpose: a 15 next to a 16 reads as a mistake, not
+as hierarchy. The same logic gives the scale its gaps — a value between two
+steps is a shape no other element in the app has.
+
+## Every number is a framework unit
+
+A number on a size prop is not a CSS pixel. It goes through `toREM`
+(`src/utils/units.js`) and reaches the page as `value / 16` rem, so `40` is 40px
+at the default base and 60px for a reader who raised their browser font to 24.
+That is what makes one build fit a phone, a tablet and a desktop, and it is why
+the Fitts floor here is 40 rem-units rather than the 44px the guidelines quote:
+a target written in rem obeys the accessibility setting, a fixed pixel shrinks
+in relative terms the moment the type grows.
+
+`toREM` also rewrites a length someone spelled out in pixels — `"8px 12px"`
+becomes `"0.5rem 0.75rem"` — while anything that is not made only of pixel
+tokens (`"50%"`, `"calc(100% - 8px)"`, `"2px solid red"`) passes through
+untouched.
+
+Pixels stay pixels where a pixel is the honest unit:
+
+- canvas backing stores (`QRCode`, `Chart`, `CircularBar`, `CircularChart`),
+- Maps' projected tile and pin space,
+- anything measured from the DOM (`offsetWidth`, `getBoundingClientRect`, scroll offsets),
+- the hairline `borderWidth`, and shadow depth (`SHADOW_LEVELS`), because a
+  shadow that scales with the font stops matching the surface it lifts,
+- a virtualised row's scroll math — `ListView` converts `itemSize + gap` through
+  the live root font size so the slot a row gets and the row's own box agree.
+
+The framework keeps this honest with its own gate, `scripts/check-widget-scale.mjs`
+(part of `npm test`): a length written straight to `el.style.*` that is neither
+`toREM(...)` nor measured geometry fails the build.
+
+## The 21 rules
+
+When two of them conflict, take them in this order: **consistency · clarity ·
+accessibility · usability · scalability · maintainability · conversion**.
+
+| # | Rule | What it forbids |
+| --- | --- | --- |
+| 00 | The two gates | Shipping a screen neither `check` nor `ui` has run against. |
+| 01 | System before component | Deciding a value case by case; define the token, then the component, then the screen. |
+| 02 | Consistency is sacred | An arbitrary difference — a second card radius, a second button height. |
+| 03 | Design tokens only | A hex literal, a `px` string, a value off the scale. |
+| 04 | Hierarchy in three seconds | More than one primary action competing on a screen. |
+| 05 | One purpose per screen | A screen that needs "and" to describe it. |
+| 06 | Reduce cognitive load | Choices with no default, fields that could be inferred, copy that explains the interface. |
+| 07 | Spacing communicates relationship | Related things sitting farther apart than unrelated ones. |
+| 08 | Typography is structure | More than one size per element, body copy centered, a line that runs past ~75 characters. |
+| 09 | Color carries meaning | Brand color used for decoration, or a destructive action in the same fill as a safe one. |
+| 10 | Depth is a scale | An `elevation` number on a widget that never reads it, or a hand-typed `boxShadow`. |
+| 11 | Accessibility is a floor | Text under WCAG AA contrast, a tap target under 40, an image with no `alt` decision. |
+| 12 | Every interaction has four states | A control or list with no loading, empty, error or success path. |
+| 13 | Forms prevent the error | Validation that only reports after a failed submit; an unlabeled field or toggle. |
+| 14 | Destructive actions designed last | A delete that is the closest, fastest, most colorful thing on the screen. |
+| 15 | Reduce interaction cost | Taps, scrolls and keystrokes that carry no information. |
+| 16 | Respect the platform | Fighting the browser's own conventions — back, scroll, text selection. |
+| 17 | The review | Shipping before reading your own diff as the user. |
+| 18 | Where these books are wrong | Following a guideline that measurement disagrees with. |
+| 19 | What no checker can see | Taste, hierarchy in the wild, whether the screen solves the problem. |
+| 20 | The loop | Fixing the checker instead of the code, or leaving a rule you had to break undocumented. |
+
+## What `flet-box check-ui` proves
+
+The gate reads your `src/` and reports what a static pass can prove. Prop names
+come from the installed package's own registry, so it cannot invent an API while
+judging yours. Each finding carries a code, and the code maps to a rule above.
+
+### Errors (exit 1)
+
+| Code | Rule | What it catches |
+| --- | --- | --- |
+| `RAW_COLOR` | 03 | A color literal on a widget outside `src/database/themes.js`. |
+| `OFF_SCALE_SPACING` | 07 | A padding, margin, gap or size off the spacing scale — including inside a `"12px 20px"` shorthand. |
+| `OFF_SCALE_RADIUS` | 03 | A corner radius that is not a scale step. |
+| `OFF_SCALE_TYPE` | 08 | A font size off the type scale. |
+| `SMALL_TAP_TARGET` | 11 | A pressable widget under the Fitts floor, including a bare `Icon` with `onPress`. |
+| `LOW_CONTRAST` | 11 | Text measured below AA against the fill it actually sits on. |
+| `UNLABELED_FIELD` | 13 | An `Input` or `Dropdown` with neither a `label` nor a `placeholder`. |
+| `UNLABELED_TOGGLE` | 13 | A `Switch`, `Checkbox` or `Radio` with nothing to say what it toggles. |
+| `DESTRUCTIVE_COLOR` | 14 | A delete/remove verb rendered in the brand fill instead of the danger one. |
+| `UNREADABLE` | — | A file the scanner could not parse, reported rather than skipped. |
+
+### Warnings (fail with `--strict`)
+
+| Code | Rule | What it catches |
+| --- | --- | --- |
+| `LOW_CONTRAST_SOFT` | 11 | Text that clears AA only because of its size. |
+| `LOW_CONTRAST_UI` | 11 | A graphic that carries meaning below 3:1. |
+| `LOW_CONTRAST_ON_SURFACE` | 11 | Text measured against `background` and `surface` at once, when the fill is inherited. |
+| `HAND_MIXED_COLOR` | 03 | `colors.primary + "22"` — a one-off shade no other screen can reuse. |
+| `DEAD_ELEVATION` | 10 | A numeric `elevation` on a widget that never reads it: CSS drops the bare number and the box stays flat in silence. |
+| `IMAGE_NO_ALT` | 11 | An `Image` with no `alt` — `alt: ""` is a decision, a missing prop is an oversight. |
+| `ICON_ONLY_CONTROL` | 15 | A pressable glyph with no name; wrap it in `Tooltip({ text, child })`. |
+| `CENTERED_BODY_TEXT` | 08 | A paragraph centered; a paragraph needs a left edge to find the next line. |
+| `GENERIC_ACTION_LABEL` | 06 | "OK", "Submit", "Click here" — a label that says nothing about what pressing it does. |
+| `CONFIRM_ORDER` | 14 | A destructive button placed before Cancel in the same row. |
+| `UNCONSTRAINED_FORM_WIDTH` | 08 | A form block whose fields run to the full width of a desktop window. |
+
+### Informational
+
+| Code | Rule | What it says |
+| --- | --- | --- |
+| `SMALL_PRESET` | 11 | `size: "small"` on a control that is the screen's main action (~30px). |
+| `CROWDED_FORM` | 06 | Many fields in one file: group them, or split the task. |
+| `LIST_WITHOUT_STATE` | 12 | A list with no loading, empty or failed state in this file. |
+| `MULTIPLE_PRIMARY_ACTIONS` | 04 | Several filled buttons on one screen. |
+
+## Running the gate
+
+```bash
+flet-box check-ui                 # scan ./src
+flet-box check-ui --root ../my-app  # scan another project
+flet-box check-ui --tokens        # print the measured token contrast table
+flet-box check-ui --strict        # warnings fail too
+flet-box check-ui --json          # machine-readable findings
+```
+
+Aliases: `flet-box ui`, `flet-box checkUi`. Exit code is `1` when an error is
+present (or a warning, with `--strict`), so it fits in CI as the app's
+`npm run ui`.
+
+`--tokens` is the one worth reading before you pick colors. It prints the
+measured ratio of every token against `background` and `surface` — for the
+palette in use, so switch the theme and read it again if you ship both. A brand
+color that looks fine and measures 2.15:1 (`colors.warning`, decoration only)
+becomes a number instead of an argument, and the table already tells you which
+tokens clear AA body text, which are large-text-or-UI only, and on which fill
+writing text is a mistake.
+
+## Fixing a finding
+
+Fix the code, not the checker. A finding you keep needs one sentence of
+justification — in the commit or in the file — because the next person, human or
+agent, will otherwise copy the exception as if it were the rule.
+
+And a rule you had to break is information about the rule: if the exception was
+right twice, it is a defect in the scale, not in the app.
+
+## What no checker can see
+
+`check-ui` has no eyes. It cannot tell you that the screen is ugly, that the
+hierarchy reads wrong at a glance, or that the flow does not solve the user's
+problem. Those are rules 17 and 19, and they are the ones that need a person.
+Run the gate, then open the page.
+
+## Related pages
+
+- [FletBox utilities](utilities.md) — the theme and layout helpers the tokens come from.
+- [Themes](../tools/theme.md) — `registerPalette`, the call that gets your brand onto the page.
+- [The CLI](../cli/README.md) — every command, including `check-api` and `unpack`.
+- [Widget structure](widget-structure.md) — how a widget is built, and where its defaults live.
+
+---
+
+## Continue reading
+
+- **Previous:** [The CLI](../cli/README.md) — Chapter 11
+- **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 12 · Clean UI**.

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

@@ -255,6 +255,6 @@ Minification reduces the web payload inside the native application. It does not
 
 ## Continue reading
 
-- **Previous:** [The FletBox CLI](../cli/README.md)
+- **Previous:** [Clean UI](clean-ui.md) — Chapter 12
 - **Next:** [Build FletBox for mobile and other platforms](mobile-and-platforms.md) — Appendix B
 - **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/online-updates.md

@@ -15,7 +15,11 @@ you edit source code
         v
 git tag v1.0.1 pushed to GitHub
         |
-        | GitHub Actions (on: tags v*)
+        | GitHub Actions — the web job deploys www/ on every push to main,
+        | and keeps www/config.json only when that commit carries a v* tag.
+        | A run started BY THE TAG cannot deploy (the github-pages environment
+        | accepts the default branch only), so publish the feed with one
+        | manual run on main: Actions → Deploy → Run workflow.
         v
 www/ deployed to GitHub Pages      <- the ONLY place an update is published
         |
@@ -33,7 +37,7 @@ loader.js fetches <update.url>/config.json
 
 Three invariants make this safe:
 
-1. **Updates are published only by release tags.** Ordinary `git push` runs CI (so breakage is caught) but never publishes, so a half-finished test build can never reach your users.
+1. **Only a release tag can be offered as an update.** The web workflow publishes your site on every push to main, so the preview is never stale — but it deletes `www/config.json` from any build whose commit carries no `v*` tag. With no manifest to read, an installed app logs `no remote config (offline or not deployed yet)` and keeps running the release it already has. So the site is live for reading while the update feed stays on tags, and a half-finished test build can never reach your users.
 2. **The app verifies integrity.** A downloaded bundle is executed only if its sha256 matches the hash in `config.json`.
 3. **The app always launches.** Offline, a wrong URL, a hash mismatch, or a declined dialog all fall back to the bundle already on the device. OTA can never brick the app.
 
@@ -54,7 +58,7 @@ flet-box release --push     # also push the commit and the tag to origin
 2. Bumps the version in `package.json` using the odometer scheme below.
 3. Rebuilds the production bundle (`www/`), which regenerates `www/config.json` with the new version and the sha256 of the new bundle.
 4. Commits the version bump and creates the annotated tag `vX.Y.Z`.
-5. Optionally pushes (`--push`), which triggers the CI deploy.
+5. Optionally pushes (`--push`), which deploys the site. The tag is what turns the update feed on, and a tag run cannot deploy by itself — after pushing, start the workflow once more from Actions (Run workflow, on main) and that build keeps `www/config.json`.
 
 If the build fails, the version bump is rolled back so a failed release leaves no trace.
 
@@ -79,6 +83,10 @@ Every bundle ships a small manifest at `www/config.json`. This is what a running
   "builtAt": "2026-10-11T19:53:24.524Z",
   "bundle": "src/app.js",
   "size": 36132,
+  "assets": [
+    { "path": "docs/widget/Maps.md", "hash": "b0f2…", "size": 4213 },
+    { "path": "data/catalog.json", "hash": "7ac9…", "size": 980 }
+  ],
   "minNativeVersion": "0.0.0",
   "update": {
     "url": "https://kuko53348.github.io/my-app/",
@@ -96,6 +104,7 @@ Every bundle ships a small manifest at `www/config.json`. This is what a running
 | `hash` | sha256 of the bundle. **This is what drives the update decision**, not the version. |
 | `bundle` | Path of the bundle relative to the update URL. |
 | `size` | Bundle size in bytes (shown in the dialog as KB). |
+| `assets` | Extra files this release publishes (see [Shipping extra files](#shipping-extra-files-release-assets)). Each entry is verified by its own `hash`; the bundle `hash` never covers them. |
 | `minNativeVersion` | Oldest native shell this bundle supports. Older shells are told to update from the store instead. |
 | `update.url` | Where `config.json` and the bundle are published (your GitHub Pages site). |
 | `update.mode` | `prompt` (ask the user, default) or `auto` (download silently). |
@@ -127,6 +136,92 @@ To configure it by hand, create `fletbox.config.json`:
 }
 ```
 
+## The Pages address of a generated app
+
+The URL you paste into `update.url` is not a guess: `flet-box create` knows the
+address the app will be published to and prints it when it finishes.
+
+```bash
+flet-box create my-app --repo kuko53348/my-app
+```
+
+That `--repo` (or the same value typed at the interactive prompt) does three
+things at once:
+
+- sets `update.url` in `fletbox.config.json` to `https://kuko53348.github.io/my-app/`;
+- 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.
+
+**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*
+belongs to, read from GitHub itself:
+
+```text
+site:    https://kuko53348.github.io/my-app/     <- from the running repo
+header:  https://TU-USUARIO.github.io/my-app/    <- from the file
+version: 1.0.3
+```
+
+When those two disagree, trust `site:`. They disagree when the repository was
+created with a different name than the folder, or when the app was never pushed.
+Note the owner is lower-cased: GitHub Pages serves the site under the
+lower-cased login, so `Kuko53348` in your remote is `kuko53348` in the URL.
+
+**A green run that 404s has one cause.** The deploy job can only write to Pages
+after you enable the destination once: **Settings → Pages → Build and deployment
+→ Source: GitHub Actions**. Until you do, every run succeeds and no site exists —
+which is exactly what the `Where this lives` step prints in the log, so a failed
+release is never mistaken for a broken bundle.
+
+The address is a **sub-path** (`/<repo>/`), and that is why the bundle uses
+relative asset paths: the same `www/` a phone polls for updates is the one served
+under any path, with no rebuild for a custom domain or a rename. If you do move to
+a custom domain, change `update.url` in `fletbox.config.json` and rebuild — the
+native shell keeps the old bundle until the manifest tells it otherwise.
+
+## Shipping extra files (release assets)
+
+OTA swaps **one file**: `src/app.js`. Anything your app reads from disk at runtime — markdown pages, JSON data, per-tenant config — keeps the copy baked into the build the device installed. So an app installed three releases ago can run a bundle that was updated over the air and still be missing files the current catalog refers to. The symptom is not a crash, it is a "this page does not exist" for content that clearly exists online.
+
+Declare those files in `fletbox.config.json` and they become part of every release:
+
+```json
+{
+  "update": {
+    "assets": ["docs/**/*.md", "data/catalog.json"]
+  }
+}
+```
+
+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.
+
+The app then reads them through the loader instead of `fetch`:
+
+```js
+const asset = await globalThis.__FLETBOX_OTA_ASSET__?.("docs/widget/Maps.md");
+const markdown = asset && asset.ok ? await asset.text() : await (await fetch("./docs/widget/Maps.md")).text();
+```
+
+It returns a `Response`, or `null` when the file exists in neither place. For each path it tries, in order:
+
+1. **The OTA cache** — the published copy already downloaded on a previous launch, so repeat reads and offline reads are free.
+2. **The published release** at `update.url`. The bytes are verified against the manifest hash; a mismatch is logged and ignored rather than trusted.
+3. **The copy inside this build**, exactly as `fetch` would return it.
+
+Because step 3 is always available, the helper can never leave you with less than you had before: an unpublished file, an offline device, or a tampered download all serve the shipped copy.
+
+Two rules keep this honest:
+
+- **A file only updates OTA if it is listed.** An empty or missing `assets` list means the manifest publishes nothing but the bundle.
+- **Bundle and assets are verified separately.** `hash` is the bundle; each asset entry carries its own hash, so one corrupted file cannot serve unverified content — and a bad asset never blocks a good bundle update.
+
+**Old shells have no helper.** `loader.js` is baked into the native build and OTA replaces the bundle, never the loader — so a store build made before this feature cannot fetch published assets, however many updates it accepts. That is what the `fetch` fallback in the snippet is for, and it closes only when you ship a new store build.
+
 ## What the app does on launch
 
 `www/loader.js` (wired in automatically as the module entry of every production bundle) runs **before** your app:
@@ -141,17 +236,17 @@ The dialog is plain HTML/CSS rendered by the loader itself, so it appears before
 
 ## What OTA can and cannot change
 
-OTA replaces the **web layer only** — the files inside `www/`.
+OTA replaces the **web layer only**: the `src/app.js` bundle plus whatever you list in `update.assets`. Everything else on the device is what the store build shipped.
 
 | Updates over the air | Needs a new store submission |
 | --- | --- |
 | UI, screens, widgets, styles | New native plugins / Capacitor version |
 | App logic and routing | New Android/iOS permissions |
-| Text, images, fonts, assets in `www/` | Changes to `AndroidManifest.xml` / `Info.plist` |
+| Release assets declared in `update.assets` (markdown, JSON, images) | Changes to `AndroidManifest.xml` / `Info.plist` |
 | Bug fixes and new JS features | Native code or signing changes |
 | Anything inside the bundle | Anything that changes the app's identity or purpose |
 
-Rule of thumb: if the change lives in `src/` (your FletBox code) it ships OTA; if it lives in the native shell it goes through the store. The `minNativeVersion` field exists for the boundary case where a new web bundle needs a newer shell: older shells skip the OTA and you direct users to the store update.
+Rule of thumb: if the change lives in `src/` (your FletBox code) it ships OTA; if it lives in the native shell it goes through the store. A data or content file ships OTA only when it is listed in `update.assets` — otherwise the device keeps the copy its store build baked in. The `minNativeVersion` field exists for the boundary case where a new web bundle needs a newer shell: older shells skip the OTA and you direct users to the store update.
 
 ## Store policy (read this before relying on OTA)
 
@@ -170,19 +265,20 @@ The generated service worker uses a hybrid strategy so OTA and offline coexist:
 - **Static assets** (fonts, icons, images, css): cache-first, since they are immutable per release.
 - **Cross-origin requests** (your remote `config.json` and bundle) are left to the network and are never cached by the worker.
 
-Downloaded OTA bundles live in a **separate** cache (`fletbox-ota`) owned by the loader, so a service-worker update never wipes an installed OTA bundle.
+Downloaded OTA bundles **and** release assets live in a **separate** cache (`fletbox-ota`) owned by the loader, so a service-worker update never wipes an installed OTA bundle. The loader fetches published assets with `cache: no-store`, so a stale service-worker copy of a file in `www/` cannot shadow the published one.
 
 ## Requirements and troubleshooting
 
-Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings → Pages → Source = "GitHub Actions"), and the workflow from `flet-box create` (it already deploys `www/` on `v*` tags). GitHub Pages and Actions are free for public repos.
+Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings → Pages → Source = "GitHub Actions"), and the workflow from `flet-box create` (`.github/workflows/build.yml` publishes `www/` on every push, and publishes the OTA manifest only for a `v*` tag; Android and iOS live in `build-native.yml`, which starts by hand). GitHub Pages and Actions are free for public repos.
 
 | 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 the tag was never pushed (CI never published). |
+| 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. |
 | `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. |
+| A data/content file is missing on the device but published online | It is not listed in `update.assets`, so OTA only ever replaced the bundle — or the installed shell predates release assets, in which case the app must fall back to its own copy. |
 | Want to force a clean state | Clear site data for the app origin (this removes the OTA cache and localStorage entry). |
 
 Because the decision is hash-based, two builds of identical source produce the same hash and no spurious update is offered; only a real content change triggers the dialog.

package/docs/tools/README.md

@@ -98,7 +98,7 @@ Helpers for shaping collections and generating data.
 
 - `parseMarkdown(md)`, `parseInlineMarkdown(md)` — reserved placeholders that pass text through unchanged (real rendering is `markdownToWidgets`/`parseInlineToWidgets`).
 - `markdownToWidgets(md)` / `parseMarkdownToWidgets(md)` — markdown string → widgets (alias names for the same function).
-- `tokenize(code)`, `generateHighlightedHtml(code)`, `highlightColors` — syntax highlighting.
+- `tokenize(code)`, `generateHighlightedHtml(code, palette?)`, `highlightColors` — syntax highlighting (light and dark token maps; the highlighter picks one from the active theme).
 - `escapeHtml(text)` — escape untrusted text before inserting it as HTML.
 
 ## Visual effects

package/docs/tools/animation.md

@@ -31,7 +31,7 @@ one style would otherwise fight, and the older animation would resume after the
 
 ## Widgets
 
-- `AnimatedBox({ animations, timing, delay, fillMode, child, top, right, bottom, left })` — animates a child widget. `animations` is an array of `{ effect, from, to, duration }` entries; effects include `backgroundColor`, `color`, `borderRadius`, `opacity`, `scale`, `translate`, `rotate`, `width`, `height`, spacing, `boxShadow`, and gradients.
+- `AnimatedBox({ animations, timing, delay, fillMode, child, top, right, bottom, left })` — animates a child widget. `animations` is an array of `{ effect, from, to, duration }` entries; each plays once and holds `to` at the end (add `reverse: true` to cycle back, and `loop: true` to repeat); effects include `backgroundColor`, `color`, `borderRadius`, `opacity`, `scale`, `translate`, `rotate`, `width`, `height`, spacing, `boxShadow`, and gradients.
 - `AnimatedText({ child, animations, sameTime, delayBetween, orientation })` — animates a `Text` widget (letters split per animation).
 - `MatrixRain({ chars, fontSize, speed, fadeAmount, resetProbability, useDynamicColor, position, zIndex })` — the falling-characters canvas effect (returns a `canvas`).
 - `ParallaxBox({ type, speed, direction, maxOffset, reverse, child })` — content that moves; `type` is `"scroll"`, `"mouse"`, or `"hover"`, `direction` is `"vertical"`, `"horizontal"`, or `"both"`.