@oxy.so/bloom 2.12.4 → 3.0.0

package/README.md

@@ -20,7 +20,7 @@
 
 ### What it is
 
-Components, hooks and design tokens published as `@oxy.so/bloom` across 167 subpath exports, shipped as `src` for Metro and as compiled CommonJS and ESM for everyone else. Web builds resolve platform forks automatically through export conditions, so a `.web.tsx` fork never reaches a native bundle.
+Components, hooks and design tokens published as `@oxy.so/bloom` across 168 subpath exports, shipped as `src` for Metro and as compiled CommonJS and ESM for everyone else. Web builds resolve platform forks automatically through export conditions, so a `.web.tsx` fork never reaches a native bundle.
 
 Styling is NativeWind classes throughout. There are no colour props and no wrapper components to theme a button, because a second way to set a colour is a second thing that can disagree.
 
@@ -151,11 +151,11 @@ Every palette is generated from a single seed colour by a dependency free colour
 
 ## Components
 
-Bloom publishes 167 subpath exports. Importing from the subpath rather than the root keeps a bundle to what it actually renders.
+Bloom publishes 168 subpath exports. Importing from the subpath rather than the root keeps a bundle to what it actually renders.
 
 | Group | Exports |
 |---|---|
-| Providers and theme | `provider`, `theme`, `theme-toggle`, `color-presets`, `preset-vars`, `design-tokens`, `tailwind-preset`, `styles`, `hooks` |
+| Providers and theme | `provider`, `theme`, `theme-toggle`, `color-presets`, `preset-vars`, `design-tokens`, `tailwind-preset`, `styles`, `control-surface`, `hooks` |
 | App shell and navigation | `app-shell`, `page-header`, `sidebar`, `rail`, `breadcrumb`, `pagination`, `tabs`, `tab-bar`, `layout`, `content-panel` |
 | Overlays | `dialog`, `alert-dialog`, `bottom-sheet`, `popover`, `context-menu`, `dropdown-menu`, `menubar`, `tooltip`, `overlay`, `portal`, `teleport`, `surfaces`, `settings-modal` |
 | Actions | `button`, `button-group`, `social-button`, `fab`, `frosted-icon-button`, `pressable-scale`, `subtle-hover` |
@@ -175,7 +175,7 @@ Bloom publishes 167 subpath exports. Importing from the subpath rather than the
 
 ## Documentation
 
-Component guides live in [`docs/`](./docs), one `.mdx` per family, and **they ship inside the package** at `node_modules/@oxy.so/bloom/docs/`. The copy you read there always describes the version you installed, which matters most for [migrating to 2.0](./docs/migrating-to-2.0.mdx).
+Component guides live in [`docs/`](./docs), one `.mdx` per family, and **they ship inside the package** at `node_modules/@oxy.so/bloom/docs/`. The copy you read there always describes the version you installed, which matters most for [migrating to 3.0](./docs/migrating-to-3.0.mdx).
 
 Start with [getting started](./docs/getting-started.mdx), [theme](./docs/theme.mdx) and [design tokens](./docs/design-tokens.mdx). Then per surface: [app shell](./docs/app-shell.mdx), [sidebar](./docs/sidebar.mdx), [data table](./docs/data-table.mdx), [chart cards](./docs/chart-cards.mdx), [composer panel](./docs/composer-panel.mdx), [dialog](./docs/dialog.mdx), [bottom sheet](./docs/bottom-sheet.mdx), [toast](./docs/toast.mdx), [alert](./docs/alert.mdx), [dropdown menu](./docs/dropdown-menu.mdx), [select](./docs/select.mdx), [context menu](./docs/context-menu.mdx), [button](./docs/button.mdx), [avatar](./docs/avatar.mdx), [text field](./docs/text-field.mdx), [settings list](./docs/settings-list.mdx), [tab bar](./docs/tab-bar.mdx) and [loading](./docs/loading.mdx).
 

package/docs/button-group.mdx

@@ -1,12 +1,15 @@
 ---
 title: ButtonGroup
-description: Secondary-style buttons fused into one bordered pill — toolbars, filters and pagers.
+description: Buttons the consumer declared as one control — a fused bordered pill, or one translucent island — for toolbars, filters, pagers and a floating header's actions.
 order: 11
 ---
 
 # ButtonGroup
 
-A row of secondary-style buttons fused into one control: one bordered, shadowed container, items divided by 1px hairlines, only the outer ends rounded. The container is a full pill, like `Button`. Colours come from the same Bloom-derived ramps as `Button` (`src/button/shared.ts`).
+A row of buttons declared as ONE control. Two materials:
+
+- **`solid`** (default): secondary-style buttons fused into one bordered, shadowed container, items divided by 1px hairlines, only the outer ends rounded. The container is a full pill, like `Button`. Colours come from the same Bloom-derived ramps as `Button` (`src/button/shared.ts`).
+- **`glass`**: the same group as a floating **island** — one translucent pane the items sit flush on, with no fill and no blur of their own.
 
 ```tsx
 import { ButtonGroup, ButtonGroupItem } from '@oxy.so/bloom/button-group';
@@ -18,6 +21,40 @@ import { ButtonGroup, ButtonGroupItem } from '@oxy.so/bloom/button-group';
 </ButtonGroup>
 ```
 
+## Materials
+
+```tsx
+<ButtonGroup variant="glass" accessibilityLabel="Page actions">
+  <ButtonGroupItem iconOnly leadingIcon={RiSearchLine} accessibilityLabel="Search" />
+  <ButtonGroupItem iconOnly leadingIcon={RiShare2Line} accessibilityLabel="Share" />
+</ButtonGroup>
+```
+
+The variant is **inherited** when you do not name it: a `ButtonGroup` inside a floating [`PageHeader`](/docs/page-header)'s `actions` is glass with no prop written on it, and the same group inside a card is solid without one either. An explicit `variant` still wins. The rule and its limits are in [Composition](/docs/composition).
+
+On glass:
+
+- The GROUP owns the material. Items paint `transparent` at rest, and their hover/press states are an alpha of the theme's own `text` — an ink wash, not a fill. That is the one recipe that survives a backdrop Bloom cannot predict: a fixed neutral tuned against the island's fill disappears the moment a photograph moves the pane 40 levels, while a wash of the label's colour keeps the same relation to the label at every composite.
+- Items round their own press highlight, because the island does not clip. (`overflow: hidden` on a glass box clips the iOS drop shadow away.)
+- `dividers` defaults to **false**. A hairline is how a solid pill says "separate controls, fused"; over a moving backdrop it reads as an artifact of the material. Pass `dividers` to draw them anyway.
+
+## Items as triggers
+
+`ButtonGroupItem` declares the props an anchored family's `asChild` trigger merges onto it, so a menu button inside a group is an item OF that group rather than a second control that looks like one:
+
+```tsx
+<ButtonGroup accessibilityLabel="Page actions">
+  <Popover>
+    <PopoverTrigger asChild label="More">
+      <ButtonGroupItem iconOnly leadingIcon={RiMore2Line} accessibilityLabel="More" />
+    </PopoverTrigger>
+    <PopoverContent label="More">…</PopoverContent>
+  </Popover>
+</ButtonGroup>
+```
+
+The item announces its own expanded state on both platforms. A control whose props are a closed list would have dropped `aria-expanded`, `aria-haspopup` and `onLongPress` silently, since all of them are optional — see [Composition](/docs/composition).
+
 ## Selection
 
 `selected` paints an item with its hover fill and announces it as pressed (`aria-pressed` on web, `accessibilityState.selected` on native). Drive it from state for single- or multi-select toolbars; leave every item unselected for a pure action row. For an animated thumb, use `SegmentedControl`.
@@ -46,11 +83,16 @@ Text is `body-medium` (Inter 14/20 500) through Bloom's typography `Text` — a
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `ButtonGroup.size?` | `'medium' \| 'small'` | `'medium'` | Size for every item. |
+| `ButtonGroup.variant?` | `'solid' \| 'glass'` | inherited, then `'solid'` | The material the group paints. |
+| `ButtonGroup.size?` | `'medium' \| 'small'` | inherited, then `'medium'` | Size for every item. |
+| `ButtonGroup.dividers?` | `boolean` | `solid` → `true`, `glass` → `false` | Hairlines between items. |
 | `ButtonGroup.accessibilityLabel?` | `string` | — | Names the group. |
-| `ButtonGroupItem.onPress?` | `() => void` | — | Press handler. |
+| `ButtonGroupItem.onPress?` | `(event) => void` | — | Press handler. Receives the event, so a composed trigger handler can `preventDefault()` it. |
 | `ButtonGroupItem.selected?` | `boolean` | `false` | Hover fill + pressed state. |
 | `ButtonGroupItem.disabled?` | `boolean` | `false` | Disabled paint, blocks presses. |
 | `ButtonGroupItem.iconOnly?` | `boolean` | `false` | Square icon-only item. |
 | `ButtonGroupItem.leadingIcon?` / `trailingIcon?` | `BloomIconComponent` | — | Icon components. |
 | `ButtonGroupItem.size?` | `'medium' \| 'small'` | group size | Per-item override. |
+| `ButtonGroupItem.variant?` | `'solid' \| 'glass'` | group material | Per-item override. Rarely needed — the group owns it. |
+| `ButtonGroupItem.hitSlop?` | `number \| {top,bottom,left,right}` | — | Extra touch area. NOT defaulted: items in a group are adjacent, so slop on one overlaps its neighbour. Use it for an item that stands alone in its own island. |
+| `ButtonGroupItem.onLongPress?` / `aria-expanded` / `aria-haspopup` / `accessibilityRole` | | — | The trigger contract, set by an anchored family. |

package/docs/composition.mdx

@@ -0,0 +1,159 @@
+---
+title: Composition
+description: How Bloom components work together — the inherited presentation contract, field membership, trigger composition, scroll ownership and edge claims — with what is done and what is not.
+order: 3
+---
+
+# Composition
+
+Bloom components share tokens. Sharing tokens is not the same as working together: a control still has to be told what material the container around it is painting, a label still has to be wired to the control it names, and a header still has to know which scroller it is following. Written as props, each of those is a thing the app repeats at every call site and gets wrong at one of them.
+
+This page is the set of small, explicit contracts that answer those questions, and the rules that keep them small. Each is a context a container publishes and a component opts into. None of them is a framework, a singleton, or a component that reads its children's types to decide what to do with them.
+
+## The precedence rule
+
+Every contract on this page resolves the same way:
+
+```
+an explicit prop  >  the nearest container  >  the component's own default
+```
+
+`undefined` is the only value that defers. Passing `variant="solid"` inside a glass island paints a solid control — the container is a default, not an override, and a caller can always win.
+
+**A constraint is not a default.** Anything that RESTRICTS a control — `disabled`, a modal's inertness, the user's reduce-transparency or reduce-motion preference — travels on its own channel and combines with `||`, never `??`. The rule above is exactly wrong for those: a descendant must not be able to re-enable an action its group disabled by passing a prop.
+
+**State does not travel either.** `checked`, `selected`, a field's value, a business datum: those belong to the component that holds them. A visual context that also carried state would make every container a place state can leak from.
+
+## Control presentation — `ControlSurface`
+
+`@oxy.so/bloom/control-surface`
+
+What a container tells the controls inside it about presentation, and nothing else. Two fields, both visual configuration:
+
+| field | values | meaning |
+| --- | --- | --- |
+| `material` | `'solid'` \| `'glass'` | the surface a control CONTAINER paints |
+| `density` | `'medium'` \| `'small'` | the size controls default to |
+
+```tsx
+import { ControlSurface } from '@oxy.so/bloom/control-surface';
+
+<ControlSurface material="glass">
+  <ButtonGroup accessibilityLabel="Playback">…</ButtonGroup>
+</ControlSurface>
+```
+
+It renders no node of its own, so it can be dropped anywhere without moving anything. Bloom's own containers mount it for you — `glass/GlassIsland` does, which is why a `ButtonGroup` inside a floating `PageHeader` is glass with no prop written on it.
+
+A field left `undefined` inherits rather than resetting: `<ControlSurface density="small">` inside a glass island stays glass.
+
+**Who reads it today:** `ButtonGroup` and `ButtonGroupItem`. `Button` does not — a `Button` in a floating header keeps its own chrome, which is right for a primary action in its own capsule and wrong for an icon action that should sit flush on an island. Use `ButtonGroup`/`ButtonGroupItem` for the latter. Extending this to more families is adoption work, not a gap in the contract; see [What is not done](#what-is-not-done).
+
+Precedence is gated in both directions by `src/__tests__/ControlSurface.test.tsx`, including the assertion that the context carries exactly two fields.
+
+## Field membership — `Field`
+
+`@oxy.so/bloom/field`
+
+A `Field` used to draw a label, a control and a hint, and wire none of them together. It associates them now: the control's id, `aria-describedby` for whichever of description/error is showing, the invalid state, the required state and the disabled state.
+
+```tsx
+<Field label="Email" description="We never share it." error={emailError} required>
+  <TextFieldInput label="Email" value={email} onChangeText={setEmail} />
+</Field>
+```
+
+- **Ids come from `useId`** when no `nativeID` is given, so they survive SSR and hydration. An explicit `nativeID` still owns every derived id.
+- **The control's accessible NAME is the field's label.** On web a `<label for>` is a real association, but `aria-label` would override it; on native there is no association at all and the control must carry the name. So a control inside a field defers to the field's label text, and the visible label and the announced name cannot disagree.
+- **`disabled` is a constraint.** A control inside a disabled field is disabled, and cannot opt out.
+- **`multiple` is the several-controls case** — a radio set, a date's three boxes. The field becomes a labelled `group`, publishes no control id and describes the GROUP rather than each control: one id on three inputs is invalid HTML, and one error described by three inputs is announced three times.
+- **A floating label and a `Field` label are alternatives, not layers.** `<TextFieldInput floatingLabel>` inside a `Field label="…"` shows the same words above the box and inside it. Pick one.
+
+A control opts in by reading `useFieldControl()`:
+
+```tsx
+const field = useFieldControl();
+<TextInput
+  nativeID={field?.controlId ?? nativeID}
+  aria-describedby={field?.describedBy}
+  aria-invalid={field?.invalid || isInvalid || undefined}
+  accessibilityLabel={field?.labelText ?? label}
+  editable={!(field?.disabled || disabled)}
+/>
+```
+
+Opt-in, not magic. A child that does not read the context renders exactly as before — a container cannot give an arbitrary child behaviour by wrapping it, and one that inspected its children's types to try would be guessing.
+
+**Who reads it today:** `TextFieldInput` (both the default and floating-label renderings). Gate: `src/__tests__/FieldAssociation.test.tsx`.
+
+## Trigger composition — `asChild`
+
+Every anchored family (`Popover`, `DropdownMenu`, `ContextMenu`, `Menubar`, `Select`) takes `asChild` and merges its open handler and a11y state onto the caller's single element child. Three properties are worth knowing:
+
+- **The child's handler runs first, and can CANCEL the open.** `event.preventDefault()` in the child's `onPress` stops the surface from opening — for a trigger that has just found the form dirty, or the row it belongs to gone. It is the event's own vocabulary because both platforms hand `onPress` a React synthetic event. On web the same call also suppresses the browser's default for that click, so cancelling on an anchor child cancels its navigation too.
+- **A fragment child is refused.** `<Trigger asChild><>{control}</></Trigger>` passes every check a clone can make and then drops every prop, because a fragment has no host node. It throws now, naming the fix.
+- **`disabled` is read from BOTH sides** — the trigger's own prop and the child's — in `cloneTrigger`, not left to whatever element the caller passed.
+
+**A control used as a trigger must DECLARE the props it will be handed.** A component whose props are a closed list drops the ones it does not name, silently, because all of them are optional. `ButtonGroupItem` declares them, so this works:
+
+```tsx
+<ButtonGroup accessibilityLabel="Page actions">
+  <Popover>
+    <PopoverTrigger asChild label="More">
+      <ButtonGroupItem iconOnly leadingIcon={RiMore2Line} accessibilityLabel="More" />
+    </PopoverTrigger>
+    <PopoverContent label="More">…</PopoverContent>
+  </Popover>
+</ButtonGroup>
+```
+
+Gate: `src/__tests__/TriggerComposition.test.tsx`.
+
+## Scroll ownership — `ScrollOffsetProvider`
+
+`@oxy.so/bloom/layout`
+
+A screen has exactly one scroll owner, and the owner publishes its offset. Chrome reads it. Neither imports the other, so the provider's position in the tree is what pairs them — two panels side by side, each with its own header and its own scroller, resolve correctly.
+
+```tsx
+const scrollY = useSharedValue(0);
+const onScroll = useAnimatedScrollHandler(
+  { onScroll: (e) => { scrollY.value = e.contentOffset.y; } },
+  [scrollY],
+);
+
+<ScrollOffsetProvider value={scrollY}>
+  <PageHeader title="Inbox" />
+  <Animated.ScrollView onScroll={onScroll} scrollEventThrottle={16}>…</Animated.ScrollView>
+</ScrollOffsetProvider>
+```
+
+The context carries the `SharedValue`, not a number. It crosses once, at mount; every subsequent frame reaches the chrome on the UI thread through `useAnimatedStyle`, with no React render. A context whose value changed per frame would re-render every consumer per frame, which is the cost this exists to avoid.
+
+`PageHeader` resolves its offset as: the `scrollY` prop, then this context, then `window.scrollY` on web. Without any of the three on native it stays at rest. The context step is the one that matters for a desktop shell, where `window.scrollY` never moves and a header that followed it looked deliberately inert.
+
+## Edge claims — `TopEdgeProvider` / `BottomEdgeProvider`
+
+`@oxy.so/bloom/layout`
+
+A surface that parks at a window edge CLAIMS its footprint; a surface or a scroll container that must clear it READS the total. Claims combine with `max`, not sum — every claim is measured from the same edge, so two surfaces at that edge overlap rather than stack.
+
+The bottom edge is the tab bar and the FAB (`docs/fab.mdx`). The top edge is chrome that overlays content:
+
+```tsx
+<ScrollView contentContainerStyle={{ paddingTop: useTopEdgeInset() }}>
+```
+
+`BloomProvider` mounts both. A nested provider scopes a subtree to its own claims — a full-screen modal with its own header, whose content must clear the MODAL's header rather than the screen's.
+
+A claim registers in an effect, so a reader mounted in the same commit sees `0` on its first render. `PageHeader` narrows that to one frame by claiming its resting height (safe area + 56) immediately and replacing it with the measured height when `onLayout` reports.
+
+## What is not done
+
+This page describes contracts that exist and are gated. Issue #145 asks for more than that, and the rest is honest to name:
+
+- **No full inventory of the public API.** The matrix over every family — platforms, contexts, state families, triggers, semantics, styles, tests — has not been produced. Nothing here should be read as "the library was audited"; it was extended where the header integration needed it.
+- **State-family naming is not unified.** `value`/`defaultValue`/`onValueChange`, `checked`/`onCheckedChange` and `open`/`onOpenChange` are used consistently by the families that have them, and `useControllableState` is the shared implementation, but no sweep has been made to rename the exceptions (`onChangeText` among them, which is a React Native contract worth keeping).
+- **Only two families read `ControlSurface`, and one reads `Field`.** Every other control renders as it always did. Adoption is per-family work with its own regressions to check.
+- **`BloomProvider` still imports the Expo Router adapter directly.** Decoupling the core from the router is listed in #145 §8 and is not in this change.
+- **No adaptive overflow.** Actions that do not fit are not collapsed into a menu. #145 says explicitly that this is not required for the first header, and nothing here does it.

package/docs/field.mdx

@@ -35,7 +35,45 @@ import { TextField, TextFieldInput } from '@oxy.so/bloom/text-field';
 | `error`       | the message; `null` or omitted means valid                    |
 | `required`    | the required marker and the announced requirement             |
 | `disabled`    | dims the whole group                                         |
-| `nativeID`    | the id the label and control are wired through                |
+| `multiple`    | the field holds several controls — a labelled `group`         |
+| `nativeID`    | the id the label and control are wired through; generated when omitted |
+
+## What the wiring actually does
+
+The label, description and error are ASSOCIATED with the control, not merely stacked around it. A control opts in by reading `useFieldControl()`; Bloom's `TextFieldInput` does.
+
+| the field publishes | the control applies |
+| --- | --- |
+| `controlId` | its `nativeID`, so the label's `for` points at it |
+| `describedBy` | `aria-describedby` — the description, or the error once there is one |
+| `labelText` | its accessible NAME |
+| `invalid` | `aria-invalid` |
+| `required` | `aria-required` |
+| `disabled` | its own disabled state |
+
+Three things worth knowing:
+
+- **The ids come from `useId`** when no `nativeID` is given, so they survive SSR and hydration. An explicit `nativeID` still owns every derived id (`<id>-description`, `<id>-error`), so a form already wired by hand keeps working.
+- **The field's label wins over the control's own.** On web `aria-label` OVERRIDES a `<label for>`, and on native there is no association at all and the control must carry the name — so a control inside a field defers to the field's label text, and the visible label and the announced name cannot disagree.
+- **`disabled` is a constraint, not a default.** A control inside a disabled field is disabled and cannot opt out.
+
+Opt-in, not magic: a child that does not read the context renders exactly as before. A container cannot give an arbitrary child behaviour by wrapping it, and one that inspected its children's types to try would be guessing. See [Composition](/docs/composition).
+
+## One control, or several
+
+A field with ONE control gives it the field's id and describes the error BY that control. A field with several — a radio set, a date's three boxes — must not: three inputs sharing one id is invalid HTML, and one error described by three inputs is announced three times.
+
+```tsx
+<Field label="Date of birth" multiple error={dobError}>
+  <DayInput /> <MonthInput /> <YearInput />
+</Field>
+```
+
+`multiple` makes the field a `role="group"` labelled by its own label and described by its own hint, and publishes no control id. Each control keeps its own id and its own name.
+
+## Floating labels are an alternative, not a layer
+
+`<TextFieldInput floatingLabel>` inside a `Field label="…"` shows the same words above the box and inside it. The ids and the described-by still travel, so the error is still announced — but pick one of the two labels.
 
 ## `error` is a string, not a boolean
 

package/docs/glass.mdx

@@ -92,3 +92,49 @@ Three things the table settles:
 
 So there is no single alpha that both matches the reference and reads as glass on a flat surface. That is a property of the material — a blur needs a backdrop — not a constant nobody has tuned yet. To make a specific surface read as glass, put something behind it.
 
+
+## The chrome role
+
+Everything above prices a **brand** fill: a `primary`-coloured pane over one of Bloom's own five neutral surfaces, labelled with that fill's on-colour. A page header's island is the other case, and almost nothing about it is the same:
+
+| | accent | chrome |
+| --- | --- | --- |
+| fill | the caller's brand token | rung 1 of the surface ladder — the fill a card and a menu panel paint |
+| label | the fill's own on-colour | the theme's own `text` |
+| backdrop | Bloom's five neutral surfaces | anything: a photograph, a video still, a map |
+| alpha | 0.85 | 0.72 light · **0.80 dark** |
+
+Inside Bloom — `theme/glass-colors.ts` is not a published subpath, for the same reason `resolveGlassColors` is not:
+
+```tsx
+import { resolveSurfaceLevel } from '../styles/surface-levels';
+import { resolveChromeGlassColors } from '../theme/glass-colors';
+
+const level = resolveSurfaceLevel(theme, 1);
+const glass = resolveChromeGlassColors(level.background, level.border, theme.isDark);
+```
+
+Both arguments are resolved colour strings the caller already holds, because the caller is the only one that knows which rung of the ladder its container sits on.
+
+**Dark carries the higher alpha**, which is the opposite of the intuition that a dark UI can afford more transparency. The worst case for each mode is the backdrop it is furthest from: a light pane is washed *down* over black and barely moves, because it is already near white; a dark pane over white has the whole luminance range above it to be washed out into.
+
+Because the backdrop is unknown, the range measured is the **whole** range — pure white and pure black. Every composite a real backdrop can produce lies between them on every channel, so a pane that clears AA at both ends clears it everywhere between.
+
+Measured over 64 presets × 2 modes × 2 endpoints × 2 platforms (512 rows), with the theme's own `text` as the label:
+
+| | failures below AA | worst ratio |
+| --- | --- | --- |
+| light | 0 / 256 | **8.23** (over black, web) |
+| dark | 0 / 256 | **6.43** (over white, web) |
+
+and the pane still moves **49.98–69.97** of 255 between a black and a white backdrop, so it is glass rather than a tinted slab. Web is the worse of the two platforms in both modes: `expo-blur`'s own tint adds body on native that CSS `backdrop-filter` does not.
+
+Gate: `src/theme/__tests__/chrome-glass.test.ts`, which pins the two floors to the hundredth and the translucency range with **literal** bounds. A floor derived from the alpha constant would move with it, so an opaque material would satisfy its own floor.
+
+## Islands
+
+`glass/GlassIsland` is the assembly: the material, the hairline, the geometry and the drop shadow, in the order that works. `GlassSurface` deliberately owns none of the last three — it clips itself, and a shadow drawn on a clipping node is clipped away on iOS — so every caller that wants a floating pane would otherwise repeat the same four steps.
+
+An island also mounts a `ControlSurface` with `material: 'glass'`, so controls inside it paint flush. That is the material's rule rather than a preference: a translucent pane inside a translucent pane composites two alphas and two blurs for one pane's worth of depth, and on Android the second blur is not available at all.
+
+Internal (`glass/` is not a published subpath). It is reached through `ButtonGroup`'s `glass` variant and `PageHeader`'s floating presentation.

package/docs/layout.mdx

@@ -1,16 +1,25 @@
 ---
 title: Layout
-description: Window-edge geometry — how far a floating surface sits from the edge, and what is already parked there.
+description: Window-edge geometry and screen-scope coordination — how far a floating surface sits from an edge, what is already parked there, and which scroller the chrome follows.
 order: 76
 ---
 
 # Layout
 
-Two questions every floating surface has to answer, answered once for all of
-them.
+The questions every floating surface and every piece of scroll-linked chrome has
+to answer, answered once for all of them.
 
 ```tsx
-import { EDGE_GAP, windowEdgeGap, useBottomEdgeInset, useClaimBottomEdge } from '@oxy.so/bloom/layout';
+import {
+  EDGE_GAP,
+  windowEdgeGap,
+  useBottomEdgeInset,
+  useClaimBottomEdge,
+  useTopEdgeInset,
+  useClaimTopEdge,
+  ScrollOffsetProvider,
+  useScrollOffset,
+} from '@oxy.so/bloom/layout';
 ```
 
 ## `windowEdgeGap` — how far from the edge
@@ -59,6 +68,65 @@ FAB with no tab bar, both, or a surface written later.
 `BloomProvider` mounts the registry. Outside one, `useBottomEdgeInset()` returns
 `0` and `useClaimBottomEdge` is a no-op, so a surface stays usable standalone.
 
+## `useTopEdgeInset` / `useClaimTopEdge` — the same thing, one edge up
+
+A header that participates in layout answers this by existing: the content
+starts where the header ends, because they are siblings in a column. A header
+that **overlays** content — [`PageHeader`](/docs/page-header)'s
+`placement="overlay"`, where the page scrolls under translucent islands —
+occupies no layout space at all, and the first item of the content lands
+underneath it.
+
+```tsx
+// The chrome that parks there — PageHeader does this for you.
+useClaimTopEdge(measuredHeight);
+
+// The content that has to clear it.
+<ScrollView contentContainerStyle={{ paddingTop: useTopEdgeInset() }}>
+```
+
+Same registry object as the bottom edge, so everything below about `max`,
+about a nested provider and about the one-frame settle applies unchanged.
+
+**The height is measured, not computed.** A subtitle, an enlarged font and a
+notch all move it, and a constant plus the insets fails silently — the content
+starts a few points under the islands and looks like a design decision.
+
+**Apply the safe area once.** The header pads itself by `insets.top`, and the
+claim already includes that padding. Adding `insets.top` again in the scroll
+container double-counts the notch.
+
+## `ScrollOffsetProvider` / `useScrollOffset` — which scroller
+
+A screen has exactly one scroll owner, and the owner publishes its offset. Chrome
+reads it. Neither imports the other, so two panels side by side — each with its
+own header and its own scroller — resolve correctly, because the provider's
+position in the tree is what pairs them.
+
+```tsx
+const scrollY = useSharedValue(0);
+const onScroll = useAnimatedScrollHandler(
+  { onScroll: (e) => { scrollY.value = e.contentOffset.y; } },
+  [scrollY],
+);
+
+<ScrollOffsetProvider value={scrollY}>
+  <PageHeader title="Inbox" />
+  <Animated.ScrollView onScroll={onScroll} scrollEventThrottle={16}>…</Animated.ScrollView>
+</ScrollOffsetProvider>
+```
+
+The context carries the **`SharedValue`**, not a number: it crosses once, at
+mount, and every subsequent frame reaches the chrome on the UI thread through
+`useAnimatedStyle`, with no React render. A context whose value changed per frame
+would re-render every consumer per frame, which is precisely the cost this
+avoids — the same reasoning as the section below.
+
+Without it, chrome falls back to `window.scrollY` on web and to nothing on
+native. That default is right for exactly one layout — a web page whose document
+*is* the scroller — and silently wrong for a desktop panel and for every native
+screen, with no error: the header simply never reacts.
+
 ## The collapse is not here, on purpose
 
 The tab bar minimizes 58 → 44 on scroll. This registry twice tried to publish

package/docs/migrating-to-3.0.mdx

@@ -0,0 +1,169 @@
+---
+title: Migrating to 3.0
+description: Every breaking change between @oxy.so/bloom 2.12.4 and 3.0.0 — PageHeader's floating default, the split of `transparent` into two props, and what is additive.
+order: 2
+---
+
+# Migrating to 3.0
+
+Bloom 3.0 is a small release with one large default change. `PageHeader` is a
+floating header now — a back capsule, islands of grouped actions and a gradient
+edge — where it used to be an opaque full-width strip. Everything else in this
+release is additive.
+
+Bloom keeps its clean-cut rule: there are no `@deprecated` aliases and no shims.
+The flat bar is still here, but you ask for it by name.
+
+## The short version
+
+1. Install `@oxy.so/bloom@^3.0.0`.
+2. Decide, per header: keep the bar (`presentation="bar"`) or take the islands.
+3. If a header used `transparent` over media, add `titleReveal="onScroll"` —
+   `transparent` no longer hides the title.
+4. Nothing else breaks. `tsc` will not catch either of the above, because both
+   are default changes rather than API removals; this guide is the checklist.
+
+## 1. `PageHeader` defaults to `presentation="floating"`
+
+A `<PageHeader>` with no `presentation` used to paint an opaque strip with a
+hairline separator and a scroll-linked shadow. It now paints nothing across the
+width: the back button sits in its own translucent capsule, the `actions` slot
+is a glass control surface, the title floats between them, and a vertical
+gradient of the page colour fades out below the whole thing.
+
+**To keep exactly what you had:**
+
+```diff
+-<PageHeader title="Order #4821" onBack={router.back} />
++<PageHeader presentation="bar" title="Order #4821" onBack={router.back} />
+```
+
+That header is byte-for-byte what it was — same background, same separator, same
+shadow, same back button, same geometry.
+
+**To take the new one**, decide who reserves the space:
+
+- `placement="inline"` (the default) leaves the header in layout, as before.
+  Nothing passes under it; the page colour shows through where the strip used to
+  be. This is the smallest step, and it is what an existing screen gets for free.
+- `placement="overlay"` floats the header over the content, which is what the
+  islands are actually for. The content then has to clear it:
+
+  ```tsx
+  import { useTopEdgeInset } from '@oxy.so/bloom/layout';
+
+  const inset = useTopEdgeInset();
+  <ScrollView contentContainerStyle={{ paddingTop: inset }}>…</ScrollView>
+  ```
+
+  `BloomProvider` already mounts the registry. Do not add `insets.top` on top of
+  the claim — the header's own safe-area padding is already in it.
+
+**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 and it is still legible; it is just
+not the shape:
+
+```diff
+ actions={
+-  <>
+-    <Button variant="secondary" iconOnly leadingIcon={RiSearchLine} accessibilityLabel="Search" />
+-    <Button variant="secondary" iconOnly leadingIcon={RiShare2Line} accessibilityLabel="Share" />
+-  </>
++  <ButtonGroup accessibilityLabel="Page actions">
++    <ButtonGroupItem iconOnly leadingIcon={RiSearchLine} accessibilityLabel="Search" />
++    <ButtonGroupItem iconOnly leadingIcon={RiShare2Line} accessibilityLabel="Share" />
++  </ButtonGroup>
+ }
+```
+
+A primary action keeps its own `Button` — an accent capsule beside the islands is
+the intended shape for Save or Done.
+
+## 2. `transparent` no longer hides the title
+
+`transparent` did two things: it faded the bar's background in with scroll, and
+it held the title back until the scroll arrived. The first is right for any
+header over media; the second is right only when something else on screen
+already names the page. A header that wanted one inherited both.
+
+They are two props now:
+
+```diff
+-<PageHeader transparent scrollThreshold={264} title="Lisbon loft" />
++<PageHeader presentation="bar" transparent titleReveal="onScroll" scrollThreshold={264} title="Lisbon loft" />
+```
+
+If your header used `transparent` and you were happy for the title to show at
+rest, drop `titleReveal` and you now get what you wanted.
+
+## 3. `border` and `transparent` are `presentation="bar"` props
+
+The floating presentation has no strip to fade and no separator to draw, so it
+ignores both. Its counterpart is `scrim`:
+
+| bar | floating |
+| --- | --- |
+| `border="auto"` | `scrim="auto"` — the gradient fades in with scroll |
+| `border="always"` | `scrim="always"` — the gradient paints at rest |
+| `border="none"` | `scrim="none"` — no gradient; the islands carry legibility alone |
+| `transparent` | (the floating header is always transparent) |
+
+A floating header on a screen that paints its own background colour also wants `scrimColor`: the ramp fades content into the surface it is leaving, and the header cannot read the pixel behind it.
+
+## Everything else is additive
+
+Nothing below removes or renames anything.
+
+- **`@oxy.so/bloom/control-surface`** — the inherited presentation contract. A
+  container declares a material and a density once; the controls inside default
+  to it. See [Composition](/docs/composition).
+- **`ButtonGroup` gains `variant`, `dividers`, and a `glass` material.** The
+  default is `solid`, which is what every existing group renders, unchanged.
+- **`ButtonGroupItem` gains `hitSlop`, `variant` and the trigger contract**
+  (`onLongPress`, `aria-expanded`, `aria-haspopup`, `accessibilityRole`), so an
+  item can be an anchored family's `asChild` trigger. `onPress` now receives the
+  press event; a `() => void` handler still type-checks.
+- **`@oxy.so/bloom/layout` gains `TopEdgeProvider` / `useTopEdgeInset` /
+  `useClaimTopEdge`** and **`ScrollOffsetProvider` / `useScrollOffset`**.
+  `BloomProvider` mounts `TopEdgeProvider` for you.
+- **`Field` associates rather than only stacking.** It generates SSR-stable ids,
+  wires `aria-describedby`, `aria-invalid`, `aria-required` and the control's
+  accessible name, and gains `multiple` for a field holding several controls.
+  One behaviour change worth naming: **`Field disabled` now disables a control
+  that reads the field context** (today, `TextFieldInput`). It previously only
+  dimmed the label. If you were relying on a disabled-looking field with a live
+  input, that combination no longer exists.
+- **`Label.htmlFor` accepts `null`**, meaning "this label names a group, not a
+  control". Omitting it still falls back to `nativeID`.
+- **`asChild` triggers can be cancelled.** `event.preventDefault()` in the
+  child's own `onPress` stops the surface opening. A fragment child now throws
+  instead of rendering a dead trigger — if you were passing one, the trigger was
+  never working.
+- **A neutral `chrome` glass role**, measured over the whole backdrop range. See
+  [Glass](/docs/glass).
+
+## One fix that changes existing pixels on web
+
+`<Svg style={StyleSheet.absoluteFill}>` does not fill anything on web. An
+`<svg>` is a replaced element, so `width: auto` resolves to its intrinsic size
+and an SVG without one falls back to CSS's default 300 × 150 — `left: 0;
+right: 0` does not stretch it. Three surfaces were affected, all of them
+shipping since before 3.0:
+
+- **`Button`'s gradient** — a button wider than 300px stopped its gradient dead
+  at 300px, and every narrower one scaled the vertical ramp over 150px instead
+  of the button's own height, so only the top quarter of the gradient showed.
+- **`GlassSurface`'s sheen** — the same, on every glass surface.
+- The new header's scrim, which is how it was found.
+
+All three now declare `width="100%" height="100%"`. **Native was never
+affected** (react-native-svg lays its host view out with flexbox there), so this
+changes web pixels only, in the direction of what the component always meant to
+paint. Gate: `src/__tests__/svg-absolute-fill-size.test.ts`.
+
+## What did not change
+
+The theme, the tokens, the icon set, the typography, every other family's API,
+and the license. If your app does not render a `PageHeader`, 3.0.0 is a drop-in
+upgrade from 2.12.x.