@oxy.so/bloom 2.10.0 → 2.11.0

package/docs/call-ui.mdx

@@ -0,0 +1,297 @@
+---
+title: Call UI
+description: Voice and video calls — the stage, the controls, the incoming banner and screen, the group grid and the call log. Presentational only.
+order: 64
+---
+
+# Call UI
+
+```tsx
+import {
+  CallScreen,
+  CallControls,
+  CallControlButton,
+  CallMinimisedPill,
+  IncomingCallBanner,
+  IncomingCallScreen,
+  GroupCallGrid,
+  GroupCallTile,
+  GroupCallBar,
+  CallHistoryRow,
+  CallHistoryList,
+} from '@oxy.so/bloom/call-ui';
+```
+
+**Nothing here knows what WebRTC is.** A video frame arrives as a `ReactNode`
+slot, the elapsed time arrives as the string your app already formatted
+(`"00:42"`), and `speaking` arrives from whatever audio-level meter you run. The
+family draws a call; it does not place one.
+
+## The stage is dark in both modes
+
+A `CallScreen` backs a video frame Bloom does not own. White chrome over an
+unknown frame is the only thing that survives a bright kitchen and a dark
+bedroom in the same call, so the stage stays a deep neutral and the MODE picks
+the depth only — `neutral-900` in light, `neutral-950` in dark. The preset's hue
+still tints both, and the accent still comes from your theme.
+
+The surfaces that sit IN the app — `IncomingCallBanner`, `GroupCallBar`,
+`CallHistoryRow`/`List` — take the ordinary theme surface and flip with the mode
+like every other card in Bloom.
+
+## `CallScreen`
+
+```tsx
+<CallScreen
+  mode="voice"
+  name="Ana Restrepo"
+  subtitle="Mobile"
+  avatar={avatarUrl}
+  status="active"
+  duration="00:42"
+  encryption="End-to-end encrypted"
+  onMinimise={minimise}
+  onOpenChat={openChat}
+  controls={{
+    muted,
+    onMutedChange: setMuted,
+    speaker,
+    onSpeakerChange: setSpeaker,
+    onEndCall: hangUp,
+  }}
+/>
+```
+
+| prop                  | decides                                                                  |
+| --------------------- | ------------------------------------------------------------------------ |
+| `mode`                | `'voice'` (avatar over an accent wash) or `'video'`                       |
+| `status`              | `calling · ringing · connecting · active · reconnecting · onHold · ended` |
+| `duration`            | the elapsed time, PRE-FORMATTED. Only drawn while `active`                |
+| `statusText`          | replaces the status line entirely                                         |
+| `accentColor`         | the hue the voice stage is washed with — derive it from artwork yourself  |
+| `encryption`          | a string beside a padlock, or your own node                               |
+| `remoteVideo`         | fills the stage                                                          |
+| `localVideo`          | the picture-in-picture                                                   |
+| `localVideoCorner`    | `'top-right'` by default; CONTROLLED                                      |
+| `onMoveLocal(corner)` | called with the NEXT corner when the PiP is pressed                       |
+| `controls`            | `CallControlsProps` — the bar at the foot                                 |
+| `controlsSlot`        | replaces the bar entirely                                                 |
+| `minimised`           | collapses the whole screen to `CallMinimisedPill`                         |
+
+### The status line has a precedence, and it is a function
+
+`resolveCallStatusLine({ status, duration, statusText, labels })` is exported,
+and `CallScreen` calls it rather than branching in JSX:
+
+1. `statusText` — you said exactly what to show
+2. `ended` — **never** a timer; a frozen last tick reads as a live call
+3. `reconnecting` — the timer keeps counting underneath, but saying so while
+   the media is down is a lie the user can see
+4. `active` — `duration`, or "Connected" until the first tick arrives
+5. anything else — that status's own label
+
+Every label is overridable through `labels` for translation.
+
+### The PiP moves by PRESS
+
+A drag has no keyboard and no screen-reader equivalent, so pressing the local
+frame cycles the corners clockwise and reports the new one through
+`onMoveLocal`. The whole 96×140 frame is the target. If you want a real drag
+gesture, wrap the screen and report the corner it landed in — `localVideoCorner`
+is a controlled prop, so both paths drive the same state.
+
+## `CallControls`
+
+**A control appears when you hand it a HANDLER.** `onMutedChange` draws the mic,
+`onVideoChange` the camera, `onFlipCamera` the flip, `onEndCall` the red button.
+There is no `mode` prop and no `show*` booleans, because a list of what to show
+kept in sync with a list of what to do is two sources of truth for one row — and
+the failure is a button that does nothing.
+
+```tsx
+<CallControls
+  muted={muted}
+  onMutedChange={setMuted}
+  videoOn={cameraOn}
+  onVideoChange={setCameraOn}
+  onFlipCamera={flip}
+  onScreenShareChange={setSharing}
+  onEndCall={hangUp}
+  size="large"
+  showLabels
+/>
+```
+
+`controls` reorders and narrows the set; a key in it with no handler is still
+skipped, so it can never put a dead button back. The end button is last, always.
+
+| size     | button | glyph |
+| -------- | ------ | ----- |
+| `small`  | 40     | 20    |
+| `medium` | 48     | 22    |
+| `large`  | 56     | 26    |
+
+### Toggle accessibility
+
+`CallControlButton`'s `active` prop decides the accessibility SHAPE. Passing it
+makes the button a toggle: it emits `aria-pressed` for web **and**
+`accessibilityState.selected` for native, because react-native-web reads only
+the first and React Native has no concept of the second. Leaving `active`
+undefined makes a plain action button — "flip camera" is not a state, and a
+button reporting `aria-pressed="false"` forever announces one it does not have.
+
+The name flips with the state and says what pressing DOES: "Mute" → "Unmute".
+
+## `CallMinimisedPill`
+
+```tsx
+<CallMinimisedPill
+  name="Ana Restrepo"
+  duration="00:42"
+  muted
+  onMutedChange={setMuted}
+  onExpand={reopen}
+  onEndCall={hangUp}
+  style={{ position: 'absolute', left: x, top: y }}
+/>
+```
+
+The timer is in tabular figures, so a running clock does not jitter sideways.
+
+**It does not drag itself.** Your app knows the safe areas, the keyboard and
+what is underneath; a component that moves itself inside a layout it cannot see
+ends up under a tab bar. Pass `style` with the offsets — an animated one is
+fine.
+
+`<CallScreen minimised />` renders exactly this, reading `name`, `duration`,
+`mode`, `accentColor` and `controls.muted` from the screen's own props, with
+`onMinimise` becoming the pill's EXPAND press.
+
+## `IncomingCallBanner` and `IncomingCallScreen`
+
+The banner is a card for a call arriving while the app is open. Its two round
+buttons are SIBLINGS of the banner's own press target, never nested inside it: a
+button inside a button is one hit area on web and two announcements on native.
+
+```tsx
+<IncomingCallBanner
+  name="Marcel Dubé"
+  mode="video"            // "Incoming video call"
+  status="online"
+  onAccept={answer}
+  onDecline={decline}
+  onPress={openFullScreen}
+/>
+```
+
+The screen is the full-bleed version, with two answer modes:
+
+```tsx
+<IncomingCallScreen
+  name="Lucía Ferrer"
+  answerMode="slide"      // or "buttons" (the default)
+  onAccept={answer}
+  onDecline={decline}
+  onMessage={reply}
+  onRemind={snooze}
+/>
+```
+
+**The slide track answers a PRESS as well as a drag**, and that is not a
+convenience: the press is the same control's accessible path, so the knob
+carries `role="button"` and the accept name whichever way it is used. A release
+past 60% of the track answers (`SLIDE_ANSWER_THRESHOLD`); an unmeasured track
+never does, because `dx >= 0` is true for every stray touch.
+
+The chevrons behind the knob breathe on a 1.4s loop and stand still under
+reduced motion — the hint is the arrows, not the movement.
+
+## `GroupCallGrid`
+
+```tsx
+<GroupCallGrid
+  participants={people}          // { id, name, avatar?, video?, muted?, speaking?, presenting? }
+  maxTiles={9}
+  onParticipantPress={focus}
+/>
+```
+
+Columns are `ceil(sqrt(n))` — 2 side by side, 4 a square, 6 as 3×2, 9 as 3×3,
+12 as 4×3. `callGridColumns(n)` and `callGridLayout(count, maxTiles, columns?)`
+are exported and pure, so the arithmetic is testable without rendering.
+
+**Past `maxTiles` the last CELL becomes `+N`**, rather than a cell being added
+beside the grid: a 9-up that quietly becomes a 10-cell 4×3 the moment a tenth
+person joins is the failure that shape exists to stop. With `maxTiles={9}` and
+12 people you get 8 faces and a `+4`.
+
+`layout="spotlight"` draws one big tile over a strip of the rest. The big one is
+`spotlightId`, else whoever is `presenting`, else whoever is `speaking`, else the
+first — `callSpotlightIndex` is exported too.
+
+The grid MEASURES itself unless you pass `width`, and draws nothing until it has
+one: a first paint at zero stacks every tile on top of itself, and on native
+that frame is visible.
+
+### The speaking ring
+
+`GroupCallTile` draws it as an OVERLAY, never as the tile's own border — a
+border that appears changes the content box, so every tile would shift by 3px
+each time somebody started talking. It pulses by opacity on a 900ms loop and
+holds still at full opacity under reduced motion.
+
+## `GroupCallBar`
+
+```tsx
+<GroupCallBar
+  title="Saturday planning"
+  speakingName="Marcel"        // wins over statusText, with a live dot
+  statusText="4 on the call"
+  participants={people}
+  joined={joined}
+  onJoin={join}
+  onLeave={leave}
+  muted={muted}
+  onMutedChange={setMuted}
+  onPress={openCall}
+/>
+```
+
+The speaking line REPLACES the status line rather than sitting beside it: two
+lines in a 56px strip is a strip that scrolls, and "who is talking" is the only
+thing on it that changes second to second. Avatars overlap by 10px and the tail
+becomes a `+N` mark.
+
+## `CallHistoryRow` and `CallHistoryList`
+
+```tsx
+<CallHistoryList
+  sections={[
+    { title: 'Today', items: [{ id: '1', name: 'Ana Restrepo', direction: 'missed', meta: '09:14', count: 2 }] },
+    { title: 'Yesterday', items: [...] },
+  ]}
+  onItemPress={open}
+  onCallBack={ring}
+/>
+```
+
+**Direction is two signals, not one.** The arrow says which way the call went
+(down-left arrived, up-right left) and the COLOUR says whether it connected —
+`missed` and `declined` are drawn in the negative colour. A missed call told
+apart from a received one by hue alone is a distinction one reader in twelve
+cannot make, so the second line names it in words ("Missed · Yesterday, 18:40")
+and the row's accessible name carries it too.
+
+`meta` and every section `title` arrive PRE-FORMATTED. Deciding what
+"yesterday" means needs a locale and a timezone your app has and a component
+does not. An empty section is dropped rather than drawn with a heading and
+nothing under it; `emptyState` covers the case where every section is empty.
+
+## What jest cannot see here
+
+The suite (`src/__tests__/CallUi.test.tsx`) reads the emitted DOM through the
+real react-native-web, so it pins every accessible name, both toggle spellings
+and the grid's geometry. It cannot see whether the stage's scrim actually keeps
+the controls legible over a bright frame, whether the PiP overlaps the top bar
+on a short screen, or whether the speaking ring reads as a ring at all. Those
+are browser and device checks.

package/docs/card.mdx

@@ -104,3 +104,34 @@ because a child deliberately overflows — opts out through `style`:
 spacing and type conventions, not requirements. A card with entirely custom
 content is a normal thing; use the parts when you want the same rhythm as every
 other card.
+
+## `Card` does not publish a surface
+
+A `ContentPanel` tells its children what they are sitting on — level 1 of the
+ladder in [Styles](/docs/bloom/main/styles), plus the colour it actually painted
+— and a `Card` deliberately does not, even though it paints the same colour. The
+difference is ownership: a panel is a surface Bloom paints and keeps painting,
+while a `Card` is a box a consumer routinely repaints through `style` /
+`className`, and a fill Bloom cannot guarantee is worse than none — every
+`TextField`, `Tabs` rail, hovered row and `SettingsListGroup` inside it would
+then step off a colour that is not there. (`ContentPanel` hits the same wall when
+it IS repainted, and answers it with an explicit `surfaceColor` prop rather than
+a guess.)
+
+So a component that needs to know what is behind it inside a card is still told:
+pass `SettingsListGroup`'s `variant`, or publish the surface yourself for a card
+you know you have not repainted. `SurfaceLevelProvider` ships on the `styles`
+subpath, not the root barrel:
+
+```tsx
+import { SurfaceLevelProvider } from '@oxy.so/bloom/styles';
+
+<Card>
+  <SurfaceLevelProvider level={1} fill={colors.card}>
+    <SettingsListGroup title="Account">…</SettingsListGroup>
+  </SurfaceLevelProvider>
+</Card>
+```
+
+Pass `fill` as well as `level`: the level says how deep the subtree is, the fill
+says what you actually painted, and it is the fill everything inside steps off.

package/docs/chart-cards.mdx

@@ -165,3 +165,14 @@ Series tones follow the `CHART_TONES` order — `chart-2` lime, `chart-6` blue,
 # Building a chart card
 
 The chrome is published for composing your own card: `ChartCardSurface`, `ChartHeader` / `ChartHeadline`, `ChartRangePill` / `ChartRangeSelect` + `useChartRange`, `ChartLegend`, `ChartStatTiles`, `ChartCenterReadout` and `CartesianPlot`. `src/chart-cards/README.md` documents each one and how a card is assembled from them.
+
+## Axis labels and captions are floored on the card
+
+`textSecondary` and `textTertiary` are read off the card's own fill (and the
+stat tiles', which are a second fill they land on) with `quietTextOver` — see
+[Styles → Quiet text](/docs/bloom/main/styles). As ramp stops they measured
+4.38:1 light / 3.78:1 dark for the label and **2.42:1 / 2.29:1** for the axis
+ticks, because `neutral-400` was chosen against the page and a chart card is not
+the page. They now clear 7:1 and 4.5:1 on every preset in both modes; the delta
+chips' labels clear 4.5:1 on their own chips. Gate:
+`surface-level-adoption.test.ts`.

package/docs/chat-composer.mdx

@@ -0,0 +1,233 @@
+---
+title: Chat Composer
+description: The message bar of a person-to-person chat — attach, autosizing field, emoji, the mic that becomes send — with its banners, suggestions, voice recorder and the emoji, reaction and message menus.
+order: 64
+---
+
+# Chat Composer
+
+```tsx
+import {
+  ChatComposer,
+  ComposerBanner,
+} from '@oxy.so/bloom/chat-composer';
+
+<ChatComposer
+  value={draft}
+  onValueChange={setDraft}
+  onSend={send}
+  banner={replyTo ? <ComposerBanner kind="reply" title={replyTo.author} preview={replyTo.text} onClose={clearReply} /> : null}
+  attachments={pending}
+  onRemoveAttachment={remove}
+  onAttachPress={openAttachMenu}
+  onEmojiPress={openEmojiPicker}
+  onMicPress={startRecording}
+/>
+```
+
+A radius-24 pill: an attach button, an autosizing field that grows one 20px line at a time up to `maxLines` and then scrolls, an emoji button, and a right control that cross-fades between a mic (nothing to send) and an accent send disc (there is). Everything above the bar — reply and edit previews, the attachment strip, a slow-mode line, the suggestion list — is a separate part that composes into it.
+
+## Why this is not `composer-panel`
+
+`composer-panel` is Bloom's AI-prompt composer and stays that. It is two rows tall and its second row is a control strip: a permission mode, a model picker, an effort slider. Its state is about *how the model will answer*.
+
+This one is one row, and its state lives **above** the bar — who you are replying to, which message you are editing, what is uploading, whether the channel is in slow mode. Its right control swaps between two different actions rather than staying a send button, and its keyboard has to choose between Enter-sends and Enter-newlines because a chat message is usually one line and a prompt usually is not.
+
+What genuinely transfers is reused rather than retyped: the 56px attachment tile and the rounded-rect progress path come from `composer-panel/shared` (`ringPath`), and the 36px round control, the pill geometry and the `bg-button-primary` send gradient are the same recipe. What did **not** transfer is the two-row card, the model/permission/effort surface and the status tab.
+
+## Exports
+
+| Export | What it is |
+|---|---|
+| `ChatComposer` | The bar. |
+| `ComposerBanner` | One reply / edit / forward preview, or a one-line `note`. |
+| `ComposerAttachmentStrip` | The pending-attachment tiles. `ChatComposer` draws one from `attachments`; export it for a standalone strip. |
+| `ComposerIconButton` | The 36px round control, for a slot that has to match. |
+| `SuggestionList` | `@mention`, `/command` and `:shortcode` rows — one part, three `kind`s. |
+| `VoiceRecorder` | Recording, locked and preview. |
+| `AttachmentMenu` | The plus menu, as a `Popover`. |
+| `EmojiPicker` | The controlled emoji grid. |
+| `ReactionPicker` | The quick reaction bar. |
+| `MessageContextMenu` | The per-message menu, as a `DropdownMenu`. |
+| `formatRecordingTime`, `filterEmojiGroups`, `applySkinTone`, `emojiChar` | The pure helpers, so an app can format and search the same way. |
+| `ATTACHMENT_MENU_ITEMS`, `REACTION_PICKER_EMOJIS`, `EMOJI_CATEGORY_ICONS`, `SKIN_TONE_MODIFIERS` | Defaults, for extending rather than retyping. |
+
+## Anatomy
+
+| Part | Geometry |
+|---|---|
+| bar | radius 24, 1px border, padding 6, min height 48 |
+| controls | 36 round; the send disc paints the `bg-button-primary` gradient, the rest paint only on hover/press/focus |
+| field | `body-regular`, one 20px line, up to `maxLines` (6) then scrolls |
+| banner | radius 12, accent wash, a 3px accent rail, padding 6 / left 8 / right 4 |
+| note banner | no rail, no wash — a `caption-1-regular` line |
+| attachment tile | 56, radius 12, 1px border; the ring is a 2px accent stroke over that border |
+| suggestion row | min 44, radius 10, in a radius-16 panel |
+| emoji cell | 36; category tabs 32; the grid body is 288 tall by default |
+| reaction cell | 36 (`small` 30), in a full-pill bar |
+
+Full pill radius only on the button-like parts — the controls, the reaction bar, the emoji category tabs. The banner, the tiles and the panels keep normal radii.
+
+## Keyboard (web)
+
+| Key | What happens |
+|---|---|
+| Enter | Sends (`sendOn="enter"`, the default). With `sendOn="mod-enter"` it breaks the line. |
+| Shift + Enter | Breaks the line. |
+| ⌘ / Ctrl + Enter | Sends when `sendOn="mod-enter"`. |
+| Escape | `onEscape` — cancel the reply or the edit. |
+| ↑ on an empty draft | `onEditLast`. |
+| ↑ / ↓ with `suggestions` open | Moves `activeIndex` (wrapping) through `onActiveIndexChange`. |
+| Enter with a highlighted suggestion | Takes it instead of sending. |
+
+An open IME composition is respected: committing a candidate with Enter never sends the half-written word behind it. Native has no key events to read here — the send button is the only way to submit, and `showKeyboardHint` draws nothing off web.
+
+## State
+
+`value` / `defaultValue` / `onValueChange` — the draft, controlled or not; an uncontrolled draft clears after a send and a controlled one is left to its owner. **Everything else is a prop**, deliberately: the app owns a draft per conversation, which banner is up, what is uploading and which suggestion is highlighted. A composer that kept its own would lose all of it on the first navigation, and a highlight it owned would fight the pointer for it.
+
+Times ("12:41", "Yesterday") never appear here. `VoiceRecorder` takes `seconds` and `duration` as numbers and formats them with `formatRecordingTime`; nothing in this family reads the clock.
+
+## Slots
+
+`leading` replaces the attach button, `emojiSlot` the emoji button and `recorder` the entire bar. That is how a menu gets anchored to a control that lives inside the composer:
+
+```tsx
+<ChatComposer
+  leading={
+    <AttachmentMenu onSelect={handleAttachment}>
+      <ComposerIconButton icon={RiAddLine} accessibilityLabel="Attach" iconSize={22} />
+    </AttachmentMenu>
+  }
+  recorder={recording ? <VoiceRecorder state="recording" seconds={elapsed} amplitudes={levels} onCancel={cancel} onLock={lock} /> : undefined}
+/>
+```
+
+`AttachmentMenu` renders its child through `PopoverTrigger asChild`, which merges the open handler, `aria-expanded` and `aria-haspopup` onto it — `ComposerIconButton` accepts and forwards all three, so any other trigger you write must too.
+
+## Banners
+
+```tsx
+<ComposerBanner kind="reply" title="Ana Restrepo" preview="Still on for Thursday?" onClose={clear} />
+<ComposerBanner kind="edit" title="Edit message" preview="See you at six" onClose={clear} />
+<ComposerBanner kind="forward" title="Forward to Harbour crew" preview="1 photo" thumbnail={uri} onClose={clear} />
+<ComposerBanner kind="note" title="Slow mode: 12s" icon={RiTimerLine} />
+```
+
+`reply`, `edit` and `forward` are one row — rail, glyph, optional thumbnail, two lines, close — because they are the same affordance: *the next message is about this, and here is how to get out of it*. `note` drops the rail and the wash, which is the difference between "you are in a mode" and "here is a fact about sending". Stack several by passing a `View` of them as `banner`.
+
+`accentColor` paints the rail and the title; pass a per-sender colour to match the quoted bubble. The banner names itself from both lines, so assistive tech announces it as one thing rather than two.
+
+## Suggestions
+
+```tsx
+<ChatComposer
+  suggestions={people}
+  suggestionKind="mention"
+  activeIndex={active}
+  onActiveIndexChange={setActive}
+  onSelectSuggestion={(suggestion) => insert(suggestion.handle)}
+/>
+```
+
+One `SuggestionList` serves all three kinds; only the leading slot differs (an avatar, a glyph disc, the emoji). Rows are `role="option"` inside a `role="listbox"` with `aria-selected` — the spelling react-native-web reads; `accessibilityState` alone would render a list with no state on web. Each row is named by its label **and** handle, because "Ana" alone is ambiguous in a group.
+
+The list renders **in flow** above the bar rather than in a portal. Anchoring it over the conversation is a layout decision an app makes with its own container (`position: absolute` on a wrapper); a portal here would have to guess the scroll parent.
+
+## Voice recorder
+
+```tsx
+<VoiceRecorder state="recording" seconds={7} amplitudes={levels} onCancel={cancel} onLock={lock} />
+<VoiceRecorder state="locked" seconds={64} amplitudes={levels} onCancel={cancel} onSend={send} />
+<VoiceRecorder state="preview" seconds={position} duration={41} amplitudes={levels} playing={playing} onPlayToggle={toggle} onDelete={discard} onSend={send} />
+```
+
+`amplitudes` is `0`–`1`, oldest first. The bar count is derived from the MEASURED width, so the same recorder reads correctly in a 390px column and a 900px one, and `waveformBars` drops the overflow from the **front** — a growing array scrolls left like a live meter. Silence is floored at `0.06` so a quiet passage is a row of ticks rather than an invisible gap that reads as a dropped recording.
+
+`slideToCancel` defaults to `true` off web: a pointer has no slide gesture, so on web the hint is replaced with an explicit cancel button. The gesture itself belongs to the app — this part draws the affordance and takes `onCancel`.
+
+## Attachment menu
+
+`Popover`, not a surface of its own. Bloom's popover is already an anchored panel on a pointer and a bottom sheet on a phone, so this family ships **no platform fork**: it inherits the dismissal, stacking and focus behaviour those surfaces were gated for. `layout="grid"` (default, `columns` 4) draws 48px tinted discs with captions; `layout="list"` draws rows. `recent` is a slot above the items for a recent-gallery strip.
+
+## Emoji picker
+
+**Bloom ships no emoji dataset**, and that is the design. A full set with names and keywords is tens of kilobytes that every app with its own would still pay for, and emoji names are localised.
+
+```ts
+interface EmojiGroup {
+  key: string;      // 'smileys' | 'people' | … keys the built-in category glyph
+  label: string;
+  emojis: (string | { char: string; name?: string; keywords?: string[] })[];
+  icon?: ChatComposerIcon;
+}
+```
+
+The object form is what the built-in search matches on. A dataset of **bare glyphs still renders** — it just only matches a pasted glyph, which is the honest behaviour rather than a silent one. Pass `filter={false}` to hand searching to the app entirely and supply pre-filtered `groups`.
+
+The grid is a `FlatList` on **both** platforms, over pre-chunked rows rather than single emoji, with exact `getItemLayout` offsets. A few thousand entries is the normal case: at eight columns that is a few hundred rows of which a dozen are mounted, and the exact offsets are what let a category tab jump straight to its header instead of estimating. The active category follows a TAP, not the scroll position — tracking the scroll would need viewability callbacks whose thresholds differ per platform.
+
+`skinTone` (0–5) applies a Fitzpatrick modifier through `applySkinTone`, which only modifies an emoji whose base accepts one and never splices a modifier into a ZWJ sequence — that renders a stray colour square beside the glyph. `tabs` adds top-level siblings to "Emoji" (stickers, GIFs) whose `content` replaces the body.
+
+## Reactions and the message menu
+
+```tsx
+<ReactionPicker selected={mine} onSelectEmoji={react} onMorePress={openPicker} />
+
+<MessageContextMenu items={items} onSelect={run} selectedReaction={mine} onSelectReaction={react} onMoreReactions={openPicker}>
+  <MessageBubble … />
+</MessageContextMenu>
+```
+
+The viewer's own reaction is marked with **both** `aria-pressed` and `accessibilityState` — React Native has no concept of `aria-pressed` and react-native-web reads nothing else, so a toggle that sets one of the two is stateless on one platform.
+
+`MessageContextMenu` is a `DropdownMenu`: an anchored panel on a pointer, a bottom sheet on a phone, with Bloom's own row vocabulary (destructive colour, disabled, shortcuts). `items` is a prop and not a fixed list — which actions exist depends on who sent the message, how old it is and what the channel allows, and a menu that hid its own rows would be deciding policy the app owns. Drive it from a long-press or a right-click with the controlled `open`.
+
+## Accessibility
+
+Every control is named (`Attach`, `Emoji`, `Camera`, `Record a voice message`, `Send`), and `labels` translates all of them — a glyph-only button has no other name.
+
+**The mic and the send disc both stay mounted for the cross-fade**, so the hidden one leaves the accessibility tree: `aria-hidden` for react-native-web and `importantForAccessibility="no-hide-descendants"` for React Native. Setting one of the two hides it on one platform only, and the symptom is a composer that announces "Send" and "Record a voice message" side by side while only one of them does anything.
+
+`pointerEvents` on those layers is a **prop**, never a style entry — react-native-web drops it from a style object silently, and a hidden layer that still takes the press is a send button that fires on an empty draft.
+
+## Motion
+
+State colours 150ms; the mic ↔ send cross-fade 220ms; the recording dot pulses on a 1s clock (CSS keyframes on web, a reanimated loop on native). Everything snaps under reduced motion. No press or scale feedback on any control.
+
+## Props
+
+### `ChatComposer`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` / `defaultValue` / `onValueChange` | `string` | `''` | The draft. |
+| `onSend` | `(value) => void` | — | Send button and the keyboard. |
+| `sendOn` | `'enter' \| 'mod-enter'` | `'enter'` | Which keystroke sends on web. |
+| `maxLines` / `minLines` | `number` | `6` / `1` | The field's growth range. |
+| `placeholder` | `string` | `'Message'` | |
+| `disabled` | `boolean` | `false` | Greys the bar; no callback fires. |
+| `notice` / `noticeIcon` | `ReactNode` / icon | — | Replaces the input row. |
+| `banner` | `ReactNode` | — | Usually one or more `ComposerBanner`. |
+| `attachments` / `onRemoveAttachment` | `ChatComposerAttachment[]` / `(id) => void` | — | |
+| `leading` / `emojiSlot` / `recorder` | `ReactNode` | — | Slots. |
+| `onAttachPress` / `onEmojiPress` / `onCameraPress` | `() => void` | — | Draw the matching default control. |
+| `onMicPress` / `onMicPressIn` / `onMicPressOut` | `() => void` | — | Press-and-hold lives here. |
+| `canSend` | `boolean` | derived | Forces the send disc. |
+| `suggestions` / `suggestionKind` / `activeIndex` / `onActiveIndexChange` / `onSelectSuggestion` | | | The list above the bar. |
+| `onEscape` / `onEditLast` | `() => void` | — | Escape, and ↑ on an empty draft. |
+| `showKeyboardHint` | `boolean` | `false` | The hint line under the bar (web). |
+| `inputRef`, `onFocus`, `onBlur`, `labels`, `style`, `testID`, `accessibilityLabel` | | | |
+
+### The other parts
+
+`ComposerBanner` — `kind`, `title`, `preview`, `thumbnail`, `icon`, `accentColor`, `onClose`, `closeLabel`, `trailing`.
+`ComposerAttachmentStrip` — `attachments`, `onRemove`, `size` (56), `removeLabel`.
+`SuggestionList` — `kind`, `suggestions`, `activeIndex`, `onSelectSuggestion`, `onActiveIndexChange`, `header`, `maxHeight` (232).
+`VoiceRecorder` — `state`, `seconds`, `duration`, `amplitudes`, `playing`, `onPlayToggle`, `onCancel`, `onDelete`, `onSend`, `onLock`, `slideToCancel`, `labels`.
+`AttachmentMenu` — `open`/`defaultOpen`/`onOpenChange`, `items`, `layout`, `columns`, `onSelect`, `recent`, `label`.
+`EmojiPicker` — `groups`, `onSelectEmoji`, `activeGroup`, `query`, `filter`, `frequentlyUsed`, `skinTone`, `columns` (8), `height` (288), `tabs`, `activeTab`, `labels`.
+`ReactionPicker` — `emojis`, `selected`, `onSelectEmoji`, `onMorePress`, `moreLabel`, `size`, `surface`, `emojiLabel`.
+`MessageContextMenu` — `items`, `onSelect`, `reactions`, `selectedReaction`, `onSelectReaction`, `onMoreReactions`, `open`/`defaultOpen`/`onOpenChange`, `label`.
+
+All of them take `style` and `testID`.