flet-box 1.1.2 → 1.1.3

package/skills/fletbox-design/SKILL.md

@@ -417,6 +417,35 @@ waiting, remembering (p.099).
 - Break a convention only when the measurement says the convention is wrong here,
   and write that measurement down.
 
+### The phone range is the test device — strict
+
+"Fine on my phone" is not a measurement. Every phone is `xs` in the breakpoint
+table, so nothing in the shell changes between 320 and 430; the layout has to.
+Compose at 360 and prove the screen at each width below, in portrait:
+
+| Width × height | Device | What that width judges |
+| --- | --- | --- |
+| 320 × 568 | iPhone SE 1 / small Android | **the floor** — nothing overflows or clips |
+| 360 × 640 | Android baseline | **compose here first**, the cramped common case |
+| 375 × 667 | iPhone SE 2/3 | narrow and tall |
+| 390 × 844 | iPhone 12/13/14 | the modern default |
+| 393 × 852 | iPhone 14 Pro / 15 / 16 | notch and home indicator |
+| 412 × 915 | Pixel 7 | large Android |
+| 430 × 932 | iPhone 14/15 Pro Max | **the ceiling** — no measure so wide it loses the eye |
+
+- At 320 nothing overflows or clips: `scrollWidth <= clientWidth` on the page
+  and on every bar, and no label ellipsized because its row ran out of room.
+- A heading whose text the app does not control — a lesson name, a chapter, a
+  user's title — is `24` on a phone and `32` only where the layout is wide
+  (`atLeast("md")`). At 360 a 55-character name at `32` is four lines, and the
+  tab strip under it leaves the first screen. The size steps down; the copy is
+  never cut to fit it.
+- Fixed chrome is inside the 320 budget, not outside it: an app bar title plus
+  its actions, a tab strip, a labeled bottom bar. If a bar needs more than 320,
+  shorten what it says — never let it scroll sideways.
+- Verify by resizing the viewport at each width and reading the layout that
+  results, not by scaling a 1440 composition down.
+
 ## 17 Composition starts as a sentence
 
 Before the first widget, write four lines: what this screen decides for the
@@ -465,9 +494,9 @@ broken" report, and none of them is something `npm run ui` can see:
   (long-press, a native back gesture), not a layout one. A screen built from two
   hard-coded layouts is two screens to maintain; a screen with one per-step value
   where the shape truly changes is one.
-- Overlays go in a `Stack` with `stackPosition`, not in absolute coordinates on
-  `Container({ pos: "absolute", top, left })`. The first survives a content
-  change; the second is a pixel bomb in any language longer than English.
+- Overlays go in a `Stack` with `stackPosition`, never in absolute coordinates
+  (`pos: "absolute"`, `top`, `left`) on a plain `Container`. The first survives a
+  content change; the second is a pixel bomb in any language longer than English.
 
 ## 19 The dated tells
 
@@ -588,7 +617,7 @@ Both are worth more read than copied. The parts that do not survive measurement:
 ```bash
 npm run check
 npm run ui
-npm run dev        # look at the screen, at 375px and at 1440px
+npm run dev        # look at the screen at 320, 430 and 1440px
 ```
 
 Fix the code, not the checker. Then make the rule reusable: if the fix was right
@@ -701,6 +730,28 @@ that made it findable.
   bloom over a light page is indistinguishable from a smudge:
   `CircularBar({ glow: true, glowColor: colors.primary })`, or a tinted `shadow`
   string on the CTA. One glowing element per screen.
+- A reader's choice does not raise the budget. `ThemePicker` lets them pick the
+  hue; the three placements stay the only places it is spent. The picker marks
+  the chosen square with the page's ink and a tick, never with the accent — a
+  swatch selected in its own color says nothing the square does not already say,
+  and rule 28 forbids spending the accent on the control that hands it out.
+- A hue may also be worn as a **theme**, which is a different thing from spending
+  it: `ThemePicker({ surfaces: true })` and `setAccent("teal", { surfaces: true })`
+  derive the page, the panels, the cards and the hairlines from the same ramp, so
+  the screen is tinted teal while the accent itself stays on its three placements.
+  Only those five surface tokens move — the ink scale, `primaryBg` and every
+  semantic signal keep the palette's values, which is what lets a tinted theme
+  still say "this failed" in red — and `getAccentSurfaces()` answers which of the
+  two the reader is wearing. Offer it when 27's paper archetype is the app's look;
+  offer brand-only when the page is meant to stay neutral.
+- An app that ships a brand color sets it at boot with
+  `applyAccentPreference("teal")`, never with `setAccent`: the first paints a
+  default without writing a preference down, so a reader who has already chosen
+  still opens on their own hue; the second answers for them and stores it, which
+  is the app overwriting a person on every load. A created app ships `neutral` —
+  no hue, the page's own ink — so the picker opens with that square ticked and
+  the reader leaves it, rather than choosing between twelve colors on a first
+  visit.
 
 ## 29 The number is the hero
 
@@ -741,6 +792,14 @@ Column({ gap: 4, children: [
 
 - Controls are pills: `borderRadius` = half the height. Cards are 16-24. Inner
   thumbnails and tiles are 12-16, one step below their card.
+- **A pill is a one-line shape.** `borderRadius: 999` reads as a control only
+  while its height is about one line of its label: a label that wraps turns the
+  fill into an egg and the capsule's rounded ends cut into the words. `Button`
+  holds its label on one line and ellipsizes what does not fit, so a CTA that
+  needs three lines is a copy bug wearing a pill. Keep the label a verb and its
+  - **Follow Mission 1** — and leave the lesson title to the heading
+  (rule 04). If the action genuinely needs a sentence, the control is a card or
+  a list tile, not a button (rule 32).
 - **The nesting rule**, as arithmetic: `outer = inner + padding`. A 16-radius
   tile inside 8 of padding needs a 24-radius card. Equal radii at both levels is
   the failure — the inner corner and the outer corner curve on the same radius,
@@ -807,6 +866,7 @@ Stack({ alignment: "bottom-left", height: 420, children: [
 | switch 2 views of one object | segmented pill with a sliding plate | `Tabs({ variant: "pills", tabs, activeIndex, activeTextColor, buttonColor })` |
 | choose 1 of N with a preview | selection **tile**, not a radio list | `ListTile({ selected, selectedBgColor })`, or a 2-up `Row` of `Card`s |
 | pick a color/size | dot row, selected gets a ring | `Avatar({ shape: "circle", size: 28 })` row, ring via `borderColor` + `borderWidth` |
+| pick the app's accent | two-tone square per hue family | `ThemePicker({ size: 48, showLabels: true })` — it repaints the screen and remembers the choice; hand-built swatches do neither |
 | count then buy | stepper merged into the CTA | one `Row` of `Button`s inside the add-to-cart bar, not two actions |
 | navigate the app | bottom bar, active = accent + label | `BottomNavigation({ items, currentIndex, selectedColor, unselectedColor, showLabels: true })` |
 | a badge on an icon | dot, never a word | `Badge({ value, size, offset, borderColor: colors.background })` |
@@ -878,7 +938,31 @@ ink      white or near-white, and its opacity tiers
 - **Ramp, not swatch.** A family is 5-7 stops (base → tint → accent → shadow).
   Build it as a ramp so a card, a tile and a plate can be three steps of one hue
   instead of three hues — which is the only way 27's surface discipline is
-  possible without breaking 25's one-accent law.
+  possible without breaking 25's one-accent law. The framework already does this
+  arithmetic for a reader who asks for a colored app: `setAccent(id,
+  { surfaces: true })` takes the five stops it ships and writes `background`,
+  `surface`, `card`, `border` and `divider` off them (palest → wash → white card →
+  wash darkened, light; the deep stop scaled toward black in four steps, dark), so
+  a tinted theme is a call, not a hand-mixed set of hexes.
+- **A preset beats a mid-tone.** An app that has no ramp of its own does not pick
+  a blue and hope: it takes one of the twelve families the framework ships
+  (`listAccents()`, `listAccentRamps()` to see the stops) and paints a **stop** of
+  that ramp, so `colors.primary` and `colors.primaryBg` are two steps of one
+  gradient and never a hue plus a guess. Each pair is bought with seven measured
+  numbers per theme: the accent carries its own label at 4.5:1, reads as text on
+  the page at 4.5:1 and as a glyph on a card at 3:1, its wash holds page ink,
+  secondary ink and the accent at 4.5:1, and the wash lifts off the background by
+  1.04-1.5. That is why `#3b82f6` is not a brand color — white words on it
+  measure 3.15:1 — and why a hue the list lacks is registered instead of
+  invented: `registerAccent` takes an `id`, a `label` and a `light`/`dark` pair —
+  one hex each, or a five-stop ramp, whose stop 0 (light) and stop 1 (dark) are
+  the ones painted and whose wash is a stop further along the same direction.
+  Run a ramp the other way and the plate lands *under* the accent instead of just
+  off the page. It belongs in `src/database/themes.js` beside the palette it
+  feeds (rule 03), and a registered pair answers to the same veto as a hand-built
+  one. What `flet-box create` boots is the `neutral` family — the accent is the
+  page's own ink, so an unfinished app reads as paper and type rather than as
+  somebody else's brand — and the first change a designer makes is that id.
 - **The light/dark pair rule**: for the same hue in both palettes, lift the
   lightness and drop the saturation going dark. That is why this framework's dark
   `dangerStrong` is `#fca5a5` where the light one is `#b91c1c` — the readable red

package/skills/fletbox-motion/SKILL.md

@@ -232,7 +232,7 @@ const chooseMotion = (on) => {
 };
 
 // A settings screen hands the decision to the reader, and the engine applies it.
-Switch({ label: 'Reduce motion', value: getMotionMode() === 'reduce', onToggle: chooseMotion });
+Switch({ label: 'Reduce motion', value: getMotionMode() === 'reduce', onPress: chooseMotion });
 ```
 
 Build the screen so it reads with zero animation anyway. Motion is a decision you

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, 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/.
+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 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
@@ -101,18 +101,47 @@ reactivity). It is the only renderer. A custom component is still a function cal
 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
+That includes the DOM itself. App code never writes `innerHTML`: a hand-written
+element skips the theme, the scale and the accessibility every widget already
+has, and it is how a screen ends up speaking two visual languages at once.
+Building an element with `document.createElement` is the same mistake one layer
+down — the gate reports it as a warning, and it is usually a sign that a widget
+is missing.
+
+## R8 The gates, after every edit
 
 ```bash
+npm run verify     # every gate at once — one report, one exit code. This is the
+                   # command to run after every edit
+npm run verify -- --fix   # the same, after the mechanical repair: a typo is the
+                   # tool's job, not yours
 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
+                   # prop key, a prop the framework renamed. Anything ambiguous is
+                   # printed, never touched
+npm run metrics    # the north metric: how much code passed the gate with no
+                   # correction at all, and which failures keep coming back
 ```
 
+`npm run verify` parses every module first — `node --check`, the parser the
+runtime uses, so a missing `)` comes back as `file:line:column` with the
+offending line, a caret under the character and a hint — then runs the API check,
+the type check (the same `jsconfig.json` the editor reads, through the same
+TypeScript service: a widget typed as a bare `HTMLElement` makes
+`widget.update()` an error here and there), the design check, the structural
+check (two of your modules importing each other
+in a circle, a module outside the project folders, markup written by hand) and
+the prop contract, and then any test scripts the project declares. It prints one
+report: the gate that failed, the file at `line:column`, and what to do about it.
+
+Fix the line it names. Do not rewrite the file to make it pass, and do not
+reformat a line the report did not name — a diff you cannot justify is a diff
+you should not make.
+
 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.
@@ -121,14 +150,37 @@ 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.
 
+Every `npm run verify` writes a row into `.fletbox/metrics/generations.md`, green
+or not, so `npm run metrics` can say how much code passed the gate with no
+correction at all. The same command prints the failures that recur most often
+and the rule each one should belong to — and it **fails** when a code comes back
+three times with no rule behind it. That is the loop: the same mistake is a rule
+you did not write, and you are the one who writes it. A code that comes back
+*with* a rule behind it is a different problem, and the command says so: the
+rule is not landing.
+
+But a recurring code can also be the gate's own defect. When you prove that,
+write it into the log's **Gate defects** table with the window of runs it
+explains and where the fix lives — do not rename exports in the app to dodge
+it, and do not hard-code an exception inside the checker: the window is scoped,
+so the same code counts against the project again after the fix day.
+
 ## 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:
+and the installed version is the truth for this app. Four 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.
+- **A renamed prop never breaks the call, so nothing will tell you.** The old
+  spelling keeps working, marked `@deprecated`, until the next major; the gate
+  stays green either way, and an example you copied from three versions ago still
+  runs. The cheatsheet marks it — `onToggle?: (value: boolean) => void
+  (deprecated → onPress)` — and the prop after the arrow is the one to write.
+  `npm run fix` renames the calls it can prove (imports, prop typos and
+  deprecations in one pass) and prints the ones it cannot, so run it after every
+  upgrade and read the diff — a codemod that guesses is worse than one that stops.
 - 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.

package/src/core/runApp.js

@@ -9,6 +9,7 @@ import {
 import { Container } from "../widgets/Container.js";
 import { setGlobalRender } from "../tools/useState.js";
 import { beginRenderPass, endRenderPass } from "../widget-factory/reactiveValue.js";
+import { renderFailure } from "../utils/errorBoundary.js";
 
 /**
  * Mounts a FletBox application into the DOM and manages its full lifecycle.
@@ -184,12 +185,23 @@ export const runApp = (
     // state value surgical.
     beginRenderPass();
     let appContent;
+    let failure = null;
     try {
       appContent = typeof App === "function" ? App() : App;
+    } catch (error) {
+      failure = error;
     } finally {
       endRenderPass();
     }
 
+    // A throw in the component body — before any widget exists — has no widget
+    // to catch it. Without this the root stayed empty and the screen was
+    // blank; now it says what went wrong and where.
+    if (failure) {
+      renderFailure(root, failure, { widgetName: "App", phase: "app" });
+      return;
+    }
+
     const mainContainer = Container({
       margin: 0,
       padding: 0,