@oxy.so/bloom 2.10.0 → 2.11.0

package/docs/design-tokens.mdx

@@ -204,6 +204,40 @@ memory rather than from the file, `bloomDesignTokens()` from
 | `border-border-input` | input border | `--input` |
 | `border-border-input-active` | focused input | `--ring` |
 
+### One quiet-text role, one colour
+
+`text-text-tertiary` and `theme.colors.textTertiary` are the **same colour**:
+`--muted-foreground`, the theme's one quiet-text token.
+
+They were not. The utility has always aliased `--muted-foreground` (8.42:1 light
+/ 11.33:1 dark) while `theme.colors.textTertiary` read the engine's `outline`
+(4.04:1 / 6.12:1) — one named role, two colours, and the JS one was **below AA
+for body text in light**. The tie is broken toward the token, because a fixed
+third grey cannot be a third rung: it is measured against one surface and used on
+all of them. `neutral-400` is the same mistake one ramp over — it clears AA on
+the page and measures 2.42:1 on a chart card.
+
+**A genuinely quieter rung is asked for against the fill it lands on**, with
+`surfaceTextOn(theme, fill).textTertiary` — see
+[Styles](/docs/bloom/main/styles). That is what `chart-cards`, `creator-studio`,
+`property-insights`, `media-header` and `text-field` now do.
+
+Gates: `surface-levels.test.ts` (both spellings agree, and clear AA, over all 64
+presets x 2 modes) and `surface-level-adoption.test.ts` (the families).
+
+## Surfaces above the page
+
+The ramp below answers where the PAGE's own rungs sit. It does not answer "the
+surface one level above the current one", which is what a card, a popover tile
+or a field inside either of them needs — and thirty families each answered that
+by hand, leaving four different dark card fills in one tree.
+
+That question belongs to `styles/surface-levels.ts`
+([Styles](/docs/bloom/main/styles)): `resolveSurfaceLevel`, `surfaceFillOn`,
+`hairlineOn`, `surfaceTextOn` and the `SurfaceLevelProvider` that lets a
+container publish the rung its children sit on. It is built BESIDE the policy,
+reading `theme.colors`, and changes no preset and no token.
+
 ## The neutral surface ramp
 
 `--background`, `--surface`, `--popover`, `--muted`/`--accent` and `--card` are a

package/docs/dropdown-menu.mdx

@@ -150,6 +150,8 @@ Verified in a real browser by `scripts/verify-submenu-flyout.mjs` — jest can s
 
 On native these are ignored. The menu is a bottom sheet, which is anchored to the screen rather than to the trigger.
 
+An open menu follows its trigger as the page scrolls, at one measurement per animation frame and no re-render when nothing moved — the same panel behaviour every anchored surface gets, described under [Popover → Following the anchor](/docs/bloom/main/popover).
+
 ## Naming a row that is not a plain string
 
 A row whose child is a string names itself. A row composed of elements does not:

package/docs/hooks.mdx

@@ -58,6 +58,49 @@ The shared press transform, so a press dip is the same everywhere.
 The screen's horizontal insets, from one place, so a header and the content
 below it agree about where the margin is.
 
+## `useContainerWidth`
+
+The width the component was laid out at, or `null` before the first layout.
+
+```tsx
+const { width, onLayout } = useContainerWidth();
+
+<View onLayout={onLayout}>
+  {width !== null && width >= 600 ? <Wide /> : <Narrow />}
+</View>
+```
+
+A component measures ITSELF rather than the window, so a page split into a
+content column and a side column picks its layout from the space it has rather
+than from the size of the screen. The width is rounded and only stored when it
+changes, so a resize that lands on the same pixel does not re-render.
+
+Nine families across housing and music reached into `listing-details` for this
+before it lived here.
+
+## `moveItem` / `dragTarget` / `dragShift`
+
+The list maths behind every drag-to-reorder surface — a track list, a queue, a
+photo grid. Pure, so the drag, the keyboard path and the move buttons share one
+definition of "move".
+
+```tsx
+const target = dragTarget(drag.from, drag.dy, ROW_HEIGHT, rows.length);
+const shift  = dragShift(index, drag.from, target, ROW_HEIGHT);   // px, per row
+onReorder(moveItem(rows, drag.from, target));
+```
+
+Degenerate input, where the three copies of this used to disagree:
+
+- `moveItem` clamps and rounds the TARGET into range, but refuses an
+  out-of-range SOURCE — clamping that would silently move the wrong item.
+- `dragTarget` answers `from` when there are no rows or the row has not been
+  measured (`rowHeight <= 0`). Answering `0` sends the row to the top of a list
+  nobody has measured yet.
+
+`@oxy.so/bloom/queue-panel` publishes the same three as `moveQueueItem`,
+`queueDragTarget` and `queueDragShift`; they are re-exports.
+
 ## `useHaptics`
 
 Haptic feedback through Bloom's optional-peer boundary — a no-op when

package/docs/icons.mdx

@@ -36,6 +36,67 @@ Colour travels on `fill` and size on `size` (the `xs`…`xl` rung, or `width` /
 label has to be told both — an icon that "looks black in dark mode" is almost
 always one that was never given a `fill`.
 
+## `BloomIconComponent` — the type of an icon you hand to a component
+
+Most Bloom components that take an icon take the COMPONENT, not an element, so
+they can size and colour it themselves.
+
+```tsx
+import type { BloomIconComponent } from '@oxy.so/bloom/icons';
+import { RiHotelBedLine } from '@oxy.so/bloom/icons';
+
+interface FactProps {
+  icon: BloomIconComponent;
+  label: string;
+}
+
+<ListingFact icon={RiHotelBedLine} label="2 beds" />   // ✅ the component
+<ListingFact icon={<RiHotelBedLine />} label="2 beds" />  // ✗ an element
+```
+
+```ts
+type BloomIconComponent = ComponentType<{
+  width?: number; height?: number; fill?: string;
+}>;
+```
+
+All three props are optional, which makes this the WIDEST icon a component can
+be handed: a component whose props are stricter is not assignable, on purpose.
+It is also the LEAST a part may ask for, so it is the right type wherever a part
+only sets width, height and fill — which is nearly everywhere.
+
+### What this type is NOT for
+
+A part that hands its icon more than those three props takes `Props` from
+`@oxy.so/bloom/icons` instead — the full Bloom icon surface, with `style`,
+the `size` rung, `gradient` and everything `react-native-svg` accepts.
+`IconCircle` is the clear case: it sets `size` and a `color` style, so only a
+real `Ri*` icon will do and `ComponentType<Props>` says so. `ChatIconComponent`
+(`chat-indicators`) is narrower for its own reason — it adds `testID`, because
+the chat parts label their glyphs for tests.
+
+Those are deliberate and stay. Reaching for `Props` when you only set
+width/height/fill is not: it refuses a caller's own glyph for no benefit.
+
+### The per-family names still work
+
+Twenty-five families had declared this same type under their own name
+(`SidebarIcon`, `TrackIconComponent`, `ListingFactIcon`, `PlayerGlyph`,
+`BadgeIcon`, `CallGlyph`, …). Those names still work — they are `@deprecated`
+aliases of this one — so nothing needs changing; new code should reach for
+`BloomIconComponent`.
+
+That sentence is checked rather than promised. Writing the shape out again is
+never a compile error (the literal IS the type), so a family can quietly mint a
+twenty-sixth spelling and nothing goes red — which is exactly what happened to
+`PlayerGlyph`, `BadgeIcon` and `CallGlyph`: named in this page as converted
+while their own files still declared the literal.
+`src/__tests__/icon-component-type.test.ts` now parses `src/` and holds four
+properties: the shape is declared exactly once, that one declaration is
+`icons/icon-component.ts`, the alias list is an EQUALITY (dropping one breaks a
+consumer; adding one is a new name for a type that has one), and every alias
+carries `@deprecated`.
+
 ## Migrating from the retired Bloom icon set
 
 The old `<Subject>_<Stroke2|Filled>_Corner0_Rounded` exports (and the unsuffixed

package/docs/image-resolver.mdx

@@ -34,6 +34,35 @@ That is also why there is no `avatarUrl` field on any DTO and no per-app URL
 helper: **one chokepoint**, `getFileDownloadUrl(id, variant)`, plus this
 resolver.
 
+## `isImageUrl` — the one answer to "URL or id"
+
+Every component that takes a `source` has to decide the same thing: render the
+string, or hand it to the resolver. That decision is one exported function.
+
+```tsx
+import { isImageUrl } from '@oxy.so/bloom/image-resolver';
+
+const uri = isImageUrl(source) ? source : resolver?.(source, 'thumb');
+```
+
+It is true for `http://`, `https://`, `data:`, `blob:`, `file:` and **a leading
+slash** — `/img/cover.jpg` is a root-relative path to an asset the app already
+serves. It is deliberately not a URL parser: it routes, and anything that is
+not one of those shapes is an id.
+
+**This used to differ per family.** Twelve copies of this predicate had grown across the
+package under three spellings (`isUrl`, `isImageUrl`, and an inline check in
+`Avatar`), and they disagreed. Only `listing-card`'s accepted a leading slash;
+`Avatar`'s accepted neither `blob:` nor `file:`. All of them now behave like the
+one above, which is strictly more permissive — a path or a `blob:` URL used to
+be sent to the resolver, and a resolver has nothing to answer for one, so the
+image rendered as its placeholder. If an app really does mint ids that start
+with `/`, `blob:` or `file:`, they are no longer routed to the resolver.
+
+It also tightened in one place: `media-player` and `music-library` matched on
+the bare scheme (`http:a.jpg` with no `//`), which `<Image>` cannot load anyway.
+Those strings are now treated as ids.
+
 ## `source` versus `uri` — the failure that is total and silent
 
 `Avatar` invokes the resolver only for a **non-URL string** passed as `source`.

package/docs/listing-actions.mdx

@@ -131,7 +131,7 @@ const [mode, setMode] = useState<ExchangeMode>('swap');
   `'horizontal'` or `'vertical'`.
 - **Box.** DATES | GUESTS are `BookingCard`'s cells; empty ones show
   `datesPlaceholder` / `guestsPlaceholder`.
-- **Mode.** `Chip`s — `swap` "Reciprocal swap", `host` "Guest points", `both`
+- **Mode.** `Chip`s on the `xl` rung (32 tall — a target rather than a tag) — `swap` "Reciprocal swap", `host` "Guest points", `both`
   "Either" (`EXCHANGE_MODE_LABELS`, override with `modeLabels`, restrict with
   `modes`). The chosen one is `selected` (`aria-pressed`).
 
@@ -277,8 +277,9 @@ large icon-only secondary button sits before the primary one.
 - **Calculator** fields are named by their labels; the slider is named
   "Down payment percent" with `aria-value*`; the donut is `role="img"` named by
   its two amounts; the monthly payment is a polite live region.
-- **Checklist** progress is a `progressbar` with `aria-valuenow` / `-max` /
-  `-text`; each action is named with its item ("Upload Employment contract").
+- **Checklist** progress is a [`Meter`](/docs/stat-bar) — a `progressbar` with
+  `aria-valuenow` / `-max` / `-text`; each action is named with its item
+  ("Upload Employment contract").
 - Every custom pressable shows a 2px accent ring under keyboard focus on web.
 
 **Dark mode note.** `TextField` and `Textarea` fill with neutral-800 in dark

package/docs/listing-card.mdx

@@ -198,3 +198,9 @@ arrow buttons are the floating surface (the menu palette and Bloom's secondary
 `neutral-950` at 50%, saved `red-500` from the theme's `error` hue. The photo
 placeholder is `neutral-100` (dark: the raised neutral). Offering badges take
 their colours from `OfferingBadge` (`docs/offering-badge.mdx`).
+
+## Disabled
+
+The favourite button fades to `tokens.DISABLED_OPACITY` (0.5), not the 0.6 it
+carried. See [Styles → Disabled](/docs/bloom/main/styles) for when a fade is
+allowed at all.

package/docs/listing-editor.mdx

@@ -97,7 +97,9 @@ const [offering, setOffering] = useState<OfferingValue>({ kinds: [] });
 
 ## `ListingQualityMeter`
 
-A completeness score: a ring, a checklist and tips.
+A completeness score: a ring, a checklist and tips. The ring is a 72px
+[`MeterRing`](/docs/stat-bar) — the shared neutral-200 (dark neutral-700) track
+and accent arc — easing over 400ms on web.
 
 ```tsx
 <ListingQualityMeter

package/docs/lyrics.mdx

@@ -91,11 +91,13 @@ A card with a 16 radius and 20 padding, lines in title-3 (18/26). Unsynced text
 
 `resolveLyricsPalette(theme, artworkColor)`:
 
-- **With an artwork colour**, the background is the first stop of that colour's ramp — from 800 in light mode, 900 in dark — under which white keeps **7:1**, and the text is white. The ramp's 950 stop always clears it, so a pale colour (a cream, a yellow) simply lands deeper rather than flipping to dark text.
+- **With an artwork colour**, the background is that colour pulled toward black only as far as it takes for white to keep **7:1** on it, and the text is white. Black clears any light foreground, so a pale colour (a cream, a yellow) simply lands deeper rather than flipping to dark text. It is the same in both modes — the artwork is.
+
+  It DARKENS the colour rather than walking its generated ramp, which it used to do. A ramp re-derives every stop's lightness and chroma from the hue, so a near-black `#101820` came back as a mid-slate ten times lighter than it went in, and a vivid `#1db98a` lost its red channel entirely. Scaling every channel by the same factor keeps their ratio, so a darkened teal is still teal. The trade: the pane no longer overshoots its bar, so contrast across the matrix went from a 7.84 floor to 7.00 — still AAA, and the near-black case went from 8.33 at the wrong colour to 17.89 at the right one.
 - **Without one** (or with something that does not parse), the background is the neutral surface (`neutral-100` light, `neutral-900` dark) under the theme's text colour.
 - Upcoming lines and the footer are the text colour mixed toward the background no further than **4.5:1**; past lines no further than **3:1** (they are 20px and larger). The pills are filled in the text colour with the background as their label.
 
-The test suite checks those ratios for every colour preset in both modes over a spread of artwork colours, including white, black and unparseable input.
+`src/__tests__/artwork-contrast.test.ts` checks those ratios for every colour preset in both modes over a spread of artwork colours, including white, black and unparseable input, and pins the measured floor as an EQUALITY — improving it fails as loudly as regressing it, so either way somebody looks.
 
 ## Accessibility
 

package/docs/media-card.mdx

@@ -98,7 +98,12 @@ The name is composed from the title, the type and the lines under it — "Night
 
 ## Generated covers keep their text legible
 
-A mix, a recap, a share card, a genre tile and a cover-less playlist are painted from `artworkColor`. The colour's own ramp is stepped darker (its 500, then 600 … 900) until the light text drawn on it clears **4.5:1**, and the gradient runs two stops further down — so a pale colour yields a deeper tile rather than unreadable text. Without a colour, or with one that does not parse, the cover is the theme's neutral 700 → 900. Gradient stops are always opaque: react-native-svg drops the alpha inside a stop colour.
+A mix, a recap, a share card, a genre tile and a cover-less playlist are painted from `artworkColor`. The colour is pulled toward black in 5% steps until BOTH foregrounds drawn on it — the title and the muted line under it — clear **4.5:1**, and the gradient's bottom is a further 25% darker, so a pale colour yields a deeper tile rather than unreadable text. Without a colour, or with one that does not parse, the cover is the theme's neutral 700 → 900. Gradient stops are always opaque: react-native-svg drops the alpha inside a stop colour.
+
+Two things changed when this moved onto the shared `darkenUntilContrast` ([`@oxy.so/bloom/styles`](/docs/bloom/main/styles)), which the immersive player and the browse tiles already used:
+
+- **The muted line is checked now.** It was not, and it painted at **4.18:1** — under AA — over the palest artwork colours. The title's own floor rose from 4.69 to 5.07 in the same change.
+- **The colour is darkened, not re-derived from a ramp.** A ramp re-derives each stop's lightness and chroma from the hue, so a vivid `#1db98a` came back with its red channel zeroed. Scaling keeps the channels in ratio, so a darkened teal is still teal. Pale colours land on a lighter, less saturated tile than before — more faithful to the colour the backend sent.
 
 ## Laying cards out
 

package/docs/media-controls.mdx

@@ -49,10 +49,20 @@ Every control is controlled: it draws the props it is given and reports what the
 | `variant`            | `'accent'` (default) filled accent; `'inverse'` filled in the text colour; `'plain'` the glyph alone, for rows |
 | `loading`            | a spinning ring replaces the glyph and `aria-busy` is set; the button still presses          |
 | `subject`            | appended to the name: "Play Night Drive"                                                      |
+| `interactive`               | `false` draws the disc as decoration: no button role, no focus stop, hidden from assistive tech unless `accessibilityLabel` names it — for a play glyph inside a pressable poster or row |
 | `playLabel` / `pauseLabel` | the two actions, default "Play" / "Pause" — translate them                              |
 | `accessibilityLabel` | replaces the composed name                                                                    |
 | `disabled`, `style`, `testID` |                                                                                      |
 
+**The pause glyph is Bloom's own.** Measured in the shared 24 viewBox, the play
+triangle covers 95.5 units² and a stock two-bar pause (2 × 14, twice) covers 56 —
+0.59 ×. The button therefore changed WEIGHT as it toggled, at every size, which
+is the one thing a play/pause pair must not do, since the two are the same
+control. `PauseGlyph` widens the bars to 3 and gives them the triangle's own
+vertical extent (y 4 → 20): 96 units², 1.005 ×, gap unchanged at 6. The sizes
+were always right; only the ink was not. Gate: `PauseGlyph.test.ts`, which
+measures both paths rather than pinning a remembered number.
+
 **Why no `aria-pressed`.** A toggle button keeps ONE name and flips a pressed state. This button instead names what pressing does next ("Pause Night Drive"), which is what a listener needs to hear. Doing both would announce "Pause, pressed" — two answers to one question. So it is a plain `button` whose name changes.
 
 ## `LikeButton`

package/docs/media-header.mdx

@@ -175,3 +175,9 @@ const { progress } = useMediaHeaderScroll({ start: 260, window: true });
 ## Platform notes
 
 Hover states (the edit overlay, underlined links, row washes) are web affordances; native shows the pencil badge and needs no hover. The band gradients use `background-image` on web and the native CSS-gradient style elsewhere. Keyboard focus rings hang off `data-bloom-media-header-press` in one adopted sheet.
+
+## Quiet labels
+
+`textMuted` is floored with `quietTextOver` against both the page and the card it
+paints on. As `neutral-500` it measured 4.38:1 on the light card. See
+[Styles → Quiet text](/docs/bloom/main/styles).

package/docs/media-player.mdx

@@ -149,7 +149,7 @@ The phone's floating bar above the tab bar. Press it to open the full player.
 
 ### The artwork tint and its contrast fallback
 
-`artworkColor` is a hex from the backend — never sampled from the image. `resolveArtworkTint(color, text, textMuted)` darkens it in 5% steps until BOTH the dark theme's text and muted text clear **4.5:1**, stopping at the first step that holds (a dark colour is used as given; `#F4E3A1` comes out as a deep olive). The bar's content then renders under the dark theme, so it reads light-on-colour in a light app too.
+`artworkColor` is a hex from the backend — never sampled from the image. `resolveArtworkTint(color, text, textMuted)` darkens it in 5% steps until BOTH the dark theme's text and muted text clear **4.5:1**, stopping at the first step that holds (a dark colour is used as given; `#F4E3A1` comes out as a deep olive). The walk itself is `darkenUntilContrast` from [`@oxy.so/bloom/styles`](/docs/bloom/main/styles), shared with the lyrics pane, the generated covers and the browse tiles. The bar's content then renders under the dark theme, so it reads light-on-colour in a light app too.
 
 No colour, or one that does not parse, falls back to the floating-surface recipe under the app's own theme: the card with a neutral-200 hairline (dark: neutral-800 with neutral-700).
 

package/docs/media-shelf.mdx

@@ -83,4 +83,6 @@ The same header rhythm and gaps as `Shelf`, with square (or `round`) covers over
 | `accessibilityLabel` | the group's name, default "Filters" |
 | `contentInset` | horizontal padding inside the scroll track |
 
-Each option is a large `Chip`: subtle at rest, the solid accent when selected. The row scrolls horizontally when it does not fit. Each chip is a toggle button with `aria-pressed` (and `accessibilityState.selected` on native — the `Chip` contract).
+Each option is an `xl` `Chip` (32 tall, 12px sides): neutral subtle at rest, the brand subtle tint when selected. The row is a `ChipRow`, so it scrolls sideways with an edge fade. Each chip is a toggle button with `aria-pressed` (and `accessibilityState.selected` on native — the `Chip` contract).
+
+Two things changed here and are worth knowing if you were matching them. It asked for `variant="solid"` when selected, the one filter row in the library that shouted its selection where every other one tints it. And it overrode the side padding with `paddingLeft`/`paddingRight` against a base that spells it `paddingHorizontal`, so on WEB the override dropped and the pills drew at 6 — native got 12, web got 6, and nothing failed. The rung carries 12 for both.

package/docs/message-bubble.mdx

@@ -0,0 +1,279 @@
+---
+title: Message Bubble
+description: The transcript — bubbles, runs, reactions, replies, separators and the service rows a person-to-person chat repeats on every screen.
+order: 64
+---
+
+# Message Bubble
+
+```tsx
+import {
+  CallSummaryRow,
+  DateSeparator,
+  MessageBubble,
+  MessageGroup,
+  MessageList,
+  SystemMessage,
+  TypingBubble,
+  UnreadSeparator,
+  bubblePositions,
+  groupMessages,
+  senderNameColor,
+} from '@oxy.so/bloom/message-bubble';
+```
+
+The bubble SHELL, its text and its metadata. Rich media — images, voice notes,
+files, polls — is a slot (`media`), not this family's job: pass whatever draws
+it and the bubble clips it to its own radius.
+
+Everything is a prop. No component here reads the clock: `"12:41"`,
+`"Yesterday"`, `"4 min"` and `"12.4K"` arrive already formatted, because what
+counts as "today" depends on a timezone and a locale the component cannot see.
+
+## `MessageBubble`
+
+```tsx
+<MessageBubble direction="incoming" text="Doors open at half six." time="18:02" />
+<MessageBubble direction="outgoing" text="On my way." time="18:04" status="read" />
+```
+
+| prop                      | decides                                                                      |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| `direction`               | `'incoming'` a neutral surface · `'outgoing'` the theme accent fill           |
+| `position`                | `'single' \| 'first' \| 'middle' \| 'last'` — which corner is cut             |
+| `text` / `children`       | the body; `children` wins                                                     |
+| `media`                   | the rich-media slot, edge to edge inside the radius                           |
+| `metaOverlay`             | float the meta over the media on a translucent pill (default on media-only)   |
+| `tail`                    | the SVG notch on the cut corner — OFF by default                              |
+| `senderName`              | the coloured name line (a group; `MessageGroup` normally draws it instead)    |
+| `senderColorSeed`         | what `senderNameColor` hashes; defaults to `senderName`                       |
+| `replyTo` / `onPressReply`| the quote block, and what pressing it does                                    |
+| `forwardedFrom`           | the "Forwarded from …" line                                                   |
+| `editedLabel`             | the "edited" mark in the meta row                                             |
+| `time` / `status`         | the meta row: a pre-formatted time and the delivery ticks                      |
+| `channelViews` / `authorSignature` | a channel post's view count and signature                           |
+| `reactions`               | the pills under the bubble; `onToggleReaction`, `onAddReaction`               |
+| `pending` `failed` `deleted` `selected` `highlighted` | the five states                            |
+| `onPress` `onLongPress` `onContextMenu` `onDoublePress` `onSwipeReply` | the gestures              |
+| `maxWidth`                | default `'78%'`                                                               |
+| `labels`                  | every English string this family draws                                        |
+
+### Colour
+
+`outgoing` is the theme accent. The text on it is chosen by CONTRAST rather
+than assumed: `primaryForeground`, white or near-black, whichever clears AA over
+the accent this preset resolved to. The meta row inside it is the most
+transparent mix of that on-colour that STILL clears AA — quiet, but never the
+2.8:1 a flat 60% opacity gives you on a mid-blue.
+
+`incoming` is the card in light mode and neutral-800 in dark, with a hairline in
+light mode only: a card on a near-white page has no edge of its own, a
+neutral-800 bubble on a neutral-950 page already does.
+
+### Grouping geometry
+
+Radius 18 on every corner, except ONE: the last bubble of a run cuts its own
+side to 4. `'first'` and `'middle'` stay fully round, which is what makes a run
+read as one block with a single spout instead of a column of identical
+lozenges. `MessageGroup` and `MessageList` compute `position` for you;
+`bubblePositions(count)` is exported for a list that renders its own rows.
+
+`tail` draws the notch on that corner. It is off by default and drawn OUTSIDE
+the bubble box, so turning it on re-lays out nothing.
+
+### The meta row tucks
+
+Time, "edited", views and the ticks sit bottom-right INSIDE the bubble, on the
+same line as the last words when they fit and on a line of their own when they
+do not. It is a wrapping flex row with an `auto` left margin on the meta — the
+one spelling of "float after the text" that Yoga and the browser agree on. On a
+media-only bubble it becomes a translucent pill over the media (`metaOverlay`).
+
+### States
+
+```tsx
+<MessageBubble direction="outgoing" text="Queued." status="sending" pending />
+<MessageBubble direction="outgoing" text="Did not send." failed onRetry={retry} />
+<MessageBubble direction="incoming" deleted />
+<MessageBubble direction="incoming" text="…" selected onPress={toggle} />
+<MessageBubble direction="incoming" text="…" highlighted />
+```
+
+`pending` dims. `failed` washes the fill towards the error colour and offers
+`onRetry` beside the bubble. `deleted` replaces everything with one italic line
+and no meta. `selected` bands the whole ROW — selection is a property of the
+message and the band has to reach the avatar gutter — and `highlighted` flashes
+that same band once, which is what a jump-to-message lands on. Under reduced
+motion the flash appears without animating.
+
+### Interaction
+
+`onPress`, `onLongPress` and `onDoublePress` work on both platforms;
+`onContextMenu` is web only (right-click, defaulted for you) and `onSwipeReply`
+is native only. That last split is deliberate: on web the same horizontal drag
+is text selection, and a pan handler that won that race would take away the one
+thing people do with a transcript in a browser.
+
+`onDoublePress` suppresses the second `onPress` of a pair, so "double-press to
+react" does not also toggle selection twice.
+
+### Entities
+
+`text` is scanned for links, `@mentions` and `#hashtags`. Without
+`renderEntity` they are simply painted in the accent; with it you decide:
+
+```tsx
+<MessageBubble
+  direction="incoming"
+  text="Ping @marcel about #gear"
+  renderEntity={(entity) =>
+    entity.type === 'mention' ? <Mention handle={entity.text} /> : undefined
+  }
+/>
+```
+
+Return `undefined` for a span you want the default paint for. `messageEntities`
+and `splitMessageText` are exported and pure if you want the ranges yourself.
+
+## `MessageGroup`
+
+```tsx
+<MessageGroup direction="incoming" senderName="Ana Restrepo" avatarSource={ana}>
+  <MessageBubble direction="incoming" text="First." />
+  <MessageBubble direction="incoming" text="Second." time="12:41" />
+</MessageGroup>
+```
+
+A run of consecutive messages from one sender. It computes each child's
+`position`, puts the avatar at the run's BOTTOM edge (beside the last bubble,
+the one the tail hangs off) and draws the sender name once above the first.
+Spacing is 2px inside a run and 8px between runs, so the block reads as one
+utterance and the gap reads as a turn.
+
+`showAvatar={false}` in a 1:1 chat — an avatar repeated beside every message of
+a two-person conversation is noise.
+
+### `senderNameColor(seed, theme)`
+
+The per-sender hue, exported. It hashes the seed onto the eight chart hues,
+which rotate with the theme preset, then walks that hue's ramp (600 → 900 in
+light, 400 → 100 in dark) to the first stop that clears AA over the incoming
+bubble. A single stop per mode is not enough: the hues are not equally light,
+and the yellow at 400 lands at 2.8:1 on a neutral-800 bubble where the indigo
+clears comfortably.
+
+Deterministic: same seed, same theme, same colour. Seed on a stable id
+(`senderId`), not on a display name someone can change.
+
+**Eight hues means collisions.** Two seeds in a group land on the same hue
+roughly one time in eight — the `Group conversation` story shows exactly that,
+with two of its three speakers in the same green. If a chat has to guarantee
+distinct colours, assign them yourself and pass `senderColor`.
+
+## `MessageList`
+
+```tsx
+<MessageList items={messages} showAvatars={false} showSenderNames={false} />
+```
+
+A plain vertical stack — date separators, the unread rule, service rows and runs
+— from one array. **Not virtualised**, and that is the contract: right for a
+thread you have just opened, wrong for a year of history.
+
+For a long history, render the parts yourself:
+
+```tsx
+const entries = useMemo(() => groupMessages(items), [items]);
+
+<FlatList
+  data={entries}
+  keyExtractor={(entry) => entry.key}
+  renderItem={({ item: entry }) =>
+    entry.kind === 'date' ? <DateSeparator label={entry.label} />
+    : entry.kind === 'unread' ? <UnreadSeparator />
+    : entry.kind === 'system' ? <SystemMessage text={entry.item.system} />
+    : <MessageGroup direction={entry.direction} senderName={entry.messages[0]?.item.senderName}>
+        {entry.messages.map(({ item, position }) => (
+          <MessageBubble key={item.id} {...item} position={position} />
+        ))}
+      </MessageGroup>
+  }
+/>
+```
+
+Every one of those is a standalone export that takes props and holds no list
+state.
+
+### `groupMessages(items)`
+
+Pure, exported. It inserts a `DateSeparator` when `dateKey` changes, an
+`UnreadSeparator` above an item with `unreadBefore`, and breaks a run on a
+change of `senderId`, a change of `direction`, or anything BETWEEN two messages
+— a day, the read marker, a service line. That last one matters: "Ana joined the
+group" between two of Ana's messages is a break, and a grouper that ignored it
+would round the corners of a run that no longer looks like one.
+
+## Separators and service rows
+
+```tsx
+<DateSeparator label="Today" />
+<UnreadSeparator />
+<SystemMessage text="Ana Restrepo joined the group" />
+<SystemMessage text="You pinned a message" icon={<RiPushpinLine width={12} height={12} fill={color} />} />
+<CallSummaryRow direction="incoming" outcome="missed" title="Missed voice call" time="09:41" />
+<TypingBubble senderName="Ana Restrepo" avatarSource={ana} label="Ana is typing…" />
+```
+
+`CallSummaryRow` splits direction from outcome on purpose: the ARROW says which
+way the call went and the COLOUR says whether it connected, because a missed
+incoming call and a missed outgoing call are different events and one red glyph
+for both would lose that.
+
+`TypingBubble` draws no text, so nothing can name it by contents — `label`
+(default "Typing…") is its accessible name, and an empty string is not one.
+
+## Accessibility
+
+The bubble is ONE node with a composed name: sender, text, time, then what a
+sighted reader gets from colour and a tick glyph — "Read", "Not sent",
+"Selected". The ticks inside it are hidden (`label=""`), because announcing the
+delivery state twice per message is the price of announcing it in words at all.
+
+With `selected` defined the bubble becomes a TOGGLE and carries both spellings —
+`aria-pressed` for web and `accessibilityState.selected` for native — and so
+does every reaction pill. React Native has no pressed state and react-native-web
+ignores `accessibilityState`; missing either half is silent on one platform.
+
+Pass your own `accessibilityLabel` to replace the composed one entirely.
+
+## Reaction pills
+
+```tsx
+<MessageBubble
+  direction="outgoing"
+  text="Booked it."
+  reactions={[{ emoji: '🎸', count: 2, mine: true }]}
+  onToggleReaction={(emoji) => toggle(emoji)}
+  onAddReaction={openPicker}
+/>
+```
+
+They overlap the bubble's bottom edge by 8px, which is what makes them read as
+attached to the message rather than as a row of their own, and they wrap. `mine`
+paints the pill in the accent and flips its pressed state. `onAddReaction` adds
+the `+` pill at the end; leave it out and there is none.
+
+## Localisation
+
+Every English string is in `labels`:
+
+```tsx
+<MessageList
+  items={items}
+  labels={{ deleted: 'Se eliminó este mensaje', forwardedFrom: 'Reenviado de' }}
+/>
+```
+
+`DateSeparator`, `UnreadSeparator`, `SystemMessage`, `CallSummaryRow` and
+`TypingBubble` take their text directly, since every string they draw is one
+the app already had to format.