flet-box 1.1.0 → 1.1.2

package/skills/fletbox-motion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fletbox-motion
-description: When a FletBox screen may move and with which API - AnimatedBox, AnimatedText, ParallaxBox, animate/fadeIn/pulse, the frequency gate, durations that match the interaction, the two easing vocabularies the framework actually has, and what must never animate. Use when adding any transition, entrance, loading pulse, hover lift, parallax or hero motion.
+description: When a FletBox screen may move and with which API - the named transitions (slideIn, slideOut, popIn, shake), AnimatedBox, AnimatedText, ParallaxBox, animate/fadeIn/pulse, springs and the easing vocabulary, reduced motion with setMotionMode, the frequency gate, and what must never animate. Use when adding any transition, entrance, error feedback, loading pulse, hover lift, parallax or hero motion.
 ---
 
 # Motion — the only animation contract this app has
@@ -23,27 +23,61 @@ A screen the user works in all day gets *less* motion than a page they visit onc
 If you cannot say which row of this table the interaction is in, it gets no
 animation.
 
-## M1 The API is four things
-
+## M1 Pick the shortest API that says it
+
+- **The named transitions** — the three gestures a product repeats, with the
+  distance and the duration already chosen:
+  `slideIn(widget, { direction, distance, duration, easing, fade })`,
+  `slideOut(…)` (the mirror, and the unmount follows it),
+  `popIn(widget, { from, to, duration, easing })`,
+  `shake(widget, { axis, distance, cycles, duration })`. Each returns a cancel
+  function; each has an `…Async` form that resolves with the widget. Use these
+  before reaching for `animate`: they are one call instead of three, and they
+  already obey M7.
+- **The imperative helpers** — `animate(widget, property, from, to, duration, easing)`
+  for one property, `animateAsync` when the next step has to wait, `fadeIn` /
+  `fadeOut` / `pulse` (+ the `…Async` forms), `applyPulse`, and
+  `stopAnimation(widget, property)` for the cleanup you did not keep a handle for.
+  `animateSpring(widget, property, from, to, { stiffness, damping })` when the
+  movement should settle like an object instead of stopping like a timer.
 - **`AnimatedBox`** — declarative keyframes on one child:
   `AnimatedBox({ child, animations: [{ effect, from, to, duration, reverse, loop, delay }], timing, delay, fillMode })`.
+  Each step carries its own `duration`, `delay` and `loop` and each one is read off
+  that step: a 600 ms `scale` and a 400 ms `opacity` in the same entrance are one
+  rule that ends at 600 ms with the fade holding from 400 ms on. 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 that loops and a step that plays once cannot share a rule —
+  repeating the rule repeats the entrance too — so they become two `@keyframes`, and
+  two rules cannot compose one `transform`: keep the transform steps in one group.
 - **`AnimatedText`** — the same steps across the characters of a text, with
-  `delayBetween` (a stagger in ms) and `sameTime: true` to fire it at once.
+  `delayBetween` in **seconds** (`0.05` is a 50 ms stagger; `40` is forty seconds)
+  and `sameTime: true` to fire it at once.
 - **`ParallaxBox`** — offset driven by input: `type: 'scroll' | 'mouse' | 'hover'`,
   `speed`, `direction: 'vertical' | 'horizontal' | 'both'`, `maxOffset`, `reverse`,
   `disabled`, `onParallaxMove`.
-- **The imperative helpers** — `animate(widget, property, from, to, duration, easing)`
-  which returns a cancel function, `animateAsync` which returns a Promise,
-  `fadeIn` / `fadeOut` / `pulse` (+ the `…Async` forms), `applyPulse`,
-  `stopAnimation(widget, property)`.
 
 Anything else — a hand-written `transition: all`, a CSS library, a `requestAnimationFrame`
-loop in a widget — is a second animation system, and this app already has one.
-
-**Effects `AnimatedBox` knows:** `scale`, `rotate`, `rotateX`, `rotateY`,
-`translateX`, `translateY`, `opacity`, `color`, `backgroundColor`, `borderColor`,
-`borderWidth`, `borderRadius`, `width`, `height`, `boxShadow`, `background`,
-`textGradient`. Anything outside that list does nothing, silently.
+loop in a widget — is a second animation system, and this app already has one. A
+hand-rolled loop is also the one way to ship motion that ignores reduced motion,
+because the engine is what reads the preference.
+
+**Effects `AnimatedBox` knows:** `scale`, `scaleX`, `scaleY`, `rotate`, `rotateX`,
+`rotateY`, `rotateZ`, `skewX`, `skewY`, `translateX`, `translateY`, `translateZ`,
+`opacity`, `color`, `backgroundColor`, `borderColor`, `borderWidth`, `borderRadius`,
+`width`, `height`, `boxShadow`, `background`, `textGradient`. Anything outside that list
+does nothing, silently. The spacing effects (margin and padding, per side) work as
+well — they are routed by prefix, so the gate cannot see them by name.
+
+**Properties `animate()` moves:** the same names, plus any real CSS property
+(`width`, `opacity`, `borderRadius`, `color`…). A bare number is a **framework unit**,
+exactly as it is in a widget: `translateY: 20` is `20 / base-font-size` rem, so the
+movement scales with the reader's font instead of freezing at 20 pixels. A unit
+string keeps its unit (`"16px"`), a color blends whether you write `#rrggbb`,
+`rgb(…)` or `rgba(…)`, and a pair the framework cannot blend (`"red"` → `"blue"`)
+holds the start and lands on the end rather than writing `NaN`. `translateX`,
+`translateY` and `scale` are separate loops whose outputs are merged into one
+`transform` string, so an element can slide and grow at the same time.
 
 ## M2 Duration follows the distance, and the interaction
 
@@ -58,31 +92,38 @@ what slow feels like after the third repetition:
 | Menu, dropdown, sheet | 150–250 | `opacity` + `translateY` 8 → 0 |
 | Modal, drawer | 200–400 | `translateX`/`translateY`, never scale |
 | Screen entrance, hero | 300–500 | `opacity` + `translateY` 16 → 0 |
+| Rejected input | 300–360 | `shake`, never a color flash alone |
 | Loading | loop | `Skeleton({ animation: 'wave' })` |
 
 Nothing in the UI exceeds 500ms. A 300ms number on every element is not a design
 decision — it is the default.
 
 ```js
-// A sheet entering: 220ms, distance 24, nothing else.
-AnimatedBox({
-  child: panel,
-  animations: [
-    { effect: 'opacity', from: 0, to: 1, duration: 220 },
-    { effect: 'translateY', from: 24, to: 0, duration: 220 },
-  ],
-});
+// A sheet entering: the whole gesture is one call.
+slideIn(panel, { direction: 'up', distance: 24, duration: 220 });
+
+// …and leaving is the same sentence in the other direction, then the unmount.
+await slideOutAsync(panel, { direction: 'down' });
+panel.remove();
 ```
 
 ## M3 Two easing vocabularies — do not mix them
 
 This is a real trap, and it fails silently:
 
-- **`animate(..., easing)`** takes a *framework name*: `'linear' | 'easeIn' | 'easeOut' |
-  'easeInOut'`. An unrecognized string falls back to `linear`.
+- **`animate(..., easing)`** takes a *framework name* — one of `EASING_NAMES` — or
+  a curve (`cubicBezier(0.2, 0, 0, 1)`, `spring().easing`). An unrecognized string
+  warns and falls back to `linear`.
 - **`AnimatedBox({ timing })` and `ParallaxBox({ easing })`** are passed straight to
   CSS: `'ease' | 'ease-out' | 'ease-in' | 'linear' | 'cubic-bezier(…)'`. `easeIn` in
-  a `timing` string is not a curve CSS knows, and the step runs linear.
+  a `timing` string is not a curve CSS knows, and the step runs linear. `ease-out`
+  in `animate()` is not a framework name, and it runs linear too.
+
+The names the engine knows: `linear`, `easeIn`, `easeOut`, `easeInOut`, the powers
+(`easeOutCubic`, `easeInOutQuart`, `easeOutExpo`, `easeOutCirc` and their `In` /
+`InOut` siblings), the overshoot family (`easeOutBack`, `easeInOutBack`,
+`easeOutElastic`, `easeOutBounce`), and the Material shapes (`standard`,
+`emphasized`, `emphasizedDecelerate`, `emphasizedAccelerate`).
 
 Rules that hold for both:
 
@@ -91,13 +132,23 @@ Rules that hold for both:
 - **Never** `easeIn` on an interface element: it starts slow, so the first 100ms of
   a press feels broken. Save it for something leaving the screen at speed.
 - A loop that has to feel like a machine uses `linear`.
+- Use the overshoot family for one thing per screen at most. `easeOutElastic` on a
+  modal is a toy; on a badge that just arrived it is a highlight.
 - Never `transition: all`, and never animate `width`, `height`, `top`, `left` or
   `boxShadow` for something the user presses repeatedly: they reflow or repaint the
   page. `AnimatedBox` *can* animate them, which is exactly why this rule needs to be
   written down. Transform and opacity are the two properties that cost nothing:
   `scale`, `translateX/Y`, `rotate`, `opacity`.
 - Nothing enters from `scale: 0`, and nothing from full scale on a big element: use
-  **0.9–0.97**. From zero, the element is a dot that pops.
+  **0.9–0.97**. From zero, the element is a dot that pops. That is `popIn`'s default.
+
+```js
+// The curve a stylesheet would use, on the imperative side of the same screen.
+animate(card, 'translateY', 24, 0, 240, cubicBezier(0.2, 0, 0, 1));
+
+// Something the pointer just flicked finishes like an object, not like a timer.
+animateSpring(button, 'scale', 0.96, 1, { stiffness: 260, damping: 20 });
+```
 
 ## M4 Press feedback, done right
 
@@ -112,16 +163,29 @@ onPress: (widget) => animate(widget, 'scale', 1, 0.97, 140, 'easeOut');
 of that is three simultaneous answers to one question. Pick one — and if the color
 change is enough, which it usually is, ship it and move on.
 
+`shake` is not press feedback. It is the answer to "the server said no": 320ms,
+three decaying swings, and it ends at rest so the field does not stay off its
+column. Call it once per rejection, not on every keystroke.
+
+```js
+if (!result.ok) {
+  shake(loginForm, { axis: 'x', distance: 6, cycles: 3 });
+}
+```
+
 ## M5 Entrance and stagger
 
 Motion on first paint is the one place a longer budget is fair, with two limits:
 
 - Stagger **30–80ms** between siblings, and cap the total. `AnimatedText` gives this
-  for free with `delayBetween: 40`; a hand-built list needs `delay` per step, and a
-  list of 20 rows at 60ms each is a 1.2s wait before the content is readable.
-  Animate the first 5–8 items and let the rest appear.
+  for free with `delayBetween: 0.05` — that prop is in **seconds**, the unit the
+  framework writes into its `animation-delay`, so `40` would not be a fast stagger
+  but forty seconds. A hand-built list uses `stagger(index)` —
+  `stagger(3, { step: 60, max: 8 })` stops growing after 8 items, which is the
+  difference between a screen arriving and a screen loading: a list of 20 rows at
+  60ms each is a 1.2s wait before the content is readable.
 - One direction per screen. Elements arriving from the left *and* the bottom *and*
-  scaled is three ideas. A short `translateY` (8–24) plus `opacity` reads as one.
+  scaled is three ideas. `slideIn` is one direction plus opacity, on purpose.
 
 ## M6 Loops, ambient motion and `ParallaxBox`
 
@@ -134,28 +198,59 @@ Motion on first paint is the one place a longer budget is fair, with two limits:
   small (8–24). A background that moves 120px is not depth, it is a screensaver.
 - Ambient motion gets its own budget: one per screen, at most.
 
-## M7 What must never move
+## M7 Reduced motion is decided once, in the engine
+
+The user can ask for no movement, and FletBox listens:
+
+- `prefersReducedMotion()` — `true` when they have.
+- `setMotionMode('auto' | 'reduce' | 'full')` — the app's own switch, wired to a
+  settings control; `'auto'` (the default) follows the operating system.
+- `getMotionMode()`, and `onMotionModeChange(reduced => …)` for a widget holding a
+  live loop — it returns the unsubscribe, so release it in `onUnmount`.
+
+What it does to each surface, and why none of it needs a per-screen `if`:
+
+- `animate()` and the named transitions run one frame that **writes the end value**,
+  so the state still lands and an `await` still resolves. Only the movement goes.
+- `AnimatedBox` plays its keyframes once at `0.01ms` with no delay, and `fillMode:
+  'forwards'` leaves the element on its `to` values — content never stays hidden
+  waiting for an animation that was not allowed to run. A `loop` stops looping.
+  The reader can flip the OS setting *while the app is open*: the engine injects one
+  `@media (prefers-reduced-motion: reduce)` rule that overrides every element it
+  animates, so a loop already running stops without a rebuild and without a listener
+  to leak. The factory marks any element it gives an `infinite` animation — a
+  `Skeleton`, a striped `ProgressBar`, a `ListView` spinner — so a loop you write
+  yourself through the `animation` prop is covered too. Nothing in the app has to do
+  anything about it.
+- `ParallaxBox` parks its layer at the origin. `MatrixRain` paints one static field
+  and releases its `requestAnimationFrame`. `applyPulse` does nothing.
 
-- Text the user is reading at length; body copy that animates is copy they re-read.
-- Anything under a pointer or a finger while they aim at it — a control that shifts
-  while being targeted is a control you cannot hit (this is why press feedback scales
-  the element instead of moving it).
-- A field while typing, a list while scrolling, a number while it is being compared.
-- Two things at once in the same region: the last animation started is the one that
-  should win, and `stopAnimation(widget, property)` exists for exactly that.
+```js
+const chooseMotion = (on) => {
+  if (on) return setMotionMode('reduce');
+  return setMotionMode('auto');
+};
+
+// A settings screen hands the decision to the reader, and the engine applies it.
+Switch({ label: 'Reduce motion', value: getMotionMode() === 'reduce', onToggle: chooseMotion });
+```
 
-FletBox has no reduced-motion switch. That is not an excuse: build the screen so it
-reads with zero animation, then add motion as a decision you can point at. If the
-motion is only decoration, the honest answer to "respect reduced motion" is to not
-add it.
+Build the screen so it reads with zero animation anyway. Motion is a decision you
+can point at, and if it is only decoration the honest answer is to not add it —
+reduced motion is not a second design to maintain, it is the same design with the
+movable parts still.
 
 ## M8 Clean up
 
-An animation is a resource. `animate()` returns a cancel function — hold it and call
-it when the widget unmounts, or call `stopAnimation(widget, property)`. A loop that
-outlives its widget keeps a `requestAnimationFrame` alive and animates a detached
-node forever. A widget that registers timers, listeners or observers releases them in
-its `onUnmount` disposer.
+An animation is a resource. `animate()` and the presets return a cancel function —
+hold it and call it when the widget unmounts, or call `stopAnimation(widget, property)`.
+A loop that outlives its widget keeps a `requestAnimationFrame` alive and animates a
+detached node forever. A widget that registers timers, listeners or observers releases
+them in its `onUnmount` disposer.
+
+Starting a second animation on the same widget and property replaces the first — that
+is the engine, not a bug to work around. Two gestures on one element (`translateY` plus
+`scale`) are two loops and are merged into one `transform`, so they do not fight.
 
 ## M9 The check
 
@@ -166,3 +261,6 @@ its `onUnmount` disposer.
    animation, not to tune it.
 4. Check the frame, not the curve: press a control while something else moves. If
    the press feels delayed, the motion is the cause.
+5. Turn the mode to `'reduce'` and walk the screen. Everything must still arrive,
+   still be readable, still be operable — with nothing moving. That is the test
+   reduced motion asks for, and it is five minutes.

package/skills/fletbox-rules/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fletbox-rules
-description: The working contract for a FletBox app - FletBox syntax only, never a widget or prop from React/Vue/Svelte/Flutter, look an API up before using it, the rem unit contract, prop aliases, key-based state, resource cleanup and the two gates that prove the work. Read first, before any other skill, and before writing or editing a single file in src/.
+description: The working contract for a FletBox app - FletBox syntax only, never a widget or prop from React/Vue/Svelte/Flutter, look an API up before using it, the rem unit contract, prop aliases, key-based state, resource cleanup, one home for every shared helper, and the two gates that prove the work. Read first, before any other skill, and before writing or editing a single file in src/.
 ---
 
 # Rules — how to work inside this framework
@@ -152,3 +152,142 @@ learns something and does not write it is a session that has to be repeated.
 They cover the same screen from three angles and do not repeat each other. When
 they disagree, this file wins about the API, `fletbox-design` wins about the
 screen, and the checker wins about a value.
+
+## R12 The tools are the short form — use one before you hand-write it
+
+`flet-box` exports 123 helpers alongside the widgets. They exist because the code
+they replace is longer, and because the longer version is the one every model
+writes from memory. The rule is not "wrap everything in a helper": it is that a
+hand-written replacement has to be **shorter or clearer** than the tool, and for
+the list below it is not.
+
+| What you were about to write | Use instead |
+| --- | --- |
+| `Array.from({ length: n }, (_, i) => …)`, and a second branch for an object | `mapList(source, fn)` — takes an array, a number or an object |
+| a mock list built field by field | `createList(row, 12)` with `row = { name: () => random.fullName(), price: () => random.number(5, 40) }` |
+| `list.map` + `sort` + `[...new Set(…)]` chains | `sort(rows, 'price', 'desc')`, `unique(xs)`, `shuffle`, `chunk`, `reverse` |
+| a `for (let i = 0; …)` that only builds children | `range(0, 10)`, `repeat(3, Divider({}))` |
+| `'0px 4px 12px 0px rgba(…)'` typed out | `shadow(0, 4, 12, 0, rgba(0, 0, 0, 0.12))` |
+| `` `rgba(${r},${g},${b},${a})` `` and `` `linear-gradient(…)` `` | `rgba(37, 99, 235, 0.2)`, `gradient('linear', [a, b], 135)` |
+| a `transform` string you have to keep in sync by hand | `transform({ translate: [10, 20], rotate: 45, scale: 1.5 })` |
+| `'all 0.3s ease 0s'`, `'blur(5px) brightness(0.8)'` | `transition({ property: 'opacity', duration: 0.3 })`, `filter({ blur: 5, brightness: 0.8 })` |
+| a hex you re-lighten by eye, or hand-picked tints | `color(colors.primary).darken(12).hex()` |
+| `Math.floor(Math.random() * …)` and `Math.random().toString(36)` | `random.number(a, b)`, `random.choice(list)`, `shortId()`, `uuid()`, `timestampId()` |
+| `new Date(d).toLocaleDateString()` chains, a hand-written `"… ago"` | `formatDate(d, 'YYYY-MM-DD')`, `formatDateLong(d)`, `formatTimeAmPm(d)`, `relativeTime(iso)`, `timeAgoLocale(d, 'es')` |
+| `d.getTime() + 7 * 86400000` and a `(b - a) / 86400000` you have to re-derive | `addDays(d, 7)`, `subtractHours(d, 3)`, `dateDiff(a, b, 'days')`, and `days(7)` where you need the milliseconds |
+| `new Date().getDay() === 0`, a weekday name built from an array | `dayOfWeek(d)`, `monthName(d)`, `isWeekend(d)`, `isToday(d)` |
+| `new Promise(r => setTimeout(r, ms))`, a retry loop written twice, a poll loop written twice | `delay(ms)`, `withMinDelay(p, 600)` (a spinner that never flashes), `retry(fn, 3, 500)`, `waitUntil(() => ready, seconds(30))` |
+| a timer loop plus a handle you have to remember to clear | `everySecond(fn)`, `every(minutes(5), fn)` — and per R6, release the id it hands back on unmount |
+| a `const cache = {}` keyed by `JSON.stringify(args)` | `memo(fn)`, `memoWithKey(fn, keyFn)` |
+| `obj[k] !== undefined ? obj[k] : d`, `Object.entries(o).map(…)` | `dict(obj).get(k, d)`, `.items()`, `.has(k)`, `fromJSON(text)` |
+| `console.log('[' + label + '] ' + msg)` | `print('synced', 'success', { label: 'cart' })` |
+| `let el = null` plus `ref: (v) => (el = v)` | `const display = ref()`, then `Text({ ref: display })` and `display.update({ text: '…' })` |
+| `window.innerWidth >= 768`, and a resize listener that fires per pixel | `atLeast('md')`, `pick({ xs: 16, md: 24 })`, `onBreakpointChange(cb)` |
+| `navigator.clipboard.writeText(x)` (which throws without a gesture fallback) | `clipboard.copy(x)` |
+| injecting a `<link>` for a webfont | `loadFont('Inter', { weights: [400, 600] })`, then `fontsReady()` before a canvas paint |
+| `String(arr).split(sep)`, `s.trim().startsWith(x)` written as three calls | `split(s, sep)`, `join(arr, sep)`, `trim(s)`, `startsWith(s, x)`, `endsWith(s, x)`, `includes(s, x)` |
+| a `theme` object rebuilt per screen from hex literals | `colors.*`, `setTheme`, `subscribeTheme` |
+
+Four traps, because the rule is only honest with them:
+
+1. **A routed prop already *is* the short form.** `Container({ padding: 16 })` is
+   shorter and more correct than `padding: padding(16)` — the number reaches the
+   rem contract; the helper returns a **string** of pixels. Reach for
+   `padding(...)`/`margin(...)` only when you are writing a CSS value the props
+   cannot express (a `styles` object, a computed shorthand). Asymmetric sides have
+   props: `px: 20, py: 12`, `pt`, `pr`, `pb`, `pl`.
+2. **`filter` is the CSS filter, not a list filter.** `mapList`, `sort`, `unique`
+   and `createList` do list work; `filter({ blur: 5 })` builds a string.
+3. **`color()` is a chain, not a value.** `color(x).lighten(20)` is a `Color`; it
+   only becomes CSS at `.hex()`, `.rgb()` or `.rgba()`.
+4. **`months()` and `years()` are approximations, and a day is not 24 hours.**
+   `months(1)` is 30 days and `years(1)` is 365 — fine for a cache window, wrong
+   for a birthday. Whole-day steps (`addDays`, `subtractDays`) count on the
+   calendar, so they hold across a DST night; `addHours` and below count in real
+   elapsed time, which is what a countdown needs and what a "same time tomorrow"
+   must not use.
+
+R2 still outranks this one: when the exact signature is not in memory,
+`npm run check -- --list` and `flet-box unpack` say what is real. A confident wrong
+call is worse than the plain JavaScript it replaced — and `npm run check` will
+catch it, which is the point of running it.
+
+## R13 The keyboard is part of the screen, not an extra
+
+The engine already carries the whole of it, and an app only has to not break it:
+
+- **A handler given as a prop is a keyboard control.** `onPress` (or `onClick`)
+  on any widget makes the engine add `role="button"`, put it on the Tab path and
+  wire Enter and Space. A handler attached to the element *after* the widget was
+  built is a mouse-only control — the pass already ran. Express the control with
+  a prop.
+- **Never write `outline: none`**, and never add a global `*:focus` rule that
+  removes it. The ring is one rule the framework injects, coloured by the
+  `colors.focusRing` token; an inline `outline` outranks it and leaves a screen
+  where nobody can see where they are. Change the token with
+  `registerPalette`, or override with a class — the rule is zero-specificity for
+  exactly that.
+- **A control needs a name.** An icon with no `aria-label` and no visible text is
+  read as "button". An unnamed `Icon` is `aria-hidden` decoration by design, so
+  pressable icons take a label.
+- **Fields keep two jobs apart:** the border is validation, the ring is focus.
+  `label` names the field, the widget's own `validate` method announces the
+  verdict, and the message is already a live region with `aria-invalid` on the
+  input.
+- **Overlays trap focus and give it back.** `Modal`, `BottomSheet` and `Drawer`
+  do it; do not build a full-screen scrim with its own Escape listener beside
+  them.
+
+Prove it the way the framework does: press Tab through the screen, then Enter and
+Space on each control, then open an overlay and Tab past its last control.
+`npm run ui` covers names, labels, tap targets and contrast, and no checker has a
+keyboard — the last step is yours.
+
+## R14 The second copy is a module
+
+The first time you write a helper, it is yours. The second time the same code
+appears — the same formatter, the same validation, the same escaped string, the
+same card — it stops being a line you happen to share and becomes one module both
+files import. A screen-specific variant is a prop on the shared component, never a
+second component that starts as a copy.
+
+**Why:** two identical copies pass every test on the day they are written. They
+diverge on the day one of them is fixed — the fix lands in the copy that was in
+front of you, the other keeps the bug, and nothing tells you which is which.
+This is not hypothetical in this framework: the HTML escaper existed three times,
+`margin()` and `padding()` were byte-identical files apart from one word, and a
+keyframe injector lived in two modules, so the same animation name could be
+appended twice and neither dedupe set knew about the other.
+
+- Put a pure helper in **`src/helpers/`** — one file per behaviour, and it
+  **imports nothing at all**. That is the property that makes it reusable: a
+  widget can import it without dragging a theme, the parser or another widget
+  into its graph. If the helper needs another module it is a service, not a
+  helper, and it belongs in `src/utils/`. Anything that returns widgets goes in
+  `src/components/`. Name it for the behaviour, not for its first caller.
+- Import it from its own path. Re-exporting through a barrel is fine; copying the
+  body "to avoid a dependency" is not — if the import drags in too much, move the
+  helper down into a leaf module instead, which is exactly why the framework's
+  escaper imports nothing at all.
+- A helper that writes CSS state (`@keyframes`, an injected `<style>`) is owned by
+  one module for the whole document. A second injector is a second document-level
+  cache, and the same name is then defined twice.
+
+## R15 Essential code only
+
+Write the code the screen needs, in the smallest shape that says it. A feature
+nobody asked for is not a head start — it is code that has to be read, tested and
+maintained before it has a single caller, and it is the code most likely to be
+wrong because nothing uses it yet.
+
+- No option "for later", no prop nobody passes, no abstraction with one caller.
+  The second caller is when the helper appears (R14), not before.
+- A wrapper that only forwards its arguments is code to delete, not to keep: call
+  the function it forwards to.
+- Prefer removing a branch to adding a flag that selects between two branches.
+- Before writing a helper, look for the one that already does it: `flet-box`
+  ships 123 (R12), and the framework's own three are `escapeHtml`, `boxEdges`
+  and `injectKeyframes`.
+
+
+