flet-box 1.1.0 → 1.1.2

package/docs/guides/accessibility.md

@@ -0,0 +1,282 @@
+# Accessibility: the engine's half and your screen's half
+
+A FletBox control is a `div` that the framework teaches to behave like a
+`button`. That is what makes the syntax pleasant — `Container({ onPress })`
+instead of a stylesheet and three event listeners — and it is also where
+accessibility is won or lost. Three things have to be true for someone with no
+pointer: the control must be **reachable** (Tab), **operable** (Enter and
+Space), **announced** (a role and a name), and the person must be able to see
+**where they are** (a focus ring). An overlay owes a fourth: hold the keyboard
+while it is open, and give it back when it closes.
+
+The engine already does all four. This chapter is about the half it cannot do
+for you, and about the two ways an app destroys the half it was given.
+
+## 1. The focus ring is a stylesheet, not a paint
+
+A focus ring is not a decoration — it is a *state*, and a state can only live in
+a stylesheet. `src/utils/focusRing.js` appends one `<style id="fletbox-focus-ring">`
+to `<head>` the first time any widget is created, and never appends a second:
+
+```css
+:where(a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])):focus-visible {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+```
+
+Three deliberate choices, each worth knowing when you want something different:
+
+- **`:focus-visible`, not `:focus`.** A click with a mouse does not ring; the
+  keyboard does. That is the browser's own distinction, not the framework's.
+- **`:where(…)` keeps specificity at zero.** One class of yours overrides it,
+  and no `!important` is needed anywhere.
+- **The color is a token.** `--color-focusRing` is written by `applyPalette` for
+  every theme, so the ring moves with the theme instead of being a literal that
+  only suits one background. The light palette's `#1d4ed8` is 6.4:1 on the page,
+  the dark one's `#93c5fd` is 11:1, and the literal after the comma in the rule
+  is the boot value a page shows before the first `setTheme`.
+
+The widths are pixels on purpose, next to `SHADOW_LEVELS` and the hairline
+`borderWidth`: a 1px ring is invisible and a 6px one is a blob, whatever the
+reader's font size is.
+
+### The one thing an app must never do
+
+```javascript
+// Never. An inline declaration outranks every stylesheet rule, including the
+// engine's, so this is what "the focus ring does not work" looks like in code.
+element.style.outline = "none";
+
+// Never, for the same reason, anywhere in a global stylesheet:
+// *:focus { outline: none; }
+```
+
+If you do not like the ring's colour, change the token — or override the rule
+with one class of your own, which `:where()` makes possible:
+
+```javascript
+import { registerPalette } from "flet-box";
+
+// The token is part of the palette, so both themes move it and nothing is
+// overridden behind the framework's back. A registered palette repaints only
+// when it is the one on screen.
+registerPalette("light", { focusRing: "#0f766e" });
+registerPalette("dark", { focusRing: "#5eead4" });
+```
+
+```css
+/* or, for one component only: a class beats :where(...) whatever the order */
+.chart:focus-visible { outline-color: var(--color-primary); }
+```
+
+### A field rings as a whole control
+
+`Input` is a wrapper with a border, an icon and sometimes a reveal button, and
+the native `<input>` inside it is only part of the control. A ring around the
+text box alone draws a box *inside* the thing it is supposed to mark. So the
+rule has a second pair:
+
+```css
+:where([data-fb-field]):has(> input:focus-visible) {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+:where([data-fb-field]) > input:focus-visible {
+  outline: none;
+}
+```
+
+The `outline: none` there is a *rule*, at zero specificity, which any app can
+still override — that is the whole difference between silencing the inner box
+and killing the ring. The marker (`data-fb-field`) is written by `Input`; if you
+build your own composite field (a text box with a button inside), put the same
+marker on the wrapper and the ring lands where the control is.
+
+And keep the two jobs apart: **the border is validation, the ring is focus.**
+A field that paints focus by recolouring its rim, or by adding a `box-shadow`,
+puts two indicators where one belongs and loses the validation state the moment
+someone types.
+
+## 2. A press is a press, however it arrives
+
+Give any widget a click handler as a prop and the engine runs a keyboard pass
+over it — `src/widget-factory/effects.js`:
+
+- it sets `role="button"` **if you have not set a role**;
+- it sets `tabIndex = 0` **if you have not set one** (an explicit `-1` is your
+  decision to keep the element off the Tab path, and it is respected);
+- Enter and Space fire the same handler a pointer fires, with Space's default
+  (scrolling the page) cancelled and a held key counted as one press;
+- a nested control keeps its own keys — Enter on a `Button` inside a pressable
+  `Card` presses the button and the card, not twice the card;
+- native `button`/`a[href]` are left alone, and disabled controls are not made
+  Tab stops.
+
+```javascript
+Container({ onPress: openDetails, children: [Text({ text: "Details" })] });
+// role="button", tabIndex=0, Enter and Space → openDetails
+```
+
+The one way an app defeats this is to attach the handler to the element after
+the widget was built. The pass runs during construction; a handler assigned
+afterwards leaves a control with a click, no role, no Tab stop and no keyboard:
+
+```javascript
+const card = Container({ children: [Text({ text: "Details" })] });
+card.onclick = openDetails; // mouse-only: the engine already ran
+```
+
+Express the control with a prop instead — `onPress` (or `onClick`) on any
+widget — and the engine sees it.
+
+### An icon is decoration until it is a control
+
+`Icon` has two lives, and it picks one by itself:
+
+- `Icon({ name: "search" })` — no name for a reader, so it is marked
+  `aria-hidden="true"` and kept off the Tab path. Correct inside a `Button`
+  that already has text.
+- `Icon({ name: "search", onPress: focusSearch, "aria-label": "Search" })` — a
+  named, pressable icon keeps `role="button"` and is read as "Search, button".
+
+An icon-only control with no `aria-label` is read as "button", which is the
+worst of both worlds: reachable, operable, and anonymous. The places where the
+framework wires a glyph up for you already name it — the `AppBar` back arrow,
+`Input`'s `onIconPress` and reveal button, and the menu icon a `Scaffold`
+connects to its drawer.
+
+## 3. Names, roles and states the widgets already declare
+
+You can pass `role` and `tabIndex` as ordinary props, and any `aria-*`
+attribute reaches the element verbatim (`"aria-label": "…"`). Everything below
+is already in place; the table exists so you know what not to duplicate.
+
+| Widget | Role | States it keeps in sync |
+| --- | --- | --- |
+| `Button`, `Container` with `onPress` | `button` | — (engine pass) |
+| `Switch` | `switch` | `aria-checked` |
+| `Checkbox` | `checkbox` | `aria-checked` |
+| `Radio` / `Rating` | `radio` / `radiogroup` | `aria-checked` |
+| `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` |
+| `Dropdown` list | `listbox` / `option` | `aria-selected` |
+| `Tabs` | `tablist` / `tab` / `tabpanel` | `aria-selected`, roving `tabIndex`, `aria-controls` |
+| `Accordion` | `button` / `region` | `aria-expanded`, `aria-controls` |
+| `Pagination` | `navigation` | `aria-current="page"` |
+| `Stepper` | — | `aria-current="step"` |
+| `BottomNavigation` | — | `aria-current="page"` |
+| `Modal`, `BottomSheet`, `Drawer` | `dialog` | `aria-modal="true"` |
+| `SnackBar` | live region | `aria-live="polite"`, `"assertive"` for error and warning |
+| `Tooltip` | `tooltip` | `aria-describedby` on the trigger while shown |
+| `Maps` | `application` | — |
+| `CircularChart` | `img` | give it an `aria-label`; it is a picture of data |
+
+Composite widgets answer the keyboard the way their ARIA pattern says: `Tabs`,
+`Dropdown`, `Rating` and `Slider` move with the arrow keys, take `Home` and
+`End`, and keep a single Tab stop per group. The Dropdown's options are
+deliberately *not* Tab stops — the selector holds focus, the arrows move the
+highlight and `aria-activedescendant` names the row.
+
+What is left for you is **naming**: a visible `label` where the widget has one
+(`Input`, `Dropdown`), `text` for a button (`"Save"` is a name; `"OK"` is not —
+see the clean-UI rule about generic action labels), `alt` on images, and
+`aria-label` for anything that has no visible words of its own.
+
+## 4. An invalid field says so in two places
+
+A red rim is the visual half. The other half is the state and the reason, and
+`Input` keeps them together: while a message is showing, the field carries
+`aria-invalid="true"` and an `aria-describedby` pointing at the message, which
+is a `polite` live region; when the value becomes valid, all three leave
+together. A described-by pointing at a `display: none` node would be a control
+claiming a description it does not have.
+
+```javascript
+const email = Input({ label: "Email", validation: "email", required: true });
+
+// submit
+const { valid, message } = email.validate(); // paints, links and announces
+```
+
+Use `validate()` (or `setValue()`, which validates) rather than colouring a rim
+by hand: `showValidationMessage` decides whether the reason is on screen, and a
+ring with no message tells a reader "wrong" and nothing else.
+
+## 5. Overlays hold the keyboard, then give it back
+
+`Modal`, `BottomSheet` and `Drawer` share one scope (`src/utils/focusScope.js`),
+and one implementation on purpose:
+
+- focus moves into the panel when it opens — the first control, or the panel
+  itself (`tabIndex="-1"`) when it has none, so an alert with two lines of text
+  still takes the keyboard;
+- Tab and Shift+Tab cycle **inside** the panel instead of walking out behind
+  the scrim into a page the person can no longer see;
+- Escape closes it (each overlay already listens);
+- closing hands focus back to whatever was focused before, and skips that if the
+  element has left the page (a route change replaced it).
+
+The trap and the ring read the same list of reachable elements — `a[href]`,
+`button`, `input`, `select`, `textarea`, `summary` and anything on the Tab path
+— so a stop you can Tab to is always a stop that shows a ring.
+
+For an app, the contract is simply: open and close these through their props and
+refs, and do not build a full-screen scrim by hand with its own Escape listener.
+
+## 6. Verify it with the keyboard
+
+Five minutes, no screen reader needed:
+
+1. Press Tab from the top of the screen. Every control gets a ring; nothing is
+   skipped and nothing rings twice.
+2. Press Enter and Space on each control. The same thing happens as with a click.
+3. Focus a field and type. The rim stays put until there is a verdict.
+4. Submit an invalid form. The message is under the field, the field says
+   `aria-invalid`, and the message disappears with the fix.
+5. Open a modal. Tab to the last control and press Tab once more: focus is back
+   at the first, not behind the scrim.
+6. Press Escape. Focus is back on whatever opened it.
+7. Repeat 1–6 with a screen reader (VoiceOver: `Cmd+F5`; TalkBack on Android) and
+   listen for names: "Search, button", "Email, invalid entry, Invalid email
+   address".
+
+Then let the gates do what they do:
+
+```bash
+npm run check    # the API is real: widgets, props, imports
+npm run ui       # names, labels, tap targets, contrast:
+                 #   UNLABELED_FIELD, UNLABELED_TOGGLE, ICON_ONLY_CONTROL,
+                 #   IMAGE_NO_ALT, SMALL_TAP_TARGET, LOW_CONTRAST*, UNREADABLE
+npm run dev      # then Tab through it; the checker has no keyboard
+```
+
+In the framework repository itself, `node scripts/check-a11y.mjs` runs inside
+`npm test` and holds the invariants of this chapter: nothing writes an inline
+`outline`; the ring rule is injected and carries the token; both palettes define
+`focusRing`; the pressable path sets role, Tab stop and Enter/Space and releases
+its listener; every overlay that reads Escape also traps focus; the trap and the
+ring agree on what is reachable; and no handler is attached after the factory
+returned. Every one of those rules has been proven to fail on the bug it
+forbids. The runtime half lives in `/tests/a11y.html`.
+
+## See also
+
+- [Clean UI](clean-ui.md) — the design rules this chapter's checklist comes from.
+- [Themes](../tools/theme.md) — `registerPalette`, the call that moves the ring.
+- [Input](../widget/Input.md) — the props used above.
+- [Modal](../widget/Modal.md) · [BottomSheet](../widget/BottomSheet.md) ·
+  [Drawer](../widget/Drawer.md) — the three overlays and what they return.
+- [Widget structure](widget-structure.md) — where a widget's defaults and
+  disposers live.
+
+---
+
+## Continue reading
+
+- **Previous:** [Clean UI](clean-ui.md) — Chapter 12
+- **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 13 · Accessibility**.

package/docs/guides/clean-ui.md

@@ -35,13 +35,13 @@ pointed at from one `.cursor/rules/<name>.mdc` each:
 | Skill | What it owns |
 | --- | --- |
 | `fletbox-rules` | The working contract: FletBox syntax only, never invent an API and the four ways to look one up, the rem rule, aliases, cleanup, the two gates, the memory duty. |
-| `fletbox-design` | The 25 numbered rules below — tokens, the scale, hierarchy, the four states, measured contrast, composition, the framework traps, the dated tells, density. |
+| `fletbox-design` | The numbered rules below — tokens, the scale, hierarchy, the four states, measured contrast, composition, the framework traps, the dated tells, density (00–24), then the visual atlas of looks that hold up, each reduced to calls this framework makes (25–37). |
 | `fletbox-motion` | Whether a thing may move at all, and through which of `AnimatedBox`, `AnimatedText`, `ParallaxBox` or `animate`. |
 | `fletbox-memory` | The `.fletbox/memory/` journal that hands progress from one AI to the next. |
 
 | Home | What it holds |
 | --- | --- |
-| `skills/fletbox-design/SKILL.md` (framework) → `skills/…`, `.claude/skills/…`, `.qoder/skills/…` (app) | The rules as the agent reads them, in 25 numbered sections. The app's copies are generated; edit the framework file and regenerate, never the mirror. |
+| `skills/fletbox-design/SKILL.md` (framework) → `skills/…`, `.claude/skills/…`, `.qoder/skills/…` (app) | The rules as the agent reads them, in 38 numbered sections across two parts. The app's copies are generated; edit the framework file and regenerate, never the mirror. |
 | `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, and `scripts/check-skills.mjs` fails when a skill and the gate stop naming the same codes. |
@@ -55,7 +55,7 @@ components it uses do not follow. The defaults and the checker read one table.
 | 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 |
+| Radius | `0 · 4 · 8 · 12 · 16 · 20 · 24 · 999` — `999` is a pill, `0` a flush edge; both are decisions. 20 and 24 are on the scale because the nesting rule (`outer = inner + padding`) lands there and `Drawer`, `DrawerItem` and the `Tabs` indicator default there |
 | 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 |
@@ -93,9 +93,17 @@ The framework keeps this honest with its own gate, `scripts/check-widget-scale.m
 (part of `npm test`): a length written straight to `el.style.*` that is neither
 `toREM(...)` nor measured geometry fails the build.
 
-## The 25 rules
+## The rules
 
-When two of them conflict, take them in this order: **consistency · clarity ·
+The skill numbers its rules 00–37 and splits them in two parts. **00–24 are the
+enforceable contract**: each one is cited by at least one `check-ui` code, so
+`npm run ui` can fail a screen for breaking it, and `scripts/check-skills.mjs`
+fails if a code loses its rule. **25–37 are the visual atlas** — the archetypes,
+the accent budget, the surfaces, the dated tells — judgement about what to
+choose, which no static pass can prove. The atlas lives only in the skill; this
+page indexes it by number and does not copy it, so the two cannot drift.
+
+When two rules conflict, take them in this order: **consistency · clarity ·
 accessibility · usability · scalability · maintainability · conversion**.
 
 | # | Rule | What it forbids |
@@ -126,6 +134,29 @@ accessibility · usability · scalability · maintainability · conversion**.
 | 23 | What no checker can see | Taste, hierarchy in the wild, whether the screen solves the problem. |
 | 24 | The loop | Fixing the checker instead of the code, or leaving a rule you had to break undocumented. |
 
+### Part II — the visual atlas, 25–37
+
+Read these after the table, never instead of it: every recipe still has to pass
+`npm run check` and `npm run ui`. They are indexed here so a rule number in a
+review comment points somewhere, and they are written out in full in
+`skills/fletbox-design/SKILL.md`.
+
+| # | Rule | What it decides |
+| --- | --- | --- |
+| 25 | Three laws | One accent, one surface family, one hero — across mobile, web, both themes. |
+| 26 | Pick an archetype | Acid-on-black, tinted paper, photo-bleed, bento, editorial, single-hue field — name one before the first widget. |
+| 27 | Surfaces are never the extremes | No pure black under pure white: the steps between them are where hierarchy lives. |
+| 28 | The accent budget | How much saturated hue a screen may spend, and on what. |
+| 29 | The number is the hero | The one element at 3–5× the rest, and why it is usually a number. |
+| 30 | Radius, nesting and the pill | `outer = inner + padding`, and when a pill is a decision. |
+| 31 | Photo, scrim, sheet | The sheet overlaps the photo, the scrim earns the text over it. |
+| 32 | The shape of each control | Which control carries which affordance, from the widgets that exist. |
+| 33 | Data widgets | The dial, the bento tile, the axis-less chart. |
+| 34 | Genre recipes | What a finance, commerce, travel or wellness screen actually uses. |
+| 35 | Deriving a palette | Building a hue family from one accent without leaving contrast behind. |
+| 36 | The dated visual tells | What reads as 2021, and what to choose instead. |
+| 37 | Choosing, in five questions | How to land on an archetype and a palette for a brief. |
+
 ## What `flet-box check-ui` proves
 
 The gate reads your `src/` and reports what a static pass can prove. Prop names
@@ -157,7 +188,7 @@ judging yours. Each finding carries a code, and the code maps to a rule above.
 | `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` | 11 | A pressable glyph with no name; wrap it in `Tooltip({ text, child })`. |
+| `ICON_ONLY_CONTROL` | 11 | A pressable glyph with no accessible name; give it `aria-label` (a `Tooltip` is a description, not a name). |
 | `CENTERED_BODY_TEXT` | 08 | A paragraph centered; a paragraph needs a left edge to find the next line. |
 | `GENERIC_ACTION_LABEL` | 14 | "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. |
@@ -170,7 +201,7 @@ judging yours. Each finding carries a code, and the code maps to a rule above.
 | `SMALL_PRESET` | 03 | `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. |
+| `MULTIPLE_PRIMARY_ACTIONS` | 04 | More than one filled button in one view; keep one and make the rest outlined or text. |
 
 ## Running the gate
 
@@ -203,6 +234,20 @@ 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.
 
+## The framework runs this gate on itself
+
+A widget cannot ship a default that the gate would reject in your app, because
+`npm test` runs the same checker over the framework's `src/`
+(`scripts/check-framework-ui.mjs`). It found real defects the first time: a tab
+badge wrote white on the signal red (2.77:1 in the dark theme), a `ListTile`
+description borrowed the disabled grey (2.57:1), a dialog painted two filled
+buttons at once, and eleven defaults sat off the scale.
+
+The list of accepted findings lives in `scripts/framework-ui-baseline.json` and
+is shrink-only: every entry carries the reason it is not a defect, and
+`--write-baseline` exits `1` while any entry has no justification. A new finding
+has to be fixed, not snapshotted.
+
 ## What no checker can see
 
 `check-ui` has no eyes. It cannot tell you that the screen is ugly, that the
@@ -223,7 +268,7 @@ Run the gate, then open the page.
 ## Continue reading
 
 - **Previous:** [The CLI](../cli/README.md) — Chapter 11
-- **Next:** [Minify and protect a FletBox build](minification-and-protection.md) — Appendix A
+- **Next:** [Accessibility](accessibility.md) — Chapter 13
 - **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
 
 You are reading **Chapter 12 · Clean UI**.

package/docs/guides/first-app.md

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

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

@@ -255,6 +255,6 @@ Minification reduces the web payload inside the native application. It does not
 
 ## Continue reading
 
-- **Previous:** [Clean UI](clean-ui.md) — Chapter 12
+- **Previous:** [Accessibility](accessibility.md) — Chapter 13
 - **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/mobile-and-platforms.md

@@ -75,6 +75,44 @@ Your Capacitor configuration must point `webDir` to that output directory, commo
 
 The exact configuration file may be `capacitor.config.ts`, `capacitor.config.json`, or another format depending on how Capacitor was initialized.
 
+### The safe area
+
+Every app `flet-box create` writes carries `viewport-fit=cover` in `index.html`,
+which lets the web view paint behind the notch and the home indicator. That is
+what a full-bleed app wants, but it only looks right if content steps back from
+those edges, so the framework reads `env(safe-area-inset-*)` wherever a widget
+touches a screen edge: the [AppBar](../widget/AppBar.md) adds the top inset to
+its own padding, the [Drawer](../widget/Drawer.md) pads its panel and the
+[Tooltip](../widget/Tooltip.md) measures the same box before it picks the side
+its bubble goes on, so a header never sits under the status bar, a footer never
+under the gesture bar and a tooltip never flips into either. The
+value is `0` on a device with no inset, so nothing is configured per platform and
+a desktop browser is untouched.
+
+A screen that pins its own content to an edge — a hand-built tab bar, a floating
+action row — has to ask for the same inset. A length prop accepts the expression
+as it stands, because only a value made purely of pixels is converted to rem:
+
+```js
+Container({
+  paddingBottom: "calc(16px + env(safe-area-inset-bottom, 0px))",
+  children: [/* tabs */],
+});
+```
+
+### Hover does not exist here
+
+A touch screen has no resting pointer, and iOS answers the first tap on an
+element with a synthetic `mouseenter` that no `mouseleave` ever follows. So a
+hover-only affordance on a phone is one that appears and then cannot be
+dismissed, which is why [Tooltip](../widget/Tooltip.md) binds its hover path only
+when `matchMedia("(hover: hover)")` matches and stays reachable through keyboard
+focus everywhere else. The same test is the one to copy for a custom hover card,
+peek row or mouse-following cursor: gate it on the media query, and give the
+information a home the finger can reach — the control's own label, a
+[SnackBar](../widget/SnackBar.md), or a
+[BottomSheet](../widget/BottomSheet.md).
+
 ## Install Capacitor
 
 ```bash
@@ -225,6 +263,19 @@ Both platforms serve the app from a local HTTPS origin
 `capacitor.config.json`. A remote API has to allow that origin in its CORS
 configuration.
 
+### Text fields do not zoom the page
+
+iOS magnifies the whole viewport when a text control whose computed font size is
+under 16px receives focus, which reads as the screen growing and staying
+deformed after you type. FletBox floors the field text at 16px on iOS only: a
+`medium` or `small` field renders slightly larger there, while its box, label
+and icons keep the design's sizes. A reader who raises the browser font still
+gets a larger field, because the floor bounds the field's rem value instead of
+replacing it.
+
+Nothing has to be configured in the app, and the viewport is left alone: adding
+`maximum-scale=1` would stop the zoom by also blocking pinch-to-zoom.
+
 ### Add iOS to the project
 
 ```bash

package/docs/guides/online-updates.md

@@ -116,7 +116,7 @@ Every bundle ships a small manifest at `www/config.json`. This is what a running
 
 `update.url` is resolved automatically, in this order:
 
-1. `update.url` in `fletbox.config.json` at your project root (explicit wins).
+1. `update.url` in `fletbox.config.json` at your project root (explicit wins) — unless it is still the scaffold placeholder, which is not a choice. See [The Pages address of a generated app](#the-pages-address-of-a-generated-app).
 2. Derived from the `repository` field of `package.json`, mapped to GitHub Pages: `https://<user>.github.io/<repo>/`.
 3. Derived from the **current project's** git remote `origin` (when it is a GitHub URL). This means `flet-box createBundle` always points at the project it is built in, never at the flet-box framework installed as a dependency.
 4. If none of these exist, OTA is **disabled** and the bundle simply runs what shipped in it.
@@ -152,10 +152,22 @@ things at once:
 - writes that address into the header of the generated `.github/workflows/build.yml`;
 - prints it in the closing summary, with the one-time setting Pages needs.
 
-Without `--repo` nothing is invented. `fletbox.config.json` keeps the generic
-placeholder `https://TU-USUARIO.github.io/TU-REPO/`, the workflow header names a
-guess built from the folder name, and the workflow says so in its own comment:
-write the real address in both files that state it.
+Without `--repo` nothing is invented at scaffold time. `fletbox.config.json` keeps
+the generic placeholder `https://TU-USUARIO.github.io/TU-REPO/`, the workflow
+header names a guess built from the folder name, and the workflow says in its own
+comment which part of that address still has to be checked by hand.
+
+The build does not trust that placeholder. `TU-USUARIO` and `TU-REPO` mean "not
+configured yet", so `flet-box createBundle` falls through to rules 2 and 3 and
+writes the address it derived — and prints that it derived, because a manifest
+pointing at a real site next to a file that still says `TU-REPO` is a half-filled
+config you should either finish or leave alone. A project with no GitHub remote
+yet gets `update.url: null`: OTA is off, the bundle runs what shipped in it, and
+nothing polls a host that does not exist.
+
+That matters because the failure used to be silent. The app compares bundle
+**hashes**, and OTA is built never to break the app, so a placeholder URL that
+reached a bundle produced no error, no dialog and no update — ever.
 
 **The workflow log is the authority.** The header names the address you typed at
 scaffold time; the `Where this lives` step prints the address the run *actually*
@@ -274,7 +286,7 @@ Requirements: a **public** GitHub repository, GitHub Pages enabled (Settings →
 | Symptom | Likely cause |
 | --- | --- |
 | Build prints "THIS APP DOES NOT SUPPORT OTA UPDATES" | No public GitHub repo is reachable from the project (no `origin` remote, a non-GitHub remote, or nothing configured). The app still works — it runs the bundle it shipped with. Create the repo, push it, and rebuild. |
-| No dialog, app runs old code | `update.url` missing/incorrect, or no `v*` tag was published — a normal push updates the site but deliberately leaves the manifest out, so there is nothing to compare against. |
+| No dialog, app runs old code | `update.url` wrong — a real address that is not where the bundle is (the scaffold placeholder is not one of those: the build derives the address and prints it). Or no `v*` tag was published — a normal push updates the site but deliberately leaves the manifest out, so there is nothing to compare against. |
 | `hash mismatch` in console | The published `config.json` and bundle are from different builds. Re-run `flet-box release` so both are published together. |
 | Dialog appears but download fails | The Pages site is not reachable/CORS-blocked from the app origin. Pages serves with permissive headers; check you are not behind a proxy that strips them. |
 | Update applies but reverts on next launch | Cache Storage unavailable (private browsing). The bundle runs once but cannot persist. |