@oxy.so/bloom 2.10.0 → 2.11.0

package/docs/message-media.mdx

@@ -0,0 +1,330 @@
+---
+title: Message Media
+description: Everything that goes inside a chat bubble besides text — photos, albums, video, voice notes, files, locations, contacts, polls, stickers, GIFs, link previews — plus the info panel's media and file grids.
+order: 64
+---
+
+# Message Media
+
+```tsx
+import {
+  ContactMessage,
+  DocumentGrid,
+  FileMessage,
+  GifMessage,
+  ImageMessage,
+  LinkPreviewMessage,
+  LocationMessage,
+  MediaAlbum,
+  PollMessage,
+  SharedMediaGrid,
+  StickerMessage,
+  VideoMessage,
+  VoiceMessage,
+} from '@oxy.so/bloom/message-media';
+```
+
+Thirteen blocks that go INSIDE a bubble, and none of them draw one. The shell —
+grouping, the tail, the meta row, reactions — is `message-bubble`'s job; these
+fill its `media` slot, or stand on their own in a panel.
+
+## The two things every block has
+
+**`tone`.** `'incoming'` (default) is the neutral bubble, `'outgoing'` the accent
+one. It is not styling: half of these surfaces sit on a saturated fill where
+`colors.textSecondary` lands anywhere between 1.1:1 and 3:1 depending on the
+preset, so a block that reads page colours is illegible on one of the two
+bubbles and nobody notices until a preset changes. `resolveMessageMediaPaint()`
+takes the bubble fill and MIXES the bubble's own on-colour up from it until the
+result clears 4.5:1 — so the muted label is muted by the same amount on every
+preset, in both modes, and is never unreadable.
+
+```tsx
+<ImageMessage tone="outgoing" source={photo} />
+<FileMessage tone="incoming" name="Lease.pdf" sizeBytes={2_560_000} />
+```
+
+`onColor` and `bubbleColor` override the two ends for an app painting its own
+bubble; everything between them is re-derived, so the contrast guarantee holds.
+
+**`radius`.** The BUBBLE owns the corners. A photo flush with the bubble's edge
+has to take the bubble's radius on the side it touches, or the two draw two arcs
+a pixel apart. Default 16; `message-bubble` passes its own.
+
+## `ImageMessage`
+
+```tsx
+<ImageMessage
+  source={photo}                    // URL, {uri}, require(), or an Oxy file ID
+  aspectRatio={4 / 3}
+  placeholderColor="#5b6f7a"        // the flat colour a blurhash resolves to
+  spoiler
+  onPress={(index) => open(index)}  // index is always 0, so one handler serves a photo and an album
+/>
+```
+
+| prop                              | decides                                                             |
+| --------------------------------- | ------------------------------------------------------------------- |
+| `aspectRatio` / `maxWidth` / `maxHeight` | the frame; the photo is fitted inside both caps, never cropped |
+| `placeholderColor`                | the fill shown until the photo paints. Bloom decodes no blurhash — that needs a decoder dependency; pass the average colour the decoder gives you |
+| `spoiler` / `spoilerLabel` / `onReveal` | hides the photo until pressed. Revealing LATCHES               |
+| `state` / `progress` / `onCancel` / `onRetry` | `'sending'` draws the ring, `'failed'` the retry row     |
+
+**The spoiler is opaque on native.** On web it is a translucent wash with a
+`backdrop-filter` blur, which is the look. A real blur on native needs
+`expo-blur`, an optional peer this family does not take, and a translucent cover
+with no blur behind it shows the photo it exists to hide — so native covers it
+completely. A spoiler that half-works is not a spoiler.
+
+## `MediaAlbum`
+
+```tsx
+<MediaAlbum
+  items={photos}          // 2–10 cells; past `maxTiles` the last takes a "+N"
+  width={260}
+  onPress={(index) => open(index)}
+/>
+```
+
+The packed grid, laid out by `albumLayout(count, width, { gap, radius, maxTiles })`,
+which is exported so an app (or a test) can read the geometry without rendering:
+
+| items | rows      | shape                                      |
+| ----- | --------- | ------------------------------------------- |
+| 2     | `[2]`     | two squares                                 |
+| 3     | `[1, 2]`  | one banner over two halves                  |
+| 4     | `[2, 2]`  | 2 × 2                                       |
+| 5     | `[2, 3]`  |                                             |
+| 6     | `[3, 3]`  |                                             |
+| 7     | `[2, 2, 3]` |                                           |
+| 8     | `[2, 3, 3]` |                                           |
+| 9     | `[3, 3, 3]` |                                           |
+| 10    | `[3, 3, 4]` |                                           |
+
+Cells are ABSOLUTE rectangles with integer widths that sum to the frame exactly.
+A flex row rounds each child independently, and the last cell in a row of three
+ends up a pixel short of a ROUNDED outer corner — which reads as a rendering
+fault rather than as a gap. Only the group's four outer corners are rounded; a
+cell in the middle is square on every side.
+
+A `video` cell draws a play glyph and a duration pill; `spoiler` works per cell.
+
+## `VideoMessage`
+
+```tsx
+<VideoMessage source={poster} duration={187} sizeBytes={25_800_000} onPress={play} />
+<VideoMessage source={poster} variant="videoNote" duration={31} position={19} />
+```
+
+`thumbnail` is a poster with the shared `PlayButton` (`media-controls`,
+`inverse`) centred on it and a duration pill. `watched` dims the pill and adds a
+tick rather than removing anything — a watched video is still a video.
+
+`videoNote` is the round short note: the circle is a mask and the ring around it
+is `position / duration`.
+
+**The play disc is drawn, not pressed.** The whole poster is the button; the
+`PlayButton` inside it carries no handler and is hidden from the pointer and
+from assistive tech. A second `role="button"` nested in the first swallows the
+press on web and is read twice by a screen reader.
+
+## `VoiceMessage`
+
+```tsx
+<VoiceMessage
+  samples={amplitudes}          // any length — resampled to `barCount`
+  duration={14}
+  position={position}
+  playing={playing}
+  onPlayPress={toggle}
+  onSeek={setPosition}
+  rate={rate} onRateChange={setRate}   // 1 → 1.5 → 2 → 1
+  unplayed={position === 0}
+  transcript="Left the keys with the neighbour."
+/>
+```
+
+`samples` are amplitudes 0..1, oldest first. Down-sampling takes the PEAK of
+each bucket, not the mean: a voice note is silence with peaks in it, and
+averaging flattens every recording into the same grey slab. Every bar has an 18%
+floor, so real silence is a short bar rather than a hole in the waveform.
+
+Played bars take the accent, unplayed ones the rail — two colours, NOT one at
+two opacities. An opacity composites against what is behind it, and behind it is
+the accent bubble half the time.
+
+The waveform is a `slider` (`accessibilityRole="adjustable"`) with flat
+`aria-value*` props, focusable on web, answering arrows / Home / End and the
+native `increment` / `decrement` actions. `seekPositionAt(x, width, duration)`
+is exported and clamps at BOTH ends — hit slop reports a negative `locationX`.
+
+The clock shows the LENGTH before playback starts and the ELAPSED position
+after. Two numbers side by side is a player's idiom; in a bubble the second one
+is chrome.
+
+## `FileMessage`
+
+```tsx
+<FileMessage name="Tenancy agreement.pdf" sizeBytes={2_560_000} onDownload={save} />
+<FileMessage variant="compact" name="Rents.xlsx" sizeBytes={831_488} transfer="downloading" progress={0.4} onCancel={stop} />
+```
+
+The kind comes from `fileKindFor(name, mimeType)` — the NAME first, because a
+`.csv` served as `text/plain` is still a spreadsheet to its sender. Ten kinds:
+`pdf doc sheet slides zip audio video image code other`, each with its own glyph
+and hue from the theme's status / accent roles.
+
+**The kind colour survives BOTH tones.** On the neutral bubble the disc is a
+light tint of the hue. On the accent bubble a tint of the hue would be a tint of
+a saturated fill, so the disc becomes a near-white plate and the hue is darkened
+onto it — rather than the colour being dropped because the bubble is coloured.
+
+The meta line is `"2.4 MB · PDF"`, formatted with `formatFileSize` from
+`file-upload` — the SAME formatter the uploader uses, extended with a gigabyte
+branch, so a size cannot read two ways in one app.
+
+The ring IS the button: the thing you press to cancel is the thing showing you
+how far it got.
+
+## `LocationMessage`
+
+```tsx
+<LocationMessage
+  title="Casa del Puerto"
+  address="Carrer de la Marina 118"
+  renderMap={({ width, height }) => <YourMapView width={width} height={height} />}
+/>
+<LocationMessage live liveUntilLabel="Live until 18:30" onStopSharing={stop} />
+```
+
+Bloom ships no map engine — a tile provider is a dependency, a key and a licence
+— so `renderMap` is the slot. Without it the frame draws a neutral grid, which
+is deliberately abstract: a fake coastline would be a map of somewhere.
+
+`live` swaps the pin for a pulsing dot (still under reduced motion — it reports
+"sharing", not "working", and the label already says so) and puts "Stop sharing"
+BELOW the frame rather than on it: it is destructive and must not be one mis-tap
+from "open the map". `liveUntilLabel` arrives pre-formatted; a component that
+reads the clock renders differently in every test and every timezone.
+
+## `ContactMessage`
+
+```tsx
+<ContactMessage name="Marta Ferreira" detail="+34 600 11 22 33" onMessage={chat} onAdd={save} />
+```
+
+Avatar, name, handle, and two EQUAL actions. "Message" and "Add" are the same
+size of decision, and ranking one with a filled button puts a second accent
+surface inside an accent surface. Only the actions are pressable.
+
+## `PollMessage`
+
+```tsx
+<PollMessage question="When should we do the handover?" options={options} onVote={vote} />
+<PollMessage question="…" multiple anonymous onVote={vote} />
+<PollMessage question="…" quiz voted options={[{ id: 'a', label: '…', votes: 3, correct: true }]} />
+```
+
+| prop                        | decides                                                          |
+| --------------------------- | ---------------------------------------------------------------- |
+| `multiple`                  | checkboxes, picks held locally until "Vote"                      |
+| `anonymous` / `quiz`        | labels on the question — they change what voting MEANS            |
+| `voted` / `showResults`     | bars and percentages replace the marks                            |
+| `totalVotes`                | defaults to the sum of `votes`                                    |
+
+Percentages come from `pollPercentages(votes, total?)`, which distributes the
+rounding remainder by largest fraction so the column sums to exactly 100.
+Rounding each share on its own gives three equal options 33/33/33 and two equal
+ones 51/51 — a poll that visibly cannot add up is a poll nobody believes. No
+votes at all is all zeroes, not an even split: "nobody voted" and "everyone
+agrees" are different facts. An explicit `total` LARGER than the votes cast is
+not inflated back to 100.
+
+Before the results an option is a `radio` / `checkbox` with `aria-checked`;
+after them it is a `progressbar` with its own name and the three `aria-value*`
+attributes, because pressing it no longer does anything. A quiz marks the right
+answer AND the viewer's wrong pick — hiding the right answer teaches nobody.
+
+## `StickerMessage` and `GifMessage`
+
+```tsx
+<StickerMessage source={sticker} accessibilityLabel="Sticker: grinning sun" />
+<GifMessage source={gif} aspectRatio={1.6} />
+```
+
+**A sticker draws NO surface** — no background, no radius, no padding. Render it
+with `message-bubble`'s `variant="bare"`: a bubble behind a sticker is a picture
+of a sticker, and its scrim turns a cut-out into a square. `resizeMode` is
+`contain`; cropping one cuts the drawing. The NAME matters more here than
+anywhere else — a sticker IS its meaning and there is no caption beside it, so
+pass the emotion rather than letting it announce "Sticker".
+
+A GIF is capped narrower than a photo (220 rather than 260) because they are
+usually low-resolution. The pill is the only thing that says the frame moves,
+which matters when it has not started — Android's `Image` decodes an animated
+GIF as a still unless the app enables the animated decoders in its Fresco
+config, so `playing={false}` plus the play glyph is the honest state there.
+
+## `LinkPreviewMessage`
+
+```tsx
+<LinkPreviewMessage
+  url="https://example.invalid/guides/moving-in"
+  siteName="Vila Nova Guide"
+  title="What to check before you sign a lease"
+  description="Damp, meters, deposits…"
+  image={cover}
+  layout="large"        // or "inline": a 56px thumb beside the text
+/>
+```
+
+**Why this is not `link-preview`'s `LinkPreviewCard`.** That card was read first
+and is the right component everywhere else; it is a `Card variant="outlined"` at
+`radius-20` painting `colors.text` / `colors.textSecondary` on `colors.card`.
+All three are PAGE colours. Dropped into an outgoing bubble it draws a
+page-coloured card on the accent fill — a second surface inside the message,
+with its own border and background, and a body colour that is a grey on a
+saturated fill. Giving it a tone, a palette and a no-chrome mode would be a
+different component wearing the same name. So the bubble's preview is its own
+block: no surface, an accent RULE down the left edge instead of a border, every
+colour from the tone's palette. Use `LinkPreviewCard` outside a bubble and this
+inside one.
+
+## `SharedMediaGrid` and `DocumentGrid`
+
+The two tabs of a chat's info panel.
+
+```tsx
+<SharedMediaGrid items={media} width={340} maxItems={9} onPressItem={open} onPressOverflow={seeAll} />
+<DocumentGrid items={files} onPressItem={open} onDownloadItem={save} />
+```
+
+`SharedMediaGrid` is the tight 3-column grid: square tiles, 2px gaps, radius 4 —
+a grid, not a row of cards. At three columns a 16px radius on every tile turns
+it into a pattern of gaps, and the outer corners belong to the panel. Column
+widths are integers summing to the width, the same arithmetic the album uses.
+"+N more" REPLACES the last tile so the grid stays rectangular.
+
+`DocumentGrid` is the files tab: a list of `FileMessage variant="compact"` rows,
+so the icons, colours, meta line and download ring are the ones the bubble draws.
+A second file-row implementation is a second place for the size format to drift.
+
+**The row's press target is the identity half only.** The download / cancel
+control beside it is its own button, laid out as a sibling — nesting it inside
+the row's `Pressable` would be a button inside a button (invalid HTML, and one
+action announced twice). `testID`-wise that is `<id>-open` for the row's press
+target and `<id>-row` for the box around both.
+
+## Exports
+
+Components aside, the family publishes the maths so an app can lay out against
+it: `albumLayout`, `albumRows`, `pollPercentages`, `formatVoteCount`,
+`resampleWaveform`, `seekPositionAt`, `nextPlaybackRate`, `fileKindFor`,
+`fileTypeLabel`, `resolveMessageMediaPaint`, `resolveBubbleColor`.
+
+## Images
+
+Every `source` accepts a full URL, an RN source object, a `require()` result, or
+a bare Oxy file ID resolved through the registered `ImageResolver` — the same
+rule `Avatar` uses, so one registration covers the whole family. A file ID with
+no resolver renders the placeholder rather than requesting a broken URL.

package/docs/music-library.mdx

@@ -115,7 +115,7 @@ A 48-tall full pill: search glyph, input, a clear × once there is text, then a
 />
 ```
 
-Pills painted like `Chip` (neutral at rest, primary subtle when selected), 32 tall, scrolling sideways when they do not fit. A `tablist` of `tab`s with `aria-selected`; on web the row is one tab stop and the arrow keys, Home and End move focus.
+`Chip`s on the `xl` rung (32 tall, 12px sides): neutral at rest, the brand subtle tint when selected. The row is a `ChipRow`, so it scrolls sideways with a fade at whichever edge has more behind it. A `tablist` of `tab`s with `aria-selected` — `Chip`'s `role="tab"`, which picks `aria-selected` over `aria-pressed`; on web the row is one tab stop and the arrow keys, Home and End move focus.
 
 ## `TopResultCard`
 

package/docs/offering-badge.mdx

@@ -46,6 +46,12 @@ re-exported here.
 A full pill, 4 between the icon and the label, the leading padding 2 tighter
 when there is an icon. One line, truncated.
 
+Those two rows ARE [`Badge`](/docs/bloom/main/badge)'s `label-small` and
+`label-medium` rungs, and this component is a preset over them — about forty
+lines that map an offering to a word, a glyph and a tone. It used to carry its
+own copy of the geometry, its own paint resolver and its own pill, and the
+listing card's status pill had grown a third copy of the same table.
+
 | offering          | icon                   | tone      |
 | ----------------- | ---------------------- | --------- |
 | `long_term_rent`  | `RiKey2Line`           | `info`    |
@@ -63,9 +69,9 @@ whereas a brand tint would collide with one of them (a blue brand IS `info`, a
 green one `success`). Swap takes the one neutral, which no preset can collide
 with. The four stay distinct on every preset in both modes.
 
-`onMedia` is a `neutral-50` pill with a `neutral-900` label and icon and
-`shadow-s`, the same in both modes because the photo under it does not change
-with the theme.
+`onMedia` is `Badge`'s own `onMedia` fill: a `neutral-50` pill with a
+`neutral-900` label and icon and `shadow-s`, the same in both modes because the
+photo under it does not change with the theme.
 
 ## Accessibility
 

package/docs/overlay.mdx

@@ -42,6 +42,43 @@ Toasts are the one deliberate exception: `ToastHost` mounts for the app's whole
 life, so taking a rank would wedge the counter, and it passes an explicit
 `zIndex` instead.
 
+## An overlay starts a new painting context
+
+`OverlayRoot` publishes surface level 0 for everything inside it (the ladder in
+[Styles](/docs/bloom/main/styles)). React context reaches through a portal even
+though the DOM does not, so without that reset a dialog opened from a control
+inside a `ContentPanel` would inherit "I am on a card" and paint itself
+differently from the same dialog opened on a bare screen — a surface taking its
+colours from where its TRIGGER lives.
+
+It publishes the **rung alone, with no `fill`**, and that is the shape of what an
+`OverlayRoot` knows. It paints nothing itself — it is a transparent, `box-none`
+full-screen layer — so it has no colour to report. What it can say truthfully is
+"you are not on the surface your trigger was on", and level 0 is the assumption
+that costs least when nothing better arrives: the page rung, which is what every
+unwrapped consumer already assumed.
+
+The surfaces that DO know their colour declare it INSIDE their own `OverlayRoot`,
+which is what makes each claim absolute rather than a step off an ancestor it
+cannot see:
+
+| Surface | Publishes |
+| --- | --- |
+| `dialog/Dialog` (both forks) | level 0, `fill` = `colors.background` |
+| `bottom-sheet/BottomSheetBase` | level 0, `fill` = `colors.background` |
+| `floating/FloatingPanel` | level 1 — the menu/popover surface |
+
+**Not every overlay body paints `colors.background`.** `SettingsModal` paints
+`resolveSettingsPalette(theme).full` and `Tooltip` paints the menu palette, and
+neither publishes a fill — so content inside either reads the page rung rather
+than the real colour behind it. That is an approximation inherited from before
+the ladder existed, not a claim this root makes; the fix is for each surface to
+publish its own `fill`, not for `OverlayRoot` to guess one on its behalf.
+
+Native bottom sheets never reach an `OverlayRoot` (they mount in an RN
+`<Modal>`), so `bottom-sheet/BottomSheetBase` does the same reset itself, once,
+for every sheet-presenting family.
+
 ## The `pointerEvents` rule
 
 `box-none` and `box-only` are React Native-only values and **must be passed as

package/docs/popover.mdx

@@ -110,6 +110,14 @@ A popover centres on its trigger by default, where a menu starts at its left edg
 
 A numeric `maxWidth` prop replaces the viewport cap.
 
+## Following the anchor (web)
+
+An open panel tracks its trigger. Bloom listens for `scroll` in the CAPTURE phase, which is the only listener that hears a scroll inside an ancestor — a panel opened from a row of a scrolling list stays on its row — plus `resize`, because the viewport is what the surface flips and clamps against.
+
+What it does NOT do is work per event. A scroll gesture dispatches a stream of events and nested scrollers dispatch one each, while the browser paints once; so the measurement is coalesced to at most one pass per animation frame, and the frame boundary is the last moment before the paint, which makes it the most recent position the panel can be given. A pass that resolves to the box the surface already holds is dropped rather than stored: the anchor and the placement keep their identity, nothing re-renders, and the listeners — registered once when the panel opens — are not detached and re-attached. Opening still measures synchronously in a layout effect, so the first painted frame is already in the right place.
+
+This is `FloatingPanel`'s behaviour, so it is every menu, popover and select's; `Tooltip` follows its trigger every frame instead, for the reason its own page gives. The cost model is pinned by `src/__tests__/floating-anchor-cost.test.tsx`, which counts measurements, commits and listener registrations in a real DOM.
+
 ## Native
 
 The popover is a bottom sheet on native: a phone has no room to float a panel beside a control, and every Bloom overlay resolving to the same sheet is what makes the native surfaces feel like one system. The sheet is the chrome (its surface, corner and drag handle), so the placement props are ignored and only the body takes the panel geometry — the same 10px inset on the sides and bottom, below the handle's clearance — so the panel parts line up exactly as they do on web. `className`, `style` and `testID` land on that body.
@@ -125,3 +133,10 @@ Press outside or hit Escape. `dismissible={false}` turns both off, for a popover
 Escape stops at the innermost open surface, so a popover opened from inside a dialog closes the popover and leaves the dialog up.
 
 The outside press is caught by a transparent backdrop (it closes the popover and goes no further). Popovers are non-modal — a press outside would otherwise also reach the page — but Bloom keeps the caught press so a popover opened inside a dialog cannot dismiss the dialog with the same click.
+
+## The panel publishes its surface
+
+`FloatingPanel` — the surface behind every menu, popover, select and tooltip —
+wraps its children in `SurfaceLevelProvider level={1}`
+([Styles → Ambient level](/docs/bloom/main/styles)). A `TextField` inside used to
+step off the PAGE and land on exactly the panel's own fill (1.000:1, no shell).

package/docs/property-insights.mdx

@@ -146,13 +146,21 @@ the band stay the model's range — only the picture refuses to look precise.
 
 ## `PricePerAreaComparison`
 
-Rows of label + `display` over an 8-tall bar from zero; the `highlight` row is primary,
-the rest neutral. A named list; each row reads "This home: €2,790/m²".
+Rows of label + `display` over an 8-tall bar from zero. This is the one family here
+that is a CHART rather than a meter — each bar is a different subject compared with
+the others — so its colours come from the chart palette, not the meter's: the
+`highlight` row takes the brand-anchored data hue (`chartHueTone(theme, 6)`) and the
+comparators `neutralSeries`. Painting them with the accent would have said each row was
+progress toward something. There is no rail: `neutralSeries` is neutral-800 in dark, so
+on any rail dark enough to read as one the comparators land on its colour — and a bar
+chart does not draw the remainder anyway. A named list; each row reads
+"This home: €2,790/m²".
 
 ## `NeighbourhoodScores` and `NearbyPlaces`
 
 `NeighbourhoodScores` draws each score as a bar (`variant="bars"`, default) or a 56px
-ring (`rings`), with an optional icon and a short `description`. The labels are yours
+ring (`rings`) — both [`Meter`](/docs/stat-bar) and `MeterRing`, so the shared
+neutral track and accent fill — with an optional icon and a short `description`. The labels are yours
 ("Transport", "Schools", "Quiet"…); `max` defaults to 10. Columns: 1 below 560 wide,
 2 from 560 (`columns`). Every bar or ring is a `progressbar` named by its label with
 flat `aria-valuemin/max/now` and `aria-valuetext` ("9.2 out of 10").
@@ -175,3 +183,10 @@ success (`deltaTone` overrides). An empty list draws "No history for this home y
 - "Why this estimate" carries `aria-expanded` (web) and `expanded` (native).
 - Nothing relies on colour alone: verdicts are words, events are labelled, the energy
   class is a letter.
+
+## Quiet labels
+
+`muted` is floored with `quietTextOver` against BOTH fills the family paints on
+(the page and the card), rather than taken from `theme.colors.textTertiary` —
+which is the page's rung and was 4.04:1 in light before it was fixed. See
+[Styles → Quiet text](/docs/bloom/main/styles).

package/docs/queue-panel.mdx

@@ -70,7 +70,9 @@ Three ways, one callback — `onReorder(section, from, to)`, with indices inside
 
 Every move is announced: "Slow Tide moved to position 2 of 3" — through a polite live region on web and `AccessibilityInfo.announceForAccessibility` on native.
 
-`moveQueueItem(list, from, to)` applies a move to your array (a new array, target clamped). `queueDragTarget` and `queueDragShift` are the arithmetic the drag uses, exported for anything that wants to draw the same preview.
+`moveQueueItem(list, from, to)` applies a move to your array (a new array, target clamped; an out-of-range `from` is refused rather than clamped, so a stale index cannot move the wrong row). `queueDragTarget` and `queueDragShift` are the arithmetic the drag uses, exported for anything that wants to draw the same preview.
+
+All three are re-exports of `moveItem` / `dragTarget` / `dragShift` from [`@oxy.so/bloom/hooks`](/docs/bloom/main/hooks), which the track list and the sortable photo grid share. `queueDragTarget` used to answer slot `0` when the row height was not measured; it now answers `from`, i.e. "it has not moved".
 
 ## `RecentlyPlayedList`
 
@@ -114,3 +116,10 @@ Every string is in `labels` — pass any subset to translate. The ones that name
 ## Colours
 
 From the theme only, light and dark: the panel is the menu surface and hairline, a row under the pointer takes the menu row highlight, the glyph buttons one neutral step above it, and the playing title the accent. Hover and press change colour only; nothing scales.
+
+## The panel publishes its surface
+
+In `panel` variant the family wraps its content in `SurfaceLevelProvider level={1}`
+([Styles → Ambient level](/docs/bloom/main/styles)), so a control inside steps off
+the PANEL rather than off the page. Without it a `Tabs` strip inside painted its
+rail `neutral-800` — the panel's own fill, ΔE 0.

package/docs/radio.mdx

@@ -93,3 +93,10 @@ right.
 `value` may be `undefined`. Prefer that over pre-selecting an option the user
 did not choose: a default that happens to be first is indistinguishable from an
 answer, and it silently becomes the submitted value.
+
+## The focus ring's gap
+
+Both the row's dot ring and `RadioCard`'s ring take their 2px gap from
+`var(--bloom-ring-offset)`, set inline from the surface behind the control. It
+was a hardcoded `#FFFFFF` — a white halo in dark mode. See
+[Styles → The focus ring gap](/docs/bloom/main/styles).

package/docs/rating.mdx

@@ -46,6 +46,10 @@ apps in other languages pass `accessibilityLabel`.
 | `display`    | the text on the right ("4.9", "86%"), also the bar's `aria-valuetext`      |
 | `labelWidth` | without it the label flexes and the bar is 96 wide (a category list); with it the bar flexes (a distribution) |
 
-The track is 4 tall with a 2px radius, neutral-200 (dark neutral-800), filled
-with text-primary. The bar is a `progressbar` carrying `aria-valuemin`,
-`aria-valuemax` and `aria-valuenow`.
+The bar is a [`Meter`](/docs/stat-bar): 4 tall with a 2px radius, the shared
+neutral-200 (dark neutral-700) track, filled with the ACCENT. It used to be
+filled with text-primary — a near-black bar reading as ink rather than as a
+measurement — and a rating breakdown is not a chart: the rows do not encode
+different categories by colour, they all say "how good is this, out of 5". It is
+a `progressbar` carrying `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and
+`aria-valuetext` (from `display`).

package/docs/settings-list.mdx

@@ -88,26 +88,112 @@ When `rightElement` is set, the chevron is hidden automatically (you can overrid
 />
 ```
 
-## On a card-coloured surface
+## The group knows what it is sitting on
 
 A group paints the `card` colour, which reads as a raised card on a page painted
-in `background`. Inside something that is already `card` — a `ContentPanel`, a
-Dialog body — that same group has no edge left and its rows float on the page.
-`variant="filled"` paints the group in `backgroundSecondary` instead, the same
-surface `Card variant="filled"` uses:
+in `background`. Inside something *already* painted `card` — a `ContentPanel` —
+that same group has no edge left: the rows float, and the group is there,
+correct, and invisible.
+
+**You do not tell it which.** A container that paints a surface publishes the
+colour it painted (the surface ladder in [Styles](/docs/bloom/main/styles)), and
+the group resolves off that colour:
+
+- on the **page**, `theme.colors.card` — what these groups have always painted;
+- on **anything else**, one ladder step off the fill the container published.
+
+So this is the whole of it, on a page and in a panel alike:
 
 ```tsx
 <ContentPanel>
-  <SettingsListGroup variant="filled" title="Account">
+  <SettingsListGroup title="Account">
     <SettingsListItem title="Privacy" onPress={openPrivacy} />
   </SettingsListGroup>
 </ContentPanel>
 ```
 
-| `variant` | Surface | Use on |
-| --- | --- | --- |
-| `plain` (default) | `card` | a page painted in `background` |
-| `filled` | `backgroundSecondary` | a surface painted in `card` |
+This used to be a `variant="filled"` at every call site — ~75 of them in one app
+with a settings tree, each one a chance to forget, and forgetting produced no
+error and no visible control. A question about the PARENT is not something a call
+site should have to answer.
+
+| `variant` | Surface |
+| --- | --- |
+| *(unset — the normal case)* | `card` on the page; one step off the container's own fill anywhere else |
+| `plain` | `card` |
+| `filled` | `backgroundSecondary` |
+
+**A step, rather than `backgroundSecondary`, because `backgroundSecondary` is
+calibrated against `card` and nothing else.** On a `ContentPanel` it works (dark
+1.378–1.404 across all 64 presets); on the menu surface `FloatingPanel` and
+`QueuePanel` publish it measures **1.086–1.106 in dark, failing the ladder's 1.1
+just-noticeable floor on 52 of the 64 presets** — the disappearance this default
+exists to prevent, one container over. The step measures 1.296–1.312 there, on
+all 64. In light both clear it, which is why this is only visible if you look in
+dark.
+
+### Every container this changes
+
+Anything that publishes a surface now decides what a group inside it paints, not
+just `ContentPanel`:
+
+| Container | What a group inside it paints now |
+| --- | --- |
+| a bare screen | `card` — unchanged |
+| `ContentPanel` | a step off the panel's fill (was `card` unless you passed `variant="filled"`) |
+| `FloatingPanel` — `Popover`, `DropdownMenu`, `ContextMenu`, `HoverCard`, `Select`, menu flyouts | a step off the menu surface (was `card`) |
+| `QueuePanel` (as a panel) | a step off the panel surface (was `card`) |
+| `Dialog`, `BottomSheet` and the sheet-backed surfaces | `card` — unchanged; they publish `colors.background` |
+
+The first row and the last are the ones to notice: nothing on a plain screen and
+nothing in a dialog moves. A group that was ALREADY passing `variant="filled"`
+inside a panel keeps painting `backgroundSecondary` until the prop comes off.
+
+### When to pass `variant` anyway
+
+For a surface Bloom does not paint and so cannot publish a fill for — your own
+coloured section, a third-party container. An explicit `variant` always wins over
+the ambient one.
+
+```tsx
+<View style={{ backgroundColor: colors.card }}>
+  <SettingsListGroup variant="filled" title="Account">…</SettingsListGroup>
+</View>
+```
+
+The alternative, if that container is yours and holds more than a settings list,
+is to publish the surface once instead of annotating everything inside it.
+`SurfaceLevelProvider` ships on the **`styles` subpath**, not the root barrel:
+
+```tsx
+import { SurfaceLevelProvider } from '@oxy.so/bloom/styles';
+
+<View style={{ backgroundColor: mySectionColour }}>
+  <SurfaceLevelProvider level={1} fill={mySectionColour}>
+    <SettingsListGroup title="Account">…</SettingsListGroup>
+  </SurfaceLevelProvider>
+</View>
+```
+
+Pass `fill` as well as `level`: the level says how deep you are, the fill says
+what you actually painted, and it is the fill the group steps off.
+
+### Overlays do not inherit the panel
+
+A dialog, a bottom sheet or a menu opened from inside a `ContentPanel` starts its
+own painting context, so a group inside a dialog is a `card` again whether the
+trigger lived on a bare screen or inside a panel. That takes a deliberate reset:
+React context reaches through a portal and through an RN `<Modal>` even though
+neither paints anything. `Dialog` and the bottom-sheet shell publish
+`colors.background`, `FloatingPanel` publishes the menu surface, and
+`overlay/OverlayRoot` resets the ambient surface for anything portaled that does
+neither.
+
+Two portaled surfaces paint something they do not publish — `SettingsModal`
+(`resolveSettingsPalette(theme).full`) and `Tooltip` (the menu palette) — so a
+group inside either reads the page rung and paints `card`. That is inherited from
+before the ladder existed, and the fix is for each of them to publish its own
+fill.
 
 ## Footer / header text
 
@@ -134,7 +220,7 @@ surface `Card variant="filled"` uses:
 | `footer?` | `string` | Section footer. |
 | `children` | `React.ReactNode` | `Item`, `Divider`. |
 | `style?` | `StyleProp<ViewStyle>` | Override group container style. |
-| `variant?` | `'plain' \| 'filled'` | The group's surface: `card` (default) or `backgroundSecondary`, for a group on a card-coloured surface. |
+| `variant?` | `'plain' \| 'filled'` | Overrides the surface the group would resolve from the container's published fill — `card` or `backgroundSecondary`. Normally left unset; see [above](#the-group-knows-what-it-is-sitting-on). |
 
 ### `SettingsListItem`