@oxy.so/bloom 3.5.0 → 4.0.0

package/docs/chat-list.mdx

@@ -135,12 +135,20 @@ One list, two affordances:
   row travels with the finger and snaps open past 40% of the pane, closed below;
   while a pane is open, pressing the row closes it rather than opening the chat.
   The gesture fails on vertical travel, so a list scroll never becomes a swipe.
-- **Web** — the same actions appear as icon buttons over the right column on
-  hover and on keyboard focus, because a drag is undiscoverable with a mouse.
+  It is `SwipeRow`, the library's one drag implementation — see
+  [Swipe Row](/docs/swipe-row).
+- **A mouse** — the same actions appear as icon buttons over the right column on
+  hover and on keyboard focus, because a drag is undiscoverable with a pointer.
   They are hidden entirely under `@media (hover: none)`.
 
-`swipeEnabled` defaults to "on wherever the platform is not web"; set it to
-`false` to keep the hover buttons and drop the gesture.
+`swipeEnabled` defaults to `useSwipeAvailable()` — every touch pointer on any
+platform, which includes a web build running on a phone. Set it to `false` to
+keep the hover buttons and drop the gesture, or to `true` to force it.
+
+A swipe is not reachable by keyboard or by a screen reader. On web the hover
+buttons are that second path (they appear on `:focus-within` and are in the tab
+order); on native this family offers none, and a host that needs one should give
+the row a long-press menu of the same actions.
 
 `tone` paints the pane: `accent`, `negative` (delete), or the default neutral.
 

package/docs/chat-screen.mdx

@@ -162,47 +162,53 @@ inside it.
 
 ### Measured contrast
 
-A bubble is an OPAQUE fill, so the wallpaper never gets between a fill and its
-own label — **bubble text contrast is a property of the bubble**, and it does not
-move with the wallpaper. What a wallpaper CAN do is stop a bubble being told
-apart from the page. So the number that matters is the SEPARATION between a
-bubble fill and the worst pixel a variant can paint behind it, and that needs the
-extremes, not an average.
+A bubble is an opaque fill: its label contrast does not move with the
+wallpaper. Wallpaper separation is a different measurement, between that fill
+and the background behind it. **Checking the darkest and lightest endpoints
+of a photograph does not cover all its pixels**: an intermediate pixel can
+have exactly the bubble's luminance.
 
-Measured over 16 presets × light and dark (32 themes), against an incoming bubble
-(the chrome surface) and an outgoing one (accent-500):
+Measured over the 16 named presets × light and dark in
+`ChatBackgroundContrast.test.ts`, against actual incoming `colors.card` and
+outgoing `colors.primary` fills:
 
 | what                                          | worst  | best  |
 | --------------------------------------------- | ------ | ----- |
-| incoming bubble text over its own fill        | 13.82  | —     |
-| outgoing bubble text over its own fill        | 4.55   | —     |
-| date-pill text over the pill                  | 4.71   | —     |
-| bubble ↔ `plain` wallpaper (the baseline)     | 1.07   | 1.11  |
-| bubble ↔ `pattern` wallpaper                  | 1.07   | 1.11  |
-| bubble ↔ `gradient` wallpaper                 | 1.07   | 1.11  |
-| bubble ↔ `image` wallpaper (dimmed)           | 1.12   | 1.24  |
-
-Both text figures clear WCAG AA (the incoming one clears AAA). **No variant
-separates worse than the bare page**, and the dimmed image variant separates
-BETTER than it — that is what the dim is for, not taste. The figures are pinned
-as equalities in `ChatBackgroundContrast.test.ts`, so a recipe change goes red in
-either direction.
-
-Two decisions fall out of the measurement, and both are counter-intuitive:
-
-- **The image dim is toward a mid-light neutral, not toward white.** White
-  dimmed toward white is white, which is the card colour — a white incoming
-  bubble over a bright photo then separated by exactly **1.00**, i.e. not at all.
-  The gate keeps that as a negative control.
-- **The gradient's stops move AWAY from the page, never toward the card**:
-  darker than the page in light, lighter in dark. The first recipe brightened a
-  light page and put its lightest pixel onto the incoming bubble's own colour —
-  16 of 32 themes separated worse than no wallpaper at all.
-
-The floating surfaces (the date pill, the two jump buttons) are deliberately NOT
-in that measurement: their separation reaches 1.00 in the worst case — a dark
-patterned wallpaper IS the pill's own surface colour — which is exactly why every
-one of them carries a 1px hairline. A bubble has no such rule to fall back on.
+| incoming bubble text over its own fill         | 9.47   | —     |
+| outgoing bubble text over its own fill         | 4.55   | —     |
+| date-pill text over the pill                   | 8.84   | —     |
+| bubble ↔ `plain` wallpaper endpoints           | 1.10   | 1.57  |
+| bubble ↔ `pattern` wallpaper endpoints         | 1.10   | 1.57  |
+| bubble ↔ `gradient` wallpaper endpoints        | 1.10   | 1.57  |
+| bubble ↔ `image` wallpaper endpoints (dimmed)   | 1.17   | 1.65  |
+
+Opaque bubble labels clear AA; incoming text clears AAA. Generated pattern and
+gradient endpoints retain at least the bare-page separation. The image case
+has a recorded limitation: `yellow/dark` has poorer endpoint separation than
+the plain page, and **all 16 dark themes have an image luminance interval that
+contains a bubble fill's luminance**. A photograph can therefore produce
+separation **1.00** at an intermediate pixel. The test pins both named sets and
+the endpoint ranges as equalities; it does not assert full-image separation.
+The default dim remains `0.55` light / `0.62` dark, preserving photo visibility.
+Caller-supplied stops, ink, opacity or images need their own visual check.
+
+Historical hazards remain relevant:
+
+- White dimmed toward white stays white: for the monochrome light card this
+  removes the incoming bubble edge completely (**1.00**). The negative control
+  retains that case; the light image dim uses a mid-light neutral instead.
+- The original gradient brightened a light page toward the incoming card;
+  **16 of 32 themes** then separated worse than the page. With the current tonal
+  ladder, dark pattern ink and gradient stops must also move darker, away from
+  the raised card. Reusing the old dark brightening direction reduced separation.
+- Before the tonal ladder and exact-primary migration, measured incoming text
+  was **13.82**, pill text **4.71**, generated endpoints **1.07–1.11**, and image
+  endpoints **1.12–1.24**. The former image-is-safer claim covered endpoints only;
+  it never proved a continuous photograph could not match a bubble.
+
+Floating date and jump controls carry a 1px hairline because wallpaper can
+match their surface. Their old measured separation of **1.00** on a dark
+pattern remains the reason for that border; it is not a bubble-text failure.
 
 ## `ScrollToBottomButton` and `JumpToMentionButton`
 

package/docs/checkbox.mdx

@@ -44,21 +44,21 @@ const [checked, setChecked] = useState(false);
 
 ## Sizes and colour
 
-`size` is `small`, `medium` (default) or `large`. `color` overrides the accent the checked gradient is built from; it defaults to the theme primary, and the mark on top of it resolves to that preset's readable foreground rather than a hardcoded white (a caller `color` falls back to white).
+`size` is `sm`, `md` (default) or `lg`. `tone` selects the shared semantic fill and its paired mark foreground; it defaults to `accent`.
 
 ## What it looks like
 
 Geometry and colours, the latter run through the shared recipe (the `button/shared.ts` ramps).
 
-|         | `small` | `medium` | `large` |
+|         | `sm` | `md` | `lg` |
 | ------- | ------- | -------- | ------- |
 | box     | 14      | 16       | 20      |
 | label   | `body-2-medium` 13/18 | `body-medium` 14/20 | `headline-medium` 16/22 |
 | gap     | 6       | 8        | 8       |
 
-`large` extends the ramp beyond the standard two sizes. The box has a 4px radius. Label and description are set in Inter from the type ramp (`TYPE_SCALE`), not the platform face.
+`lg` extends the ramp beyond the standard two sizes. The box has a 4px radius. Label and description are set in Inter from the type ramp (`TYPE_SCALE`), not the platform face.
 
-- **Unchecked** — the card surface, a 1px neutral-300 border and the `xs` shadow (dark: neutral-800 fill, neutral-700 border). Hover darkens the border one stop.
+- **Unchecked** — the themed card surface, a 1px semantic border and the `xs` shadow.
 - **Checked / mixed** — an accent-500 → accent-600 gradient with an inset white top highlight and an inset 1px accent edge; hover lightens it to 400 → 500. The tick draws itself in over 200ms (skipped under reduced motion); the mixed state is a rounded bar.
 - **Disabled** — the BOX drops to 50% opacity. The label stays at full strength.
 - No press scale. On native, where there is no hover, a held press shows the hover paint.
@@ -103,13 +103,13 @@ in one field is the `multiple` case — see [Field](/docs/field).
 
 ## Touch target
 
-The box is 16dp at the default size, well under what a finger needs. The pressable is grown to 44dp with `hitSlop` — the target grows, the drawing does not — and the slack is derived per size, so `large` does not overshoot into a neighbouring row.
+The box is 16dp at the default size, well under what a finger needs. The pressable is grown to 44dp with `hitSlop` — the target grows, the drawing does not — and the slack is derived per size, so `lg` does not overshoot into a neighbouring row.
 
 For a labelled checkbox the pressable already spans the label, so the whole row is the target.
 
 ## Keyboard focus on web
 
-The pressable takes a `:focus-visible` ring, drawn from the same shared recipe every Bloom control's web CSS is built from. The browser focuses the row — the box AND its label — but the ring is drawn around the BOX whenever that row has keyboard focus — `ring-2 ring-offset-2`: a 2px accent ring outside a 2px **white** offset. The offset is white in dark mode too; that is Tailwind's default `ring-offset-color`, left un-overridden; the row's own outline is suppressed so there is exactly one ring, and it is only ever shown for the focused row.
+The pressable takes a `:focus-visible` ring, drawn from the same shared recipe every Bloom control's web CSS is built from. The browser focuses the row — the box AND its label — but the ring is drawn around the BOX whenever that row has keyboard focus — `ring-2 ring-offset-2`: a 2px accent ring outside a 2px offset matching the scoped page background; the row's own outline is suppressed so there is exactly one ring, and it is only ever shown for the focused row.
 
 `:focus-visible`, not `:focus`: a mouse click never leaves a ring behind.
 

package/docs/chip.mdx

@@ -147,3 +147,7 @@ The `:focus-visible` ring is the accent ramp's 500, the colour every other ring
 ## A pill does not shrink
 
 In a flex row of chips — a filter bar, a tag list — each pill keeps its size and the row overflows, rather than every label squeezing into an ellipsis to make room. Inside one pill, the label yields first: a chip narrower than its own text ellipsises rather than spilling past its radius.
+
+## Compatibility
+
+The shared `size`, `tone` and `appearance` vocabulary coexists with the previously published family props. Explicit shared props take precedence over legacy spellings; existing size and state callbacks remain supported. New code should prefer the shared vocabulary.

package/docs/coherent-system-migration.mdx

@@ -0,0 +1,58 @@
+---
+title: Coherent system migration
+description: Shared component contracts and composition alongside the current APIs.
+order: 2
+---
+
+# Coherent system migration
+
+This integration adds a shared vocabulary while retaining the current Button, field, Chip, Badge and AppShell APIs. The table shows the preferred spellings for new code, not a list of removed props. Explicit shared props win over compatibility presets. Existing AppShell variants, slots and drawer behavior remain supported; passing a navigation model selects the adaptive composition.
+
+| Previous usage | Replacement |
+| --- | --- |
+| `size="small/medium/large"`, duplicate aliases | `size="sm/md/lg"` |
+| Button `variant="primary"` | `appearance="solid" tone="accent"` |
+| Button `variant="secondary"` | `appearance="outline" tone="neutral"` |
+| Button `variant="destructive"` | `appearance="solid" tone="danger"` |
+| Button `variant="ghost"` | `appearance="subtle"` |
+| Button `variant="text/link"` | `appearance="plain"`; add `href` for navigation |
+| `PrimaryButton`, `SecondaryButton`, `GhostButton`, `OutlineButton`, `TextButton`, `DestructiveButton`, `LinkButton` | `Button` with explicit semantic props |
+| `IconButton`, `iconOnly`, `size="icon"` | `Button icon={IconComponent}` with no children |
+| `InverseButton` | Explicit scoped colors or a themed surface; no implicit white control over unknown media |
+| Button `onClick` | `onPress` |
+| Button `aria-label` | `accessibilityLabel` |
+| Button `fullWidth` | `style={{ width: '100%' }}` or layout class |
+| Icon elements in managed icon slots | Icon components; custom nodes go in `leading` / `trailing` |
+| Semantic badge/chip `color` | `tone`; `default → neutral`, `primary → accent`, `error → danger` |
+| Badge/chip `variant` | `appearance`; `outlined → outline` |
+| `isInvalid` | `invalid` |
+| Field `onChangeText` | `onValueChange` |
+| Switch `value/onValueChange` | `checked/onCheckedChange` |
+| Radio/RadioCard `selected/onSelect` | `checked/onValueChange`; selection callback receives the option value |
+| SegmentedControl `onChange` | `onValueChange` |
+| DataTableSearch `onChangeText` | `onValueChange` |
+| Chip / ButtonGroupItem `selected`; FrostedIconButton `active` | `checked`; optionally use `onCheckedChange` for a controlled toggle. `onPress` remains the action callback |
+| Card `variant="elevated/filled/outlined/plain"` | `appearance="solid/subtle/outline/plain"`; `elevation` remains an independent override |
+| FrostedIconButton icon element or `children` alias | `icon={IconComponent}`; size and active-state `tone` inherit from `BloomScope` |
+| Menu item `variant="default/destructive"` | `tone="neutral/danger"` |
+| ButtonGroup / ButtonGroupItem `variant="solid/glass"` | `material="solid/glass"`; the shared island and inherited control surface are preserved |
+| ControlSurface `density="medium/small"` | `density="md/sm"`; item heights remain 34/30 |
+| ThemeToggle `appearance`, `ThemeToggleAppearance` | Structural `variant`, `ThemeToggleVariant` |
+| FAB `placement/offset/zIndex/minimizeBehavior` | Still supported; prefer parent composition with `Screen` / `BottomBar` for new screens |
+| Implicit Expo Router root | Universal `BloomProvider` from the provider subpath; explicit `scrollAdapter` |
+| Sidebar `flat` | `surface="plain"`; choose `surface="card"` for a detached rounded panel or `surface="docked"` for an edge-attached square column |
+| AppShell `drawer`, `drawerOpen`, `onDrawerOpenChange` | `navigationPlacement="auto"` or explicit `bottom` / `rail` / `sidebar`; existing drawer state remains supported |
+| AppShell with an already scrolling list | `scroll="external"`; `VirtualList screen={{ active, restoration }}` |
+| FAB `variant`, numeric `size`, icon element | Still supported alongside `tone` / `appearance` and `size="xs/sm/md/lg"` |
+
+The shared vocabulary is `size: xs|sm|md|lg`, `tone: neutral|accent|support|action|success|warning|danger|info`, and `appearance: solid|subtle|outline|plain`. `BloomScope` inherits size and tone only; component props win. Appearance, interaction state, callbacks and navigation selection stay local. Visual sizes remain family-specific. Do not mechanically apply the control scale to image aspect ratios, chart data, typography roles, or platform-native props such as `ActivityIndicator.size`.
+
+## Navigation
+
+`AppShell` accepts a destination model with `value`, `label`, and `icon`, a selected `value`, and `onValueChange`. `navigationPlacement="auto"` chooses bottom navigation below 768, rail from 768 through 1023, and sidebar from 1024. Breakpoints use the measured shell width. Set `bottom`, `rail`, or `sidebar` to override. `primaryAction` takes Fab props and travels with the navigation. `navigationMaterial` selects `solid` or `translucent`. For a standalone screen, `Screen.primaryAction` takes a React node; when using a BottomBar directly, supply `action={<Fab ... />}`.
+
+AppShell persists around route Screens: routes inherit navigation motion and bottom clearance while keeping independent scroll offsets. A covering modal uses `Screen navigationScope="isolated"`. Use one scroller per content region. `ScreenScrollView` is for normal content; virtualized lists bind to the screen without being wrapped in another scroll view. `Screen active={focused}` or `AppShell active={focused}` disables retained background scroll writers; `headerHeight` / `bottomBarHeight` declare custom initial footprints. Geometry reserves the expanded chrome footprint; the visible collapse runs on shared animated values.
+
+## Verification
+
+Review `Templates/Coherent system` stories **Feed**, **Form**, **Desktop**, and **Surfaces**, plus `Foundations/Screen / Continuous Content` alongside the component stories. Verify narrow/wide containers, both color modes, disabled/loading controls, nested scopes and long lists. The browser verifies DOM and web behavior; native safe areas, keyboard and gestures require an iOS/Android run before release.

package/docs/composer-loader.mdx

@@ -43,7 +43,7 @@ Under reduced motion the band stops (web: `animation: none`; native: no clock),
 |------|------|---------|-------------|
 | `children` | `ReactNode` | — | The composer. |
 | `active?` | `boolean` | `true` | Show the light; fades in/out over 450ms. |
-| `colors?` | `[string, string, string, string]` | `#5eead4 #46baec #e633a4 #00faa7` | Gradient left → right. Any colour string. |
+| `colors?` | `[string, string, string, string]` | Theme primary / support / action foreground roles | Gradient left → right. Any colour string. |
 | `speed?` | `number` | `4.5` | Seconds per lap. |
 | `intensity?` | `number` | `0.7` | Overall light opacity. |
 | `bloom?` | `number` | `16` | How far the bloom bleeds inward, px. `0` drops the layer. |
@@ -60,8 +60,10 @@ Under reduced motion the band stops (web: `animation: none`; native: no clock),
 | `style?` | `StyleProp<ViewStyle>` | — | Outer wrapper. |
 | `testID?` | `string` | — | Also derives `-surface` and `-light`. |
 
-The default colours are an iridescent set, kept literal on purpose: they are the effect's identity, not a theme role. Pass `colors` to tint it to a brand.
+The default colours follow the current preset and mode: `primarySubtleForeground`, `secondarySubtleForeground`, `tertiarySubtleForeground`, then primary again to close the moving band. Both platforms use `resolveComposerLoaderColors(theme)`. Pass `colors` for an explicit override.
 
 ## Accessibility
 
 The surface and the light are decorative (`aria-hidden`, `pointerEvents="none"`); only the children are exposed. Announce the busy state from the composer itself (for example on its send / stop button).
+
+`DEFAULT_COMPOSER_LOADER_COLORS` remains exported as a deprecated legacy rainbow for callers that pass it explicitly via `colors`. It is no longer the component default; prefer `resolveComposerLoaderColors(theme)` for theme-aware values.

package/docs/composer-panel.mdx

@@ -68,7 +68,7 @@ import { ComposerPill, ComposerStatusBar } from '@oxy.so/bloom/composer-panel';
 <ComposerStatusBar branch="Main" folders={folders} mode="Agent" context={57} />
 ```
 
-- **Pill** — 52 tall, full radius, p 8, gap 10, background-primary + shadow-xs. The add disc is a step lighter than the panel's (neutral-100 / dark 700, hovered 200 / 600) and reuses the panel's `AddMenu`. The field is body-regular with an accent-500 caret; its placeholder shortens to `compactPlaceholder` ("Ask me") under 640 wide, and unfocused on web its last 32px fade into the pill.
+- **Pill** — 52 tall, full radius, p 8, gap 10, background-primary + shadow-xs. The add disc follows the tertiary surface (secondary on hover) and reuses the panel's `AddMenu`. The field is body-regular with an primary-subtle-foreground caret; its placeholder shortens to `compactPlaceholder` ("Ask me") under 640 wide, and unfocused on web its last 32px fade into the pill.
 - **Model menu** — a 32-tall trigger (radius 12, py 6 / pr 4 / pl 8) with a turning 18px chevron, opening a 266px panel upward: "Models" radio rows (p 8, radius 10, 14px radio, primary-hover while selected), a full-bleed divider (7 above, 12 below), "Effort *value*" (the value blurs in on change), Faster / Smarter and the six-stop slider. Choosing a model closes it; the slider leaves it open. Omit `models` to hide the button.
 - **Model identity** — `models` takes `{ id, name }` entries, the same contract as `ModelPicker`: the menu keys, matches and reports the **id** and only ever draws the `name`. A bare string is shorthand for `{ id: name, name }`, which is why the old `models={['Fable 5']}` form still behaves exactly as it did — but a routing identifier that is matched by display name is a bug waiting for two models to share a label, so pass ids where you have them.
 - **No effort axis** — `effortLevels={[]}` drops the divider and the whole effort half of the panel. A model with no stops gets the model rows alone, not an empty chip over a slider that cannot commit.
@@ -143,22 +143,21 @@ Everything is controllable and works uncontrolled: `value`/`defaultValue`, `perm
 
 ## Colours
 
-From the theme through `button/shared` ramps:
-
-| Token | light | dark |
-|---|---|---|
-| card, panels, mic | `colors.card` | neutral-800 |
-| hover / selected row | neutral-100 | neutral-700 at 60% over neutral-800 |
-| panel hairline, mic border | neutral-200 | neutral-700 |
-| status tab | neutral-200 | neutral-700 at 50% (translucent) |
-| add button / hover | neutral-200 / 300 | neutral-700 / 600 |
-| tile border | neutral-200 | white at 14% over neutral-800 |
-| rail | neutral-100 | neutral-900 at 50% over neutral-800 |
-| effort chip / hover | neutral-200 / 300 | neutral-800 / 700 |
-| effort track / fill | neutral-100 / 300 | neutral-900 / 700 |
-| secondary / tertiary text | neutral-500 / 400 | neutral-500 / 600 |
-| send | `bg-button-primary` accent gradient; disabled gradient at 40% | same |
-| upload ring / percentage | accent-400 / accent-500 | same |
+The palette reads canonical theme roles in both modes; it does not reconstruct surfaces or text colors from neutral ramp indices.
+
+| Element | Role |
+|---|---|
+| Card, panels, mic | `colors.card` |
+| Hover, secondary surfaces, rail | `colors.backgroundSecondary` |
+| Status tab, add disc, tertiary surfaces | `colors.backgroundTertiary` |
+| Panel/tile hairline | `colors.borderLight` |
+| Thumb border | `colors.border` |
+| Secondary / tertiary text and icons | `colors.textSecondary` / `colors.textTertiary` |
+| Send | Shared Button `solid` / `action` recipe |
+| Upload ring, focus ring | `colors.primary` |
+| Upload percentage, caret | `colors.primarySubtleForeground` |
+
+Provider marks and shadows retain their existing branding and geometry. The action role only promotes Send; ordinary composer controls remain neutral.
 
 ## Motion
 

package/docs/composition.mdx

@@ -18,7 +18,7 @@ Every contract on this page resolves the same way:
 an explicit prop  >  the nearest container  >  the component's own default
 ```
 
-`undefined` is the only value that defers. Passing `variant="solid"` inside a glass island paints a solid control — the container is a default, not an override, and a caller can always win.
+`undefined` is the only value that defers. Passing `material="solid"` inside a glass island paints a solid control — the container is a default, not an override, and a caller can always win.
 
 **A constraint is not a default.** Anything that RESTRICTS a control — `disabled`, a modal's inertness, the user's reduce-transparency or reduce-motion preference — travels on its own channel and combines with `||`, never `??`. The rule above is exactly wrong for those: a descendant must not be able to re-enable an action its group disabled by passing a prop.
 
@@ -33,7 +33,7 @@ What a container tells the controls inside it about presentation, and nothing el
 | field | values | meaning |
 | --- | --- | --- |
 | `material` | `'solid'` \| `'glass'` | the surface a control CONTAINER paints |
-| `density` | `'medium'` \| `'small'` | the size controls default to |
+| `density` | `'md'` \| `'sm'` (also `'medium'` \| `'small'`) | the size controls default to |
 
 ```tsx
 import { ControlSurface } from '@oxy.so/bloom/control-surface';
@@ -47,7 +47,7 @@ It renders no node of its own, so it can be dropped anywhere without moving anyt
 
 A field left `undefined` inherits rather than resetting: `<ControlSurface density="small">` inside a glass island stays glass.
 
-**Who reads it today:** `ButtonGroup` and `ButtonGroupItem` read `material`; `TextField`, `Textarea` and `TimeField` read `density`, and `PhoneInput` gets it by passing its `size` straight to `TextField`. `density` is `'medium' | 'small'`, which is exactly the text-field family's `size` vocabulary — so a filter row can ask for `small` once instead of writing it on five controls:
+**Who reads it today:** `ButtonGroup` and `ButtonGroupItem` read `material`; `TextField`, `Textarea` and `TimeField` read `density`, and `PhoneInput` gets it by passing its `size` straight to `TextField`. `density` accepts `'medium' | 'small'` alongside `'md' | 'sm'`; legacy form sizes retain their public spellings — so a filter row can ask for `small` once instead of writing it on five controls:
 
 ```tsx
 <ControlSurface density="small">
@@ -165,7 +165,7 @@ const onScroll = useAnimatedScrollHandler(
 
 The context carries the `SharedValue`, not a number. It crosses once, at mount; every subsequent frame reaches the chrome on the UI thread through `useAnimatedStyle`, with no React render. A context whose value changed per frame would re-render every consumer per frame, which is the cost this exists to avoid.
 
-`PageHeader` resolves its offset as: the `scrollY` prop, then this context, then `window.scrollY` on web. Without any of the three on native it stays at rest. The context step is the one that matters for a desktop shell, where `window.scrollY` never moves and a header that followed it looked deliberately inert.
+`PageHeader` resolves its offset as: the `scrollY` prop, then the nearest `Screen`, then this context, then `window.scrollY` on web. Without any of the three on native it stays at rest. The context step is the one that matters for a desktop shell, where `window.scrollY` never moves and a header that followed it looked deliberately inert.
 
 ## Edge claims — `TopEdgeProvider` / `BottomEdgeProvider`
 
@@ -173,7 +173,7 @@ The context carries the `SharedValue`, not a number. It crosses once, at mount;
 
 A surface that parks at a window edge CLAIMS its footprint; a surface or a scroll container that must clear it READS the total. Claims combine with `max`, not sum — every claim is measured from the same edge, so two surfaces at that edge overlap rather than stack.
 
-The bottom edge is the tab bar and the FAB (`docs/fab.mdx`). The top edge is chrome that overlays content:
+`BottomBar` coordinates its navigation and lateral FAB footprint (`docs/bottom-bar.mdx`). The top edge is chrome that overlays content:
 
 ```tsx
 <ScrollView contentContainerStyle={{ paddingTop: useTopEdgeInset() }}>

package/docs/contact-card.mdx

@@ -0,0 +1,199 @@
+---
+title: ContactProfileCard
+description: A person or a company in a CRM — identity, the numbers the record is read for, the channels you can reach them through, and the tags — as a card and as a row.
+order: 123
+---
+
+# ContactProfileCard
+
+One component, two densities, two subjects.
+
+```tsx
+import { ContactProfileCard } from '@oxy.so/bloom';
+
+<ContactProfileCard
+  name="Nora Vance"
+  role="Head of Operations"
+  company="Larkspur Freight"
+  status={{ label: 'Customer', tone: 'success' }}
+  channels={[
+    { kind: 'email', onPress: composeEmail },
+    { kind: 'phone', onPress: dial },
+  ]}
+  headline={{ label: 'Open pipeline', value: '€248,000', delta: '+2 deals' }}
+  stats={[
+    { value: '4', label: 'Open deals' },
+    { value: '€62k', label: 'Avg deal' },
+    { value: '6 days', label: 'Last touch' },
+    { value: '3h', label: 'Replies in' },
+  ]}
+  owner={{ name: 'Marta Oyeleye' }}
+  tags={['Enterprise', 'Renewal Q4']}
+  lastTouch="Last contacted 6 days ago"
+  onPress={openRecord}
+/>
+```
+
+## Why it is not called `ContactCard`
+
+`listing-details` already publishes a `ContactCard`: the card a renter uses to
+reach the person LETTING a home. Two families cannot offer one name from two
+declarations — ES modules drop the name from the barrel outright when two star
+exports disagree about it, and bob's CommonJS output resolves it first-wins
+instead, so the two builds of one file would disagree about what `ContactCard`
+is (gate: `barrel-name-collisions.test.ts`).
+
+The two are genuinely different things — an ACTION card for reaching a listing's
+agent, and the RECORD of a customer — so this one is the contact's profile and
+says so. The family directory stays `contact-card`.
+
+## A company is the same card
+
+`kind="company"` does not switch components. It squares the avatar into a
+squircle so a logo reads as a logo, reads `role` as the INDUSTRY, and drops
+`company` — a company has no company. Everything else is the same slot with a
+different fact in it: `stats` carries the headcount and the deal count, `people`
+carries the facepile of who works there, and the owner, the tags and the last
+touch mean exactly what they meant for a person.
+
+That is the whole reason it is a `kind` and not a `CompanyCard`. Two components
+would be the same card plus a fork, and the fork would drift.
+
+## The geometry
+
+It is drawn the way Bloom draws a RECORD — `ai-profile-card` is the register,
+and the `BesideTheReference` story puts the two in one shot at the same width:
+
+| block | what it holds |
+| --- | --- |
+| cover | a band across the top of the card: the caller's image, or an accent wash in `coverTone` |
+| mark | the 72 avatar, hanging half off the band's bottom edge, with the channel actions opposite it |
+| identity | the name at `title-2-medium`, then ONE line — the role and the account — with the status `Badge` beside it |
+| figure | a quiet `body-medium` label over the `headline` number at `title-1-medium`, with a tinted delta `Chip` |
+| tiles | one `stats` tile per number: the value over what it counts |
+| tags | ONE scrolling `ChipRow` — the last touch, the `facts`, the `tags` |
+| footer | the facepile, and the owner as a quiet attribution line |
+
+| | comfortable | compact |
+| --- | --- | --- |
+| surface | a `Card` (`outlined`, `radius-20`) | none — the list owns it |
+| cover | 96 tall | none |
+| mark | 72, overlapping the cover | 36, inside the press target |
+| name | `title-2-medium`, 2 lines | `body-semibold`, 1 line |
+| figure, tiles, chips, facepile, owner | drawn | not drawn |
+| last touch | the first chip in the row | a quiet third line |
+| channels | labelled, beside the mark | glyphs, beside the identity |
+| height | what it needs | at least 64 |
+
+Compact is the ROW, not a small card. It deliberately draws no surface and no
+cover: a list, a settings group or a panel is already painting one, and a row
+with a band across it is a card with the padding taken out — which is not a
+different density, it is a worse card.
+
+### There are no negative margins in the overlap
+
+The cover is absolutely positioned across the top of the card and the content
+block simply starts `CONTACT_COVER_HEIGHT - CONTACT_AVATAR_OVERLAP` down. The
+mark is therefore the first thing in normal flow, it overlaps the band by half
+its own height, and everything under it stacks without an offset. Pulling the
+mark up with a margin would have been one number that every later block had to
+know about.
+
+## The card measures ITSELF
+
+`CONTACT_NARROW_WIDTH` (480) is compared against the card's OWN laid-out width,
+through `useContainerWidth` on the content block — not against the window. The
+same card is 358 wide in a phone column and 900 wide in a record pane, and the
+window cannot tell those apart.
+
+Under it, two things change together: the channel actions drop their labels to
+glyphs, and the tiles stack two by two. They are one threshold rather than two
+because a card too narrow for four tiles is too narrow for three labelled
+buttons beside a 72 mark.
+
+Before the first layout the width is unknown and the labels are ON
+(`contactActionsAreLabelled(null)`). That is the better of the two guesses: an
+unmeasured card is one a caller has not constrained.
+
+## A channel is a labelled CONTROL
+
+Each entry in `channels` is a `Button` — `variant="secondary" size="small"` with
+the kind's glyph and its ACTION word ("Email", "Call", "Meet") — so it carries
+the surface, the border, the hover, the disabled treatment and the focus ring
+every other Bloom action has. Bare icons floating on a card surface are not an
+affordance anywhere else in this library.
+
+**The label and the NAME are different things.** The label is dropped on a
+narrow card; the name never is. Every control is named `"{verb} {label ?? name}"`
+from `CONTACT_CHANNEL` — "Email Nora Vance", "Open the website of Quillon
+Health" — so an `iconOnly` channel is still named, and a caller cannot ship an
+unnamed one by forgetting a prop. Pass `icon` on a channel to change the glyph;
+the KIND still decides the verb and the word.
+
+The control DRAWS at 32, the size a card wants, and is HIT at 44 through
+`CONTACT_CHANNEL_HIT`, the size a thumb needs.
+
+## The press target is the identity block, not the card
+
+`onPress` is bound to the text (and, in a row, the mark with it), never to the
+whole surface; the channels and the `actions` slot sit outside it.
+
+A pressable card wrapping pressable channels is a control inside a control:
+invalid on web, ambiguous on native, and it RENDERS FINE either way — a
+prop-level test sees two correct components. `ContactProfileCard.test.tsx`
+asserts the containment instead.
+
+## The numbers come before the labels
+
+`headline` and `stats` are the shape of the card; the chips are what is left
+over. That order is the claim the card makes, and the suite asserts it by
+document position rather than by looking at the styles — a record is read for
+its figures.
+
+A tile is the value over what it counts, on the next fill UP from the card
+(`surfaceFillOn`), with its own text rungs read off that tile — `neutral-100` is
+right on white and invisible on a dark card, which is why nothing here names a
+ramp stop.
+
+**`stat-cards` could not express this tile.** `StatCard` is a 132-tall KPI card
+with a mandatory icon tile and a mandatory delta chip, and `StatCards` picks its
+column count from the WINDOW width, so four of them inside a 420-wide record
+card is not a layout that exists. The tile here is `ai-profile-card`'s — value
+over label, a rounded inset panel — on Bloom's radius scale rather than that
+card's raw 10. If the two are ever unified, this is the tile to lift.
+
+## The chips are ONE line
+
+The last touch, the `facts` and the `tags` are one `ChipRow`, which SCROLLS
+rather than wrapping. A wrapping wall of pills is what the tiles replaced; the
+leftovers of a record take one line, or they take the card over.
+
+`lastTouchTone` is the one exception to the outline: with a tone the last-touch
+chip turns `subtle` in that tone, because "41 days ago" IS a state and the card
+is being asked to say so. Everything else is `variant="outlined"` — a neutral
+FILLED pill reads as a disabled control.
+
+This card never edits a tag: the INPUT is `tag-field`, a family of its own.
+
+## The leading mark is neutral
+
+`Avatar` derives a pastel tint from the name unless it is told otherwise, which
+is right in a people LIST — the colour is what tells two rows apart — and wrong
+on a record card, where the subject is already named and the tint reads as a
+status nobody set. So the mark is `color="neutral"`.
+
+The facepile under a company keeps its tints (`showInitials`): four colleagues
+with no photo would otherwise be four identical grey discs, which is the case
+the tint exists for.
+
+## Colour
+
+Every colour is read off the fill the content actually lands on, through
+`styles/surface-levels.ts`: the card resolves against `theme.colors.card`, the
+compact row against whatever `useSurfaceFill()` reports, and a tile against the
+step above whichever of those it is. The cover wash and the delta pill come from
+`resolveAccentColors` — the tone's PAIR, never the fill colour with an alpha
+appended to it, which is the failure `docs/badge.mdx` describes.
+
+The comfortable card publishes its own fill with `SurfaceLevelProvider`, so
+anything nested inside it steps off the card rather than off the page.

package/docs/context-menu.mdx

@@ -35,7 +35,7 @@ import {
     </ContextMenuItem>
     <ContextMenuItem onPress={() => save(photo)}>Save to library</ContextMenuItem>
     <ContextMenuSeparator />
-    <ContextMenuItem variant="destructive" onPress={() => remove(photo)}>
+    <ContextMenuItem tone="danger" onPress={() => remove(photo)}>
       Delete
     </ContextMenuItem>
   </ContextMenuContent>

package/docs/data-table.mdx

@@ -97,7 +97,7 @@ With `inset`, give columns `flex` shares (`flex: 1.4` for the first, `1` for the
 
 ## `DataTableRowAction`
 
-A small icon button under a 200ms `md` tooltip: Bloom's secondary `Button`, 32×32 with a 16px glyph — a full pill, per Bloom's radius rule. `label` is both its accessible name and the tooltip's text; `accessibilityLabel` overrides the name (e.g. "More actions for John Clarkson" with the tooltip "More actions"). `active` paints the pressed state while a menu it opened is showing. It forwards the props an anchored family's `asChild` trigger merges in, so it is the trigger of a row's `DropdownMenu`:
+A small icon button under a 200ms `md` tooltip: Bloom's plain neutral `Button`, 32×32 with a 16px glyph — a full pill, per Bloom's radius rule. `label` is both its accessible name and the tooltip's text; `accessibilityLabel` overrides the name (e.g. "More actions for John Clarkson" with the tooltip "More actions"). `active` paints the pressed state while a menu it opened is showing. It forwards the props an anchored family's `asChild` trigger merges in, so it is the trigger of a row's `DropdownMenu`:
 
 ```tsx
 <DropdownMenu open={open} onOpenChange={setOpen}>
@@ -126,7 +126,7 @@ import {
 toolbar={<>
   <DataTableFilter label="Filter by region" value={region} onValueChange={setRegion}
     options={[{ value: 'all', label: 'All regions' }, …]} />
-  <DataTableSearch label="Search customers" value={query} onChangeText={setQuery} />
+  <DataTableSearch label="Search customers" value={query} onValueChange={setQuery} />
 </>}
 
 { id: 'purchase', header: 'Purchase', cell: ({ row, size }) => (

package/docs/date-picker.mdx

@@ -23,7 +23,7 @@ const [time, setTime] = useState<string | null>('18:30');
 
 ## Pickers
 
-A secondary `Button` trigger (calendar icon + value, 38 tall, full pill) opens Bloom's `Popover`: on web an anchored panel 4px below the trigger, aligned to its end, radius 24, `background-secondary-default`, `shadow-dropdown`; on native a bottom sheet.
+An outlined neutral `Button` trigger (calendar icon + value, 38 tall, full pill) opens Bloom's `Popover`: on web an anchored panel 4px below the trigger, aligned to its end, radius 24, `background-secondary-default`, `shadow-dropdown`; on native a bottom sheet.
 
 The choice is **pending until Apply**. Pressing days or presets, or typing in the `DD/MM/YYYY` chips, only moves the pending value; Cancel restores the committed one, and every open starts again from it. `onChange` fires on Apply.