flet-box 1.0.9 → 1.1.0

package/skills/fletbox-memory/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: fletbox-memory
+description: The project journal that lets any AI pick up where the last one stopped - read .fletbox/memory/MEMORY.md before working, write an entry the moment something is learned, keep a running status note so a screen, a fix or a half-finished flow survives a change of model. Use at the start and the end of every session, before a risky change, and whenever the user says "continue" or "what is the state".
+---
+
+# Memory — the handover between sessions
+
+An app is built across many sessions and, more often than not, by different
+models. None of them remembers the last one. The only thing that carries over is
+what is written down, so writing it is part of the work, not a courtesy at the end.
+
+A session that learned something and did not write it is a session that will have
+to be repeated.
+
+## MEM1 Read before writing code
+
+At the start of a session, in this order:
+
+1. `AGENTS.md` — the contract.
+2. `.fletbox/memory/MEMORY.md` — one line per entry, with what it is about.
+3. The entries the task touches: the current status note, and any entry naming the
+   screen, widget or flow you are about to change.
+
+If the index points at a file that is not there, that is itself a finding: fix the
+index before you trust it, and say so.
+
+## MEM2 One entry per fact, never one entry per day
+
+`.fletbox/memory/notes/<slug>.md`, kebab-case, named after the **fact**, not the
+session: `checkout-form.md`, `listview-itemsize.md`, `dark-contrast.md`. Ten files
+about real things beat one `notes/2026-10-24.md` nobody can search.
+
+Every entry has the same shape, and the last two lines are what make it usable a
+month from now:
+
+```markdown
+---
+name: listview-itemsize
+description: ListView virtualises — itemSize must match the row it renders
+metadata:
+  type: project
+---
+
+A `ListView` row taller than its `itemSize` is clipped, and the scroll math drifts
+with it. Set `itemSize` to the real row height, or leave the list unvirtualised by
+passing `children` instead of `data`.
+
+**Why:** the row looked fine at the top of the list; only after 30 items did the
+bottom of each one disappear. Nothing in `npm run ui` can see it.
+
+**How to apply:** whenever a `ListView({ data, renderItem })` is added or a row's
+content changes, re-measure the row and update `itemSize`.
+```
+
+`type` is `project` (what this app is and where it is going), `decision` (a choice
+with a reason behind it), `finding` (something the framework or a screen does that
+surprised you), or `task` (open work someone has to finish).
+
+Then add the pointer to `MEMORY.md` — one line, under 150 characters, with a hook:
+
+```markdown
+- [ListView itemSize](notes/listview-itemsize.md) — a row taller than itemSize is clipped; re-measure after any row change
+```
+
+## MEM3 Keep one status note, and update it as you work
+
+`notes/current-status.md` is the handover document: the next model reads it and
+knows where it is standing. Keep four sections, short, and rewrite them instead of
+appending to them.
+
+```markdown
+# Status
+
+**Doing:** the checkout form — step 2 (payment) is built, step 3 is stubbed.
+**Done and verified:** `npm run check` clean, `npm run ui` clean, 375px and 1440px
+looked at in both themes.
+**Not done / half-done:** the "Apply coupon" action has no loading state; the empty
+cart is a blank panel.
+**Next:** add the two missing states (rule 12), then wire `onEndReached` on the
+product list.
+**Blocked:** the coupon endpoint is not decided — ask, do not guess.
+**Last touched:** src/screens/Checkout.js, 2026-10-24.
+```
+
+Honesty here is the whole value of the file. A note that says "done" when the empty
+state is missing is worse than no note: the next session builds on top of it.
+
+## MEM4 What belongs in memory, and what does not
+
+Write it when it passes one of these tests:
+
+- **You would get it wrong again.** A prop that silently does nothing, a widget that
+  ignores `elevation`, a default that surprises — re-deriving these costs a session.
+- **It explains a rule you broke.** The one-sentence justification for a kept
+  `npm run ui` finding belongs next to the finding.
+- **It is a decision with a reason.** "The list is unvirtualised because rows have
+  variable height" tells the next session not to "optimise" it back.
+- **It is user preference.** Tone, language, what they call the feature, what they
+  refused. This is the most valuable kind and the first thing a new model loses.
+
+Do not write:
+
+- Anything the code or `.fletbox/api/api.json` already says. Memory that restates
+  the API goes stale the next release; the generated files do not.
+- A log of what you edited. `git log` knows; a journal of diffs is noise that pushes
+  the useful entries out of view.
+- The scratch plan for a task you are about to finish. Delete it when the work lands,
+  or keep the decision and drop the plan.
+
+## MEM5 Correct the record instead of arguing with it
+
+Memory is a claim about a point in time, not a law. Before acting on an entry that
+names a file, a prop or a behavior, check that it is still true:
+
+- Still accurate → use it.
+- Contradicted by the code, by `npm run check` or by what the screen does → **the
+  code wins.** Fix the entry, or delete it, in the same change that fixes the screen.
+- About work that is now finished → remove the `task` entry and fold whatever was
+  learned into a `finding` or `decision` entry.
+
+Never leave a wrong entry because deleting it feels like losing history. A stale
+entry is the mechanism by which one model's mistake becomes the next model's
+"existing pattern".
+
+## MEM6 Write before the session ends, not after
+
+Update the status note at each natural boundary — a screen that passes both gates, a
+fix confirmed in the browser, a decision taken, a blocker found. Do not plan to write
+it "at the end": the end of a session is the one moment that reliably does not
+happen.
+
+One line in `MEMORY.md`, one file in `notes/`, and the status note rewritten is the
+whole cost. If the change is big enough to commit, the memory change goes in the same
+commit — the code and the reason for it should not be able to drift apart.

package/skills/fletbox-motion/SKILL.md

@@ -0,0 +1,168 @@
+---
+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.
+---
+
+# Motion — the only animation contract this app has
+
+Motion is a sentence, not a coat of paint. One screen says one thing with it:
+"this appeared", "this is loading", "this is where you are". Every other movement
+is noise that costs the frame budget and the user's attention.
+
+## M0 The frequency gate, first
+
+Ask how often the user sees this interaction. That number decides everything else:
+
+| Seen | Verdict |
+| --- | --- |
+| 100+ times a day (a button, a form field, a list row, a tab) | **No animation.** Feedback is a color or a state, not a movement. |
+| 10–100 times (a modal, a drawer, a filter applied) | 120–250ms, one property, no choreography. |
+| First time only (an onboarding screen, a hero, a landing page) | This is where the budget lives: entrance, stagger, one parallax. |
+
+A screen the user works in all day gets *less* motion than a page they visit once.
+If you cannot say which row of this table the interaction is in, it gets no
+animation.
+
+## M1 The API is four things
+
+- **`AnimatedBox`** — declarative keyframes on one child:
+  `AnimatedBox({ child, animations: [{ effect, from, to, duration, reverse, loop, delay }], timing, delay, fillMode })`.
+- **`AnimatedText`** — the same steps across the characters of a text, with
+  `delayBetween` (a stagger in ms) 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.
+
+## M2 Duration follows the distance, and the interaction
+
+Milliseconds, in the ranges that read as "instant" instead of "smooth" — smooth is
+what slow feels like after the third repetition:
+
+| Interaction | duration | What moves |
+| --- | --- | --- |
+| Press feedback | 100–160 | `scale` 1 → 0.97 |
+| Hover / focus state | 120–180 | `opacity`, `borderColor` |
+| Tooltip, chip, badge | 125–200 | `opacity` |
+| 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 |
+| 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 },
+  ],
+});
+```
+
+## 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`.
+- **`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.
+
+Rules that hold for both:
+
+- Entering and exiting UI use an **out** curve (`easeOut` / `ease-out`) — it starts
+  fast, which reads as responsive.
+- **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`.
+- 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.
+
+## M4 Press feedback, done right
+
+A press is 100+ times a day (M0): the answer is a state change, not a show.
+
+```js
+// The whole of it: 140ms, 3% of scale, back on release.
+onPress: (widget) => animate(widget, 'scale', 1, 0.97, 140, 'easeOut');
+```
+
+`Button` already changes color on press. Adding a lift, a glow and a scale on top
+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.
+
+## 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.
+- 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.
+
+## M6 Loops, ambient motion and `ParallaxBox`
+
+- A loop is a status. `loop: true`, `pulse`, `applyPulse` and `MatrixRain` say
+  "waiting" or "this is the one". If it never stops and means nothing, turn it off.
+- Loading uses `Skeleton({ animation: 'wave', count, gap, height })` in the shape of
+  the content that will replace it — not a spinner in the middle of a blank page.
+- `ParallaxBox` belongs to a hero or a single decorative layer, never inside a
+  working screen, and `type: 'mouse'` never on a touch-first app. Keep `maxOffset`
+  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
+
+- 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.
+
+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.
+
+## 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.
+
+## M9 The check
+
+1. `npm run check` — every prop named exists (`flet-box unpack AnimatedBox`).
+2. `npm run ui`.
+3. Watch it, twice, at 375px. Then answer: how many times a day does a real user
+   see this? If the answer is "a lot", the correct fix is usually to delete the
+   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.

package/skills/fletbox-rules/SKILL.md

@@ -0,0 +1,154 @@
+---
+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/.
+---
+
+# Rules — how to work inside this framework
+
+AGENTS.md is the short version of this file. It exists because the models that
+work here keep making the same five mistakes, and every one of them produces a
+screen that renders and is quietly wrong.
+
+## R1 FletBox only — no other framework
+
+A widget is a **function call that returns an element**. That is the whole model.
+Nothing from another ecosystem is valid here, however close it looks:
+
+```js
+// Correct: a function call with a props object.
+Text({ text: 'Hello', size: 18, color: colors.text });
+
+// Wrong: JSX.                    <Text size={18}>Hello</Text>
+// Wrong: positional args.        Text('Hello', 18);
+// Wrong: a foreign import.       import { Button } from 'react-native';
+// Wrong: a framework that is not this one. <div class="…">, Svelte markup, Vue SFC.
+```
+
+Every file is ESM (`"type": "module"`), imports come from `'flet-box'`, and there
+is no build step to learn and no compiler to blame.
+
+## R2 Never invent an API — look it up
+
+This is the rule the rest of the file exists to protect. A prop that silently does
+nothing is worse than a compile error: it renders as a broken layout and nobody
+finds it for weeks.
+
+| I want to know… | Look here |
+| --- | --- |
+| Which widgets exist and which props each accepts | `.fletbox/api/cheatsheet.md` |
+| Everything about one widget, with proof | `flet-box unpack <Widget>` |
+| A call that is safe to paste | `flet-box unpack <Widget> --example` |
+| Which props are documented but dead | `flet-box unpack <Widget> --diff` |
+| The whole surface as data, to build calls from | `.fletbox/api/api.json` |
+| Whether a name is exported at all | `npm run check -- --list` |
+
+**If a name is not in those files, it does not exist.** The four places a prop can
+live — `src/index.d.ts`, the prop registry, the widget's own source, its doc page —
+do not always agree, and `unpack` labels every disagreement: `DEAD` (typed, routed
+by nothing, read by nothing), `INVENTED` (read by the widget, declared nowhere),
+`UNDOCUMENTED`. Design against what reaches the DOM.
+
+- Do not edit `node_modules/flet-box`. It is a dependency, not source. A limitation
+  you hit there is fixed upstream, in the framework repo, or not at all.
+- Regenerate the API files (`npm run api`) after upgrading the package; never
+  hand-edit them.
+- When the API genuinely has no answer, choose a real composition or say the gap
+  out loud. Do not add a prop and hope the engine reads it — it drops unlisted
+  props.
+
+## R3 Aliases are the API, not a mistake
+
+`bgColor` ≡ `backgroundColor`, `onPress` ≡ `onClick`, and the rest. They are
+deliberate: each alias has exactly one meaning, resolved by the factory. Pick one
+spelling per screen and keep it — but never "clean up" an alias out of the
+framework, and never assume a second spelling is dead code.
+
+## R4 A number is not a pixel
+
+Any length you hand a rem-routed prop (`padding`, `margin`, `gap`, `width`,
+`size`, `borderRadius`, …) is divided by the base font size and emitted as `rem`,
+so the whole interface grows when the reader raises their browser font. That is
+the feature: one build fits phone, tablet and desktop.
+
+```js
+Container({ padding: 16 });   // 1rem — 16px at the default base, more at a bigger one
+```
+
+Pixels stay where pixels are honest: a canvas backing store, a value measured back
+out of the DOM (`offsetWidth`, `getBoundingClientRect`, scroll offsets), the
+hairline `borderWidth`, and a virtualised row's math in px space. Never write a
+`'16px'` string for something that should scale.
+
+## R5 State, and one way to re-render
+
+State is key-based RAM with subscribers: `useState('cart', 0)` returns the value
+and a setter; the widgets bound to the key update themselves. Do not build a second
+render system, do not reach into the DOM to change what a widget shows, and do not
+manually rebuild a tree that a setter could update. Setters on a widget
+(`widget.text = …`) are reactive for the same reason.
+
+## R6 Every resource you register, you release
+
+A widget or a screen that adds a `window`/`document` listener, a timer, a
+`requestAnimationFrame`, an observer, a router or storage subscription must release
+it when it unmounts — one idempotent disposer in `onUnmount`. A leaked loop keeps
+animating a detached node and outlives the screen that started it.
+
+## R7 One rendering engine
+
+`WidgetFactory` turns props into an element (style, events, children, lifecycle,
+reactivity). It is the only renderer. A custom component is still a function call
+returning widgets; never add a parallel way to paint, and never monkey-patch
+`container.update` — compose the update.
+
+## R8 The two gates, after every edit
+
+```bash
+npm run check      # does this API exist?  exits 1 on an invented widget, prop,
+                   # positional call, foreign import or broken module import
+npm run ui         # is this screen clean? tokens, the scale, tap targets, labels,
+                   # contrast — and it cites the rule it broke
+npm run fix        # rewrites what the checker can prove: a wrong path, a default
+                   # import of a named export, a missing import line, a typo in a
+                   # prop key. Anything ambiguous is printed, never touched
+```
+
+Then look at the screen at 375px and at 1440px, in both themes: **the checker has no
+eyes.** A clean `npm run ui` says the values are legal, not that the screen is
+understood.
+
+A finding you keep needs one sentence of justification, written where the next
+session will read it (R10). "The design wants it" is not a justification — it is a
+rule that has not been written down yet.
+
+## R9 Do not trust your memory of this framework
+
+FletBox has no `.d.ts` you have read in full, the prop set grows between versions,
+and the installed version is the truth for this app. Three habits follow:
+
+- Look up before using, even for `Text`.
+- After a dependency bump, re-run `npm run check` across the app — it also reports
+  names the package stopped exporting.
+- What is deployed is built from the **published** package, not from your working
+  tree. A fix you made in a local checkout does not exist for an installed app
+  until it is released.
+
+## R10 Write down what only you learned
+
+The project keeps its memory in `.fletbox/memory/`. Read `MEMORY.md` before you
+start, and record what the next session would otherwise rediscover the hard way.
+`fletbox-memory` is the format and the rules; it is not optional — a session that
+learns something and does not write it is a session that has to be repeated.
+
+## R11 The order the skills are read in
+
+| # | Skill | Read it when |
+| --- | --- | --- |
+| 1 | `fletbox-rules` (this file) | always, before writing code |
+| 2 | `fletbox-design` | creating, editing or reviewing any screen, form, list or dialog |
+| 3 | `fletbox-motion` | adding any transition, entrance, pulse, parallax or hover lift |
+| 4 | `fletbox-memory` | at the start and at the end of every session, and whenever progress changes |
+
+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.

package/src/utils/themes.js

@@ -103,6 +103,22 @@ export const palettes = {
     infoStrong: "#1d4ed8",
     infoPlate: "#1d4ed8",
     info: "#3b82f6",
+    // The alert tints, and the red the word "error" names. `check-ui` tells an app
+    // that "`colors.primaryBg`, `colors.errorBg` and friends are the tints" and the
+    // boot palette has had these five since the start, but the light palette did
+    // not — so an app that themed its alerts the framework way lost every tint the
+    // moment it booted into light (`colors.errorBg` came back `undefined`, and a
+    // `bgColor` of undefined is no background at all). Dark answered them first
+    // because a pale pink fill is unreadable on a black page and had to be
+    // invented; this is the same idea read from the light end: the tint is nearly
+    // white, so the ink on it is the `*Strong` of that hue — 5.91, 5.21, 4.84 and
+    // 6.16:1 in order, all over the AA line — and the page ink `#09090B` sits on
+    // all four at 18:1 and up.
+    error: "#ef4444",
+    errorBg: "#fef2f2",
+    successBg: "#ecfdf5",
+    warningBg: "#fffbeb",
+    infoBg: "#eff6ff",
     background: "#ffffff",
     surface: "#fafafa",
     card: "#ffffff",