flet-box 1.1.0 → 1.1.2

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

package/docs/tools/device.md

@@ -1,18 +1,26 @@
 # Device & environment
 
 ## Overview
-Detect what your app is running on: screen, orientation, operating system, and clipboard access. These helpers read the browser and stay in sync when the window changes.
+Detect what your app is running on: screen, orientation, operating system, and clipboard access. These helpers read the browser and stay in sync when the window changes. The same page carries the two halves a responsive screen needs — the **breakpoint** vocabulary (`BREAKPOINTS`, `currentBreakpoint`, `atLeast`, `pick`, `onBreakpointChange`), which says *which layout this viewport wants*, and `loadFont`, which makes a `fontFamily` prop real.
 
 ## When to use
 - Layout that changes between phone and desktop (`device`, `dimensions`).
+- One value per viewport (`pick({ xs: 8, md: 16 })`), or a decision that has to agree with `AdaptiveScaffold` (`atLeast("md")`).
+- Rebuild a screen when the viewport *crosses a step*, not when it moves a pixel (`onBreakpointChange`).
 - Show platform-specific UI (`os`).
 - Copy and paste text with one call (`clipboard`).
 - Walk the widget tree (`addNavigation`).
+- Load a webfont before you name it in `fontFamily` (`loadFont`, `fontsReady`).
 
 ## Import
 
 ```javascript
-import { device, os, dimensions, width, height, clipboard } from "flet-box";
+import {
+  device, os, dimensions, width, height, clipboard,
+  BREAKPOINTS, BREAKPOINT_NAMES, breakpointForWidth,
+  currentBreakpoint, atLeast, pick, onBreakpointChange,
+  loadFont, fontsReady,
+} from "flet-box";
 ```
 
 ## Objects
@@ -42,6 +50,67 @@ import { device, os, dimensions, width, height, clipboard } from "flet-box";
 
 `width` and `height` are also exported directly as numbers.
 
+### Breakpoints
+
+`dimensions` answers "how wide is the window"; a screen almost always wants the
+next question, "which layout does that width ask for". One table answers it, and
+`md` is 768 — the same line `AdaptiveScaffold` draws between a drawer and a
+permanent sidebar, so a screen and its shell cannot disagree.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `BREAKPOINTS` | `{ xs, sm, md, lg, xl }` | The widths in **CSS pixels** (0 · 560 · 768 · 1024 · 1280). A viewport is not a framework unit: it does not scale with the reader's font, and pretending otherwise puts a phone layout on a desktop. |
+| `BREAKPOINT_NAMES` | `['xs' … 'xl']` | The same names in width order. |
+| `currentBreakpoint()` | `() => Breakpoint` | The step the live window is in. `"xs"` where there is no window, so a Node import never throws. |
+| `breakpointForWidth(px)` | `(px: number) => Breakpoint` | The pure read behind it — a test, or a width that is not the viewport (an embed's container). |
+| `atLeast(name)` | `(name: Breakpoint) => boolean` | `atLeast("md")` is the sentence a two-column layout needs. |
+| `pick(values, fallback?)` | `(Record<Breakpoint, T>, T) => T` | A value per step. An unnamed step inherits the nearest smaller one: `pick({ xs: 8, md: 16 })` reads 8, 8, 16, 16, 16. |
+| `onBreakpointChange(listener)` | `(cb) => () => void` | Fires when the *name* changes, not on every pixel of a resize. Returns the unsubscribe; hand it to the widget's `onUnmount` so the subscription dies with the screen. |
+
+```javascript
+// One screen, two shapes, no second codebase.
+const gutter = pick({ xs: 16, md: 24, lg: 32 });
+
+const items = atLeast("md")
+  ? [listPane, detailPane]
+  : [currentPane];
+
+const [name, setName] = useState("bp", currentBreakpoint());
+const header = Column({ padding: gutter, children: [Text({ text: name })] });
+header.onUnmount(onBreakpointChange(setName));
+```
+
+A breakpoint is a *decision*, not a device. `device.isMobile()` reads a user
+agent, which a desktop in a narrow window cannot change and a tablet on desktop
+mode will not admit; `currentBreakpoint()` reads the width the app actually has.
+Use the width for layout and the UA only for a genuinely platform question (touch
+long-press, a native back gesture).
+
+### Fonts
+
+`fontFamily` is a name. If the bytes of that face are not on the machine, the
+browser paints its fallback and the app ships a typeface nobody chose.
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| `loadFont(family, options?)` | `(string, { weights?, url?, display? }) => Promise<boolean>` | Ask for a family. `weights` is required for a Google family if you want anything but 400 — a heading needs its weight asked for by name. `url` loads your own stylesheet instead of a provider's, which is the same-origin answer an offline launch keeps. Resolves `false` when the face could not be had; the screen keeps its fallback instead of failing. |
+| `fontsReady()` | `() => Promise<boolean>` | Wait for the faces already started. Use it before a canvas paint or an export, where text that reflows *after* the drawing is a visible bug. |
+
+```javascript
+import { Text, loadFont } from "flet-box";
+
+const body = Text({ text: "Reading", fontFamily: "Georgia, serif" });
+
+// One request per family, whoever asks first.
+loadFont("Inter", { weights: [400, 600] }).then((ok) => {
+  if (ok) body.style.fontFamily = "Inter, Georgia, serif";
+});
+```
+
+> A webfont is a network request. A self-hosted `@font-face` in the app's own CSS
+> is free of that and is the right answer for a product; a provider URL is fine
+> for a demo and is what a tunnel, a firewall or an offline launch breaks on.
+
 ### `os`
 
 | Method | Returns | Description |
@@ -111,7 +180,10 @@ dimensions.addListener(({ width, height }) => {
 
 ## Notes
 
-- `dimensions` subscribes to window resize internally; `addListener` returns an **unsubscribe function** — call it when the feature is destroyed to avoid leaks. Same for `device.onResize`/`onOrientationChange`.
+- `dimensions` subscribes to window resize internally; `addListener` returns an **unsubscribe function** — call it when the feature is destroyed to avoid leaks. Same for `device.onResize`/`onOrientationChange` and `onBreakpointChange`.
+- `onBreakpointChange` keeps **one** window listener for the whole app and fires only when the step name changes. Subscribing per card would still be one listener, but each callback would run on every pixel — a `Row` that re-renders on a pixel can change the scrollbar and resize the window again.
+- `BREAKPOINTS` are pixels by design. Everything else about a FletBox screen is a framework unit that grows with the reader's font; the viewport is the browser's own number and the layout switch has to be in the same currency as the window.
+- `loadFont` is idempotent per family and never rejects: a blocked request resolves `false`, and the app keeps its fallback. It writes a `<link>` into `document.head`, so a page with a strict CSP needs that host allowed — a self-hosted `url` avoids the question entirely.
 - `clipboard.read()` requires a user gesture in most browsers (it uses the same rules as `navigator.clipboard`).
 - `addNavigation` is idempotent — calling it twice on a widget is safe, and widgets already expose these members when they are built by the factory.
 - `os` also detects mobile/desktop families, which `device` derives for touch+screen decisions.