@oxy.so/bloom 3.5.0 → 4.0.0

package/docs/activity-feed.mdx

@@ -0,0 +1,116 @@
+---
+title: ActivityFeed
+description: Everything anyone did with a customer — calls, emails, meetings, notes, stage changes and completed tasks — grouped by day, with a filter row for the kinds.
+order: 125
+---
+
+# ActivityFeed
+
+```tsx
+import { ActivityFeed, ActivityFeedFilters, ACTIVITY_FEED_KINDS } from '@oxy.so/bloom';
+
+<ActivityFeedFilters
+  kinds={ACTIVITY_FEED_KINDS}
+  selected={kinds}
+  counts={countsByKind}
+  onToggle={toggleKind}
+/>
+<ActivityFeed entries={visible} accessibilityLabel="Activity" />
+```
+
+## A feed is not a status timeline
+
+Bloom already has two timelines, and this is deliberately a third SHAPE rather
+than a third copy.
+
+`TenancyTimeline` (and `EvictionTimeline`, which is that component with a marker
+table) draws ONE PROCESS ADVANCING. Its entries are homogeneous steps of the
+same journey, each carries a state — `complete`, `current`, `upcoming` — and a
+connector runs from each marker to the next. The connector is the component's
+central claim: this step follows that one, and there are more to come.
+
+An activity feed has no such claim to make.
+
+| | timeline | feed |
+| --- | --- | --- |
+| entries | steps of one process | heterogeneous events |
+| state | complete / current / upcoming | none — it happened |
+| subject | the process | the ACTOR, a different one each time |
+| structure | a connected spine | days, and entries inside a day |
+| ordering claim | this follows that | only "same day" |
+
+So the feed's leading mark is the ACTOR's avatar with the kind on its corner,
+there is no connector and no marker state, and the only ordering statement it
+makes is the day heading. Forcing this into `TenancyTimeline` would mean giving
+every call a `state` it does not have and drawing a line between a note and a
+stage change as if one caused the other.
+
+What they do share is the `list` / `listitem` semantics and the vocabulary of a
+tone per kind — shared by convention, not by a base component neither of them
+would fit.
+
+## Grouping is by the day STRING
+
+`entry.day` is already formatted by the app ("Today", "12 March"), and
+`groupActivityByDay` buckets on that exact string in first-seen order.
+
+Bloom does no date maths here, exactly as it does no money maths in `pipeline`.
+The app has the timezone, the locale and the decision about whether today is
+called "Today"; a component that parsed a date would be guessing at all three,
+and could then disagree with the heading it drew. Entries of the same day still
+reunite if they arrive apart — the bucket is keyed, not run-length.
+
+## The geometry
+
+```
+[avatar 32 + kind mark 18]   Marta Oyeleye called Nora about the renewal
+                             Call · 14:10
+                             The body, clamped to three lines…
+                             [Show more]
+                             (Renewal likely)
+                             Logged by Marta Oyeleye
+```
+
+16 between entries, 12 between the mark and the text, and a day heading over a
+rule that runs to the edge. The kind mark is hidden from assistive technology
+(`aria-hidden` AND `accessibilityElementsHidden`): the kind's word is already in
+the meta line, and an `img` announcing "Call" a second time reads as two events.
+
+## The clamp and its reveal
+
+`bodyLines` (default 3) clamps a long body, and a `text` button reveals it.
+`bodyLines={0}` never clamps and never draws the toggle.
+
+**The reveal is offered by CHARACTER COUNT, not by measurement**, via
+`activityBodyIsLong()` and `ACTIVITY_BODY_CHARS_PER_LINE`. React Native gives no
+reliable "did this overflow" signal on both platforms: `onTextLayout` is native
+only, and a measurement pass on web lands a frame after paint. That left two
+mistakes to choose between — a toggle that appears after the text has settled,
+moving content under the reader's eyes, or one that is occasionally offered on a
+body that did fit and collapses to the same text. The second is the cheaper one,
+and this is it. An explicit newline count wins over the character heuristic, so
+a short multi-line note clamps correctly. The per-line count is calibrated on
+the NARROW reading (about 310px of text, which is what a 390 phone leaves after
+the gutters and the 32-wide actor mark), so a wide feed errs toward offering the
+reveal rather than toward a body that silently runs on.
+
+The reveal's accessible name carries the entry ("Show more: called Nora about
+the renewal"), because a column of identical "Show more" buttons is a list of
+identical buttons to a screen reader.
+
+## The filter row is a GROUP of toggles
+
+`ActivityFeedFilters` is a `ChipRow role="group"` of `Chip`s, and each chip is a
+toggle carrying `aria-pressed`.
+
+Not a `tablist` and not a `radiogroup`: the kinds COMBINE. Turning "Call" on
+does not turn "Email" off, and a `tab` or a `radio` would announce single
+selection — the opposite of what the control does. `Chip` spells the state its
+role defines, in both the `aria-*` form web reads and the `accessibilityState`
+form native reads, so the pill is a real toggle rather than a pill that looks
+selected. (`SegmentedControl` is the right control for the other question — one
+view OF the feed — and the wrong one for this.)
+
+It is CONTROLLED and filters nothing itself. Which entries reach `ActivityFeed`
+is the app's decision; a filter row that also held the answer would be a second
+source of truth for one list.

package/docs/address.mdx

@@ -0,0 +1,93 @@
+---
+title: Address
+description: An address as a row — a glyph or an avatar, two lines, a trailing action, a selected state and a provenance flavour expressed as data — plus the sectioned list they live in.
+order: 132
+---
+
+# Address
+
+What a result list is made of. The text INPUT is not here: an app searches with `search`
+or `text-field` and renders what comes back as these rows.
+
+```tsx
+import { AddressList, AddressRow } from '@oxy.so/bloom/address';
+
+<AddressList
+  variant="picker"
+  accessibilityLabel="Delivery address"
+  selectedId={selected}
+  onSelect={setSelected}
+  sections={[
+    { title: 'Saved', entries: [
+      { id: 'home', kind: 'saved', title: 'Home', subtitle: 'Carrer de l’Om 14, 3r 2a', badge: <Badge content="Default" variant="subtle" size="label-small" /> },
+    ] },
+    { title: 'Recent', entries: [
+      { id: 'r1', kind: 'recent', title: 'Plaça de les Bruixes 2', meta: '1.2 km' },
+    ] },
+  ]}
+/>
+```
+
+## The flavour is data
+
+`kind` is `place | saved | recent | suggestion`, and it chooses the default glyph and
+nothing else. There is no `SavedAddressRow`, `RecentAddressRow` and `SuggestionRow`,
+because a picker list, a checkout summary and a search result list all draw the same row
+and differ only in what they put in it.
+
+An app whose provenance is not one of those four passes `icon`. An app that wants a face
+or a map thumbnail passes `leading`.
+
+## `leading` is read for presence
+
+- omitted → the glyph tile
+- a node → that node instead
+- **`null` → no media at all**
+
+The last one is the shape `RouteStops` needs: the marker column outside the row is already
+the gutter, so the row must not draw a tile of its own. It is a presence check rather than
+a `??`, so `leading={null}` cannot be silently answered with the tile.
+
+## It is `Item`, filled in
+
+`AddressRow` is Bloom's `Item` with an address's slots filled: the row, the press target,
+the density rungs, the selected wash, the disabled opacity and the ARIA role translation
+are all `Item`'s, and this family owns no second copy of any of them. What it adds is the
+leading tile, the badge beside the title, the `meta`/`action` pairing in the trailing
+slot, and an accessible name assembled from the row's own text in reading order.
+
+If a row needs something `Item` does not do, that is a report about `Item`, not a fork
+here.
+
+## The variant is the announced tree
+
+`AddressList`'s `variant` is not a style.
+
+| variant | container | row |
+| --- | --- | --- |
+| `list` | one `list` per section, named by its header | a `listitem` wrapping a button |
+| `picker` | a `radiogroup`, one `group` per section | a `radio` carrying `aria-checked` |
+
+**The picker is a radio group rather than the listbox ARIA would suggest, and that is a
+platform decision.** React Native's `Role` has no `listbox`; `radiogroup` and `radio` exist
+on both platforms and say exactly the right thing — pick one of these. A role that reached
+only web would be the silent half of an accessibility bug, correct in the browser and
+absent on the device.
+
+## Loading and empty
+
+`loading` draws `loadingRows` placeholder rows at the row's own geometry, on a container
+marked `aria-busy` so a reader is told to wait rather than told nothing. The empty block
+is a glyph, a title and an optional line; `empty` replaces the whole thing when an app
+wants an action in it.
+
+Empty is measured across ALL sections: a list whose sections exist but hold nothing is
+empty, which is what a search with a stale section header would otherwise render as a
+column of headings over nothing.
+
+## Naming
+
+The announced name defaults to the title, the subtitle and the meta joined in reading
+order, so a row reads as one utterance instead of three. Pass `accessibilityLabel` when
+the visible text is not the sentence you want announced — a title that is an abbreviation,
+a meta that is a distance a reader does not need.

package/docs/adoption-matrix.mdx

@@ -32,15 +32,15 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ## Totals
 
-- **161 families** in `src/`, **159** published (a subpath, the root barrel, or both). **33** carry a web fork.
+- **180 families** in `src/`, **178** published (a subpath, the root barrel, or both). **35** carry a web fork.
 - Docs, stories and suites are gated as a standard by `src/__tests__/family-coverage.test.ts`; the per-family counts are in the table below.
 
 | contract | applies to | reads | delegated | n/a¹ | adaptation |
 | --- | --- | --- | --- | --- | --- |
-| Field membership | 34 | 16 | 0 | 15 | 3 |
-| Control presentation | 14 | 7 | 1 | 6 | 0 |
+| Field membership | 39 | 18 | 0 | 18 | 3 |
+| Control presentation | 16 | 8 | 2 | 6 | 0 |
 | Trigger composition | 10 | 8 | 0 | 2 | 0 |
-| Controlled / uncontrolled state | 38 | 30 | 0 | 1 | 7 |
+| Controlled / uncontrolled state | 42 | 34 | 0 | 1 | 7 |
 
 ## What remains — the named adaptations
 
@@ -64,6 +64,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 
 ### Field membership
 
+- `address` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `agent-chat` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `chat-composer` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `chat-list` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
@@ -76,6 +77,8 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 - `media-controls` (does-not-apply) — a transport SCRUBBER (`adjustable`): it is named by the track it plays and lives in a player, not in a field.
 - `message-media` (does-not-apply) — a voice message’s scrubber — same as `media-controls`.
 - `music-library` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
+- `note-card` (does-not-apply) — the `checkbox` role is on the CARD (bulk selection in a list) and on read-only checklist PREVIEW rows. Neither is a form control: a note card is never inside a `Field`, and the preview rows take no press at all.
+- `note-editor` (does-not-apply) — the raw `TextInput` is a DOCUMENT TITLE — it draws no box, no label and no hint, because the words are the document rather than a value being collected. A `Field` around it would put a form label above a heading.
 - `sidebar` (does-not-apply) — renders a bare `TextInput` deliberately — a composer or a search box that draws its own chrome and is not a form field a `Field` wraps. Wiring it to `TextFieldInput` would give it the field shell it exists not to draw.
 - `stay-filters` (does-not-apply) — writes a selection role on a ROW or a chip rather than on a form control — a list the user picks from, inside its own container, never inside a `Field`.
 - `theme-toggle` (does-not-apply) — the switch row draws its own label ("Dark mode") as both visible text and accessible name, inside the toggle’s own menu.
@@ -87,6 +90,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 - `chat-screen` (does-not-apply) — sizes the chat HEADER, which is chrome around the screen rather than a control a container sets the density of.
 - `creator-studio` (does-not-apply) — sizes a studio stat block — a presentation part, whose two sizes happen to be spelled with the same two words as the density pair.
 - `media-header` (does-not-apply) — sizes the media header’s meta row, which is layout of a header rather than a control inside a container.
+- `note-editor` (delegated) — the toolbar passes `size` straight to `ButtonGroup`, which reads the contract — so a `ControlSurface` reaches the formatting row without this family reading anything.
 - `phone-input` (delegated) — passes `size` straight through to `TextField`, which inherits density — so a `ControlSurface` reaches the phone field without this family reading anything.
 - `tenancy` (does-not-apply) — sizes a tenancy summary row: a presentation part, for the same reason as `creator-studio` and `chat-people`.
 
@@ -104,53 +108,58 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | family | import | platform | doc | story | suites | Field membership | Control presentation | Trigger composition | Controlled / uncontrolled state |
 | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
 | `accordion` | `@oxy.so/bloom/accordion` + barrel | universal | `accordion.mdx` | yes | 2 |  |  |  |  |
+| `activity-feed` | `@oxy.so/bloom/activity-feed` + barrel | universal | `activity-feed.mdx` | yes | 1 |  |  |  |  |
 | `activity-heatmap` | `@oxy.so/bloom/activity-heatmap` + barrel | universal | `activity-heatmap.mdx` | yes | 1 |  |  |  |  |
+| `address` | `@oxy.so/bloom/address` + barrel | universal | `address.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `admonition` | `@oxy.so/bloom/admonition` + barrel | universal | `admonition.mdx` | yes | 1 |  |  |  |  |
-| `agent-chat` | `@oxy.so/bloom/agent-chat` + barrel | web fork | `agent-chat.mdx` | yes | 1 | n/a¹ |  |  | reads |
+| `agent-chat` | `@oxy.so/bloom/agent-chat` + barrel | web fork | `agent-chat.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `agent-limits-card` | `@oxy.so/bloom/agent-limits-card` + barrel | universal | `agent-limits-card.mdx` | yes | 1 |  |  |  | reads |
 | `agent-log` | `@oxy.so/bloom/agent-log` + barrel | universal | `agent-log.mdx` | yes | 1 |  |  |  |  |
 | `agent-progress` | `@oxy.so/bloom/agent-progress` + barrel | universal | `agent-progress.mdx` | yes | 1 |  |  |  | reads |
 | `agent-thinking` | `@oxy.so/bloom/agent-thinking` + barrel | universal | `agent-thinking.mdx` | yes | 1 |  |  |  |  |
-| `ai-chat` | `@oxy.so/bloom/ai-chat` + barrel | web fork | `ai-chat.mdx` | yes | 2 |  |  |  | reads |
+| `ai-chat` | `@oxy.so/bloom/ai-chat` + barrel | web fork | `ai-chat.mdx` | yes | 5 |  |  |  | reads |
 | `ai-profile-card` | `@oxy.so/bloom/ai-profile-card` + barrel | universal | `ai-profile-card.mdx` | yes | 1 |  |  |  | reads |
 | `alert-dialog` | `@oxy.so/bloom/alert-dialog` + barrel | web fork | `alert-dialog.mdx` | yes | 1 |  |  |  |  |
 | `animated-check` | `@oxy.so/bloom/animated-check` + barrel | universal | `animated-check.mdx` | yes | 2 |  |  |  |  |
 | `announcement` | `@oxy.so/bloom/announcement` + barrel | universal | `announcement.mdx` | yes | 1 |  |  |  |  |
-| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | universal | `app-shell.mdx` | yes | 1 |  |  |  | reads |
+| `app-shell` | `@oxy.so/bloom/app-shell` + barrel | web fork | `app-shell.mdx` | yes | 2 |  |  |  | reads |
+| `appearance` | `@oxy.so/bloom/appearance` + barrel | universal | `appearance.mdx` | yes | 4 |  |  |  |  |
 | `aspect-ratio` | `@oxy.so/bloom/aspect-ratio` + barrel | universal | `aspect-ratio.mdx` | yes | 1 |  |  |  |  |
 | `auth-card` | `@oxy.so/bloom/auth-card` + barrel | universal | `auth-card.mdx` | yes | 1 |  |  |  |  |
-| `avatar` | `@oxy.so/bloom/avatar` + barrel | universal | `avatar.mdx` | yes | 5 |  |  |  |  |
+| `avatar` | `@oxy.so/bloom/avatar` + barrel | universal | `avatar.mdx` | yes | 6 |  |  |  |  |
 | `avatar-group` | `@oxy.so/bloom/avatar-group` + barrel | web fork | `avatar-group.mdx` | yes | 3 |  |  |  |  |
-| `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 1 |  |  |  |  |
+| `badge` | `@oxy.so/bloom/badge` + barrel | universal | `badge.mdx` | yes | 2 |  |  |  |  |
 | `booking` | `@oxy.so/bloom/booking` + barrel | universal | `booking.mdx` | yes | 3 |  |  |  | reads |
+| `bottom-bar` | `@oxy.so/bloom/bottom-bar` + barrel | web fork | `bottom-bar.mdx` | yes | 1 |  |  |  |  |
 | `bottom-sheet` | `@oxy.so/bloom/bottom-sheet` + barrel | web fork | `bottom-sheet.mdx` | yes | 6 |  |  |  |  |
 | `breadcrumb` | `@oxy.so/bloom/breadcrumb` + barrel | universal | `breadcrumb.mdx` | yes | 1 |  |  |  |  |
-| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 48 |  |  | n/a¹ |  |
-| `button-group` | `@oxy.so/bloom/button-group` + barrel | universal | `button-group.mdx` | yes | 4 |  | reads |  |  |
+| `button` | `@oxy.so/bloom/button` + barrel | web fork | `button.mdx` | yes | 30 |  |  | n/a¹ |  |
+| `button-group` | `@oxy.so/bloom/button-group` + barrel | universal | `button-group.mdx` | yes | 5 |  | reads |  |  |
 | `calendar` | `@oxy.so/bloom/calendar` + barrel | universal | `calendar.mdx` | yes | 1 |  |  |  | reads |
 | `call-ui` | `@oxy.so/bloom/call-ui` + barrel | universal | `call-ui.mdx` | yes | 1 |  |  |  |  |
-| `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 2 |  |  |  |  |
+| `card` | `@oxy.so/bloom/card` + barrel | universal | `card.mdx` | yes | 3 |  |  |  |  |
 | `carousel` | `@oxy.so/bloom/carousel` + barrel | universal | `carousel.mdx` | yes | 1 |  |  |  |  |
 | `category-bar` | `@oxy.so/bloom/category-bar` + barrel | universal | `category-bar.mdx` | yes | 2 |  |  |  |  |
-| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 27 |  |  |  | **adaptation** |
+| `chart-cards` | `@oxy.so/bloom/chart-cards` + barrel | universal | `chart-cards.mdx` | yes | 29 |  |  |  | **adaptation** |
 | `chat-composer` | `@oxy.so/bloom/chat-composer` + barrel | universal | `chat-composer.mdx` | yes | 2 | n/a¹ | n/a¹ |  | reads |
 | `chat-indicators` | `@oxy.so/bloom/chat-indicators` + barrel | universal | `chat-indicators.mdx` | yes | 1 |  |  |  |  |
 | `chat-list` | `@oxy.so/bloom/chat-list` + barrel | universal | `chat-list.mdx` | yes | 2 | n/a¹ |  |  | **adaptation** |
 | `chat-people` | `@oxy.so/bloom/chat-people` + barrel | universal | `chat-people.mdx` | yes | 1 | n/a¹ | n/a¹ |  |  |
 | `chat-screen` | `@oxy.so/bloom/chat-screen` + barrel | universal | `chat-screen.mdx` | yes | 2 |  | n/a¹ |  | reads |
 | `checkbox` | `@oxy.so/bloom/checkbox` + barrel | universal | `checkbox.mdx` | yes | 4 | reads |  |  |  |
-| `chip` | `@oxy.so/bloom/chip` + barrel | universal | `chip.mdx` | yes | 4 |  |  |  |  |
-| `code` | `@oxy.so/bloom/code` + barrel | universal | `code.mdx` | yes | 2 |  |  |  |  |
+| `chip` | `@oxy.so/bloom/chip` + barrel | universal | `chip.mdx` | yes | 5 |  |  |  |  |
+| `code` | `@oxy.so/bloom/code` + barrel | universal | `code.mdx` | yes | 3 |  |  |  |  |
 | `command` | `@oxy.so/bloom/command` + barrel | web fork | `command.mdx` | yes | 1 | n/a¹ |  |  | reads |
 | `composer-loader` | `@oxy.so/bloom/composer-loader` + barrel | web fork | `composer-loader.mdx` | yes | 1 |  |  |  |  |
 | `composer-panel` | `@oxy.so/bloom/composer-panel` + barrel | web fork | `composer-panel.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `composition-bar` | `@oxy.so/bloom/composition-bar` + barrel | universal | `composition-bar.mdx` | yes | 1 |  |  |  |  |
 | `connection-dots` | `@oxy.so/bloom/connection-dots` + barrel | web fork | `connection-dots.mdx` | yes | 1 |  |  |  |  |
 | `connection-status` | `@oxy.so/bloom/connection-status` + barrel | web fork | `connection-status.mdx` | yes | 1 |  |  |  |  |
+| `contact-card` | `@oxy.so/bloom/contact-card` + barrel | universal | `contact-card.mdx` | yes | 1 |  |  |  |  |
 | `content-panel` | `@oxy.so/bloom/content-panel` + barrel | web fork | `content-panel.mdx` | yes | 6 |  |  |  |  |
 | `context-menu` | `@oxy.so/bloom/context-menu` + barrel | web fork | `context-menu.mdx` | yes | 2 |  |  | reads |  |
 | `control-surface` | `@oxy.so/bloom/control-surface` + barrel | universal | `composition.mdx` | yes | 3 |  | reads |  |  |
-| `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 2 |  | n/a¹ |  | **adaptation** |
+| `creator-studio` | `@oxy.so/bloom/creator-studio` + barrel | universal | `creator-studio.mdx` | yes | 3 |  | n/a¹ |  | **adaptation** |
 | `data-table` | `@oxy.so/bloom/data-table` + barrel | universal | `data-table.mdx` | yes | 3 |  |  |  | reads |
 | `date-picker` | `@oxy.so/bloom/date-picker` + barrel | universal | `date-picker.mdx` | yes | 4 | reads | reads |  | reads |
 | `design-tokens` | `@oxy.so/bloom/design-tokens` + barrel | universal | `design-tokens.mdx` | yes | 3 |  |  |  |  |
@@ -160,11 +169,11 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `dropdown-menu` | `@oxy.so/bloom/dropdown-menu` + barrel | web fork | `dropdown-menu.mdx` | yes | 4 |  |  | reads | reads |
 | `error-boundary` | `@oxy.so/bloom/error-boundary` + barrel | universal | `error-boundary.mdx` | yes | 1 |  |  |  |  |
 | `eviction` | `@oxy.so/bloom/eviction` + barrel | universal | `eviction.mdx` | yes | 1 |  |  |  |  |
-| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 4 |  |  |  |  |
-| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 4 | reads |  |  |  |
+| `fab` | `@oxy.so/bloom/fab` + barrel | web fork | `fab.mdx` | yes | 3 |  |  |  |  |
+| `field` | `@oxy.so/bloom/field` + barrel | universal | `field.mdx` | yes | 6 | reads |  |  |  |
 | `file-upload` | `@oxy.so/bloom/file-upload` + barrel | universal | `file-upload.mdx` | yes | 3 | reads |  |  |  |
 | `fill` | `@oxy.so/bloom/fill` + barrel | universal | `fill.mdx` | yes | 1 |  |  |  |  |
-| `floating` | internal | universal | — | — | 11 | n/a¹ |  | reads | reads |
+| `floating` | internal | universal | — | — | 14 | n/a¹ |  | reads | reads |
 | `fonts` | `@oxy.so/bloom/fonts` + barrel | web fork | `fonts.mdx` | yes | 2 |  |  |  |  |
 | `frosted-icon-button` | `@oxy.so/bloom/frosted-icon-button` + barrel | web fork | `frosted-icon-button.mdx` | yes | 4 |  |  |  |  |
 | `glass` | internal | universal | `glass.mdx` | — | 1 |  | reads |  |  |
@@ -173,7 +182,7 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `hooks` | `@oxy.so/bloom/hooks` + barrel | universal | `hooks.mdx` | yes | 9 |  |  |  | reads |
 | `hover-card` | `@oxy.so/bloom/hover-card` + barrel | web fork | `hover-card.mdx` | yes | 2 |  |  | reads | reads |
 | `icon-circle` | `@oxy.so/bloom/icon-circle` + barrel | universal | `icon-circle.mdx` | yes | 1 |  |  |  |  |
-| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 34 |  |  |  |  |
+| `icons` | `@oxy.so/bloom/icons` + barrel | universal | `icons.mdx` | yes | 41 |  |  |  |  |
 | `image-aspect-ratio-cache` | `@oxy.so/bloom/image-aspect-ratio-cache` + barrel | universal | `image-aspect-ratio-cache.mdx` | yes | 1 |  |  |  |  |
 | `image-resolver` | `@oxy.so/bloom/image-resolver` + barrel | universal | `image-resolver.mdx` | yes | 7 |  |  |  |  |
 | `important-alerts-card` | `@oxy.so/bloom/important-alerts-card` + barrel | universal | `important-alerts-card.mdx` | yes | 1 |  |  |  |  |
@@ -182,7 +191,8 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `item` | `@oxy.so/bloom/item` + barrel | universal | `item.mdx` | yes | 2 |  |  |  |  |
 | `kbd` | `@oxy.so/bloom/kbd` + barrel | universal | `kbd.mdx` | yes | 1 |  |  |  |  |
 | `label` | `@oxy.so/bloom/label` + barrel | universal | `label.mdx` | yes | 1 |  |  |  |  |
-| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 6 |  |  |  |  |
+| `layout` | `@oxy.so/bloom/layout` + barrel | universal | `layout.mdx` | yes | 5 |  |  |  |  |
+| `lead-score` | `@oxy.so/bloom/lead-score` + barrel | universal | `lead-score.mdx` | yes | 1 |  |  |  |  |
 | `link-preview` | `@oxy.so/bloom/link-preview` + barrel | universal | `link-preview.mdx` | yes | 2 |  |  |  |  |
 | `list` | `@oxy.so/bloom/list` + barrel | web fork | `list.mdx` | yes | 2 |  |  |  |  |
 | `listing-actions` | `@oxy.so/bloom/listing-actions` + barrel | universal | `listing-actions.mdx` | yes | 2 | **adaptation** |  |  | reads |
@@ -191,11 +201,14 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `listing-editor` | `@oxy.so/bloom/listing-editor` + barrel | universal | `listing-editor.mdx` | yes | 1 | **adaptation** |  |  | reads |
 | `loading` | `@oxy.so/bloom/loading` + barrel | web fork | `loading.mdx` | yes | 2 |  |  |  |  |
 | `lyrics` | `@oxy.so/bloom/lyrics` + barrel | universal | `lyrics.mdx` | yes | 2 |  |  |  |  |
+| `mail-compose` | `@oxy.so/bloom/mail-compose` + barrel | universal | `mail-compose.mdx` | yes | 2 | reads |  |  | reads |
+| `mail-list` | `@oxy.so/bloom/mail-list` + barrel | universal | `mail-list.mdx` | yes | 2 |  |  |  |  |
+| `mail-thread` | `@oxy.so/bloom/mail-thread` + barrel | universal | `mail-thread.mdx` | yes | 1 |  |  |  | reads |
 | `map-marker` | `@oxy.so/bloom/map-marker` + barrel | universal | `map-marker.mdx` | yes | 2 | n/a¹ |  |  |  |
-| `media-card` | `@oxy.so/bloom/media-card` + barrel | universal | `media-card.mdx` | yes | 3 |  |  |  |  |
-| `media-controls` | `@oxy.so/bloom/media-controls` + barrel | universal | `media-controls.mdx` | yes | 2 | n/a¹ |  |  |  |
+| `media-card` | `@oxy.so/bloom/media-card` + barrel | universal | `media-card.mdx` | yes | 4 |  |  |  |  |
+| `media-controls` | `@oxy.so/bloom/media-controls` + barrel | universal | `media-controls.mdx` | yes | 3 | n/a¹ |  |  |  |
 | `media-flight` | `@oxy.so/bloom/media-flight` | web fork | `media-flight.mdx` | yes | 3 |  |  |  |  |
-| `media-header` | `@oxy.so/bloom/media-header` + barrel | universal | `media-header.mdx` | yes | 2 |  | n/a¹ |  |  |
+| `media-header` | `@oxy.so/bloom/media-header` + barrel | universal | `media-header.mdx` | yes | 3 |  | n/a¹ |  |  |
 | `media-inset-border` | `@oxy.so/bloom/media-inset-border` + barrel | universal | `media-inset-border.mdx` | yes | 1 |  |  |  |  |
 | `media-player` | `@oxy.so/bloom/media-player` + barrel | universal | `media-player.mdx` | yes | 3 |  |  |  |  |
 | `media-shelf` | `@oxy.so/bloom/media-shelf` + barrel | universal | `media-shelf.mdx` | yes | 1 |  |  |  |  |
@@ -203,62 +216,72 @@ The classification is an EQUALITY in `src/__tests__/adoption-matrix.test.ts`, no
 | `message-bubble` | `@oxy.so/bloom/message-bubble` + barrel | universal | `message-bubble.mdx` | yes | 1 |  |  |  |  |
 | `message-media` | `@oxy.so/bloom/message-media` + barrel | universal | `message-media.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `motion` | `@oxy.so/bloom/motion` + barrel | web fork | `motion.mdx` | yes | 2 |  |  |  |  |
-| `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 2 | n/a¹ |  |  |  |
-| `notification` | `@oxy.so/bloom/notification` + barrel | universal | `notification.mdx` | yes | 2 |  |  |  |  |
-| `notification-center` | `@oxy.so/bloom/notification-center` + barrel | universal | `notification-center.mdx` | yes | 2 |  |  |  | reads |
+| `music-library` | `@oxy.so/bloom/music-library` + barrel | universal | `music-library.mdx` | yes | 3 | n/a¹ |  |  |  |
+| `note-card` | `@oxy.so/bloom/note-card` + barrel | universal | `note-card.mdx` | yes | 1 | n/a¹ |  |  |  |
+| `note-editor` | `@oxy.so/bloom/note-editor` + barrel | universal | `note-editor.mdx` | yes | 1 | n/a¹ | delegated |  |  |
+| `notification` | `@oxy.so/bloom/notification` + barrel | universal | `notification.mdx` | yes | 3 |  |  |  |  |
+| `notification-center` | `@oxy.so/bloom/notification-center` + barrel | universal | `notification-center.mdx` | yes | 3 |  |  |  | reads |
 | `offering-badge` | `@oxy.so/bloom/offering-badge` + barrel | universal | `offering-badge.mdx` | yes | 3 |  |  |  |  |
+| `order-status` | `@oxy.so/bloom/order-status` + barrel | universal | `order-status.mdx` | yes | 1 |  |  |  |  |
+| `outline-nav` | `@oxy.so/bloom/outline-nav` + barrel | universal | `outline-nav.mdx` | yes | 1 |  |  |  |  |
 | `overlay` | `@oxy.so/bloom/overlay` + barrel | universal | `overlay.mdx` | yes | 7 |  |  |  |  |
 | `page-header` | `@oxy.so/bloom/page-header` + barrel | universal | `page-header.mdx` | yes | 2 |  | reads |  |  |
 | `pagination` | `@oxy.so/bloom/pagination` + barrel | universal | `pagination.mdx` | yes | 1 |  |  |  |  |
 | `patient-info-card` | `@oxy.so/bloom/patient-info-card` + barrel | universal | `patient-info-card.mdx` | yes | 1 |  |  |  |  |
 | `phone-input` | `@oxy.so/bloom/phone-input` | universal | `phone-input.mdx` | yes | 2 | reads | delegated |  | reads |
+| `pipeline` | `@oxy.so/bloom/pipeline` + barrel | universal | `pipeline.mdx` | yes | 1 |  |  |  | reads |
 | `place-reviews` | `@oxy.so/bloom/place-reviews` + barrel | universal | `place-reviews.mdx` | yes | 1 |  |  |  | reads |
-| `popover` | `@oxy.so/bloom/popover` + barrel | web fork | `popover.mdx` | yes | 6 |  |  | reads | reads |
-| `portal` | `@oxy.so/bloom/portal` + barrel | web fork | `portal.mdx` | yes | 14 |  |  |  |  |
+| `popover` | `@oxy.so/bloom/popover` + barrel | web fork | `popover.mdx` | yes | 7 |  |  | reads | reads |
+| `portal` | `@oxy.so/bloom/portal` + barrel | web fork | `portal.mdx` | yes | 15 |  |  |  |  |
 | `pressable-scale` | `@oxy.so/bloom/pressable-scale` + barrel | universal | `pressable-scale.mdx` | yes | 1 |  |  |  |  |
+| `price-breakdown` | `@oxy.so/bloom/price-breakdown` + barrel | universal | `price-breakdown.mdx` | yes | 1 |  |  |  | reads |
 | `progressive-blur` | `@oxy.so/bloom/progressive-blur` + barrel | web fork | `progressive-blur.mdx` | yes | 1 |  |  |  |  |
-| `property-insights` | `@oxy.so/bloom/property-insights` + barrel | universal | `property-insights.mdx` | yes | 3 |  |  |  | reads |
+| `property-insights` | `@oxy.so/bloom/property-insights` + barrel | universal | `property-insights.mdx` | yes | 4 |  |  |  | reads |
 | `provider` | `@oxy.so/bloom/provider` | universal | `provider.mdx` | yes | 1 |  |  |  |  |
 | `questionnaire` | `@oxy.so/bloom/questionnaire` + barrel | universal | `questionnaire.mdx` | yes | 1 | **adaptation** |  |  | **adaptation** |
-| `queue-panel` | `@oxy.so/bloom/queue-panel` + barrel | universal | `queue-panel.mdx` | yes | 1 |  |  |  | **adaptation** |
+| `queue-panel` | `@oxy.so/bloom/queue-panel` + barrel | universal | `queue-panel.mdx` | yes | 2 |  |  |  | **adaptation** |
 | `radio` | `@oxy.so/bloom/radio` + barrel | universal | `radio.mdx` | yes | 3 | reads |  |  |  |
 | `radio-indicator` | `@oxy.so/bloom/radio-indicator` + barrel | universal | `radio-indicator.mdx` | yes | 1 |  |  |  |  |
 | `rail` | `@oxy.so/bloom/rail` + barrel | universal | `rail.mdx` | yes | 1 |  |  |  |  |
 | `rating` | `@oxy.so/bloom/rating` + barrel | universal | `rating.mdx` | yes | 3 | reads |  |  |  |
 | `recent-hires-card` | `@oxy.so/bloom/recent-hires-card` + barrel | universal | `recent-hires-card.mdx` | yes | 1 |  |  |  |  |
+| `route-stops` | `@oxy.so/bloom/route-stops` + barrel | universal | `route-stops.mdx` | yes | 1 |  |  |  |  |
+| `screen` | `@oxy.so/bloom/screen` + barrel | universal | `screen.mdx` | yes | 4 |  |  |  |  |
 | `scroll` | `@oxy.so/bloom/scroll` + barrel | web fork | `scroll.mdx` | yes | 5 |  |  |  |  |
 | `search` | `@oxy.so/bloom/search` + barrel | universal | `search.mdx` | yes | 1 |  |  |  |  |
 | `segmented-control` | `@oxy.so/bloom/segmented-control` + barrel | universal | `segmented-control.mdx` | yes | 3 | reads |  |  |  |
 | `select` | `@oxy.so/bloom/select` + barrel | web fork | `select.mdx` | yes | 6 | reads |  | reads |  |
 | `settings-list` | `@oxy.so/bloom/settings-list` + barrel | universal | `settings-list.mdx` | yes | 5 |  |  |  |  |
 | `settings-modal` | `@oxy.so/bloom/settings-modal` + barrel | universal | `settings-modal.mdx` | yes | 1 |  |  |  | reads |
-| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 1 | n/a¹ |  |  | reads |
+| `sidebar` | `@oxy.so/bloom/sidebar` + barrel | universal | `sidebar.mdx` | yes | 2 | n/a¹ |  |  | reads |
 | `skeleton` | `@oxy.so/bloom/skeleton` + barrel | universal | `skeleton.mdx` | yes | 1 |  |  |  |  |
 | `slider` | `@oxy.so/bloom/slider` + barrel | universal | `slider.mdx` | yes | 4 | reads |  |  |  |
 | `social-button` | `@oxy.so/bloom/social-button` + barrel | universal | `social-button.mdx` | yes | 1 |  |  |  |  |
 | `sortable-media` | `@oxy.so/bloom/sortable-media` + barrel | universal | `sortable-media.mdx` | yes | 1 |  |  |  |  |
-| `stat-bar` | `@oxy.so/bloom/stat-bar` + barrel | universal | `stat-bar.mdx` | yes | 4 |  |  |  |  |
+| `stat-bar` | `@oxy.so/bloom/stat-bar` + barrel | universal | `stat-bar.mdx` | yes | 5 |  |  |  |  |
 | `stat-cards` | `@oxy.so/bloom/stat-cards` + barrel | universal | `stat-cards.mdx` | yes | 4 |  |  |  |  |
 | `stay-filters` | `@oxy.so/bloom/stay-filters` + barrel | universal | `stay-filters.mdx` | yes | 4 | n/a¹ |  |  |  |
 | `stay-search` | `@oxy.so/bloom/stay-search` + barrel | universal | `stay-search.mdx` | yes | 4 |  |  |  |  |
 | `stepper` | `@oxy.so/bloom/stepper` + barrel | universal | `stepper.mdx` | yes | 3 | reads |  |  |  |
-| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 42 |  |  |  |  |
+| `styles` | `@oxy.so/bloom/styles` + barrel | universal | `styles.mdx` | yes | 57 |  |  |  |  |
 | `subtle-hover` | `@oxy.so/bloom/subtle-hover` + barrel | universal | `subtle-hover.mdx` | yes | 1 |  |  |  |  |
 | `surfaces` | `@oxy.so/bloom/surfaces` + barrel | web fork | `alert.mdx` | yes | 2 |  |  |  |  |
-| `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 5 | reads |  |  |  |
+| `swipe-row` | `@oxy.so/bloom/swipe-row` + barrel | universal | `swipe-row.mdx` | yes | 1 |  |  |  |  |
+| `switch` | `@oxy.so/bloom/switch` + barrel | universal | `switch.mdx` | yes | 6 | reads |  |  |  |
 | `tab-bar` | `@oxy.so/bloom/tab-bar` | web fork | `tab-bar.mdx` | yes | 12 |  |  | reads |  |
 | `table` | `@oxy.so/bloom/table` + barrel | universal | `table.mdx` | yes | 1 |  |  |  |  |
 | `tabs` | `@oxy.so/bloom/tabs` + barrel | universal | `tabs.mdx` | yes | 2 |  |  |  |  |
+| `tag-field` | `@oxy.so/bloom/tag-field` + barrel | universal | `tag-field.mdx` | yes | 2 | reads | reads |  |  |
 | `task-list` | `@oxy.so/bloom/task-list` + barrel | universal | `task-list.mdx` | yes | 1 |  |  |  |  |
 | `teleport` | `@oxy.so/bloom/teleport` | universal | `teleport.mdx` | yes | 1 |  |  |  |  |
 | `tenancy` | `@oxy.so/bloom/tenancy` + barrel | universal | `tenancy.mdx` | yes | 3 |  | n/a¹ |  |  |
-| `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 10 | reads | reads |  |  |
+| `text-field` | `@oxy.so/bloom/text-field` + barrel | universal | `text-field.mdx` | yes | 13 | reads | reads |  |  |
 | `textarea` | `@oxy.so/bloom/textarea` + barrel | universal | `textarea.mdx` | yes | 4 | reads | reads |  | n/a¹ |
-| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 244 |  |  | n/a¹ | reads |
+| `theme` | `@oxy.so/bloom/theme` + barrel | web fork | `theme.mdx` | yes | 276 |  |  | n/a¹ | reads |
 | `theme-toggle` | `@oxy.so/bloom/theme-toggle` + barrel | universal | `theme-toggle.mdx` | yes | 1 | n/a¹ |  |  |  |
 | `toast` | `@oxy.so/bloom/toast` + barrel | universal | `toast.mdx` | yes | 17 |  |  |  |  |
 | `tooltip` | `@oxy.so/bloom/tooltip` + barrel | web fork | `tooltip.mdx` | yes | 1 |  |  |  |  |
-| `track-list` | `@oxy.so/bloom/track-list` + barrel | universal | `track-list.mdx` | yes | 1 |  |  |  | **adaptation** |
+| `track-list` | `@oxy.so/bloom/track-list` + barrel | universal | `track-list.mdx` | yes | 2 |  |  |  | **adaptation** |
 | `typography` | `@oxy.so/bloom/typography` + barrel | universal | `typography.mdx` | yes | 7 |  |  |  |  |
 | `user-hover-card` | `@oxy.so/bloom/user-hover-card` + barrel | universal | `user-hover-card.mdx` | yes | 4 |  |  |  |  |
 | `web-search` | `@oxy.so/bloom/web-search` + barrel | universal | `web-search.mdx` | yes | 1 |  |  |  |  |

package/docs/ai-chat.mdx

@@ -60,7 +60,10 @@ Give the shell a sized parent — it fills it.
 - **xl and up** (1280): the `panel` 12 right of the chat at its width (410, dragged within 320–560). The grip is a 20px strip straddling the chat's edge; hovering it reveals a 15×25 grip (radius 4, border, background-primary, shadow-xs, three 1×13 icon-quaternary lines) that follows the pointer along the edge and stays while dragging. Dragging right widens the chat. With keyboard focus, ←/→ nudge by 16.
 - **below xl** the panel is a right drawer — min(410, 100% − 12) wide, background-full, p 12, shadow-sidebar, a 40-tall header with the panel name and a close button — over a 40% black backdrop, sliding 300ms. `panel` receives `'100%'` there.
 - **below lg** the `mobileSidebar` rests under the workspace (272 wide, py 12 / pl 6). Opening it slides the whole workspace 272 right and rounds it to 32 while the sidebar scales from 94% and fades in (325ms `cubic-bezier(0.42, 0, 0.58, 1)`); a 10% black / 5% white veil over the workspace closes it. Opening one drawer closes the other.
-- `navOpen` / `panelOpen` are controllable. Reduced motion snaps.
+- **The nav drawer swipes** — dragging in from the left edge opens it and dragging the open drawer back closes it, the drawer following the finger and settling on release by distance (halfway) or by a flick (0.3 px/ms), whichever the release says first. `navSwipeEnabled` (default **`true`**) turns it off: a drawer that cannot be swiped has one way to open on touch, which is what a host migrating off `expo-router`'s `Drawer` loses, so it is on unless a host says otherwise.
+
+  It is armed only where there IS a drawer — below `lg`, and only with a `mobileSidebar`. An opening drag has to start within **24px of the left edge**, travel 12px, and be **twice as horizontal as vertical** before it is claimed: a vertical drag stays the thread's scroll and a horizontal drag anywhere but the edge stays the content's, so a carousel or a scrolling code block inside the chat keeps its gestures. Once the drawer is open the closing drag may start anywhere, because the veil is over all of it by then. On **web only a real touch** is claimed — a mouse drag from the edge is left alone so a selection that starts there survives — and nothing sets `touch-action`, which would have taken horizontal panning away from every scroller inside the workspace.
+- `navOpen` / `panelOpen` are controllable. Reduced motion snaps: the drag itself still tracks the finger 1:1 (it is direct manipulation, not an animation), and only the settle at the end of it jumps rather than travels.
 - **A collapsible rail** — `sidebarWidth` fixes the in-flow column's width, `sidebarCollapsed` narrows it to `collapsedSidebarWidth` (56: one 36px control and its gutters). Without either, the sidebar sizes itself exactly as before. The column snaps between the two widths; whatever animates inside it is the sidebar's own business.
 - **`background` and `surface`** — `background` is any node, drawn above the shell's own background-full and below the sidebar, workspace and drawers; it is never interactive. The workspace paints background-full too, so pass `surface={false}` with it (that drops both) or the layer is covered exactly where the chat sits. When the layer belongs to the chat rather than the page, put it on `AiChatContainer` instead, which is the nearer slot and needs no opt-out.
 - **What the shell publishes** — `useAiChatShell()` returns the shell's state to any descendant: `compact`, `navCollapsed`, `sidebarCollapsed`, `hasNav` / `hasPanel`, `openNav` / `closeNav` / `openPanel`, and **`navPresented`**.

package/docs/ai-profile-card.mdx

@@ -18,8 +18,8 @@ import { AiProfileCard } from '@oxy.so/bloom/ai-profile-card';
   coverSource={cover}
   actions={
     <>
-      <Button variant="secondary" size="small" leadingIcon={RiShare2Line}>Share</Button>
-      <Button variant="secondary" size="small" leadingIcon={RiEditBoxLine}>Edit</Button>
+      <Button size="sm" leadingIcon={RiShare2Line} appearance="outline" tone="neutral">Share</Button>
+      <Button size="sm" leadingIcon={RiEditBoxLine} appearance="outline" tone="neutral">Edit</Button>
     </>
   }
   contributions={7462}

package/docs/announcement.mdx

@@ -36,7 +36,7 @@ import { Announcement } from '@oxy.so/bloom/announcement';
 | icon | 20px, foreground/icon/secondary — default `RiShieldStarFill` |
 | close | `CloseButton` xs at top 12 / right 12 of the card |
 | text | column, gap 2 — title body-medium text/primary, description body-2-medium text/secondary |
-| action | `Button variant="secondary" size="small"`, full width (a full pill — Bloom's button rule) |
+| action | `Button appearance="subtle" tone="neutral" size="sm"`, full width (a full pill — Bloom's button rule) |
 
 Full height with every part: 12 + 20 + 4 + (20 + 2 + 36) + 12 + 32 + 12 = 150
 (plus the 1px border each side).

package/docs/app-shell.mdx

@@ -448,3 +448,71 @@ A medium secondary icon button with the unread count (16px red disc, 1.5px ring
 280 wide, 12 from the bottom-left (`placement="inline"` renders in flow), radius 16, card-coloured hairline, the waitlist shadow; a light band across the top (default: an accent gradient; pass `backdrop` for your own, masked the same way on web), the copy, a full-width CTA with a sweeping shimmer (hidden under reduced motion) and an xs close button. It rises in after `enterDelay` (1.2s). Persisting the dismissal is the host's job.
 
 A live ray-field WebGL backdrop and animated Pro logo are brand artwork and are not included — pass `backdrop` / `logo`.
+
+## Adaptive navigation
+
+---
+
+# AppShell
+
+`AppShell` composes `Screen`, `PageHeader`, `ScreenScrollView` and navigation.
+Use `navigation={[{ value, label, icon }]}`, `value` and `onValueChange` once.
+`navigationPlacement="auto"` chooses bottom below 768, rail from 768 through 1023,
+and sidebar from 1024. Explicit `bottom`, `rail` or `sidebar` overrides that choice.
+
+`primaryAction` accepts Fab props. In bottom placement it appears beside the tab
+capsule and shares its animation; wider placements float it at the bottom-right
+of the content area, independently of the sidebar.
+`header` overrides the default header; `title`, `breadcrumb` and `actions` configure
+that default. `contentMaxWidth` defaults to 1300. `overlay` stays in the screen's
+content tree, before its chrome; dialogs and toasts should use their proper outlets.
+
+Existing `sidebar` data remains accepted and supplies mobile navigation too. An
+explicit `navigation` model wins when both are supplied. The old `drawer`,
+`drawerOpen` and `onDrawerOpenChange` API is removed: select a responsive placement
+and use a separate dialog/sheet when a secondary navigation drawer is needed.
+
+Placement follows the measured shell width (window width is only the pre-layout
+fallback). `navigationMaterial` chooses `solid` or `translucent` on the bottom bar.
+Use `scroll="external"` when the child owns scrolling. For example:
+
+```tsx
+import { AppShell } from '@oxy.so/bloom/app-shell';
+
+<AppShell navigation={items} value={selected} onValueChange={setSelected} scroll="external">
+  <VirtualList screen={{ active: focused }} data={rows} renderItem={renderRow} />
+</AppShell>
+```
+
+There is no surrounding ScrollView in this mode. Native binds the animated list;
+web retains VirtualList's document virtualizer and pins chrome within the shell
+column. Restore by passing `screen={{ active: focused, restoration }}` with the
+same list ref used by `useScrollRestoration`.
+
+## Sidebar surfaces
+
+The desktop navigation uses `Sidebar` for both `navigation` and `sidebar.items`.
+Use `sidebar={{ surface: 'card' }}` for the detached panel (the default): 12px
+space around it, 24px rounded corners, the panel hairline and shadow. Use
+`sidebar={{ surface: 'docked' }}` for a column flush with the shell: no outer
+spacing, square corners, and a separator on its inner edge. These surfaces apply
+to the expanded panel; `navigationPlacement="rail"` keeps the compact rail.
+
+```tsx
+<AppShell navigation={items} sidebar={{ surface: 'card' }} />
+<AppShell navigation={items} sidebar={{ surface: 'docked' }} />
+```
+
+Sidebar configuration (including its logo, collapse control and size) also applies
+when `navigation` supplies the items.
+
+### Responsive navigation motion
+
+The sidebar/rail change fades the existing navigation out, swaps the single
+rendered tree, then interpolates its width while revealing it. Selection remains
+controlled and reduced motion applies the new placement immediately. After the
+transition the animated width resets explicitly to `auto`: returning an empty
+style or an undefined width retained the old width in the browser, leaving a
+260px space after the sidebar itself collapsed to 52px.
+
+The adaptive entry point is selected when `navigation`, `navigationPlacement`, `primaryAction`, or `scroll="auto" | "external"` is supplied. Existing layout calls keep their `dashboard`, `feed`, `split`, `focus`, and `canvas` engine, document/container/fixed scrolling, slots and drawer behavior. Both paths render the same Sidebar, PageHeader and themed surfaces.