@oxy.so/bloom 3.6.0 → 4.0.0

package/docs/note-card.mdx

@@ -0,0 +1,131 @@
+---
+title: NoteCard
+description: One note as a preview — two densities, a tinted wash, a checklist body and the bulk-selection state a notes app lives in.
+order: 106
+---
+
+# NoteCard
+
+A note, previewed. It is the cell of a board, the row of a list, and the thing a
+bulk action is applied to — one component, because those are the same note.
+
+```tsx
+import { NoteCard } from '@oxy.so/bloom';
+
+<NoteCard
+  title="Harbour walk — what to bring"
+  excerpt="Slack water is at 06:40, which gives us about forty minutes…"
+  tags={['field notes', 'tide']}
+  meta={{ edited: '2 min ago', notebook: 'Field notes', attachments: 2 }}
+  pinned
+  onPress={open}
+/>
+```
+
+## The two densities are one component
+
+|  | `grid` | `row` |
+| --- | --- | --- |
+| padding | 16 | 12 |
+| radius | `radius-12` | `radius-8` |
+| title | 2 lines | 1 line |
+| excerpt | 4 lines | 1 line |
+| checklist preview | 4 items | 2 items |
+| tags | their own row | folded into the metadata line |
+| metadata | last line | inline after the excerpt |
+| min height | — | 72 |
+
+`grid` is the board: a masonry cell where the body is what you are scanning.
+`row` is the list: the title is what you are scanning and everything else is a
+trail after it.
+
+They are a `density` prop rather than two components on purpose. Everything but
+the arrangement — which fields are drawn, how the tone is composited, what
+selection means — is the same decision, and two components is where two answers
+to one of those grow.
+
+## Selection is two different things, so it has two spellings
+
+`selected` on its own means **this is the note you are reading**: the card takes
+the tone's edge and announces `aria-current`. The reader did not choose it out of
+a set; they are at it.
+
+`selectable` turns the list into **bulk selection**: the card IS a checkbox —
+`role="checkbox"`, both spellings of `checked`, a box in the leading slot, and a
+press toggles instead of opening. `onPress` is not called while `selectable` is
+set, which is the whole point of the mode.
+
+**A card with no handler and no `selectable` is not a control at all** — it
+renders as a plain `View` with the composed name and no role. A `Pressable` with
+its handlers left off still lands in the tab order and still announces "button",
+and neither is true of the thing on screen.
+
+The box in the leading slot is `checkbox/shared`'s own `CheckboxGlyph`, hidden
+from assistive technology and non-interactive: the CARD carries the role and the
+press, so the box is the drawing of that state rather than a second control to
+tab to.
+
+## A checklist note previews as a checklist
+
+Pass `checklist` and it replaces `excerpt`. Flattened into text, a checklist
+reads as a paragraph of fragments — "Finish part two Borrow the essays Return the
+overdue ones" — which is worse than no preview.
+
+The rows are read-only. Each announces its own state (`role="checkbox"`,
+`aria-checked`, `aria-disabled`) and is named by its text, because a tick with no
+name is a decoration. `checklistTotal` is what the "+N more" line counts against,
+so a card can be handed the first four items of nine.
+
+## The tone is composited, never appended
+
+`tone` is one of Bloom's accent tones and there is no hex here on purpose: a note
+colour picked by eye is the one that disappears in dark mode.
+
+The mechanism is the part worth knowing. `resolveAccentColors(colors, tone,
+'subtle')` returns a **translucent** tint (`rgba(…, 0.13)` light, `0.24` dark).
+Measuring a quiet text rung against that string reads the channels and ignores
+the alpha, so the contrast you compute is not the contrast the reader gets. So
+`shared.ts` flattens the tint over the surface the card actually landed on
+(`useSurfaceFill()`), and every rung — title, excerpt, metadata — is measured
+against the **composite**. `resolveNoteCardPaint` is pure, so the suite walks it
+over both modes.
+
+The same trap catches the TAG PILLS one component down, which is why
+`noteTagVariant()` exists: the neutral tone's tint IS `contrast50`, the colour a
+`tone="default"` card already painted, so a `subtle` pill on one is a label
+floating on nothing at contrast 1.00. Those pills are drawn `outlined` instead —
+the edge does what the fill cannot.
+
+The same flattening does selection: the selected card is its own tone laid on
+once more, which is why selection reads on a tinted card and on an untinted one
+with one rule rather than two.
+
+## What it owns, and what it does not
+
+**Owns:** its geometry, its wash, which quiet rung each line sits at, the
+composed accessible name, and the fact that a press in selection mode toggles.
+
+**Does not own:** the layout of the board (give the cell a width — `grid` fills
+it), the relative-time vocabulary (`meta.edited` is drawn as given), what a
+notebook is, or whether a locked note's excerpt should be hidden. That last one
+is the app's: `meta.locked` draws the marker and hides nothing, because Bloom
+cannot know whether the excerpt it was handed is already redacted.
+
+**The notebook TREE is not here either.** It already exists as `Sidebar`'s `tree`
+prop and `SidebarFolder`; a second one would be a second answer.
+
+## Traps
+
+- **A 2px selected border must not move the content.** It does not: the padding
+  gives the pixel back. If you restyle the card, keep that — a border that grows
+  the box reflows the whole board on selection.
+- **`tone` and `selected` compose.** A selected `error` note keeps its own edge
+  colour and deepens by one surface step rather than by the tone laid twice —
+  laying an OPAQUE tint over itself is a no-op, which is exactly what `default`
+  did. Check both in dark mode if you add a tone.
+- **The card publishes its surface.** Anything you put inside it through a
+  slot will step off the card's real fill, tint included, because the card mounts
+  `SurfaceLevelProvider` with the composited colour.
+- **`loading` renders `NoteCardSkeleton`**, which is also exported on its own —
+  a list that knows it is fetching ten notes should render ten skeletons rather
+  than construct ten empty note objects to satisfy a required `title`.

package/docs/note-editor.mdx

@@ -0,0 +1,115 @@
+---
+title: NoteEditor
+description: The chrome around a writing surface — the title and its quiet state line, and a formatting row that collapses into a menu.
+order: 107
+---
+
+# NoteEditor
+
+Everything around the writing surface, and nothing of the writing surface
+itself. Bloom does not ship a rich-text engine and this family does not pretend
+to: the editable node is the app's — a `Textarea`, a web contenteditable, a
+native rich-text view — and these two components are the chrome it sits between.
+
+```tsx
+import { NoteEditorHeader, NoteEditorToolbar, Textarea } from '@oxy.so/bloom';
+
+<NoteEditorHeader
+  title={title}
+  onTitleChange={setTitle}
+  saveState="saved"
+  edited="Edited 2 min ago"
+  wordCount={words}
+/>
+<NoteEditorToolbar actions={actions} accessibilityLabel="Formatting" />
+<Textarea label="Note body" value={body} onChangeText={setBody} rows={10} />
+```
+
+## NoteEditorHeader
+
+|  |  |
+| --- | --- |
+| title | `title-1-semibold` (24/34), borderless, multiline |
+| status line | `caption-1-regular`, 6px under the title |
+| separator | a middle dot between readings |
+
+**The title is not a `TextField`.** A form field is a box you fill in; a document
+title *is* the document. So it draws no chrome at all — no border, no fill, no
+inset — and the caret is the only thing that says it is editable. Bloom has no
+borderless large input for this, which is why the `TextInput` is written out in
+the component rather than composed.
+
+**The status line is three readings, not one string.** Save state, last edit,
+word count: each is drawn only if the app passed it, so a header with nothing to
+say about saving is one line shorter rather than one empty line taller.
+
+`saveState` has four values and two of them are the same colour as the rest of
+the line (`saved`, `saving` — a document doing what it is supposed to should not
+shout). `offline` and `error` take the tone's **text** member, via
+`resolveAccentColors(…, 'outlined').foreground` — never the fill token, which is
+sized to carry white and measures 3.6:1 as a label in dark mode. They are two
+states rather than one because they ask for different things: *keep typing* and
+*stop and look*.
+
+`disabled` dims the title; `readOnly` does not. Nothing is broken about a
+published or shared note, so it is not drawn as if it were.
+
+## NoteEditorToolbar
+
+One `ButtonGroup` of icon-only items, and — the moment they stop fitting — a `…`
+item **fused onto the end of the same group** that opens the rest as a
+`DropdownMenu`. The overflow is not a second control beside the row; it is the
+row's last item, so the toolbar stays one object at every width.
+
+**It measures itself, not the window.** `useContainerWidth` on the row, so a
+toolbar in a 420px side panel of a 1440px desktop collapses exactly as it does on
+a phone. A window-width breakpoint leaves that panel overflowing with no error.
+
+The arithmetic is `toolbarCapacity(width, size)`, exported and pure: a solid
+`ButtonGroup` is `1px border + n items + (n-1) hairlines + 1px border`, so every
+item after the first costs `item + 1`. `splitToolbarActions` then applies the two
+rules that are the whole design:
+
+- **`alwaysVisible` never collapses.** Pinned actions are drawn first and are
+  never candidates for the menu, so a toolbar whose author pinned six of them at
+  360px overflows rather than quietly hiding one. It cannot collapse what it was
+  told to keep, and pretending otherwise is worse than the overflow.
+- **The overflow button costs a slot.** As soon as anything moves to the menu,
+  one item's width goes to the `…`, so the remaining actions are measured against
+  a capacity one lower. Forgetting this is how an adaptive row ends up exactly
+  one item too wide at the width where it starts collapsing.
+
+**The first frame is un-measured and draws everything inline** — one frame, and
+the row clips rather than pushing the page. The alternative (start collapsed,
+expand) flashes a menu button on every desktop mount, which is the more visible
+wrong. `splitToolbarActions(actions, null)` is that state, spelled out.
+
+### A toggle is `active`; an action is not
+
+Setting `active` — even to `false` — makes an action a **toggle**: the item
+announces both spellings of pressed (web reads only `aria-pressed`, native only
+`accessibilityState`), and its overflow row becomes a checkable one. Leaving
+`active` undefined keeps a one-shot action (attach, link) a plain button and a
+plain menu row.
+
+## What neither of them does
+
+**Sticky.** Neither component reads scroll, and a header that measured it itself
+would follow the wrong scroller in a split view with no error. The app owns the
+sticky behaviour, and chrome that follows a scroller does it through
+`ScrollOffsetProvider` — see [Composition](/docs/composition).
+
+**Formatting.** `onPress` runs whatever the app's editor does. This family knows
+the label, the glyph and whether the state is on.
+
+## Traps
+
+- **Toolbar items are 34px tall (`medium`) or 30 (`small`)**, which is below the
+  44 a touch target wants. That is `ButtonGroup`'s scale, not this family's;
+  `hitSlop` is not the answer for adjacent items, because slop on one overlaps
+  its neighbour and the press lands on whichever the platform hit-tests first.
+- **`ButtonGroupItem` writes `aria-pressed` on every item**, including one with
+  no `active`. A non-toggle in the row therefore announces "not pressed". It is
+  the base layer's spelling and this family does not work around it.
+- **`accessibilityLabel` on the toolbar is required in substance.** A row of
+  glyphs has no name of its own, and each item is named by its `label`.

package/docs/notification.mdx

@@ -39,30 +39,26 @@ import { Notification } from '@oxy.so/bloom/notification';
 
 | Part | Value |
 |---|---|
-| card | radius 16, 1px border/button/default, card surface (dark `neutral-800`), `shadow-dropdown`, padding 16 / right 44, gap 12 |
+| card | radius 16, 1px border/button/default, canonical `card` surface in both modes, `shadow-dropdown`, padding 16 / right 44, gap 12 |
 | visual | 40px full-round disc, 20px Remix fill glyph — or a 40px `Avatar` with a 12px presence dot (2px card-coloured ring) |
 | header | wraps; title body-medium text/primary, timestamp body-regular text/tertiary, gap 8 × 2 |
 | description | body-regular text/secondary; content column gap 4 |
-| actions | margin-top 6, gap 8, `Button size="small"` — first `secondary`, the rest `primary` unless `variant` is set |
+| actions | margin-top 6, gap 8, `Button size="sm"` — first `appearance="subtle" tone="neutral"`, the rest `appearance="solid" tone="accent"`, unless action props override them |
 | close | `CloseButton` xs (20px disc) at top 12 / right 12 |
-| countdown | 3px accent-600 bar along the bottom edge, shrinking linearly over `autoDismissDuration` |
+| countdown | 3px primary-colour bar along the bottom edge, shrinking linearly over `autoDismissDuration` |
 
 Buttons are full pills (Bloom's rule for button-like controls); everything else
 keeps the radii listed above.
 
 ## Status colours
 
-| `status` | disc | glyph |
-|---|---|---|
-| `neutral` (default) | background/tertiary | text/secondary, `RiNotification3Fill` |
-| `information` | `info` 100 / dark 800 @ 50% | `info` 600 / dark 300, `RiInformationFill` |
-| `success` | `success` ramp, same stops | `RiCheckboxCircleFill` |
-| `warning` (Bloom addition) | `warning` ramp, same stops | `RiAlertFill` |
-| `error` | `error` on the red ramp, same stops | `RiErrorWarningFill` |
-
-Hues are Bloom's STATUS roles through the shared ramp recipe (`button/shared.ts`),
-never a brand pair. Presence: `online` success-500, `busy` error-500, `offline`
-neutral-400 (dark 600).
+Status discs use the canonical subtle/foreground pairs through
+`resolveAccentColors`: information → info, success → success, warning → warning,
+error → error. Neutral uses the muted surface/text pair. These retain status
+meaning independently of the identity and action colours.
+
+Presence reads success for online, error for busy, and tertiary text for offline.
+The card, description and timestamp use the shared card and text roles.
 
 ## Props
 

package/docs/order-status.mdx

@@ -0,0 +1,125 @@
+---
+title: Order status
+description: Where a thing that moves through named steps is now — one timeline with a vertical and a horizontal orientation, and the compact live strip that carries the current status, an ETA and a progress measurement.
+order: 130
+---
+
+# Order status
+
+A parcel goes "picked up → in transit → out for delivery → delivered". A food order goes
+"accepted → cooking → on the way → delivered". A booking goes "requested → confirmed →
+under way → finished". Those are the same four props with different words, so they are
+one component, and nothing in its API is about parcels or food.
+
+```tsx
+import { OrderStatusBar, OrderStatusTimeline } from '@oxy.so/bloom/order-status';
+
+<OrderStatusTimeline
+  accessibilityLabel="Delivery status"
+  steps={[
+    { label: 'Picked up', timestamp: 'Mon 09:12', state: 'done' },
+    { label: 'In transit', timestamp: 'Mon 14:40', state: 'done', note: 'Left the sorting hub' },
+    { label: 'Out for delivery', timestamp: 'Today 08:05', state: 'current' },
+    { label: 'Delivered', state: 'upcoming' },
+  ]}
+/>
+
+<OrderStatusBar
+  status="Out for delivery"
+  eta="Arrives 14:35"
+  detail="Four stops away"
+  icon={RiCarLine}
+  progress={{ value: 3, max: 4, accessibilityLabel: 'Delivery progress', valueText: '3 of 4 stops' }}
+  action={<GlyphButton icon={RiPhoneLine} accessibilityLabel="Call the courier" onPress={call} />}
+/>
+```
+
+## A pipeline, not a log
+
+`OrderStatusTimeline` draws a PIPELINE: a fixed set of named steps, at most one of which
+is current, with everything before it done and everything after it upcoming. That is a
+different thing from a HISTORY of events, which is what `TenancyTimeline` and
+`EvictionTimeline` draw — an open-ended list of things that happened, each with a date
+and a source.
+
+The distinction is worth knowing because it decides what the component can offer. A
+pipeline's steps are knowable in advance, so the whole journey fits on one rail and a
+horizontal orientation means something; a log's are not, so it can only ever stack. And a
+pipeline can STOP, which is the `failed` state — a log has nothing to say about that,
+because an event that happened cannot un-happen.
+
+If what you have is a history rather than a pipeline, reach for `TenancyTimeline`. The
+geometry of the vertical orientation here is deliberately the same as that one's, so the
+two sit on a screen together without a seam.
+
+## One component, two orientations
+
+`orientation` is a prop rather than a second component because the DATA does not change
+across the switch: the same array, the same keys, the same announced tree, the same
+words. A screen that switches at a breakpoint therefore switches a string, not a
+component, and cannot lose state or drift into two half-maintained call sites.
+
+What the orientation does change:
+
+| | vertical | horizontal |
+| --- | --- | --- |
+| reading order | top to bottom | left to right |
+| `note` | drawn | **not drawn** |
+| label | body rung, one column | caption rung, centred, at most two lines |
+| width | fills its parent | each step takes an equal share |
+
+**`note` is the deliberate omission.** A rail gives each step one column's width; a
+sentence in it either clips or sets the whole rail's height from its longest entry. If
+the note matters at that breakpoint, the screen wants the vertical orientation, not a
+wider rail.
+
+Keep the labels short for the same reason. A label that wraps to two lines pushes its own
+timestamp down while its neighbours' stay up, so a rail of mixed-length labels has a
+ragged bottom edge. Two words per step is the shape this rail is drawn for.
+
+## What the marker says, and what it cannot say
+
+At `comfortable` density every marker is a 24 disc, and the four states are told apart by
+SHAPE as well as colour: `done` carries a check, `current` carries the step's own glyph
+(or nothing) inside a tinted halo, `upcoming` is a hollow ring, `failed` carries a cross.
+
+At `compact` the marker is an 8 dot and there is no room for a glyph. At that rung the
+state travels as colour plus the announced word and nothing else — so **compact is the
+wrong density for a screen where the failure is the point.**
+
+The rail between two steps fills when the LATER one is `done`, `current` or `failed`, in
+that step's own tone. The rail therefore reads as "how far it got", which is the same
+sentence in both orientations.
+
+## Accessibility
+
+The timeline is a `list` of `listitem`s. Each marker is an `img` named by its state, so a
+reader hears "Done, Picked up, 14:20" — the state first, then what it belongs to. Colour
+alone never carries the state.
+
+`OrderStatusBar`'s progress goes through `Meter`, which means it is a real `progressbar`
+with `aria-valuenow`/`min`/`max` and a required name. Give `valueText` a reading a person
+would say ("3 of 4 stops"); without it a bar at 3 of 4 is announced as "75%".
+
+## What it refuses to do
+
+**It never reads a clock and never formats a date.** `timestamp` and `eta` are strings
+the app produced. A component that formatted them would have to own a locale, a time
+zone and a "2 minutes ago" refresh loop for three different apps, and would get at least
+one of the three wrong.
+
+**It never computes the progress.** `progress.value` is a measurement the app made —
+stops completed, minutes elapsed, metres covered. The component does not infer one from
+the steps, because "how far along" is not the same question as "which step is current"
+and only the app knows which one its bar is answering.
+
+## Where it sits
+
+`OrderStatusBar` paints a surface one rung above whatever it was dropped on, with a
+hairline and a 16 radius, and publishes that surface so anything inside it steps off the
+right parent. Inside a card that already paints — a checkout summary, a detail panel —
+pass `variant="plain"` and it draws the content and no chrome.
+
+`OrderStatusTimeline` paints nothing. It reads the ambient surface for its text rungs and
+its connector, so the same timeline is legible on a page, in a card and in a sheet
+without being told which it is.

package/docs/outline-nav.mdx

@@ -0,0 +1,85 @@
+---
+title: OutlineNav
+description: A document's table of contents — a real nested list, aria-current on the heading the reader is at, and a compact form that drops levels rather than squeezing them.
+order: 109
+---
+
+# OutlineNav
+
+The document's own table of contents: the headings, nested, with the one the
+reader is at marked and a bar saying how far through they are.
+
+```tsx
+import { OutlineNav } from '@oxy.so/bloom';
+
+<OutlineNav
+  headings={headings}
+  activeId={active}
+  onSelect={(heading) => scrollTo(heading.id)}
+/>
+```
+
+## Geometry
+
+|  | `full` | `compact` |
+| --- | --- | --- |
+| row height | 36 | 44 |
+| title | drawn | none |
+| progress bar | `Meter`, 4 | `Meter`, 3 |
+| levels | all | down to `compactMaxLevel` (default 2) |
+| indent | 14 per level | 14 per level, of the levels it draws |
+| rail | 2px down the left of every row, painted only on the current one |
+
+`compact` **drops** the deep levels rather than squeezing them. Below level two,
+an indent on a 360px screen is a few pixels nobody reads, so the honest compact
+form is a shorter list of full-width rows at a touch size — not the same list
+with the indent scaled down.
+
+## It is a real list
+
+`role="list"` with `role="listitem"` children, one list **nested inside another**
+for each level. A screen reader then announces "list, 3 items… list, 2 items" and
+the reader knows the shape of the document. A flat list of rows with a left
+padding looks identical and says nothing — which is exactly why this is the part
+worth a gate rather than a glance.
+
+The indent is carried by the nested list, not by a per-row padding, so the indent
+and the structure are the same fact and cannot disagree.
+
+**The tree is built from the order, not from the arithmetic.** Real documents
+skip levels (1, 3, 3 is ordinary), so a heading's parent is the nearest preceding
+heading with a *smaller* level. A document that opens at level 3 and only later
+has a level 1 gets two roots, in order, rather than a lost subtree.
+`buildOutlineTree` is exported and pure.
+
+## `aria-current`, not `aria-selected`
+
+The reader is **at** the current heading; they did not choose it out of a set. So
+it is `aria-current="location"` on web, with `accessibilityState.selected` for
+native, and the row takes the tone's colour and the painted rail.
+
+## This component does not jump
+
+`onSelect` emits the heading and the **app** scrolls. A table of contents that
+scrolled something itself would have to guess which scroller, and in a split view
+it would guess wrong with no error — see [Composition](/docs/composition) §Scroll
+ownership.
+
+The same reasoning applies to `progress`: without it, progress is derived from
+`activeId`'s position in the list, which is right for a jump list and wrong for a
+continuous scroll. A screen that measures scroll passes its own value.
+`outlineProgress` puts the **first** heading at `1/n` rather than 0 — a reader who
+has reached the first heading has read something — and an empty outline at 0,
+which is the honest answer rather than a guess.
+
+## Traps
+
+- **The progress bar is a `Meter`**, so it is a real `progressbar` with a name
+  and a `valueText` ("Heading 4 of 10"). Never hand-roll the bar; `hideProgress`
+  is there for a screen that has its own.
+- **Headings truncate to one line.** A TOC that wrapped would reflow every time
+  the active row changed weight.
+- **`compactMaxLevel` is about the COMPACT form only.** `full` always draws
+  everything; if you want a shortened full outline, shorten `headings`.
+- **Row heights are 36 in `full`** because it is the pointer variant of a side
+  column. On a touch screen use `compact`, which is 44.

package/docs/page-header.mdx

@@ -53,7 +53,7 @@ actions={
       <ButtonGroupItem iconOnly leadingIcon={RiSearchLine} accessibilityLabel="Search" />
       <ButtonGroupItem iconOnly leadingIcon={RiShare2Line} accessibilityLabel="Share" />
     </ButtonGroup>
-    <Button variant="primary" size="medium">Save</Button>
+    <Button appearance="solid" tone="accent" size="md">Save</Button>
   </>
 }
 ```
@@ -95,7 +95,7 @@ Leaving both at their defaults over a hero photo is the one combination that rea
 | `scrimColor` | `theme.colors.background` | The opaque colour the edge effect fades from. Pass it when the screen paints a background the theme does not know about. |
 | `border` | `'auto'` | `presentation="bar"` only. `auto` fades the separator in with scroll; `always`; `none`. |
 | `transparent` | `false` | `presentation="bar"` only: background and shadow fade in with scroll. It no longer hides the title. |
-| `scrollY` | — | A Reanimated `SharedValue<number>`. Omitted, the header reads `ScrollOffsetProvider`, then `window.scrollY` on web. |
+| `scrollY` | — | A Reanimated `SharedValue<number>`. Omitted, the header reads its `Screen` offset, then `ScrollOffsetProvider`, then `window.scrollY` on web. |
 | `scrollThreshold` | `20` | The offset over which the scroll-linked paint arrives. Over a hero, use the hero height minus the bar. |
 | `sticky` | `true` | Web, `placement="inline"`: `position: sticky; top: 0`. No effect on native or on an overlay. |
 | `safeArea` | native `true`, web `false` | Pads the top by the safe-area inset (read from `SafeAreaInsetsContext`; no provider → 0). |
@@ -141,8 +141,9 @@ Apply the safe area **once**: the header pads itself by `insets.top` on native,
 Everything scroll-linked interpolates over `[0, scrollThreshold]` of the resolved offset. The header resolves it in this order:
 
 1. the `scrollY` prop,
-2. the nearest `ScrollOffsetProvider` (`@oxy.so/bloom/layout`),
-3. `window.scrollY` — **web only**.
+2. the enclosing `Screen` offset,
+3. the nearest `ScrollOffsetProvider` (`@oxy.so/bloom/layout`),
+4. `window.scrollY` — **web only**.
 
 On native with none of the three, the header stays at rest.
 
@@ -215,52 +216,7 @@ And the island fill in light mode is the card fill over a near-white page — th
 
 ![The islands over a photograph, title held back](./page-header-islands-photo.png)
 
-### Android, on a device
-
-Run on a **Pixel 8a** (Android, `akita`) through Expo Go SDK 56, against the
-**published** `@oxy.so/bloom@3.0.0` from npm rather than a local build — which is
-what makes it a consumer's result rather than a rehearsal of one.
-
-| property | result |
-| --- | --- |
-| the edge ramp, light | rgb(231,224,231) → rgb(29,59,83), travelled **202** of 255 |
-| the edge ramp, dark | rgb(18,17,22) → rgb(29,59,83), travelled **61** of 255 |
-| no horizontal cut | largest single-row step **1**, monotonic, in both modes |
-| the ramp is CHROMATIC | **0 achromatic rows of 311**, in both modes |
-| a matched `scrimColor` | travelled **1** over its own page colour |
-| the island is translucent | the back capsule reads 244 over the page, **215** over a photograph |
-| the island does NOT blur | see below |
-
-The third row is the one worth having. `react-native-svg` reads `stopColor` for
-its RGB and **discards any alpha inside it**, which once painted an Android pane
-as a white-to-black wipe with R=G=B on every row while every gate stayed green
-(the mechanism is on `GLASS_SHEEN` in `theme/glass-colors.ts`). Counting
-achromatic rows is the direct refutation, and there are none: the ramp carries
-the page's hue all the way down.
-
-**No blur, measured rather than asserted.** Over a hard 10dp stripe pattern,
-sampled at the same rows inside the back capsule and on the bare stripes beside
-it:
-
-| backdrop stripe | bare | inside the island |
-| --- | --- | --- |
-| white | 255 | **254** |
-| black | 0 | **210** |
-
-Two things follow. The backdrop contributes **44 of 255** — about 17%, so the
-pane really is translucent. And the stripe EDGE stays sharp inside the island: a
-blur would smear a 26px transition, and there is none. That is tint only, which
-is the documented Android behaviour, and nothing in `logcat` asked for a blur
-method or reported a crash across five screens in both modes.
-
-The native pane is slightly more opaque than the web one (≈0.83 against 0.72),
-and that is `expo-blur`'s own tint, which one `intensity` drives together with
-the radius and which a caller cannot decline — the difference
-`GLASS_BLUR_INTENSITY` documents, showing up where it said it would.
-
-**iOS is still not verified on a device.** The material is `expo-blur` there
-too and unchanged from the `GlassSurface` the library already shipped, but
-nothing in this change has been run on an iPhone.
+**Not verified on a device.** Every number above is Chrome on Linux. iOS and Android have not been run for this change: the material is `expo-blur` on both and is unchanged from the `GlassSurface` the library already shipped, but the geometry, the safe-area padding, the top-edge claim and the scroll linkage have only been exercised in jest and in a browser. Android additionally paints **no blur at all** here, by the design described above, so what a device would show is the tint, the hairline, the sheen and the rim.
 
 ## Not included
 
@@ -278,7 +234,7 @@ nothing in this change has been run on an iPhone.
 
 **`border` and `transparent` apply to `presentation="bar"` only.** They are ignored by the floating presentation, which has no strip and no separator; `scrim` is its counterpart.
 
-**Icon actions want `ButtonGroupItem`.** A `Button variant="secondary"` in a floating header's actions paints its own opaque fill, which reads as a card floating over the content. It still works; it is just not the shape the islands are for.
+**Icon actions want `ButtonGroupItem`.** A `Button appearance="outline" tone="neutral"` in a floating header's actions paints its own opaque fill, which reads as a card floating over the content. It still works; it is just not the shape the islands are for.
 
 ## Migrating from app headers
 

package/docs/pagination.mdx

@@ -6,7 +6,7 @@ order: 27
 
 # Pagination
 
-A controlled page selector: Previous and Next are Bloom's own secondary small `Button`, with a window of page numbers between them. Colours come from the ramps in `src/button/shared.ts`.
+A controlled page selector: Previous and Next are Bloom's own plain neutral small `Button`, with a window of page numbers between them. Colours come from the ramps in `src/button/shared.ts`.
 
 ```tsx
 import { Pagination } from '@oxy.so/bloom/pagination';
@@ -33,7 +33,7 @@ page 10 of 10  1 … 6 7 8 9 10
 | | |
 |---|---|
 | row | space-between, gap 8 |
-| Previous / Next | `Button` secondary, `small` (32), Remix `RiArrowLeftLine` / `RiArrowRightLine`; disabled at either end |
+| Previous / Next | `Button` plain neutral, `sm` (32), Remix `RiArrowLeftLine` / `RiArrowRightLine`; disabled at either end |
 | page cell | 32×32 circle, `body-medium` (Inter 14/20 500), gap 2 |
 | current | card surface (dark: neutral-800), 1px neutral-200 border (dark: neutral-700), shadow-xs, text colour |
 | other pages | text-secondary (neutral-500); hover neutral-200 fill (dark: neutral-800) and the text colour |

package/docs/patient-info-card.mdx

@@ -26,7 +26,7 @@ import { RiAsterisk, RiDropLine } from '@oxy.so/bloom/icons';
 ## Layout
 
 - **Card:** 330 tall (`height`), radius 20, padding 24 top / 10 sides / 10 bottom, with the children centred and 15px apart. The 15 comes from the Figma frame's absolute positions (avatar bottom 90 → name 105 → details 146), not from the spacing scale.
-- **Avatar:** Bloom's `Avatar` at 66px. With no `avatarSource` it shows `initials` (default: the first letter of `name`) at a 24.75px semibold on the neutral disc. A 24px secondary icon `Button` (`RiAddLine`, named by `addPhotoLabel`, `"Add profile photo"` by default) sits 2px outside the avatar's top-right corner. `hideAddPhoto` removes it.
+- **Avatar:** Bloom's `Avatar` at 66px. With no `avatarSource` it shows `initials` (default: the first letter of `name`) at a 24.75px semibold on the neutral disc. A 24px subtle neutral icon `Button` (`RiAddLine`, named by `addPhotoLabel`, `"Add profile photo"` by default) sits 2px outside the avatar's top-right corner. `hideAddPhoto` removes it.
 - **Name:** 20/26 medium, one line.
 - **Rows:** they fill the remaining height, 10px apart; radius 10, padding 8/10. Each row has a 16px icon and a 14/20 regular label, both in the secondary colour, and a 14/20 medium value on the right.
 

package/docs/phone-input.mdx

@@ -39,13 +39,13 @@ const [number, setNumber] = useState('');
   country={country.iso2}
   onCountryChange={(iso2, next) => setCountry(next)}
   value={number}
-  onChangeText={setNumber}
+  onValueChange={setNumber}
 />;
 
 const e164 = `+${country.dial}${number.replace(/\D/g, '')}`;
 ```
 
-`defaultCountry` (default `US`) and `defaultValue` are the uncontrolled spellings. Formatting and validation are the caller's: `PhoneInput` does not reformat what is typed. `isInvalid` and `hint` paint the error state as on any `TextField`; `disabled` disables the select too.
+`defaultCountry` (default `US`) and `defaultValue` are the uncontrolled spellings. Formatting and validation are the caller's: `PhoneInput` does not reformat what is typed. `invalid` and `hint` paint the error state as on any `TextField`; `disabled` disables the select too.
 
 ## Look
 
@@ -53,7 +53,7 @@ Dimensions:
 
 | part | value |
 | --- | --- |
-| field | `TextField` with a leading addon: 36 tall, `pl-1 pr-2` (`small`: 32, `pl-1 pr-1.5`) |
+| field | `TextField` with a leading addon: 36 tall, `pl-1 pr-2` (`sm`: 32, `pl-1 pr-1.5`) |
 | trigger | the select trigger's own chrome (card fill, `neutral-200` hairline, xs shadow, 6px gap) at `rounded-lg px-1.5 py-1` — 8px corner, 30px tall. A control INSIDE an input, so not a pill. |
 | trigger value | 18 × 12 flag (2px corner), 5px, `+dial` in `body-medium` `text-secondary`, 16px chevron |
 | list (web) | 220px wide, `p-2`, 16px corner, 4px below the trigger, scrolls past 240px, opens scrolled to the chosen country |
@@ -68,7 +68,7 @@ import { CountryCodeSelect, CountryFlag, COUNTRIES, findCountry } from '@oxy.so/
 import { TextField, TextFieldInput } from '@oxy.so/bloom/text-field';
 
 <TextField leadingAddon={<CountryCodeSelect value={iso2} onValueChange={setIso2} />}>
-  <TextFieldInput label="Phone" value={number} onChangeText={setNumber} />
+  <TextFieldInput label="Phone" value={number} onValueChange={setNumber} />
 </TextField>
 
 <CountryFlag iso2="JP" size={24} accessibilityLabel="Japan" />