@oxy.so/bloom 2.10.0 → 2.12.0

package/docs/listing-card.mdx

@@ -84,6 +84,8 @@ and plural rules. Nothing here computes a price.
 | `badge`                                | top-left over the photo — a string draws the white pill, any node is placed as given                      |
 | `favorite`, `onFavoriteChange`         | the heart, top-right; drawn only when `onFavoriteChange` is given                                          |
 | `onPress`, `href`                      | see below                                                                                                  |
+| `onLongPress`, `onContextMenu`         | the press shortcut — see below                                                                             |
+| `hoverZoom`                            | web only, off by default: the photo scales 1.06 under the pointer                                          |
 | `loading`                              | a skeleton in the same geometry (`aria-busy`)                                                              |
 | `layout`                               | `'vertical'` (default, photo 20:19) or `'horizontal'` (square photo 40% wide, for lists and map sheets)   |
 | `density`                              | `'comfortable'` (default) or `'compact'`, a dense list row — see below                                    |
@@ -106,6 +108,32 @@ anchor's default navigation is prevented and `onPress` runs — a router takes i
 On native, `href` alone opens with `Linking`. With neither the card is not a
 control.
 
+**The press shortcut.** `onLongPress` fires on a long press — native, and a
+touch-and-hold on web. `onContextMenu` is its pointer spelling: a right-click on
+web, with the event defaulted for you, which is the same contract
+[`MessageBubble`](/docs/message-bubble) carries. Two props rather than one
+bridged prop, because they are two different events and an app may well want
+only one of them.
+
+Two things follow from defaulting the event. The browser's own menu — "open in
+a new tab", "copy link address" — no longer appears **on the card** while
+`onContextMenu` is set, so set it only where the shortcut is worth that. And
+neither event has a keyboard spelling or a name to announce, so whatever they
+open must be reachable another way: the heart, a row in a menu, a button on the
+detail screen. A long press is a shortcut, never the only door.
+
+**Hover zoom.** `hoverZoom` scales the photo to 1.06 while the pointer is over
+the card, 400ms, inside the tile that already clips — the photo comes forward,
+the card does not move and the grid does not reflow. It is WEB ONLY and guarded
+by `@media (any-hover: hover)`, so a touch screen reporting a hover it cannot
+deliver is left out, and it does nothing at all under
+`prefers-reduced-motion: reduce`. The compact density ignores it: a 112px
+thumbnail has nothing to come forward from.
+
+It is **off by default.** A card that grows under the pointer is a decision an
+app makes for its own grid, not one to turn on under every app already shipping
+this card.
+
 **The controls are siblings of the link, not children.** The heart and arrows are
 laid over the photo from outside the link: a button inside an anchor is invalid
 HTML, and would make pressing the heart open the stay. Each is its own tab stop.
@@ -190,6 +218,32 @@ it, two sit side by side, three put one tall photo beside two, four (or more) ma
 a 2×2 of the first four. The name and `description` sit under it. `onPress` and
 `href` behave as on `ListingCard`; the name is "Coast weekends, 12 saved".
 
+| prop              | decides                                                                                  |
+| ----------------- | ---------------------------------------------------------------------------------------- |
+| `name`            | the collection's name, one line                                                          |
+| `description`     | the pre-formatted line under it ("12 saved")                                              |
+| `photos`          | up to four covers, URLs or `ImageResolver` ids                                           |
+| `icon`            | a 16px glyph left of the name — decorative                                               |
+| `color`           | the `icon`'s colour, and the empty cover's tint                                          |
+| `empty`           | what the cover holds while `photos` is empty                                             |
+| `onPress`, `href` | as on `ListingCard`                                                                      |
+| `accessibilityLabel`, `style`, `testID` | `testID` derives `-cover`, `-icon`, `-empty`                           |
+
+**The icon goes beside the name, never inside it.** A folder emoji typed into
+`name` is read out by a screen reader as its character, cannot be coloured or
+sized, and counts against the one line the name gets. `icon` is a
+[`BloomIconComponent`](/docs/icons), `aria-hidden`, drawn at 16 in `color` (or
+text-secondary), and the name keeps its own line.
+
+`color` is the caller's colour rather than a token, because a collection's
+colour is the person's choice and Bloom has no ramp for it. It paints the glyph
+and tints the cover while the collection is empty.
+
+**Empty.** With no photos the cover is the placeholder square, and `empty` is
+centred in it — a glyph, a line, an "add your first save" affordance. Without
+`empty` it is the plain square it has always been, so nothing changes for a
+caller that has not asked for one.
+
 ## Colours
 
 All from the theme: the text is `text` / `textSecondary`; the badge pill and the
@@ -198,3 +252,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.