@oxy.so/bloom 3.5.0 → 4.0.0

package/docs/design-tokens.mdx

@@ -238,31 +238,35 @@ That question belongs to `styles/surface-levels.ts`
 container publish the rung its children sit on. It is built BESIDE the policy,
 reading `theme.colors`, and changes no preset and no token.
 
-## The neutral surface ramp
-
-`--background`, `--surface`, `--popover`, `--muted`/`--accent` and `--card` are a
-stack: several components carry meaning **only** in the step between two of them —
-an `ActivityHeatmap` empty cell, `Card variant="filled"`, a `Code` block, the
-`StatBar` and `CompositionBar` tracks, `DotGridMeter`'s off dots, a filled `Tabs`
-track, a selected `Item`, the solid `TabBar`, a plain `Card` on a panel, the
-`Toast` action, and the `Avatar`/`LinkPreviewCard` placeholders.
-
-Those tones are owned by `SURFACE_RAMP` in `theme/color-policy.ts` rather than
-taken from Material 3's container roles. M3's ramp steps by 2 tones, which at
-these lightnesses is about **1.2 ΔE00** — below the just-noticeable difference for
-two large flat patches. Measured across all 64 presets, **4 tones (~2.4 ΔE00)** is
-the first spacing at which every pair separates.
-
-`--background` is deliberately not part of the ramp: the page tone is every
-consuming app's page colour, so the rungs below it carry the spacing instead.
-`--card` is not either — it sits on the far side of the page in light (tone 100,
-white) and at the top of the ramp in dark, so it is expressed as the engine role
-that means exactly that in each mode.
-
-If you move any of these, measure **every** pair rather than the one you are
-fixing: the light tones 92/94/96/98/100 are exactly `--muted`, `--popover`,
-`--surface`, `--content-area` and `--card`, so any new value for one lands on
-another unless you check.
+## The tonal surface ramp
+
+The shell carries its seed hue throughout the surface, text and border families,
+using HCT chroma 28 where the gamut permits it. Monochrome seeds retain grayscale
+and their original tones. Labels and boundaries read canonical token pairs, so
+JavaScript and CSS consumers share the same palette.
+
+| Mode | Card | Page | Surface/sidebar | Popover | Muted/accent |
+| --- | --- | --- | --- | --- | --- |
+| Chromatic light | 98 | 94 | 90 | 86 | 82 |
+| Monochrome light | 100 | 96 | 92 | 88 | 84 |
+| Dark | 22 | 4 | 10 | 14 | 18 |
+
+These are authored HCT tones. The light card stops short of white to preserve
+its hue; the rest of the chromatic light ladder shifts with it. Content-area
+keeps an intermediate tone: 96 in chromatic light, 98 in monochrome light and
+6 in dark. It is not another four-tone ladder rung.
+
+The original low-chroma investigation found M3's two-tone container steps
+around 1.2 ΔE00, below the intended distinction between large flat surfaces;
+four-tone steps measured about 2.4 ΔE00. Those historical measurements are not
+claimed for the new chromatic palette. The current 64-preset × two-mode matrix
+measures every declared ladder neighbour in quantized HCT tone: the smallest
+actual gap is 3.68. Both foreground roles clear AA on all six surfaces, with a
+minimum measured ratio of 5.75. `tonal-surfaces.test.ts` guards these contracts.
+
+Never move just one surface without measuring its neighbours: a tone that
+separates one pair can land directly on another. The intentional sidebar/surface
+and muted/accent aliases do not represent separate elevations.
 
 ## Scales
 
@@ -276,6 +280,20 @@ another unless you check.
 - **Shadow**: `shadow-s`, `shadow-m` (web box-shadow). On native surfaces apply
   `bloomShadowStyle('s' | 'm')` (returns RN elevation/shadow props).
 
+### Chart series
+
+`--chart-1` through `--chart-9` and their `--chart-N-active` partners are
+the canonical categorical palette. `useTheme().chartColors` exposes these
+same nine `{ color, activeColor }` pairs to JavaScript. The original five
+series retain their colors; four interleaved hues extend the palette.
+Monochrome presets use nine separate grayscale steps in both modes.
+
+Chart cards read these pairs by default. Explicit series `color` and
+`activeColor` overrides still take precedence. Hand-authored themes may omit
+`chartColors`; charts then derive the same policy from the theme's primary
+color and mode. For a deliberate custom categorical palette, provide all
+nine pairs on `Theme.chartColors`.
+
 ### Type scale
 
 | Role | Size / line | Weight | Family |
@@ -288,3 +306,12 @@ another unless you check.
 | `sectionTitle` | 20 / 26 | 600 | sans |
 | `headerBold` | 28 / 34 | 700 | display |
 | `buttonLarge` | 17 / 22 | 600 | sans |
+
+### Media and creator surfaces
+
+Media, library, queue, creator and property-insight palettes resolve structural
+fills and quiet labels from the tonal surface helpers. Artwork bands preserve
+caller-supplied hues, darkened only when their paired labels require it; their
+black/white image ink is intentional. Energy bands remain categorical data
+colors with measured black/white foregrounds. They are not shell backgrounds.
+`media-semantic-palette.test.ts` checks those pairs across all presets and modes.

package/docs/dialog.mdx

@@ -238,7 +238,7 @@ const [busy, setBusy] = useState(false);
 
 ```tsx
 <Dialog control={control} title="Add tag">
-  <TextFieldInput label="Tag name" value={name} onChangeText={setName} />
+  <TextFieldInput label="Tag name" value={name} onValueChange={setName} />
   <Button onPress={() => { save(name); control.close(); }}>Save</Button>
 </Dialog>
 ```

package/docs/dropdown-menu.mdx

@@ -28,7 +28,7 @@ import { Button } from '@oxy.so/bloom/button';
 
 <DropdownMenu>
   <DropdownMenuTrigger asChild label="Open menu">
-    <Button variant="secondary">Open menu</Button>
+    <Button appearance="outline" tone="neutral">Open menu</Button>
   </DropdownMenuTrigger>
 
   <DropdownMenuContent>
@@ -40,7 +40,7 @@ import { Button } from '@oxy.so/bloom/button';
     </DropdownMenuItem>
     <DropdownMenuItem disabled>Billing</DropdownMenuItem>
     <DropdownMenuSeparator />
-    <DropdownMenuItem variant="destructive" onPress={signOut}>
+    <DropdownMenuItem tone="danger" onPress={signOut}>
       Sign out
     </DropdownMenuItem>
   </DropdownMenuContent>
@@ -55,7 +55,7 @@ A row dismisses the menu after it fires. Pass `keepOpen` to a row that should no
 
 ```tsx
 <DropdownMenuTrigger asChild label="Actions">
-  <Button variant="icon" onPress={track}>…</Button>
+  <Button onPress={track} appearance="outline" tone="neutral">…</Button>
 </DropdownMenuTrigger>
 ```
 

package/docs/fab.mdx

@@ -1,79 +1,34 @@
----
-title: Fab
-description: The floating action button — one per screen, for the screen's primary action.
-order: 43
----
-
 # Fab
 
-A floating button for the **one** thing a screen is mostly for: compose on a
-feed, add on a list, new message in an inbox.
+`Fab` is a prominent action built on `Button`. It shares color, focus, loading,
+press and accessibility behavior. Its parent owns placement.
 
 ```tsx
 import { Fab } from '@oxy.so/bloom/fab';
+import * as Icons from '@oxy.so/bloom/icons';
 
-<Fab
-  icon={<PencilIcon />}
-  accessibilityLabel="New post"
-  onPress={compose}
-/>
-
-<Fab
-  icon={<PencilIcon />}
-  label="New post"
-  placement="bottom-right"
-  onPress={compose}
-/>
+<Fab icon={Icons.RiAddLine} accessibilityLabel="Create post" onPress={createPost} />
+<Fab icon={Icons.RiAddLine} label="Compose" tone="action" appearance="solid" />
 ```
 
-## Which prop decides what
-
-| prop               | decides                                                    |
-| ------------------ | ---------------------------------------------------------- |
-| `icon`             | the glyph                                                   |
-| `label`            | makes it an extended FAB with visible text                  |
-| `variant`          | `primary` · `secondary` · `tertiary` · `surface`            |
-| `size`             | `small` · `medium` · `large`, or a number                   |
-| `placement`        | which corner it floats in, or `static` to place it yourself |
-| `offset`           | distance from the edges                                     |
-| `minimizeBehavior` | `none` · `hide` · `collapse` with the nearest Bloom tab bar |
-
-## An icon-only FAB needs `accessibilityLabel`
-
-Without it the button announces as "button" and nothing else. A pencil is not
-self-describing to a screen reader, and it is not always self-describing on
-screen either — which is what `label` is for.
-
-## One per screen
+`size` is `xs | sm | md | lg` (40, 48, 56, 64 points; default `md`).
+`size` and `tone` inherit from `BloomScope`. `tone` defaults to `action`;
+`appearance` defaults to `solid` and also accepts `subtle`, `outline`, `plain`.
+Icon props take a component, which receives its size and foreground color.
+Icon-only actions require `accessibilityLabel`; labeled actions use their label.
 
-A FAB claims the corner and floats above the content. Two of them are two
-primary actions, which means neither is primary, and they compete for the same
-thumb position. If a screen has several important actions, the FAB takes the
-most common one and the rest go in the content or a menu.
-
-On web, a bottom placement stays inside the content column with sticky
-positioning. The column must fill the available height, use flex-column layout,
-and render the FAB last. This keeps it at the bottom with short content and in
-view while the document scrolls, without escaping over a side rail. Top
-placements remain absolute within their positioned container.
-
-## Following a Bloom tab bar
-
-The FAB automatically clears the bottom-edge footprint claimed by Bloom's tab
-bar and follows its compact height when it minimizes. An extended FAB can also
-react to that state:
-
-```tsx
-<Fab label="Compose" minimizeBehavior="collapse" {...props} />
-<Fab label="Compose" minimizeBehavior="hide" {...props} />
-```
+An explicit tone wins over `BloomScope`, which wins over the `action` default. A utility such as “Back to top” can use `tone="neutral" appearance="subtle"`. The Color roles prototype demonstrates an action Fab alongside accent navigation and subtle support surfaces.
 
-`collapse` smoothly retracts the label and horizontal space while retaining the
-icon-only action. `hide` removes the whole action. The default is `none`, which
-preserves the full FAB.
+Use `AppShell.primaryAction` to coordinate a screen action with navigation, or
+`BottomBar.action` for a custom bottom composition. A standalone Fab stays in
+normal flow and accepts the usual `style` and `className` layout overrides.
 
-## `placement="static"` when something else owns the position
+## Migration
 
-A FAB inside a custom positioned container can use `static` to turn off Bloom's
-anchoring. Do not use it merely to avoid a Bloom tab bar; bottom-edge clearance
-and `minimizeBehavior` already cover that case.
+Remove `placement`, `offset`, `zIndex`, and `minimizeBehavior`. Position the action
+through `AppShell`/`BottomBar`; the bottom accessory hides on downward scroll
+and returns upward by default. Set `actionBehavior="visible"` on `BottomBar`
+or `bottomActionBehavior="visible"` on `AppShell` to keep it visible. Replace `variant="primary"` with `tone="action"` for the main task (or `accent` when retaining brand emphasis), `variant="surface"`
+with `tone="neutral" appearance="subtle"`. The shared `support` and `action` roles resolve the secondary and tertiary color pairs. Choose them by intent: contextual support or the main task. Replace `small/medium/large` with `sm/md/lg`, and numeric size
+with a preset plus a deliberate style override if needed. Replace icon elements
+with icon components and remove the `children` alias.

package/docs/field.mdx

@@ -21,7 +21,7 @@ import { TextField, TextFieldInput } from '@oxy.so/bloom/text-field';
   required
 >
   <TextField>
-    <TextFieldInput label="Email" value={email} onChangeText={setEmail} />
+    <TextFieldInput label="Email" value={email} onValueChange={setEmail} />
   </TextField>
 </Field>
 ```

package/docs/file-upload.mdx

@@ -71,7 +71,7 @@ The "Upload file" / "Upload in progress" frames, pixel-matched on web.
 | | |
 | --- | --- |
 | zone | 164 tall, full width, radius 16 |
-| idle | secondary fill (neutral-100, dark neutral-900), 2px **dashed** border (neutral-300 / 700) that darkens on hover or drag-over (neutral-400 / 600); 40px disc with a 24px upload-cloud icon that darkens on hover; 14 below it the Body/Medium prompt with the action word in accent-500, 8 below that the Body 2 hint |
+| idle | shared secondary surface, 2px **dashed** semantic border that uses primary on hover or drag-over; 40px disc with a 24px upload-cloud icon that darkens on hover; 14 below it the Body/Medium prompt with the action word in accent-500, 8 below that the Body 2 hint |
 | uploading | surface fill; the dashed border fades out and a 2px neutral outline fades in with an accent-400 stroke running **clockwise from top-centre**; an accent-400 `42%` pill (Caption 1/Medium, tabular figures) drops in over the top edge; bordered 40px disc with a file-type icon (spreadsheet / image / document, or `renderFileIcon`), the name (Body/Medium, truncated at 90%) and "Uploading 2.4 MB..." |
 | complete | the ring closes and the status line cross-fades to "Uploaded successfully!" |
 

package/docs/frosted-icon-button.mdx

@@ -14,19 +14,23 @@ mute toggle on a video, a back button over a hero image.
 import { FrostedIconButton } from '@oxy.so/bloom/frosted-icon-button';
 
 <FrostedIconButton
-  icon={<CloseIcon />}
+  icon={CloseIcon}
   accessibilityLabel="Close"
   onPress={close}
 />
 ```
 
+The icon is a component receiving `width`, `height` and `fill`; `children` is not an icon alias. Size and tone inherit from `BloomScope`; `tone` controls the solid active state.
+
+For a controlled toggle, pass `checked` and `onCheckedChange`. The callback receives the next boolean. `onPress` remains available for ordinary actions and runs alongside the toggle callback when both are supplied; disabled controls call neither.
+
 ## Which prop decides what
 
 | prop       | decides                                             |
 | ---------- | ---------------------------------------------------- |
 | `icon`     | the glyph                                            |
-| `size`     | `sm` · `md`, or a number                             |
-| `active`   | a persistent on state, for a toggle                  |
+| `size`     | `xs` · `sm` · `md` · `lg`, or a number                             |
+| `checked`   | a persistent on state, for a toggle                  |
 | `disabled` | dims and disables                                    |
 | `hitSlop`  | the touch target beyond the drawn circle             |
 

package/docs/glass.mdx

@@ -14,16 +14,16 @@ order: 90
 
 The glass is the sheen, not the wash. What reads as glass is the rim, the vertical gradient and the hairline; the 15% of the backdrop that shows through is a hint of depth, not the effect itself.
 
-**One measured cost, stated because it is real.** The 15% bleed moves the pane toward the surface under it, which in light mode means lighter — the one direction a white label cannot afford. Of `primary`'s 640 preset × mode × surface combinations, **73 fall below WCAG AA**, in the band 4.17–4.50, all in light mode, on `acid-canopy`, `arctic-signal`, `blue`, `bronze-neon`, `clay-current`, `copper-field`, `electric-tide`, `faircoin`, `green`, `lagoon`, `lavender`, `malachite-rush`, `midnight-citrus`, `mint`, `olive`, `orange`, `pacific-flare`, `pine`, `plum`, `pumpkin`, `reef-pulse`, `rose`, `saffron-depth`, `sky`, `solar-flux`, `viridian-orbit` and `yellow`. Both solid Button fills pass all 1,280 rows; glass `destructive` is also unaffected (0/640, worst 5.32). The alpha at which the failures reach zero remains 0.89.
+**One measured cost, stated because it is real.** The 15% bleed moves the pane toward the surface under it, which in light mode means lighter — the one direction a white label cannot afford. Of `primary`'s 640 preset × mode × surface combinations, **67 fall below WCAG AA**, in the band 4.21–4.50, all in light mode, on `acid-canopy`, `arctic-signal`, `blue`, `bronze-neon`, `clay-current`, `copper-field`, `electric-tide`, `faircoin`, `green`, `lagoon`, `lavender`, `malachite-rush`, `midnight-citrus`, `mint`, `olive`, `orange`, `pacific-flare`, `pine`, `plum`, `pumpkin`, `reef-pulse`, `rose`, `saffron-depth`, `sky`, `solar-flux`, `viridian-orbit` and `yellow`. Both solid Button fills pass all 1,280 rows; glass `destructive` is also unaffected (0/640, worst 5.32). The earlier low-chroma sweep reached zero failures at alpha 0.89; that historical sweep is retained below. The approved tonal surfaces improve the alpha 0.85 count from 73 to 67; the exact 67 row names are pinned in `tonal-glass-primary-failures.json`.
 
-The 1.0.1 catalog remains exactly 38/340, including the original 18-preset oracle at 30/180. The 30 new three-seed combinations contribute 35/300 and do not lower the existing 4.17 floor. These cohorts are asserted independently, so an unchanged total cannot hide a regression moving from one into the other.
+The 1.0.1 cohort now measures 36/340, including the original 18-preset cohort at 28/180; the 30 additions contribute 31/300. Before the approved tonal surfaces these counts were 38/340, 30/180 and 35/300. The current worst ratio improves from 4.17 to 4.21. These cohorts are asserted independently, so an unchanged total cannot hide a regression moving from one into the other.
 
 If your app runs one of those 27 presets in light mode and needs AA on its primary button, use `variant="inverse"` for that call site, or raise `GLASS_FILL_ALPHA`.
 
 Over a retained black/mid-grey/white media sample, **50 of 384** preset × mode × backdrop rows fall below AA, worst 3.61 (`destructive`: 0). The 1.0.1 catalog remains 25/204; the additions contribute 25/180, worst 4.17. That is a sample rather than a promise about arbitrary pixels. If a CTA must be legible over an image, `variant="inverse"` is opaque and backdrop-independent:
 
 ```tsx
-<Button variant="inverse">Comprar</Button>
+<Button appearance="solid" tone="neutral">Comprar</Button>
 ```
 
 `secondary`, `outline`, `ghost`, `text`, `link` and `icon` are unchanged: they have no fill for the tint to replace.
@@ -66,6 +66,8 @@ node scripts/measure-glass-alpha.mjs --url http://localhost:6006 --image docs/gl
 
 Measured in Chrome off painted pixels, with the label removed from the measurement clones so a white glyph cannot be mistaken for backdrop:
 
+**Historical low-chroma surface sweep:** these measurements predate the approved tonal shell. The current alpha 0.85 primary count is 67/640; the other sweep rows have not been remeasured.
+
 | alpha | backdrop response | blur delta over a photo (max/mean) | blur delta on a flat page | `primary` rows < AA | `destructive` rows < AA |
 | --- | --- | --- | --- | --- | --- |
 | 0.91 | 23.0 | 11 / 2.9 | 1 | 0 / 640 | 0 / 640 |
@@ -124,8 +126,8 @@ Measured over 64 presets × 2 modes × 2 endpoints × 2 platforms (512 rows), wi
 
 | | failures below AA | worst ratio |
 | --- | --- | --- |
-| light | 0 / 256 | **8.23** (over black, web) |
-| dark | 0 / 256 | **6.43** (over white, web) |
+| light | 0 / 256 | **7.84** (`sky`, over black, web) |
+| dark | 0 / 256 | **6.47** (`graphite`, over white, web) |
 
 and the pane still moves **49.98–69.97** of 255 between a black and a white backdrop, so it is glass rather than a tinted slab. Web is the worse of the two platforms in both modes: `expo-blur`'s own tint adds body on native that CSS `backdrop-filter` does not.
 
@@ -141,7 +143,7 @@ Internal (`glass/` is not a published subpath). It is reached through `ButtonGro
 
 ### On a device: tint, and no blur
 
-Measured on a **Pixel 8a** over a hard 10dp stripe pattern, sampling the same rows inside a chrome island and on the bare stripes beside it:
+Historical measurement before the tonal-shell native intensity adjustment below, on a **Pixel 8a** over a hard 10dp stripe pattern, sampling the same rows inside a chrome island and on the bare stripes beside it:
 
 | backdrop stripe | bare | inside the island |
 | --- | --- | --- |
@@ -153,3 +155,23 @@ The backdrop contributes **44 of 255** — the pane is translucent — and the s
 The composite works out at ≈**0.83** opacity against the web pane's 0.72 plus sheen. The difference is `expo-blur`'s own tint — one `intensity` drives it together with the radius and a caller cannot decline it — which is the platform gap `GLASS_BLUR_INTENSITY` documents, appearing exactly where it said it would.
 
 The ramp `PageHeader` draws over the same material was checked for the `stopColor` alpha trap at the same time: **0 achromatic rows of 311** in both modes, so the hue survives the SVG renderer.
+
+### Tonal-shell material verification
+
+The approved chroma28 shell retains the web's 10px blur and fill alpha 0.85. Native
+expo-blur intensity is now 30 instead of 50: its unavoidable neutral tint otherwise
+produced a 6.478/255 painted-channel gap against web on saturated surfaces. The
+new maximum is 3.887/255, inside the unchanged <4 gate and still measurably nonzero.
+This reduces native blur strength; it does not claim equal spatial blur across
+platforms. Sheen, fill opacity and hairline remain unchanged. Device blur behavior
+is subject to the Android topology limitations documented above.
+
+Across 3840 preset/mode/tone/surface combinations, on-fill labels now fail AA in 480
+cases and page-text labels in 2577. The earlier catalog contributes 258 and 1377;
+the additional 30 presets contribute 222 and 1200. Exact equality gates retain these
+measured limitations rather than reducing the AA requirement.
+
+Chrome islands retain zero AA failures over the black/white backdrop endpoints:
+the new light minimum is 7.84 (`sky/light/black/web`), and dark 6.47
+(`graphite/dark/white/web`). Previously pinned floors were 8.23 and 6.43. These
+are measured at unchanged chrome alphas 0.72/0.80 and now pin exact named rows.

package/docs/input-group.mdx

@@ -19,13 +19,13 @@ import { InputGroup, InputGroupAddon } from '@oxy.so/bloom/input-group';
 
 <InputGroup>
   <InputGroupAddon>oxy.so/</InputGroupAddon>
-  <TextFieldInput label="Handle" value={handle} onChangeText={setHandle} />
+  <TextFieldInput label="Handle" value={handle} onValueChange={setHandle} />
 </InputGroup>
 
 <InputGroup>
-  <TextFieldInput label="Search" value={query} onChangeText={setQuery} />
+  <TextFieldInput label="Search" value={query} onValueChange={setQuery} />
   <InputGroupAddon divider>
-    <Button size="small" onPress={run}>Search</Button>
+    <Button size="sm" onPress={run}>Search</Button>
   </InputGroupAddon>
 </InputGroup>
 ```
@@ -35,7 +35,7 @@ import { InputGroup, InputGroupAddon } from '@oxy.so/bloom/input-group';
 | prop        | decides                                                       |
 | ----------- | -------------------------------------------------------------- |
 | `size`      | `sm` 32 · `md` 36 (default) · `lg` 44 — plus a larger rung |
-| `isInvalid` | the error tint on the whole box (and no hover / focus ring)     |
+| `invalid` | the error tint on the whole box (and no hover / focus ring)     |
 | `disabled`  | paints the disabled fill and marks the group `aria-disabled`    |
 | `divider`   | per addon, a rule between it and the input                     |
 | `noPadding` | per addon, for an addon that supplies its own (a button)        |
@@ -44,7 +44,7 @@ import { InputGroup, InputGroupAddon } from '@oxy.so/bloom/input-group';
 
 A `TextFieldInput` (or a `Search`, or any `TextField`) placed in a group renders
 **bare**: it draws no fill or ring of its own, takes no side padding, stretches
-to fill the middle and inherits the group's `size`, `isInvalid` and `disabled`.
+to fill the middle and inherits the group's `size`, `invalid` and `disabled`.
 Before this, the field painted its own shell inside the group's and sized
 itself to the group's full width, pushing a trailing addon out of the clipped
 box.
@@ -56,7 +56,7 @@ in `text-secondary`.
 
 ## Why the state lives on the group
 
-`isInvalid` and `disabled` are properties of the **control**, not of the input
+`invalid` and `disabled` are properties of the **control**, not of the input
 element inside it. Setting them per part is how a box ends up with a red border
 and a normal-coloured button, or an enabled button beside a disabled input.
 

package/docs/input-otp.mdx

@@ -18,10 +18,10 @@ import { InputOtp } from '@oxy.so/bloom/input-otp';
 
 The `InputOtp` look, coloured by Bloom's theme:
 
-- Each box is **48 × 48**, radius 10, a 1px `neutral-200` border (`neutral-700` in dark) on the card surface, with the `shadow-xs` drop shadow.
+- Each box is **48 × 48**, radius 10, a 1px semantic hairline on the shared secondary surface, with the `shadow-xs` drop shadow.
 - Digits are **mono**, 18/26 medium, centred, with tabular numerals, so a row of `1`s and `8`s stays optically even.
 - Boxes sit **8px** apart; `groupEvery={3}` adds **12px** more before each group (`000 000`).
-- **Hover** darkens the border to `neutral-300`. **Focus** paints the border and a 2px ring outside it in the accent (`primary`) — on every focus, since a text input is `:focus-visible` on a click too.
+- **Hover** emphasizes the semantic border. **Focus** paints the border and a 2px ring outside it in the accent (`primary`) — on every focus, since a text input is `:focus-visible` on a click too.
 - **Invalid** gives every box a red border, a red tint and red digits; focus still wins over the red border.
 - **Disabled** dims the fill and the digits and drops the shadow.
 
@@ -47,7 +47,7 @@ Clearing a box removes its digit from the value, so later digits move left.
 | `value?` / `defaultValue?` | `string` | Controlled / initial code. |
 | `onChange?` | `(value: string) => void` | Every change. |
 | `onComplete?` | `(value: string) => void` | Once the last box is filled. |
-| `isInvalid?` | `boolean` | Error paint and `aria-invalid` on every box. |
+| `invalid?` | `boolean` | Error paint and `aria-invalid` on every box. |
 | `isDisabled?` / `disabled?` | `boolean` | Disable every box. |
 | `groupEvery?` | `number` | Gap between groups. |
 | `autoFocus?` | `boolean` | Focus the first box on mount. |

package/docs/label.mdx

@@ -14,7 +14,7 @@ import { Label } from '@oxy.so/bloom/label';
 
 <Label nativeID="workspace-name" required>Workspace name</Label>
 <TextField>
-  <TextFieldInput nativeID="workspace-name" label="Workspace name" value={name} onChangeText={setName} />
+  <TextFieldInput nativeID="workspace-name" label="Workspace name" value={name} onValueChange={setName} />
 </TextField>
 ```
 

package/docs/layout.mdx

@@ -50,21 +50,23 @@ double-counts the home indicator and strands a band of dead space.
 
 ## `useBottomEdgeInset` / `useClaimBottomEdge` — what is already there
 
-Knowing where the edge is does not tell a FAB that a tab bar is already parked
-on it. A surface that parks there **claims** its footprint; a surface that wants
-to avoid it **reads** the total.
+The registry remains a low-level geometry API for independently positioned surfaces.
+A surface **claims** its footprint; another surface can **read** the occupied extent.
+`Fab` no longer reads this registry: it is a static action positioned by `Screen`
+or beside navigation by `BottomBar`.
 
 ```tsx
 // The surface that parks there — a floating tab bar.
 useClaimBottomEdge(gap + barHeight);
 
-// The surface that avoids it — Bloom's Fab does this for you.
+// A custom independently anchored surface that avoids the claimed region.
 const occupied = useBottomEdgeInset();
 <View style={{ position: 'absolute', bottom: windowEdgeGap(insets.bottom) + occupied }} />
 ```
 
-Neither imports the other, so any combination composes: a tab bar with no FAB, a
-FAB with no tab bar, both, or a surface written later.
+Claims remain independent of their readers. For built-in screen composition, use
+`Screen` and `BottomBar`: the owner reserves geometry and renders the FAB as a
+sibling of the navigation capsule, above their shared blur.
 
 `BloomProvider` mounts the registry. Outside one, `useBottomEdgeInset()` returns
 `0` and `useClaimBottomEdge` is a no-op, so a surface stays usable standalone.
@@ -179,10 +181,12 @@ A collapse is **motion**, and motion that must stay locked to a reanimated
 animation has to travel as a shared value on the UI thread. React state is the
 wrong transport for it at any width, so it is not offered here.
 
-The **app** owns that signal. Mention drives its header, its tab bar and its FAB
-from one `SharedValue` through `useAnimatedStyle`, and everything moves together
-because nothing crosses a thread. This registry stays what it is good at:
-**geometry** — where things are, not when they move.
+`Screen` now owns the coordinated signal locally. `useScreen()` exposes
+`collapseProgress`; `AppShell` passes it to `BottomBar.minimizeProgress`, and
+`BottomBar` animates its navigation and action together. Custom chrome reads the
+same shared value. The historical workaround in Mention did this at app level;
+the shared composition now supplies that ownership. The registry still carries
+**geometry**, never animated collapse or a React boolean mirror.
 
 ## Things that are easy to get wrong
 
@@ -192,7 +196,8 @@ strand a reader at twice the height, floating mid-screen.
 
 **A z-index cannot substitute for the offset.** A tab bar host is typically the
 last sibling of the app shell, so it paints over every descendant no matter what
-they claim. The FAB has to be somewhere *else*, not merely on top.
+they claim. A separate anchored action must avoid that band; the current BottomBar instead
+places the action beside navigation in the same host, above their blur.
 
 **A modal surface should not read the registry.** A detached `BottomSheet`
 renders above the tab bar and covers it; offsetting it by a bar it is already