@oxy.so/bloom 3.6.0 → 4.1.0

package/docs/proof-of-delivery.mdx

@@ -0,0 +1,82 @@
+---
+title: Proof of delivery
+description: The proofs an app asks for at the door — a signature drawn with a finger or typed, a photo of where it was left, a code the recipient reads out, who took it and a note — each optional, all of them one result.
+order: 139
+---
+
+# Proof of delivery
+
+```tsx
+import { ProofOfDelivery, SignaturePad } from '@oxy.so/bloom/proof-of-delivery';
+
+<ProofOfDelivery
+  proofs={['recipient', 'signature', 'photo']}
+  required={['recipient', 'signature']}
+  onAddPhoto={openCamera}
+  onSubmit={(result) => result.missing.length === 0 && record(result)}
+/>
+```
+
+## Five proofs, five existing controls, one new surface
+
+| proof | control |
+| --- | --- |
+| `recipient` | `TextFieldInput` |
+| `signature` | `SignaturePad` — the one thing this family adds |
+| `code` | `InputOtp`, which already cleans, pads and reports completion |
+| `photo` | `SortablePhotoGrid` |
+| `note` | `Textarea` |
+
+Every one is a `Field`, so the label, the hint, the required mark, the error and the association with the control are said once (`docs/composition.mdx`). Two of the five draw SEVERAL controls — the signature is a pad and a name, the photo is a grid — so those fields are `multiple`: one id on three inputs is invalid HTML, and one error described by three inputs is announced three times.
+
+### Why the photo is not `FileUpload`
+
+`FileUpload` is a DROP ZONE with an upload lifecycle of its own. That is right for a document on a desktop and wrong at a door: the photo comes from a camera the app opens, and what has to be on screen afterwards is the picture, its upload state and a way to take another. `SortablePhotoGrid` is that — the app owns the picker, the grid owns the order, the per-photo progress and the retry.
+
+## The order is the door's, not the caller's
+
+`PROOF_ORDER` is recipient, signature, code, photo, note, and `proofs` is filtered through it whatever order it arrives in. Recipient first because it is the question the courier asks out loud and the answer decides the rest; then the two proofs the RECIPIENT takes part in; then the photo, taken after they have gone; then the note, written about everything above it.
+
+## The confirm control is never disabled
+
+It fires `onSubmit` on every press, with `missing` filled in. Pressing with something outstanding puts the error on each missing field AND an `error` `Admonition` in a `role="alert"` at the bottom naming them, so the answer arrives in the same gesture that asked the question.
+
+A disabled confirm is the failure mode this avoids: the reader presses, nothing happens, and nothing on screen says why — least of all to a screen reader, which is told only that a button is dimmed.
+
+The errors appear only after the first press. A form that is red before it has been filled in is a form that is wrong about the reader.
+
+`submitting` is the one thing that does stop the press, because a second confirm would record the same delivery twice.
+
+**A proof that is required but not DRAWN cannot be missing.** `missingProofs` intersects `required` with `proofs`, so an app that requires a control it never showed cannot refuse a delivery over it.
+
+## `SignaturePad`
+
+- **The pad** is a filled surface at the next level up, radius 12, with a baseline hairline at 72% of its height. A signature is written ON a line; without one a finger starts wherever it lands and the capture reads as a doodle.
+- **The ink** is one `<Path>` per stroke, quadratic through the MIDPOINTS of the samples, round caps and joins, painted in the TEXT colour — a signature is writing, not a brand mark.
+- **The pointer** is one `PanResponder`, which react-native-web routes from real mouse, touch and pen events through its own responder system. The same file draws on both platforms and there is no `.web` fork to keep in step. Points arrive in the pad's own coordinates (`locationX` / `locationY`, measured against the responder node), so a scrolled or transformed page needs no correction.
+- **The pad KEEPS the gesture** (`onPanResponderTerminationRequest: () => false`). A signature crosses a scroller, and an ancestor that stole the gesture mid-word would break the stroke in half and leave the second half unrecorded.
+- Samples closer together than 2px are dropped. A resting finger reports the same coordinate many times a second, and every repeat is a zero-length curve the smoothing then has to average out.
+- **A single tap lays down a DOT.** `signaturePath` emits `M… l0 0` for one point, which a round cap paints as a dot — a full stop in a signature is exactly that. Without it a tap draws nothing and the reader taps harder.
+
+### The typed field is the other half of the control, not a fallback
+
+A pad is a pointer affordance: there is no keyboard gesture for it, a screen reader has nothing to announce but an empty box, and a motor impairment makes it unusable. So both paths are drawn AT ONCE rather than behind a mode switch — a mode a reader has to find is a mode most readers never find — and `isSignatureGiven` treats ink and a typed name as the same answer.
+
+`typed={false}` removes it. That is a deliberate escape hatch for an app collecting the name in a field of its own on the same screen, and it is the only way to ship this control with no accessible path at all.
+
+The pad itself announces as `role="img"` named "Signature" (and "Signature, Signed" once there is ink). The drawn signature IS an image: not operable by keyboard, holding no state ARIA can read.
+
+## What jest cannot see, and where it is checked instead
+
+**A jest test cannot see a canvas.** react-native-svg renders to a native view on one platform and to a `<path>` on the other, and jsdom paints neither.
+
+So the split is deliberate:
+
+- `signaturePath`, `shouldKeepSignaturePoint`, `isProofGiven` and `missingProofs` are PURE, and `src/__tests__/ProofOfDelivery.test.tsx` walks their boundaries — no points, one point, two, a code half entered, a required proof that was never drawn.
+- That ink actually lands under a real pointer is `scripts/verify-signature-pad.mjs`: a real Chrome, `page.mouse.down/move/up` through the browser's own hit testing, reading the emitted `<path d>`. It also runs the negative control — a press with no movement, which must still leave a dot, and a press on a `disabled` pad, which must leave nothing.
+
+## Traps
+
+- **The code counts only once it is FULL.** `InputOtp` reports every keystroke, and "2 of 4 digits" is not a code the recipient read out, so `codeLength` is part of the question rather than something the caller checks after.
+- **`value` is partial and `onChange` is not.** A caller may control one field; the component fills the rest from `EMPTY_PROOF` and always reports the whole thing.
+- **`onAddPhoto` is the app's picker.** Without it the grid draws no add tile — the component opens no camera of its own on either platform.

package/docs/provider.mdx

@@ -1,64 +1,38 @@
 ---
 title: BloomProvider
-description: The one root a consuming app mounts — and why the outlets are deliberately not in it.
-order: 56
+description: Universal application state with an explicit router adapter.
 ---
 
 # BloomProvider
 
-The single root that composes Bloom's app-wide **state** providers, so none of
-them lands at the wrong depth.
+Mount one `BloomProvider` above every render branch, including loading UI. It
+composes theme, image resolution, haptics and scroll storage without importing a
+router. It is exported from both `@oxy.so/bloom` and `@oxy.so/bloom/provider`.
+Without `scrollAdapter`, automatic route restoration is inactive.
 
 ```tsx
 import { BloomProvider } from '@oxy.so/bloom/provider';
+import { expoRouterScrollAdapter } from '@oxy.so/bloom/scroll/expo-router';
 
-export default function RootLayout() {
-  return (
-    <BloomProvider>
-      <Stack />
-    </BloomProvider>
-  );
-}
+<BloomProvider scrollAdapter={expoRouterScrollAdapter}>
+  <App />
+</BloomProvider>
 ```
 
-## Why one root rather than several
+Keep the adapter reference stable. Vite and other router integrations supply their
+own `ScrollRouterAdapter`; Expo consumers now pass the adapter explicitly instead
+of receiving an implicit router dependency.
 
-Depth is not a detail for these. Mounted too low:
+Visual hosts (`ToastOutlet`, `SurfaceHost`, portal/dialog outlets) stay outside the
+provider: their position determines stacking, and mounting duplicate outlets draws
+duplicate surfaces. `Screen` scopes coordinated geometry and motion locally.
 
-- `useScrollRestoration()` **throws** for anything rendered beside it;
-- `useMinimizeState()` silently hands out a private fallback, so two parts of
-  the app disagree about the same state and neither errors.
+The original depth hazards remain: `useScrollRestoration()` throws outside its
+provider, and legacy `useMinimizeState()` creates a private fallback without its
+provider. Mounting providers beneath a sibling scroll region recreates those
+failures. New screen chrome uses the local `Screen` shared values, rather than
+sharing one global motion state across retained routes. `useTheme()` also throws
+outside its provider, including an early-return splash branch on cold start.
 
-One root removes the chance to get that wrong.
-
-## Expo/expo-router apps only
-
-`BloomProvider` binds the scroll store to `expoRouterScrollAdapter`, so it is
-expo-router-only **by construction** — which is also why the family is not on
-the root barrel: importing it would drag `expo-router` into every consumer's
-graph, and Metro does not tree-shake, so an unmet peer is a build failure
-rather than a degradation.
-
-A Vite/SPA consumer mounts the pieces instead: `BloomThemeProvider` plus
-`<ScrollRestorationProvider adapter={…}>` with its own router adapter.
-
-## The OUTLETS are deliberately not in it
-
-`ToastOutlet`, `PortalProvider`/`PortalOutlet`, `SurfaceHost` and the dialog
-hosts stay out. Where an outlet sits in the tree is an app decision — it has to
-paint over the app's own chrome — and **a second mount duplicates every
-surface**. Adding one here would silently double the toasts of any app that
-already mounts its own.
-
-That failure is quiet: two identical toasts read as a double-fire in your own
-code, not as two outlets.
-
-## Where the theme provider goes
-
-Above **every** render branch, including the splash/loading one.
-
-`useTheme()` throws outside `BloomThemeProvider`, and the classic way to hit
-that is an `appIsReady` early-return in `app/_layout.tsx` that renders a splash
-screen *before* the providers mount. It fails at runtime only — `tsc` and the
-build stay green — and only on a cold start. Verify in a real browser after any
-theming migration.
+`PortalProvider`/`PortalOutlet` are native infrastructure; the web portal uses its
+own DOM implementation. Choose outlet placement deliberately and mount each once.

package/docs/radio-indicator.mdx

@@ -27,6 +27,7 @@ import { RadioIndicator } from '@oxy.so/bloom/radio-indicator';
 | `selected`      | filled or hollow                                |
 | `size`          | the diameter (16); the dot and hairline scale   |
 | `selectedColor` | the accent the selected gradient is built from  |
+| `selectedForeground` | foreground paired with a supplied selected fill |
 | `borderColor`   | the ring when not                               |
 
 `pressed` is still accepted and ignored: there is no pressed paint.
@@ -56,12 +57,12 @@ a table row, a settings row with its own affordances.
 
 ## The dot colour is derived, not white
 
-When `selectedColor` is the theme primary, the dot uses the preset's readable
+When `selectedColor` is omitted, the dot uses the preset's readable
 foreground — dark on a yellow primary, light on a blue one. A hardcoded white
 dot disappears on a light accent, which is the same class of failure as
 appending alpha to a token: correct markup, invisible control.
 
-A caller-supplied `selectedColor` falls back to white, because Bloom cannot
+Shared radio controls pass `selectedForeground` with their semantic fill. A caller-supplied `selectedColor` without that foreground falls back to white, because Bloom cannot
 know the right contrast for an arbitrary colour. If you pass one, check it.
 
 ## Selected drops the border

package/docs/radio.mdx

@@ -33,19 +33,19 @@ import { RadioGroup } from '@oxy.so/bloom/radio';
 | `label` (group)           | the accessible name of the whole group — required    |
 | `value` / `onValueChange` | the selection; the group is fully controlled         |
 | `options`                 | the choices, each with its own `label`/`description` |
-| `size`                    | `small` · `medium` · `large`                         |
+| `size`                    | `sm` · `md` · `lg`                         |
 | `disabled`                | the whole group, or one option via its `disabled`    |
 
 ## What it looks like
 
 The dot is [`RadioIndicator`](/docs/bloom/main/radio-indicator); the row puts an 8px gap between it and the label.
 
-|       | `small` | `medium` | `large` |
+|       | `sm` | `md` | `lg` |
 | ----- | ------- | -------- | ------- |
 | dot   | 14      | 16       | 20      |
 | label | `body-2-medium` 13/18 | `body-medium` 14/20 | `headline-medium` 16/22 |
 
-`small` is the `sm` size and `medium` the `md` size; `large` extends the ramp — the same rungs as `Checkbox`, so a form mixing the two lines up. A disabled option dims the whole row to 50%. On web, keyboard focus draws a `ring-2 ring-offset-2` around the dot: a 2px accent ring outside a 2px white offset (white in dark mode too — Tailwind's default offset colour). Text is Inter from Bloom's type ramp. There is no hover or press paint and no press scale — selection is the only thing that animates.
+`sm` is the `sm` size and `md` the `md` size; `lg` extends the ramp — the same rungs as `Checkbox`, so a form mixing the two lines up. A disabled option dims the whole row to 50%. On web, keyboard focus draws a `ring-2 ring-offset-2` around the dot: a 2px accent ring outside a 2px offset matching the scoped page background. Text is Inter from Bloom's type ramp. There is no hover or press paint and no press scale — selection is the only thing that animates.
 
 ## Cards
 
@@ -74,7 +74,7 @@ tapping the words does nothing — which reads as an unresponsive control.
 
 If you need the dot alone — inside a custom row, a card selector, a table cell —
 that is [`RadioIndicator`](/docs/bloom/main/radio-indicator), which is
-presentational and takes `selected`. Using the indicator where you meant the
+presentational and takes `checked`. Using the indicator where you meant the
 control is how a "radio group" ends up announcing as decoration.
 
 ## In a `Field`

package/docs/recent-hires-card.mdx

@@ -33,7 +33,7 @@ import { RecentHiresCard } from '@oxy.so/bloom/recent-hires-card';
 | header | padding 8 8 0; label `body-medium` text-secondary, 2, count `title-1-medium`; team switcher `body-medium` + 16px chevron (text-secondary), gap 6, px 2 |
 | grid | 11 under the header, 2 × 2, gap 8; the two rows share the height left over |
 | person | radius 10, padding 10, `background-inner`, `shadow-card`, space-between: `Avatar` lg (36) + name `body-medium` / joined `body-2-medium` text-secondary (both truncate), gap 8; then the role `Chip` (small, full width, centred, full pill per Bloom's radius rule) |
-| pager | 8 under the grid: two small secondary `Button`s, gap 8, half the width each, arrow-left leading / arrow-right trailing |
+| pager | 8 under the grid: two small subtle neutral `Button`s, gap 8, half the width each, arrow-left leading / arrow-right trailing |
 
 | token | light | dark |
 |---|---|---|

package/docs/route-stops.mdx

@@ -0,0 +1,104 @@
+---
+title: Route stops
+description: An origin, a destination and what is between them — the connector line, a swap for the two-stop case, add and remove, and a "stop reached" state so the same component works while a journey is in progress.
+order: 133
+---
+
+# Route stops
+
+```tsx
+import { RouteStops } from '@oxy.so/bloom/route-stops';
+
+<RouteStops
+  stops={stops}
+  onPressStop={openPlacePicker}
+  onSwap={swap}
+  onAddStop={addStop}
+  onRemoveStop={removeStop}
+/>
+```
+
+## One component for planning and for travelling
+
+`state` (`pending | current | reached`) is what makes a route being PLANNED and a route
+being TRAVELLED the same component. A planner leaves every stop `pending`; a journey in
+progress marks the ones behind it `reached` and the one it is heading for `current`. The
+markers and the rail change, the layout does not, and an app does not swap components
+half way through a trip.
+
+## The marker column is two half-lines
+
+Each stop's marker sits between two `flex: 1` rails inside a 24 column. That is the whole
+alignment mechanism, and it is worth stating because it is what this family does INSTEAD
+of measuring anything:
+
+- the marker centres itself in whatever height the row turns out to be — with a subtitle,
+  with a badge, with a wrapped line, with none of those;
+- the half-rail below one row meets the half-rail above the next exactly, because both
+  are the same computed colour and both end at the row boundary;
+- nothing is nudged, offset or measured, so a row that changes height cannot break the
+  line.
+
+The first row's upper rail and the last row's lower rail are transparent rather than
+absent, so every marker sits at the same place in its row.
+
+## Shape says which stop, colour says how far
+
+| stop | shape |
+| --- | --- |
+| origin | a 12 ring, 3px |
+| between | an 8 dot |
+| destination | a 12 square, 3 radius — an end, not another dot |
+
+`reached` and `current` paint the accent; `pending` paints the graphical rung (the one the
+surface ladder sizes for a line or a glyph, so it clears 3:1 on whatever is behind it).
+
+**The current stop also GROWS**, by 6 (compact 4), and wears its 3px tint ring outside its
+own diameter. A halo drawn inside an 8px dot is two pixels of fill, and it shipped that
+way for one screenshot: the current stop and the one before it were the same dot, so the
+only thing saying which was which was a colour they shared.
+
+The rail fills behind the journey on the same rule the order-status rail uses: travelled
+when the stop BELOW it is reached or current.
+
+## Swap is offered for exactly two stops
+
+With three or more there is no single swap to make, so the control is not drawn. A control
+that silently meant something different at three stops would be worse than no control —
+and "reverse the whole route" is a different action with a different name, which an app
+can put in its own menu.
+
+The swap button lives in a column beside the list, centred against the whole of it, so
+with two stops it lands between them without a magic offset.
+
+## Every word is in one prop
+
+`labels` carries all of it — `origin`, `destination`, `stop(position)`, `swap`,
+`addStop`, `remove(stop)` and the three `state` words. It is one prop rather than nine
+because all of it is copy an app localises and none of it is layout.
+
+`remove` is a FUNCTION of the stop, because "Remove" on five buttons in one list names
+nothing: the default is `Remove ${stop.title}`.
+
+## Accessibility
+
+The stops are a `list` of `listitem`s named as one. Each row's announced name carries its
+POSITION and its STATE before its text — "Destination, not reached, Home, Carrer de l’Om
+14" — because the shape and the colour that say both of those things on screen say
+nothing at all to a screen reader.
+
+**Where that name lands depends on whether the row is a control, and it is one place or
+the other, never both.** A row with `onPressStop` is a button and carries the name itself.
+A read-only row is not a control: `Item`'s non-pressable branch renders `role="none"`,
+which is the one element assistive technology is told to ignore, so the name goes on the
+`listitem` instead. Naming both would announce every stop twice.
+
+Swap and add sit OUTSIDE the list, which is right: they act on the list rather than being
+members of it, so a reader moving through the stops is not interrupted by them.
+
+## Rows are `AddressRow`
+
+Each stop is an `AddressRow` with `leading={null}` — same press target, same density
+rungs, same disabled opacity, same trailing `meta`/`action` pairing. A stop's `action` is
+drawn before the remove affordance, so an app can add its own control per stop without
+losing removal.

package/docs/sankey-chart-card.mdx

@@ -47,10 +47,31 @@ import { SankeyChartCard } from '@oxy.so/bloom/chart-cards';
 
 - recharts' props: `nodeWidth` 12, `nodePadding` 14, `linkCurvature` 0.55, 32 iterations, `sort={false}`, margin top/bottom 2, left 88 and right 150 for the labels. Justified: every sink sits in the last column.
 - Nodes: rounded 5 only on their outward side (sources left, sinks right, pass-through square), so ribbons meet a flat edge (`sankeyNodePath`).
-- Ribbons: one cubic per link stroked at its thickness, stroke-opacity 0.32 at rest; neutral ink ×1.6 (capped 0.85).
+- Ribbons: closed cubic bands with value-proportional vertical thickness, fill-opacity 0.32 at rest; neutral ink ×1.6 (capped 0.85).
 - Labels (Bloom `Text` over the SVG, placed on recharts' baselines — `svg-text.ts`): sources right-aligned 8px left of the node, name `body-2-medium` text-primary over its value `caption-1` text-tertiary (a node under 26px keeps the name only); sinks 8px right, `"Name · 22%"`, the share in text-tertiary. Pass-through nodes are unlabelled.
 - Neutral: light neutral-400 (hover 500), dark neutral-300 (hover 100).
 
 ## Hover
 
-Web hover, native press-and-scrub (letting go clears). The pointer is hit-tested in `hitTestSankey`: nodes first (they paint on top), then the topmost ribbon whose stroke contains the point. A node lifts its ribbons to 0.7, fades the rest to 0.08 and every unconnected node to 35%; a link isolates itself and its two ends. The node fill steps to its `-active` colour. Opacities ease over 200ms and the fill over 150ms (`use-eased-values.ts` — react-native-svg can't CSS-transition presentation attributes); snaps under reduced motion.
+Web hover, native press-and-scrub (letting go clears). The pointer is hit-tested in `hitTestSankey`: nodes first (they paint on top), then the topmost ribbon whose filled band contains the point. A node lifts its ribbons to 0.7, fades the rest to 0.08 and every unconnected node to 35%; a link isolates itself and its two ends. The node fill steps to its `-active` colour. Opacities ease over 200ms and the fill over 150ms (`use-eased-values.ts` — react-native-svg can't CSS-transition presentation attributes); snaps under reduced motion.
+
+
+## Narrow cards
+
+Below 440px of measured plot width, labels stay beside their nodes in proportional
+left and right gutters (starting at 24% and 32%, widening for measured whole words while preserving ribbon space). Full names wrap at their regular 13px text
+size; values and sink percentages sit on a separate line. The flow retains the
+remaining width and its quantitative proportions.
+
+The plot grows when the labels need more vertical room. Their actual rendered
+heights refine the initial estimate, and labels are arranged around node centres
+without overlapping. Subtle leaders connect any displaced label to its node.
+No categories are removed or replaced by a separate legend. Wider cards retain
+the original side labels and fixed height. Layout follows the card's available
+width rather than the window.
+
+
+Ribbons use closed filled bands between each node's top and bottom link edges.
+Their vertical thickness represents value; a narrow, steep curve cannot create
+the side protrusions of an oversized SVG stroke. Pointer hit testing follows the
+same filled boundaries.

package/docs/screen.mdx

@@ -0,0 +1,90 @@
+---
+title: Screen
+description: Continuous content with coordinated header, scrolling and bottom chrome.
+---
+
+# Screen
+
+`Screen` owns a continuous page canvas. `header` and `bottomBar` overlay the content;
+`ScreenScrollView` reserves their measured footprints, adding its own content padding.
+Safe-area padding belongs to the chrome, so it is included exactly once in those measurements.
+
+```tsx
+import { Screen, ScreenScrollView } from '@oxy.so/bloom/screen';
+
+<Screen header={<PageHeader title="Inbox" />} bottomBar={<Navigation />}>
+  <ScreenScrollView><Messages /></ScreenScrollView>
+</Screen>
+```
+
+`PageHeader` automatically reads its enclosing screen's offset. `useScreen()` exposes
+`scrollY` and `collapseProgress` to coordinated chrome. Pass `collapseProgress` as
+`BottomBar`'s `minimizeProgress`; navigation and the lateral action then move together.
+
+For a virtualized list, call `useScreenScroll({ active, handler })`, bind `onScroll`,
+and apply `contentInsets.top`/`bottom` to its content container. `handler` accepts a
+processed Reanimated handler, preserving drag and momentum subscriptions. Only the
+active binding drives chrome. Set `active={false}` on retained background lists.
+Nested `Screen`s keep scroll offsets local. Under AppShell they inherit navigation motion and bottom clearance; `navigationScope="isolated"` creates an independent modal scope. Do not place several active scrollers
+in one screen; designate the primary list explicitly.
+
+`ScreenScrollView` forwards its ref. Scroll restoration remains the independent
+`useScrollRestoration` binding: pass it as `restoration={binding}` and pass the same ref. Pending restored content
+stays laid out with opacity zero; native offset recording is forwarded automatically. Web restoration observes the actual DOM scroller itself.
+
+The shell does not choose a router or create overlay outlets. Measurements settle
+on layout; content footprint stays expanded while visual chrome contracts, avoiding
+scroll-range changes during animation.
+
+For a standalone action, `primaryAction={<Fab ... />}` anchors a static action
+inside the screen. With navigation, pass the action to `BottomBar.action` instead.
+`headerHeight` and `bottomBarHeight` declare initial footprints for custom chrome;
+defaults match Bloom's 56-point header and 58-point bottom bar plus safe area.
+Measured heights replace those estimates. Custom chrome should declare its height
+to prevent the first layout changing the content's padding.
+
+On web, `documentScroll` makes the document the scroller: Screen grows with its
+children and automatically observes `window.scrollY`. Do not wrap ordinary
+content in a ScrollView or constrain Screen to a fixed-height flex slot.
+
+```tsx
+<Screen documentScroll header={<PageHeader title="Home" />} bottomBar={<Navigation />}>
+  <LongContent />
+</Screen>
+```
+
+Header and bottom chrome stay sticky within the Screen column's width. Screen
+reserves their measured footprints in document flow, including bottom clearance;
+content can scroll fully above the bottom bar. The initial declared heights still
+apply before measurement. Without chrome slots Screen adds no content padding,
+so a composed shell can own those slots and their spacing itself.
+
+`VirtualList screen={{ active, restoration }}` connects both platforms without a
+surrounding ScrollView. Use `useScreenWindowScroll` for another window virtualizer;
+its explicit writer takes priority over Screen's automatic listener. During a
+pending restoration it updates the offset without collapsing navigation. When
+that binding unmounts, automatic window tracking resumes. Returned `contentInsets`
+are zero in document mode because Screen already reserves the spacing; applying
+them does not add a second footprint. `useScreenScroll` remains the animated
+native/container binding. Only one explicit scroller should be active per scope.
+
+When navigation retains whole screens, set `Screen active={focused}` (or
+`AppShell active={focused}`). That boundary disables every descendant scroll
+writer; an explicitly isolated modal keeps its own navigation scope. During restoration,
+offsets update the header but do not trigger a new collapse. On native, showing
+the keyboard hides bottom chrome and releases its reserved content footprint;
+hiding it restores the previous footprint.
+
+AppShell establishes `navigationScope="shared"`. Route Screens use the default
+`inherit`: their local header offset is independent, while the focused list owns
+the shared navigation progress. Set every retained route's `active` explicitly;
+use `navigationScope="isolated"` for modal screens that cover the shell navigation.
+
+
+### Storybook document hosts
+
+Full-screen stories that demonstrate document scrolling declare
+`parameters: { layout: 'fullscreen', bloomScroll: 'document' }`. The preview then
+uses a minimum viewport height, allowing the document to grow. Contained demos
+keep a bounded height. This is a preview host choice, not an application prop;
+consumer roots must likewise allow the document to grow.

package/docs/search.mdx

@@ -14,7 +14,7 @@ import { Search } from '@oxy.so/bloom/search';
 
 <Search
   value={query}
-  onChangeText={setQuery}
+  onValueChange={setQuery}
   onClearText={() => setQuery('')}
   label="Search people"
 />

package/docs/segmented-control.mdx

@@ -16,7 +16,7 @@ import {
   SegmentedControlItemText,
 } from '@oxy.so/bloom/segmented-control';
 
-<SegmentedControl label="Appearance" type="radio" value={mode} onChange={setMode}>
+<SegmentedControl label="Appearance" type="radio" value={mode} onValueChange={setMode}>
   <SegmentedControlItem value="light">
     <SegmentedControlItemText>Light</SegmentedControlItemText>
   </SegmentedControlItem>
@@ -75,13 +75,13 @@ a field the group announces nothing.
 | `label`    | the accessible name of the whole group          |
 | `type`     | radio group vs tab list (see above)             |
 | `value`    | the selected segment — fully controlled         |
-| `onChange` | receives the pressed segment's `value`          |
-| `size`     | `small` (32) · `medium` (36, default) · `large` (44) |
+| `onValueChange` | receives the pressed segment's `value`          |
+| `size`     | `sm` (32) · `md` (36, default) · `lg` (44) |
 | `variant`  | `solid` (track + sliding thumb) or `plain`      |
 
 ## What it looks like
 
-A segmented control, in Bloom's colours. `medium` is the default control:
+A segmented control, in Bloom's colours. `md` is the default control:
 28-tall segments with 10px side padding on a 4px-padded track, 2px apart.
 
 - **Track** neutral-100 (dark: neutral-925); **thumb** the card surface (dark:
@@ -91,7 +91,7 @@ A segmented control, in Bloom's colours. `medium` is the default control:
   is regular weight in neutral-500 and turns primary on hover.
 - Track and thumb are full pills, like `Button`.
 - `variant="plain"` draws no track, padding or thumb.
-- Text is Inter from the type ramp: `body` (`body-2` at `small`), `-medium` when selected and `-regular` when not.
+- Text is Inter from the type ramp: `body` (`body-2` at `sm`), `-medium` when selected and `-regular` when not.
 - Disabled segments sit at 50%; keyboard focus rings the segment (2px).
 
 The control hugs its segments. To fill a row, stretch it (`style={{ alignSelf:
@@ -105,3 +105,16 @@ active from context. Passing one is a type error.
 - More than about four options, or long labels: a [`Select`](/docs/bloom/main/select).
 - A view of the same subject with real panels underneath: [`Tabs`](/docs/bloom/main/tabs).
 - A single on/off: [`Switch`](/docs/bloom/main/switch).
+
+## Drag selection
+
+Drag horizontally to move the thumb continuously across measured segment widths.
+Selection commits once on release; disabled items are skipped and cancellation
+returns to the controlled value. Vertical movement remains available to scrolling.
+Taps and keyboard activation preserve radio/tab semantics. Settling respects the
+system reduced-motion preference. Native apps mount `GestureHandlerRootView` at
+the application root, as for BottomBar. The plain variant also accepts dragging.
+
+## 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/select.mdx

@@ -107,13 +107,13 @@ It used to take a render prop instead, which handed its child a `state` object w
 ```tsx
 <Select value={status} onValueChange={setStatus}>
   <SelectTrigger label="Purchase status">
-    <SelectValue leading={(item) => item && <Badge dot color={(item as Status).tone} />} />
+    <SelectValue leading={(item) => item && <Badge dot tone={(item as Status).tone} />} />
     <SelectIcon />
   </SelectTrigger>
   <SelectContent
     items={STATUSES}
     renderItem={(item) => (
-      <SelectItem value={item.value} label={item.label} leading={<Badge dot color={item.tone} />}>
+      <SelectItem value={item.value} label={item.label} leading={<Badge dot tone={item.tone} />}>
         <SelectItemText>{item.label}</SelectItemText>
       </SelectItem>
     )}

package/docs/settings-list.mdx

@@ -56,7 +56,7 @@ The group renders a rounded card on iOS-style platforms and on web. The first it
 <SettingsListItem
   icon={<MoonIcon />}
   title="Dark mode"
-  rightElement={<Switch value={darkMode} onValueChange={setDarkMode} />}
+  rightElement={<Switch checked={darkMode} onCheckedChange={setDarkMode} />}
 />
 ```
 
@@ -202,9 +202,9 @@ fill.
   title="Notifications"
   footer="Push notifications require an enabled device permission."
 >
-  <SettingsListItem title="Marketing emails" rightElement={<Switch value={mktg} onValueChange={setMktg} />} />
+  <SettingsListItem title="Marketing emails" rightElement={<Switch checked={mktg} onCheckedChange={setMktg} />} />
   <SettingsListDivider />
-  <SettingsListItem title="Product updates" rightElement={<Switch value={prod} onValueChange={setProd} />} />
+  <SettingsListItem title="Product updates" rightElement={<Switch checked={prod} onCheckedChange={setProd} />} />
 </SettingsListGroup>
 ```