flet-box 1.1.0 → 1.1.1

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/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/utilities.md

@@ -2,6 +2,20 @@
 
 FletBox includes small helpers for common UI and application tasks. Import only the helpers you need from `flet-box`.
 
+These 123 helpers are the **short form** of code you would otherwise write by hand —
+a shadow, a gradient, a mock list, a retry, a relative date. The rule that goes with
+them is a comparison, not a prohibition: reach for a helper when the code it replaces
+is longer or less clear, which for the examples below it is.
+
+The one trap: **a routed prop is already the short form**. `Container({ padding: 16 })`
+is shorter and more correct than `padding: padding(16)`, because the number reaches the
+rem contract and the helper returns a pixel string. Use the string builders for a CSS
+value a prop cannot express, not instead of a number.
+
+Two names that read as something else: `filter({ blur: 5 })` builds a CSS filter, it
+does not filter a list (that is `mapList`, `sort`, `unique`), and `color(x).lighten(20)`
+is a chain that only becomes a color at `.hex()`, `.rgb()` or `.rgba()`.
+
 ## Layout helpers
 
 Use direct props for the simplest code:
@@ -90,20 +104,50 @@ Use random helpers for demos and sample data. Do not use generated demo values a
 
 ## Strings and dates
 
+The short form of the text and calendar code you would otherwise write by hand.
+
 ```javascript
 import {
+  addDays,
   capitalizeWords,
+  dateDiff,
+  dayOfWeek,
   formatDate,
+  formatDateLong,
+  isWeekend,
+  parseDate,
   relativeTime,
+  seconds,
+  timeAgoLocale,
+  today,
+  trim,
   truncate,
 } from "flet-box";
 
-capitalizeWords("flet box");
-truncate("A very long sentence", 10, "...");
-formatDate(new Date(), "YYYY-MM-DD");
-relativeTime("2026-01-01");
+capitalizeWords("flet box");          // "Flet Box"
+truncate("A very long sentence", 10); // "A very lon..."
+trim("   flet-box   ");               // "flet-box"
+
+formatDate(today(), "YYYY-MM-DD");    // today(), read back as itself
+formatDateLong(addDays(new Date(), 7));
+dayOfWeek("2024-01-15");              // "Monday"
+isWeekend("2024-01-15");              // false
+dateDiff(parseDate("15/01/2024", "DD/MM/YYYY"), new Date(), "days");
+relativeTime(Date.now() - seconds(90)); // "1 minute ago"
+timeAgoLocale(Date.now() - seconds(90), "es"); // "hace 1 minuto"
 ```
 
+Two things the helpers get right that hand-rolled `new Date(...)` chains usually
+don't. A bare `"YYYY-MM-DD"` is read as a **calendar day in the reader's zone**,
+so `isToday(today())` is true on a machine in any timezone; and `addDays` counts
+days on the calendar rather than adding `86400000` milliseconds, so it does not
+slip a day across a DST transition. `months(n)` and `years(n)` are the honest
+exceptions — they approximate 30 and 365 days, which is fine for a cache window
+and wrong for a birthday. For the repeating half of the same module — `every()`,
+`everySecond()`, `timer()`, `waitUntil()` — see
+[Text & time](../tools/text-and-time.md); whatever registers an interval releases
+it in `onUnmount`.
+
 ## Delays and retries
 
 ```javascript
@@ -115,6 +159,9 @@ await withMinDelay(fetchData(), 800);
 ```
 
 Use these helpers for loading states, demos, and recoverable network operations.
+`waitUntil(condition, timeout, interval)` and `waitForElement(selector, …)` cover
+the polling loop, and both **throw** at their timeout — await them inside a
+`try`, or answer them with a `.catch`.
 
 ## Device and dimensions
 
@@ -139,6 +186,62 @@ const removeListener = dimensions.addListener(({ width, height }) => {
 removeListener();
 ```
 
+`device` reads a user agent; the width is the fact a layout can trust. The full
+reference — the breakpoint table, the subscription and font loading — is
+[Device & environment](../tools/device.md).
+
+## Breakpoints
+
+One table, five steps, in CSS pixels: `xs` 0, `sm` 560, `md` 768, `lg` 1024,
+`xl` 1280. `md` is the same line `AdaptiveScaffold` draws between a drawer and a
+permanent sidebar, so a screen and its shell cannot disagree.
+
+```javascript
+import { atLeast, pick, currentBreakpoint } from "flet-box";
+
+const twoColumns = atLeast("md");
+const gutter = pick({ xs: 16, md: 24, lg: 32 });
+const step = currentBreakpoint(); // "sm" at 600px, "md" at 800px
+
+// A step that is not named inherits the nearest smaller one:
+// pick({ xs: 8, md: 16 }) answers 8, 8, 16, 16, 16.
+```
+
+Rebuild only when the viewport *crosses* a step, not on every pixel of a resize.
+`onBreakpointChange` returns the unsubscribe — hand it to the widget that owns the
+subscription:
+
+```javascript
+const [isWide, setIsWide] = useState("isWide", atLeast("md"));
+
+const screen = Column({
+  padding: gutter,
+  children: [Text({ text: String(isWide) })],
+});
+
+screen.onUnmount(onBreakpointChange(() => setIsWide(atLeast("md"))));
+```
+
+## Fonts
+
+`fontFamily` is a name. If the bytes of that face are not on the machine, the
+browser paints its own fallback and the app ships a typeface nobody chose.
+
+```javascript
+import { loadFont, fontsReady } from "flet-box";
+
+// A webfont is a network request: ask, wait, then name it.
+const loaded = await loadFont("Inter", { weights: [400, 600] });
+if (loaded) Text({ text: "Hello", fontFamily: "Inter" });
+
+// Before a canvas paint or an export, where reflowing text is a visible bug.
+await fontsReady();
+```
+
+`loadFont` resolves `false` when the face could not be had — it never fails a
+screen. Pass `url` to load your own same-origin stylesheet instead of a
+provider's, which is the answer an offline launch keeps.
+
 ## Themes and colors
 
 ```javascript
@@ -231,6 +334,15 @@ formatMediaProgress(30, 120);
 - Need URL changes? Read [Routing](router.md).
 - Need colors that follow the app theme? Use `colors` and `getColor`.
 - Need browser information? Use `device`, `os`, and `dimensions`.
+- Need a layout that changes with the window? Use `atLeast` and `pick`, and
+  subscribe with `onBreakpointChange` — never a user-agent guess.
+- Need a typeface that is not on the machine? Load it with `loadFont` before you
+  name it in `fontFamily`.
+- Need a date moved, compared or labelled? Use `addDays`, `dateDiff`, `formatDate`
+  and `timeAgo` — not a millisecond walk you have to re-derive each time.
+- Need a period, a stopwatch or a poll loop? Use `seconds(30)` and `every(…)`,
+  `timer(label)`, `waitUntil(…)`; the id `every` hands back is what `clearInterval`
+  releases in `onUnmount`.
 
 ---
 

package/docs/guides/widget-structure.md

@@ -114,6 +114,32 @@ export default MyWidget;
     pass CSS props directly (`backgroundColor`, `padding`, `flexDirection`,
     `whiteSpace`, …) with aliases resolved by the factory. `style: { ... }` is
     rejected with a warning (`processProps`), so it never silently half-applies.
+12. **A shared helper has one home.** The first time a helper is written it is
+    local; the second time it is a module both callers import. Two copies pass
+    every test on the day they are written and diverge on the day one is fixed —
+    so the home is named and the gate enforces it:
+
+    | Behaviour | Home |
+    | --- | --- |
+    | Escaping text for HTML | [`src/helpers/html.js`](../../src/helpers/html.js) |
+    | The four-side box shorthand | [`src/helpers/boxEdges.js`](../../src/helpers/boxEdges.js), behind `margin()`/`padding()` |
+    | Injecting `@keyframes`, naming one | [`src/utils/styleInjector.js`](../../src/utils/styleInjector.js) |
+    | A number that becomes a length | [`src/utils/units.js`](../../src/utils/units.js) |
+
+    **`src/helpers/` is the folder for reusable code, and a module there imports
+    nothing at all** — no widget, no theme, no engine service. That is what makes
+    it safe to import from anywhere: `html.js` has no dependencies on purpose,
+    because importing the Markdown parser from a widget would pull six widgets
+    into that widget's graph. A helper that needs another module is a service and
+    belongs in `utils/`. `node scripts/check-shared-helpers.mjs` fails on a second
+    definition, an `@keyframes` rule written outside the injector, a helper that
+    grew an import, or a caller that stopped importing the home.
+13. **Only the code the widget needs.** No prop nobody passes, no option kept
+    "for later", no abstraction with a single caller, no wrapper that only
+    forwards its arguments — that last one is code to delete, not to keep. The
+    second caller is when a helper appears (rule 12), not before. Three lines
+    repeated once reads better than a premature module; the same three lines
+    repeated three times do not.
 
 ## Controller widgets
 
@@ -158,6 +184,10 @@ Everything else returns an `HTMLElement`.
   to the baseline is never the fix.
 - `node scripts/check-widgets.mjs --write-baseline` — re-snapshot after a batch
   of fixes (only to *remove* entries in practice).
+- `node scripts/check-shared-helpers.mjs` — the single-home contract from rule
+  12: one definition per shared helper, the module named in the rule, and every
+  caller importing it. `--root <dir>` checks another checkout, which is how each
+  of its five rules was proven to fail when the rule is broken.
 - `/tests/widget-contract.html` — runtime contract: every widget instantiates,
   returns an element (or a documented controller), exposes `update()`, and
   reports its real `_widgetName`.

package/docs/tools/README.md

@@ -30,7 +30,7 @@ Each category is the next chapter of the reading path:
 | [Visual effects](visual-effects.md) | `applyShimmer`, `applyGlow`, `applyPulse`, `injectKeyframes` |
 | [Widget introspection](introspection.md) | `getWidgetProps`, `getWidgetProp`, `stringifyWidgetProps` |
 | [Input validation](validation.md) | `TextInputValidator` rules |
-| [Animation helpers](animation.md) | `animate`, `fadeIn`, `pulse` + `AnimatedBox` and friends |
+| [Animation helpers](animation.md) | `slideIn`, `popIn`, `shake`, `animate`, `fadeIn`, `pulse`, springs and `EASING_NAMES`, `setMotionMode` + `AnimatedBox` and friends |
 
 ## Styling helpers (CSS in JS)
 

package/docs/tools/animation.md

@@ -1,38 +1,159 @@
 # Animation helpers
 
 ## Overview
-Two ways to animate in FletBox: `animate`/`fadeIn`/`fadeOut`/`pulse` (and their `Async` variants) run animations on existing elements, while the widgets `AnimatedBox`, `AnimatedText`, `MatrixRain`, and `ParallaxBox` give you animated UI out of the box. Every helper-driven animation is cancelable — through the function it returns or later with `stopAnimation(widget)`.
+Three ways to animate in FletBox: the **named transitions** (`slideIn`, `popIn`, `shake`, `slideOut`) for the gestures a screen keeps repeating, `animate`/`fadeIn`/`fadeOut`/`pulse` (and their `Async` variants) for one property of one element, and the widgets `AnimatedBox`, `AnimatedText`, `MatrixRain`, and `ParallaxBox` for animated UI out of the box. Every helper-driven animation is cancelable — through the function it returns or later with `stopAnimation(widget)` — and all three honour the app's [motion preference](#reduced-motion), so a screen never has to ask whether the user wants movement.
 
 ## When to use
-- Animate an element when something happens: fade a panel in, pulse a button, animate a value change.
+- Bring a screen, sheet or card in: `slideIn(card)`, `popIn(badge)` — one call, one gesture.
+- Say "that was wrong": `shake(field)` on a rejected form.
+- Animate one property when something happens: fade a panel in, pulse a button, animate a value change.
 - Stop an animation the element no longer needs: `onUnmount(() => stopAnimation(el))`.
 - Add moving backgrounds (`MatrixRain`, `ParallaxBox`).
 
 ## Import
 
 ```javascript
-import { animate, fadeIn, fadeOut, pulse, stopAnimation, AnimatedBox } from "flet-box";
+import {
+  animate, fadeIn, fadeOut, pulse, stopAnimation,
+  slideIn, slideOut, popIn, shake, animateSpring,
+  EASING_NAMES, cubicBezier, spring, stagger,
+  prefersReducedMotion, setMotionMode, getMotionMode, onMotionModeChange,
+  AnimatedBox,
+} from "flet-box";
 ```
 
 ## Functions
 
 | Function | Signature | Returns | Description |
 | --- | --- | --- | --- |
-| `animate` | `animate(widget, property, from, to, duration?, easing?)` | cancel `() => boolean` | Animate one CSS `property` of a widget from `from` to `to` (both numbers or colors). `duration` is ms, `easing` defaults to `"linear"`. Calling the returned function stops the loop and returns `true` if it was still running. |
+| `animate` | `animate(widget, property, from, to, duration?, easing?)` | cancel `() => boolean` | Animate one `property` of a widget from `from` to `to`. A number is a **framework unit** — the same unit every widget prop takes — so `translateY: 20` is `20 / base-font-size` rem and grows with the reader's font; a unit string keeps its unit (`"16px"`); and a color blends whichever way you write it (`#rrggbb`, `rgb(…)`, `rgba(…)`). `duration` is ms, `easing` defaults to `"linear"` — a name from [`EASING_NAMES`](#easings), a `cubicBezier()` or a `spring().easing`. Calling the returned function stops the loop and returns `true` if it was still running. |
 | `animateAsync` | `animateAsync(widget, property, from, to, duration?, easing?)` | `Promise` | Same, resolves with the widget when the animation finishes — or as soon as it is cancelled or replaced, so `await` never hangs. |
+| `animateSpring` | `animateSpring(widget, property, from, to, options?)` | cancel `() => boolean` | The same loop driven by a damped spring: there is no duration to pick, the animation runs until it settles. `options` are `stiffness`, `damping`, `mass`, `initialVelocity`. |
+| `animateSpringAsync` | same, `Async` suffix | `Promise` | Promise variant of `animateSpring`. |
 | `stopAnimation` | `stopAnimation(widget, property?)` | `boolean` | Stop what is animating `widget` — one `property`, or every animated property when it is omitted. Use it in `onUnmount` when you did not keep the cancel function. |
-| `fadeIn` | `fadeIn(widget, duration?)` | cancel `() => boolean` | Fade the widget in (default 300 ms). |
-| `fadeOut` | `fadeOut(widget, duration?)` | cancel `() => boolean` | Fade it out. |
-| `pulse` | `pulse(widget, duration?)` | cancel `() => boolean` | A quick scale pulse: up for the first half, back down for the second. |
-| `fadeInAsync` / `fadeOutAsync` / `pulseAsync` | same, `Async` suffix | `Promise` | Promise variants that resolve on completion. |
+| `fadeIn` | `fadeIn(widget, duration?)` | cancel `() => boolean` | Fade the widget in to full opacity (default 300 ms). |
+| `fadeOut` | `fadeOut(widget, duration?)` | cancel `() => boolean` | Fade it out — from wherever the element actually is, so a card the theme set to `0.8` does not first jump to fully opaque. |
+| `pulse` | `pulse(widget, duration?)` | cancel `() => boolean` | A quick scale pulse: one loop that swells to `1.1` at the halfway mark and is back at `1` when it ends. |
+| `fadeInAsync` / `fadeOutAsync` / `pulseAsync` | same, `Async` suffix | `Promise` | The same single loop, awaitable, resolving with the widget — the sync and awaitable forms of a preset are one gesture, not two implementations. |
 
 Starting a second animation on the same widget and property **replaces** the first one; two loops writing
 one style would otherwise fight, and the older animation would resume after the newer had finished.
+Transform functions are the exception, and deliberately: `translateY` and `scale` are separate
+properties in the registry and are merged into one `transform` string, so an element can slide and
+grow at the same time.
+
+## Named transitions
+
+The three gestures every product repeats, with the durations and the distances already chosen, so an
+app does not hand-roll eleven slightly different entrances. Each returns a cancel function and has an
+`Async` form that resolves with the widget. `distance` is a framework unit like every other length in
+the framework — `16` is `1 rem` at the default base, not sixteen fixed pixels.
+
+| Function | Signature | What it says |
+| --- | --- | --- |
+| `slideIn` | `slideIn(widget, { direction, distance, duration, easing, fade })` | "this appeared" — a short travel plus a fade. `direction` is the way the element travels (`"up"` starts below its resting place), `distance` defaults to `16`, `duration` to `240`, `easing` to `"easeOut"`. |
+| `slideOut` | `slideOut(widget, { direction, distance, duration, easing, fade })` | "this is gone" — the mirror, one notch shorter (180 ms). What follows is your unmount: `await slideOutAsync(dialog).then(() => dialog.remove())`. |
+| `popIn` | `popIn(widget, { from, to, duration, easing, fade })` | "this belongs here" — scale from `0.94` with a small overshoot (`"easeOutBack"`). Nothing enters from `scale: 0`. |
+| `shake` | `shake(widget, { axis, distance, cycles, duration })` | "that was wrong" — one decaying sine on `translateX` (or `translateY`), 6 units, 3 swings, 320 ms, ending at rest. |
+
+```javascript
+// A sheet that arrives, and the error that refuses it.
+slideIn(panel, { direction: "up", distance: 24, duration: 220 });
+
+if (!password.valid) {
+  shake(loginForm, { axis: "x" });
+}
+```
+
+## Easings
+
+`animate()` reads a **FletBox name**, not a CSS string: `"ease-out"` is not in this vocabulary and the
+loop would run `linear` (with a warning) while `AnimatedBox({ timing })` hands the same word straight
+to CSS. `EASING_NAMES` is the list the framework knows.
+
+| Family | Names |
+| --- | --- |
+| The original four | `linear`, `easeIn`, `easeOut`, `easeInOut` |
+| Powers | `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeInExpo`, `easeOutExpo`, `easeInOutExpo`, `easeInCirc`, `easeOutCirc`, `easeInOutCirc` |
+| Overshoot | `easeInBack`, `easeOutBack`, `easeInOutBack`, `easeInElastic`, `easeOutElastic`, `easeOutBounce` |
+| Material shapes | `standard`, `emphasized`, `emphasizedDecelerate`, `emphasizedAccelerate` |
+
+An entrance decelerates — `easeOut*`, `emphasizedDecelerate` or a spring. `easeIn*` starts slow, which
+is why it belongs on something leaving the screen at speed and nowhere else in an interface.
+
+```javascript
+// Any CSS curve, on the imperative side.
+animate(card, "translateY", 24, 0, 240, cubicBezier(0.2, 0, 0, 1));
+
+// A gesture that continues into its resting place instead of stopping at it.
+animateSpring(button, "scale", 0.96, 1, { stiffness: 260, damping: 20 });
+```
+
+`stagger()` gives an entrance its choreography without the arithmetic that turns 20 rows into a 1.2 s
+wait: the delay stops growing after `max` items.
+
+```javascript
+list.forEach((row, index) => {
+  slideIn(row, { duration: 240 });
+  row.style.animationDelay = `${stagger(index, { step: 60, max: 8 })}ms`;
+});
+```
+
+## Reduced motion
+
+`prefers-reduced-motion` is not a style note: for readers with a vestibular disorder, parallax and
+large movement are physically unpleasant. FletBox answers it in the engine, so an animation cannot
+ship without the check.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `prefersReducedMotion` | `prefersReducedMotion()` | `true` when the app or the operating system asked for no movement. |
+| `setMotionMode` | `setMotionMode("auto" \| "reduce" \| "full")` | The app's own switch. `"auto"` (the default) follows the OS; `"reduce"` never moves; `"full"` always animates. Wires to a settings toggle. |
+| `getMotionMode` | `getMotionMode()` | The mode in effect. |
+| `onMotionModeChange` | `onMotionModeChange(listener)` | Calls `listener(reduced)` when the mode — or the OS setting — changes. Returns the unsubscribe; call it from `onUnmount`. |
+| `motionDuration` | `motionDuration(240)` | The duration a loop should actually run: `0` when motion is reduced. |
+
+What each surface does with it:
+
+- **`animate()` and the presets** collapse to a single frame that writes the end value. The state still
+  lands and an `await` still resolves — only the movement disappears.
+- **`AnimatedBox`** runs its keyframes at `0.01 ms`, once, with no delay. `fillMode: "forwards"` leaves
+  the element on its `to` values, and a `loop` stops looping. An element already looping when the reader
+  changes the OS setting is caught by a `@media (prefers-reduced-motion: reduce)` rule the engine injects
+  once, which overrides every animated element — no listener to leak, nothing to rebuild.
+- **Every `infinite` CSS animation the factory writes** is marked with that same hook, so the loading
+  loops belong to the widget author: `Skeleton`, `ProgressBar`, `Slider` (striped or glowing), the
+  `ListView` refresh spinner and the `Modal` spinner all stop on their own.
+- **`ParallaxBox`** parks its layer at the origin and stops answering scroll or pointer input.
+- **`MatrixRain`** paints one static field and releases the `requestAnimationFrame`.
+- **`applyPulse`** does nothing at all.
+
+```javascript
+// A settings screen that hands the decision to the reader.
+Switch({
+  label: "Reduce motion",
+  value: getMotionMode() === "reduce",
+  onToggle: (on) => setMotionMode(on ? "reduce" : "auto"),
+});
+```
 
 ## 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; 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).
+- `AnimatedBox({ animations, timing, delay, fillMode, child, top, right, bottom, left })` — animates a child widget.
+  `animations` is an array of `{ effect, from, to }` steps, and each step may carry its own `duration`, `delay`,
+  `loop` and `reverse` — every one of them is read off **that step**, so a 600 ms `scale` and a 400 ms `opacity`
+  run on two clocks inside one rule. Times are milliseconds as a number (`duration: 400`) or a CSS time as a
+  string (`delay: "0.4s"`); the widget-level `delay` is the default for the steps that do not name one. A step
+  plays once and holds `to` at the end (`reverse: true` swings it back to `from`, `loop: true` repeats it).
+  Effects are `opacity`, `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`, `rotateY`, `rotateZ`, `skewX`,
+  `skewY`, `translateX`, `translateY`, `translateZ`, `backgroundColor`, `color`, `borderColor`, `borderWidth`,
+  `borderRadius`, `width`, `height`, `boxShadow`, `background`, `textGradient` and the per-side margin/padding
+  steps. A looping step and a one-shot step generate two `@keyframes` rules — one rule per timing group — and
+  since two rules cannot compose one `transform`, keep the transform steps in one group. `timing` is a **CSS**
+  string (`"ease-out"`, `"cubic-bezier(…)"`).
+- `AnimatedText({ child, animations, sameTime, delayBetween, orientation })` — animates a `Text` widget, one step
+  per character. `delayBetween` is in **seconds** (`0.05` is a 50 ms stagger); the letters share one generated
+  rule and each carries its own delay.
 - `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"`.
 
@@ -67,7 +188,9 @@ AnimatedBox({
 
 ## Notes
 
-- Animation timing follows CSS `animation-duration` speeds (seconds/ms values depending on context — pass a number for ms in the widget props).
+- Two vocabularies of time, and each is honest about itself: `duration`/`delay` on a step or a preset are
+  milliseconds (a number, or a CSS time string the engine parses), `stagger()` returns milliseconds for
+  `animationDelay`, and `AnimatedText`'s `delayBetween` is seconds.
 - The `Async` variants are handy for sequences: `await fadeInAsync(el); await fadeOutAsync(el);`
 - For CSS-string animations use the `animation()` styling helper from [Styling helpers](styling.md).