@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/chat-screen.mdx

@@ -0,0 +1,389 @@
+---
+title: Chat Screen
+description: Everything around the transcript — header, pinned bar, wallpaper, jump buttons, date pill, empty state, info panel and the desktop split frame.
+order: 64
+---
+
+# Chat Screen
+
+```tsx
+import {
+  ChatBackground,
+  ChatDateHeader,
+  ChatEmptyState,
+  ChatHeader,
+  ChatInfoPanel,
+  ChatMemberRow,
+  ChatSplitLayout,
+  JumpToMentionButton,
+  PinnedMessageBar,
+  ScrollToBottomButton,
+} from '@oxy.so/bloom/chat-screen';
+```
+
+Nine components and one frame. Everything that is not a message: the chrome
+above the transcript, the wallpaper behind it, the controls floating over it, and
+the panel beside it. The bubbles themselves live in `message-bubble`, the media
+grids in `message-media`, the input in `chat-composer`.
+
+**Every string is a prop.** Nothing here reads a clock, counts a roster, formats
+a name or decides what "recently" means. `"12:41"`, `"last seen recently"`,
+`"5 members, 2 online"` and `"Today"` all arrive pre-formatted, because the app
+owns the locale and the timezone.
+
+## The screen, assembled
+
+```tsx
+<ChatSplitLayout
+  list={<ConversationList />}
+  info={showInfo ? <ChatInfoPanel {...info} onClose={() => setShowInfo(false)} /> : undefined}
+  pane={pane}
+>
+  <View style={{ flex: 1 }}>
+    <ChatHeader
+      title="Ana Restrepo"
+      marker="verified"
+      status="online"
+      statusTone="accent"
+      avatarSource={avatarUrl}
+      presence="online"
+      onPressBack={goBack}
+      onPressHeader={() => setShowInfo(true)}
+      onPressCall={call}
+      onPressVideoCall={videoCall}
+      onPressSearch={search}
+      onPressMore={openMenu}
+    />
+    <PinnedMessageBar pins={pins} index={pinIndex} onPressPin={jumpTo} onDismiss={hideBar} />
+    <ChatBackground variant="pattern">
+      <Transcript />
+      <ChatDateHeader label={visibleDay} visible={scrolling} />
+      <View style={{ position: 'absolute', right: 16, bottom: 16, gap: 10 }}>
+        <JumpToMentionButton visible={mentions > 0} count={mentions} onPress={jumpToMention} />
+        <ScrollToBottomButton visible={scrolledUp} unreadCount={unread} onPress={jumpToEnd} />
+      </View>
+    </ChatBackground>
+    <Composer />
+  </View>
+</ChatSplitLayout>
+```
+
+## `ChatHeader`
+
+| prop                                                         | decides                                                        |
+| ------------------------------------------------------------ | -------------------------------------------------------------- |
+| `title`                                                       | the conversation's name                                        |
+| `marker`                                                      | `'verified'` (accent badge) · `'bot'` · `'channel'` (both quiet) |
+| `markerLabel`                                                 | names the marker; `""` hides it from assistive tech            |
+| `status`, `statusTone`                                        | the second line and whether it takes the accent                |
+| `typingLabel`                                                 | `TypingDots` + "Ana is typing…"                                |
+| `connecting`, `connectingLabel`                               | the transport is down                                          |
+| `avatar` / `avatarSource`, `avatarName`, `presence`, `avatarSize` | the identity mark; pass a node for a group                 |
+| `onPressBack`, `showBack`, `backLabel`                        | back navigation                                                |
+| `onPressHeader`, `openInfoLabel`                              | wraps the identity block in a button that opens the info panel |
+| `onPressCall` · `onPressVideoCall` · `onPressSearch` · `onPressMore` | the four right-hand controls; each is drawn only when given a handler |
+| `renderMore`                                                  | REPLACES the more button with your own trigger                 |
+| `actions`                                                     | extra controls, after the built-in ones                        |
+| `compact`, `divider`                                          | layout                                                         |
+
+### The status line has one writer
+
+`connecting` > `typingLabel` > `status`. Each is newer news than the one under
+it, and a header that stacked them would claim, in one row, both that the socket
+is down and that somebody is typing over it.
+
+```tsx
+<ChatHeader title="Ana" status="last seen recently" />                       // "last seen recently"
+<ChatHeader title="Ana" status="last seen recently" typingLabel="Ana is typing…" />  // typing
+<ChatHeader title="Ana" status="online" typingLabel="Ana is typing…" connecting />   // "Connecting…"
+```
+
+### The back button is derived
+
+On by default when `onPressBack` is set AND the header is compact — below
+`1024`, or on native, where there is no list pane beside the conversation to go
+back to on screen. `showBack` overrules the derivation in either direction.
+
+### Selection mode REPLACES the header
+
+```tsx
+<ChatHeader
+  title="Ana Restrepo"
+  status="online"
+  onPressCall={call}
+  selectionCount={3}
+  onClearSelection={clear}
+  onForward={forward}
+  onCopy={copy}
+  onPin={pin}
+  onDelete={remove}
+/>
+```
+
+Any `selectionCount` above `0` removes the identity block, the status line and
+every call/video/search control. Keeping a call button beside "3 selected" is how
+a selection gets lost to a mis-tap. `formatSelectionCount` owns the wording;
+`selectionActions` replaces the four buttons outright. `0` and below is not a
+selection, so the normal header comes back.
+
+## `PinnedMessageBar`
+
+| prop                              | decides                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| `pins`                            | `{ id, preview, author?, thumbnail? }[]`; EMPTY renders nothing           |
+| `index`                           | which one shows — CLAMPED into range                                     |
+| `onPressPin(pin, index)`          | jump to it                                                               |
+| `onPressList` / `onDismiss`       | the two optional buttons; omitted without a handler                      |
+| `dismissIcon`                     | `'close'` (default) hides the bar · `'unpin'` removes the pin            |
+| `formatTitle(index, total)`       | default `"Pinned message"` for one, `"Pinned message #2"` for several    |
+
+The vertical rule carries one segment per pin, the current one at full accent and
+the rest washed. **Past eight pins it becomes one solid rule**: nine segments
+inside 32px are sub-pixel slivers, and a progress indicator that cannot be
+counted is decoration that looks like information.
+
+`index` is clamped rather than trusted. The list shrinks under you when somebody
+unpins the message you were looking at, and a bar that reads `undefined.preview`
+for one frame is a crash, not a state.
+
+## `ChatBackground`
+
+| prop                        | decides                                                          |
+| --------------------------- | ---------------------------------------------------------------- |
+| `variant`                   | `'plain'` · `'pattern'` · `'gradient'` · `'image'`                |
+| `source`                    | the wallpaper image (`image` only); URL, `ImageResolver` id or source |
+| `overlayOpacity`            | how hard the image is dimmed. Default `0.55` light / `0.62` dark  |
+| `tint`, `patternOpacity`    | the pattern's ink and its strength (default `0.5`)                |
+| `colors`                    | override the gradient stops                                       |
+| `children`                  | the transcript, drawn above the wallpaper                         |
+
+It is the CONTAINER, not a layer: put the transcript and the floating controls
+inside it.
+
+### Measured contrast
+
+A bubble is an OPAQUE fill, so the wallpaper never gets between a fill and its
+own label — **bubble text contrast is a property of the bubble**, and it does not
+move with the wallpaper. What a wallpaper CAN do is stop a bubble being told
+apart from the page. So the number that matters is the SEPARATION between a
+bubble fill and the worst pixel a variant can paint behind it, and that needs the
+extremes, not an average.
+
+Measured over 16 presets × light and dark (32 themes), against an incoming bubble
+(the chrome surface) and an outgoing one (accent-500):
+
+| what                                          | worst  | best  |
+| --------------------------------------------- | ------ | ----- |
+| incoming bubble text over its own fill        | 13.82  | —     |
+| outgoing bubble text over its own fill        | 4.55   | —     |
+| date-pill text over the pill                  | 4.71   | —     |
+| bubble ↔ `plain` wallpaper (the baseline)     | 1.07   | 1.11  |
+| bubble ↔ `pattern` wallpaper                  | 1.07   | 1.11  |
+| bubble ↔ `gradient` wallpaper                 | 1.07   | 1.11  |
+| bubble ↔ `image` wallpaper (dimmed)           | 1.12   | 1.24  |
+
+Both text figures clear WCAG AA (the incoming one clears AAA). **No variant
+separates worse than the bare page**, and the dimmed image variant separates
+BETTER than it — that is what the dim is for, not taste. The figures are pinned
+as equalities in `ChatBackgroundContrast.test.ts`, so a recipe change goes red in
+either direction.
+
+Two decisions fall out of the measurement, and both are counter-intuitive:
+
+- **The image dim is toward a mid-light neutral, not toward white.** White
+  dimmed toward white is white, which is the card colour — a white incoming
+  bubble over a bright photo then separated by exactly **1.00**, i.e. not at all.
+  The gate keeps that as a negative control.
+- **The gradient's stops move AWAY from the page, never toward the card**:
+  darker than the page in light, lighter in dark. The first recipe brightened a
+  light page and put its lightest pixel onto the incoming bubble's own colour —
+  16 of 32 themes separated worse than no wallpaper at all.
+
+The floating surfaces (the date pill, the two jump buttons) are deliberately NOT
+in that measurement: their separation reaches 1.00 in the worst case — a dark
+patterned wallpaper IS the pill's own surface colour — which is exactly why every
+one of them carries a 1px hairline. A bubble has no such rule to fall back on.
+
+## `ScrollToBottomButton` and `JumpToMentionButton`
+
+```tsx
+<ScrollToBottomButton visible={scrolledUp} unreadCount={7} onPress={jumpToEnd} />
+<JumpToMentionButton visible={mentions > 0} count={mentions} onPress={jumpToMention} />
+```
+
+| prop                   | decides                                                        |
+| ---------------------- | -------------------------------------------------------------- |
+| `visible`              | `false` renders NOTHING                                        |
+| `unreadCount` / `count`| the badge; `0` draws none                                      |
+| `badgeMax`             | `"99+"` past this. Default `99`                                |
+| `size`                 | diameter. Default `44`                                         |
+| `accessibilityLabel`   | default "Scroll to latest messages" / "Jump to mention"        |
+
+`visible={false}` unmounts rather than fades. A faded button leaves a focusable
+control in the tab order nobody can see, and a reader announcing "Scroll to
+latest messages" for a transcript already at the bottom is worse than silence.
+The badge carries its own name (`UnreadBadge` composes "7 unread messages") with
+the REAL count, not the clamped text, so the button's name never has to be
+rewritten per count.
+
+Two buttons rather than one mode: "newest" and "the message that named me" are
+different destinations, and someone scrolled far up wants both offered at once.
+
+## `ChatDateHeader`
+
+```tsx
+<ChatDateHeader label="Today" visible={scrolling} />
+<ChatDateHeader label="Yesterday" placement="inline" />   // a separator, in flow
+```
+
+`visible={false}` fades to nothing and leaves the accessibility tree, but stays
+MOUNTED — the pill is not focusable, so there is no phantom tab stop, and keeping
+it mounted stops the label re-announcing every time a scroll crosses a day
+boundary. It hides with `opacity`, never `display: none`: collapsing an element
+inside a scroller is how a restored scroll offset gets clamped to 0.
+
+The floating strip is `pointerEvents="box-none"` and the pill itself `"none"` —
+a band across the top of a conversation that swallowed taps would eat every press
+on the newest messages.
+
+## `ChatEmptyState`
+
+```tsx
+<ChatEmptyState
+  illustration={<Avatar name="Ana Restrepo" source={avatarUrl} size={80} />}
+  description="Say hello to Ana — this conversation is brand new."
+  notice="Messages in this conversation are end-to-end encrypted."
+/>
+```
+
+**`notice` has no default, and that is the point.** "Messages are end-to-end
+encrypted" is a claim about an app's transport, not about a component; a default
+would make it on behalf of every app that mounts this, including the ones that
+cannot keep it. Pass the wording you can stand behind, or pass nothing and no
+line is drawn. `noticeIcon={false}` drops the padlock.
+
+`title` DOES default to "No messages yet" — an empty transcript is a fact the
+component can see for itself.
+
+## `ChatInfoPanel`
+
+One component, two shapes. `variant="pane"` is the desktop right-hand column at a
+fixed `width` (default `380`) with a left hairline; `variant="screen"` is the
+mobile full page with no frame of its own. Nothing else differs, so a responsive
+app swaps the variant and not the composition.
+
+| prop                                                    | decides                                             |
+| -------------------------------------------------------- | --------------------------------------------------- |
+| `title`, `onClose`, `closeLabel`, `headerActions`         | the title bar                                       |
+| `cover` / `coverSource`, `coverHeight`                    | a banner behind the identity block                  |
+| `avatar` / `avatarSource`, `presence`, `avatarSize`       | the identity mark (96, or 72 over a cover)          |
+| `name`, `handle`, `bio`, `meta`                           | the identity block                                  |
+| `actions`                                                 | the action tile row: `{ key, label, icon, onPress, tone? }` |
+| `settings`, `settingsTitle`                               | the settings block — a SLOT (see below)             |
+| `tabs`, `tab`, `onTabChange`, `defaultTab`                | shared content; each pane's `content` is yours      |
+| `members`, `membersTitle`, `onPressMember`, `roleLabels`  | the roster                                          |
+| `memberSearch`, `memberQuery`, `onMemberQueryChange`      | roster search (see below)                           |
+| `onAddMember`, `addMemberLabel`, `membersEmptyLabel`      | the rest of the roster block                        |
+| `destructiveActions`                                      | Leave / Block / Report, in the negative tone        |
+| `scrollable`, `children`                                  | the panel scrolls itself by default                 |
+
+### The settings block is a slot, not a schema
+
+A notifications switch owns state, a disappearing-messages row owns a picker, an
+encryption key owns a verification flow. Every one of them needs semantics the
+panel cannot hold, so it takes a node:
+
+```tsx
+<ChatInfoPanel
+  settingsTitle="Settings"
+  settings={
+    <SettingsListGroup variant="filled">
+      <SettingsListItem
+        title="Notifications"
+        icon={<RiNotification3Line width={20} height={20} fill={colors.textSecondary} />}
+        rightElement={
+          <Switch
+            value={notifications}
+            onValueChange={setNotifications}
+            accessibilityLabel="Notifications for this conversation"
+          />
+        }
+        showChevron={false}
+      />
+      <SettingsListItem title="Disappearing messages" value="Off" onPress={openTimer} />
+      <SettingsListItem title="Encryption key" onPress={openKey} />
+      <SettingsListItem title="Conversation theme" value="Default" onPress={openTheme} />
+    </SettingsListGroup>
+  }
+/>
+```
+
+The shared-content tabs are the same bargain one level up: the panel owns the
+strip and the selection, the grids inside each pane come from `message-media`.
+
+### Roster search has two modes and they are not the same component
+
+- **Uncontrolled** (`memberQuery` omitted): the panel keeps its own query and
+  filters `members` by name.
+- **Controlled** (`memberQuery` set): the panel filters NOTHING and reports every
+  keystroke through `onMemberQueryChange`. This is the only correct behaviour
+  once the roster lives on a server — filtering a result set the server produced
+  would fight it.
+
+The field appears automatically from eight members up; `memberSearch` forces it
+either way.
+
+## `ChatMemberRow`
+
+```tsx
+<ChatMemberRow member={{ id, name, source, status, role, subtitle }} onPress={open} />
+```
+
+`owner` and `admin` draw a badge; `member` draws none — a badge on every row is a
+badge on nobody. The accessible name is composed as
+`"Ana Restrepo, Owner, last seen recently"`, so a reader hears one stop rather
+than three. `roleLabels` translates the two words.
+
+## `ChatSplitLayout`
+
+| prop                                               | decides                                              |
+| ---------------------------------------------------- | ---------------------------------------------------- |
+| `list`, `children`, `info`                           | the three panes                                      |
+| `pane`                                               | which ONE a narrow layout builds. Default `'conversation'` |
+| `listWidth` / `defaultListWidth`, `onListWidthChange`| the resizable pane (default `340`)                   |
+| `minWidth`, `maxWidth`                               | `280` … `480`                                        |
+| `infoWidth`                                          | default `380`                                        |
+| `resizable`, `resizeLabel`                           | the drag grip                                        |
+| `breakpoint`, `compact`                              | when one pane replaces three. Default `900`          |
+
+**The compact layout RENDERS one pane, it does not hide two.** A hidden pane is
+still mounted, still subscribed, still measuring, and on web still in the tab
+order; on a phone that is three screens' worth of work to show one. Asking for
+`pane="info"` with no `info` node falls back to the conversation rather than
+rendering an empty screen.
+
+Compact is MEASURED from the layout, not from the window — this frame is
+regularly mounted inside something narrower than the screen. The first render has
+no measurement, so it is seeded from the window and corrected on the next frame.
+
+The grip is `ai-chat`'s `AiChatResizeHandle`: the same pointer-capture drag,
+arrow-key nudging and hover grip the AI shell uses, rather than a second
+implementation of the same ninety lines. It reports a DELTA, so the width is
+rebased on every drag start and cannot drift.
+
+## Tokens
+
+`resolveChatScreenPaint(theme)` is the one place this family reads colour, and it
+keeps two families of surface apart:
+
+- **Chrome** (`surface`, `surfaceSubtle`, `border`) — the header, the pinned bar,
+  the info panel. In the page, separated from it by a hairline.
+- **Floating** (`floatingSurface`, `floatingBorder`, `floatingShadow`) — the date
+  pill and the two jump buttons, which hover over a wallpaper Bloom does not own.
+  These come from `floating/menu-palette.ts`, the same recipe every menu and
+  tooltip uses, so a pill over a photo is the same material as a menu over a page.
+
+`chatBackgroundExtremes(paint, variant)` returns the lightest and darkest colour a
+variant can paint, and `chatBackgroundReferenceSurfaces(paint)` the two bubble
+fills it is measured against. Both are exported so an app that invents its own
+wallpaper can measure it the same way.

package/docs/checkbox.mdx

@@ -96,3 +96,12 @@ For a labelled checkbox the pressable already spans the label, so the whole row
 The pressable takes a `:focus-visible` ring, drawn from the same shared recipe every Bloom control's web CSS is built from. The browser focuses the row — the box AND its label — but the ring is drawn around the BOX whenever that row has keyboard focus — `ring-2 ring-offset-2`: a 2px accent ring outside a 2px **white** offset. The offset is white in dark mode too; that is Tailwind's default `ring-offset-color`, left un-overridden; the row's own outline is suppressed so there is exactly one ring, and it is only ever shown for the focused row.
 
 `:focus-visible`, not `:focus`: a mouse click never leaves a ring behind.
+
+## The focus ring's gap
+
+The 2px gap between the box and the ring takes `var(--bloom-ring-offset)`, set
+inline from the surface behind the control. It was the literal `#FFFFFF` —
+Tailwind's `ring-offset-color` default, never overridden — so in dark mode a
+focused checkbox drew a white halo on a near-black page. `FOCUS_RING_OFFSET_COLOR`
+survives only as a deprecated alias of the fallback. See
+[Styles → The focus ring gap](/docs/bloom/main/styles).

package/docs/chip.mdx

@@ -64,6 +64,58 @@ The hues sit BESIDE the accent recipe, not inside it: `resolveAccentColors` is u
 
 `selected` promotes the chip to the brand tone rather than to a colour system of its own, and announces as `aria-pressed`. On web a keyboard user gets a `:focus-visible` ring — keyboard-only, so a mouse click does not leave one behind.
 
+### Role
+
+A pressable chip's ROLE decides which state attribute it carries, and the three are not interchangeable:
+
+| `role` | web | native |
+|---|---|---|
+| `button` (default) | `aria-pressed` | `accessibilityState.selected` |
+| `radio` | `aria-checked` | `accessibilityState.checked` |
+| `tab` | `aria-selected` | `accessibilityState.selected` |
+
+`aria-pressed` is invalid on a radio and on a tab, which is what this component used to emit for every one of them. Put a `radio` inside a `role="radiogroup"` and a `tab` inside a `role="tablist"` — `ChipRow` takes that role for you.
+
+On web, `tabIndex` and `onKeyDown` are passed through for a roving-tabindex row (one tab stop, arrows move focus). Both are inert on native. A chip also forwards a ref to its pressable, so a row can focus one.
+
+### `inverted`
+
+`variant="inverted"` is a fourth fill and a different idea rather than a fourth loudness. At rest it is a hairline on the page (transparent fill, neutral-200 border, dark neutral-700); selected, it turns the page's own reading pair OVER — fill `text`, label `background`.
+
+That pair is legible by construction in both modes and under every preset, which is what a filters sheet needs and what promoting to the brand tone cannot promise. It answers hover with its BORDER rather than the shared opacity step, because a pill with no fill has nothing to fade.
+
+```tsx
+<Chip size="2xl" variant="inverted" role="radio" selected={value === n} onPress={() => onChange(n)}>
+  {String(n)}
+</Chip>
+```
+
+## `ChipRow`
+
+The pill row that scrolls sideways, with a fade at whichever edge has more behind it. Without the fade a clipped pill stops mid-glyph and reads as a rendering fault rather than as "there is more".
+
+```tsx
+import { Chip, ChipRow } from '@oxy.so/bloom/chip';
+
+<ChipRow role="tablist" accessibilityLabel="Result types" fadeColor={card}>
+  {tabs.map((tab) => (
+    <Chip key={tab.value} size="xl" role="tab" selected={tab.value === value} onPress={() => onChange(tab.value)}>
+      {tab.label}
+    </Chip>
+  ))}
+</ChipRow>
+```
+
+| prop | |
+|---|---|
+| `gap` | between pills, default 8 |
+| `contentInset` | side padding inside the scroller |
+| `fadeColor` | the surface BEHIND the row — the row cannot know it. Default the page background; pass the card colour when the row sits on a card, or the fade blends into the wrong thing |
+| `ringInset` | room kept for a pill's focus ring inside the scroller, taken back out with negative margins so the row still lines up. Default 4 |
+| `role` / `accessibilityLabel` | the row's semantics, which belong to the caller |
+
+The fade is web only (it is a CSS gradient); the row scrolls on both platforms.
+
 ## Removable
 
 ```tsx
@@ -74,7 +126,23 @@ The close affordance is its own control inside the pill, with its own label and
 
 ## Sizes and icons
 
-`size` is `small` (`caption-1-medium`, 24 tall), `medium` (default, `body-medium`, 24 tall) or `large` (`body-medium`, 28 tall), all with 6px side padding and set in Inter through the typography `Text`. The close glyph is Remix `close-line` at 16. `startIcon` and `endIcon` take any node, and both are sized to the pill rather than to whatever was passed — an icon in a `small` chip and the same icon in a `large` one come out proportional.
+| `size` | height | padding-x | gap | icon | text |
+|---|---|---|---|---|---|
+| `small` | 24 | 6 | 4 | 14 | `caption-1-medium` |
+| `medium` (default) | 24 | 6 | 4 | 16 | `body-medium` |
+| `large` | 28 | 6 | 4 | 16 | `body-medium` |
+| `xl` | 32 | 12 | 8 | 16 | `body-medium` |
+| `2xl` | 40 | 16 | 8 | 18 | `body-medium` |
+
+The scale used to stop at `large`, which is why five families grew a pill of their own rather than use this one: 28 tall with 6px sides is a TAG, and a filter you tap needs a target. `xl` is the filter/segment pill; `2xl` is the filters-sheet pill, and it pins a `minWidth` of 48 so a one-character label ("1", "8+") stays a pill rather than collapsing to a dot — a rung with a `minWidth` also centres its contents.
+
+**Override the side padding with `paddingHorizontal`, never `paddingLeft`/`paddingRight`.** react-native-web maps the shorthand this component uses to `padding-inline`, which its atomic sheet ranks above `padding-left` whatever the array order — so a longhand override drops on WEB and lands on native. Two families were overriding it that way and had been drawing 6px on the web since they shipped. Better still: pick the rung that already carries the padding you want.
+
+The close glyph is Remix `close-line` at 16. `startIcon` and `endIcon` take any node, and both are sized to the RUNG rather than to whatever was passed — an icon in a `small` chip and the same icon in a `2xl` one come out proportional.
+
+## The focus ring
+
+The `:focus-visible` ring is the accent ramp's 500, the colour every other ring in the library uses. It used to be the chip's own LABEL colour, which is the one colour guaranteed to be invisible: on a solid chip the label is white and so was the ring — measured 1.09:1 in light mode, black on black in dark. The ring is drawn with `outline-offset: 2px`, i.e. on the PAGE, so what it has to contrast with is the page; `accent[500]` clears 4.2:1 against it on all 64 presets in both modes.
 
 ## A pill does not shrink
 

package/docs/content-panel.mdx

@@ -18,6 +18,28 @@ import { ContentPanel } from '@oxy.so/bloom/content-panel';
 </ContentPanel>
 ```
 
+## The panel's edge
+
+```tsx
+<ContentPanel framed chrome="elevated" />   {/* default: hairline + panel shadow */}
+<ContentPanel framed chrome="border" />     {/* hairline only */}
+<ContentPanel framed chrome="none" />       {/* flat rounded surface */}
+<ContentPanel framed shadow="0 8px 24px rgba(0,0,0,.12)" />  {/* your own lift */}
+```
+
+A framed panel wears the same edge the [`Sidebar`](/docs/bloom/main/sidebar)
+does — a hairline **and** the floating-panel shadow, from one recipe in
+`styles/panel-chrome.ts` (`resolvePanelChrome`, `PANEL_SHADOW`) so the two
+surfaces cannot drift apart. The border alone read as a box drawn on the page;
+the shadow is what makes it a panel lifted off it.
+
+- On **web** the shadow rides the same sticky overlay as the hairline, so the
+  lift and the edge always describe the same rectangle, and it paints outward
+  into the gutter the page background shows.
+- On **native** the surface carries both.
+- `chrome` is ignored while the panel is full-bleed (below `framedFrom`, or
+  `framed={false}`) — there is no edge to draw.
+
 ## Which prop decides what
 
 | prop               | decides                                                  |
@@ -26,25 +48,31 @@ import { ContentPanel } from '@oxy.so/bloom/content-panel';
 | `framedFrom`       | the breakpoint it starts framing at — `500` `640` `768` `1024` |
 | `showStickyFrame`  | whether the frame persists behind sticky content           |
 | `surfaceStyle` / `surfaceClassName` | the surface itself                        |
+| `surfaceColor`     | what the panel tells its content it is painted in — only when `surfaceClassName`/`surfaceStyle` repainted it |
 | `contentStyle` / `contentClassName` | the column inside it                      |
 | `maskColor`        | the colour the gutter mask fades to                        |
 | `overlaySizing`     | (web) how the mask/border overlays size themselves — see below |
 
-## `overlaySizing`: viewport chrome vs. a bounded shell
+## `overlaySizing`: the panel's own box, or a constant frame
 
-The web overlays default to `overlaySizing="viewport"`: sized to `100dvh` and
-`position: sticky`-pinned, so they read as a constant frame around the visible
-slice of a panel whose own DOM height can exceed one screen — the right choice
-in a document that actually scrolls (a feed page that grows with content).
+The web overlays (the border frame and the gutter bleed-mask) default to
+**`overlaySizing="panel"`**: sized to the panel's own real box through CSS Grid
+layer-stacking. The edge behaves like any other border — it scrolls with the
+content, you see the two side edges while reading and the rounded corners at the
+ends of the page.
 
-A consumer whose OWN shell already bounds the panel's height — a fixed app
-shell with its own internal scroll containers, no document scroll — doesn't
-have that problem, and viewport-sizing there is actively wrong: the overlay
-still reads `100dvh` regardless of how much of the viewport is actually the
-panel's, so anything placed OUTSIDE the panel (a header above it, say) gets
-painted over. `overlaySizing="panel"` fixes that: the overlays size to the
-panel's own real box via CSS Grid layer-stacking instead of viewport math, so
-they never extend past whatever height the panel actually has.
+`overlaySizing="viewport"` is the other mode: the overlays are `100dvh` and
+`position: sticky`-pinned, so a rounded top and bottom edge follow the viewport
+down the page. It was the default until it was measured against a long feed: the
+frame holds still while the content moves inside it and it jumps 8px on the
+first scroll, which reads as the panel breathing. It remains for a consumer that
+wants that constant frame — and it is also the mode `overlayTopOffset` exists
+for.
+
+Panel mode is additionally the right answer whenever the consumer's OWN shell
+bounds the panel (a fixed app shell with internal scroll containers): a
+viewport-sized overlay there paints over anything placed outside the panel, such
+as a header above it.
 
 ```tsx
 <View style={{ flex: 1 }}>
@@ -80,6 +108,69 @@ Two columns side by side are two panels as **siblings**:
 
 A screen picks one panel per column; the sections inside it are plain views.
 
+## The panel says what colour it is, so chrome does not have to guess
+
+A panel is the surface a screen sits on, which makes it the thing in-panel
+chrome keeps asking about: a sticky header that has to be **opaque** over the
+scrolling column, a tab rail, a search field's backing, a reply bar pinned to
+the bottom. Each one only ever wanted "be the colour of the surface I am on",
+and the only way to say that used to be to repeat the panel's own `bg-card` at
+the call site — which turns one decision about the panel's surface into a sweep
+through every screen the next time it changes. Mention carries ~65 of those.
+
+So the panel publishes it. Anything inside reads it:
+
+```tsx
+import { useSurfaceFill } from '@oxy.so/bloom/styles';
+
+function StickyReplyBar() {
+  const surface = useSurfaceFill();          // the panel's fill — `colors.card`
+  return <View style={{ backgroundColor: surface }}>…</View>;
+}
+```
+
+`useSurfaceFill()` is the cross-platform answer and the one to reach for.
+[`styles`](/docs/bloom/main/styles#surface-levels) has the rest of the model:
+the rung the panel publishes with it (`1`), the derived hairline and text rungs,
+and `--bloom-surface`, the web variable the panel writes on the element it
+paints so a stylesheet can follow the surface too.
+
+Two things are worth knowing here:
+
+- **It is the panel's REAL fill, not a rung.** `theme.colors.card` is not rung 1
+  in dark mode — the rung is a computed step off the page — and chrome that took
+  the rung would sit a visible shade off the column it is supposed to vanish
+  into. The panel publishes the fact.
+- **Repainting the surface makes the panel stop claiming to know.**
+  `surfaceClassName` is a utility Bloom cannot resolve to a colour, and a
+  `surfaceStyle` with a `backgroundColor` is the same repaint by the other door
+  — the colour is legible there, but which of the two actually paints differs by
+  platform, so the panel refuses to guess. Either way it falls back to publishing
+  the rung alone rather than a confident wrong answer. `surfaceColor` is how that
+  caller gets the exact answer back:
+
+```tsx
+<ContentPanel surfaceClassName="bg-background" surfaceColor={colors.background} />
+```
+
+`surfaceColor` changes nothing about how the panel looks — the class still
+paints it. It only decides what the panel tells its content.
+
+### What reads it
+
+`SettingsListGroup` is the first component to stop taking a prop for this: with
+no `variant` it paints one step off the panel's published fill, so a settings
+screen reads the same on a page and inside a panel without repeating the answer
+at every group ([Settings list](/docs/bloom/main/settings-list)).
+
+A surface opened *from* the panel does not inherit it. React context reaches
+through a portal and through an RN `<Modal>` even though neither paints
+anything, so a dialog, sheet or menu would otherwise take its colours from where
+its trigger happened to live. `Dialog` and the bottom-sheet shell publish their
+own fill, `floating/FloatingPanel` publishes the menu rung, and `OverlayRoot`
+resets the ambient surface for anything portaled that does neither — so the same
+dialog paints the same way from a bare screen and from inside a panel.
+
 ## Do not put a Card immediately inside a framed panel
 
 They are both surfaces. A card filling a framed panel is two borders with a few