@oxy.so/bloom 2.9.0 → 2.11.0

package/docs/listing-editor.mdx

@@ -0,0 +1,150 @@
+---
+title: Listing Editor
+description: The parts of a publish-a-listing flow — property type tiles, address precision cards, the offering editor, a quality meter and a live preview pane.
+order: 116
+---
+
+# Listing Editor
+
+The steps of publishing a home, as parts the app composes with
+[`WizardProgress` / `WizardFooter`](/docs/bloom/main/wizard), `StepperRow` and
+[`SortablePhotoGrid`](/docs/bloom/main/sortable-media). Every value is controlled; the app
+owns the draft, the validation and every label.
+
+```tsx
+import {
+  AddressPrecisionPicker,
+  ListingPreviewPane,
+  ListingQualityMeter,
+  OfferingEditor,
+  PropertyTypeSelector,
+} from '@oxy.so/bloom/listing-editor';
+import { SortablePhotoGrid } from '@oxy.so/bloom/sortable-media';
+import { StepperRow } from '@oxy.so/bloom/stepper';
+import { Textarea } from '@oxy.so/bloom/textarea';
+import { WizardFooter, WizardProgress } from '@oxy.so/bloom/wizard';
+```
+
+A typical flow is eight steps: type → address and precision → the basics
+(`StepperRow`s for rooms and area) → offerings → photos → description
+(`Textarea` with `maxLength` and `showCount`) → quality → publish. On a wide
+screen put `ListingPreviewPane` in a 360 column beside the step; on a phone show
+it on the last step. The Storybook story "Publish Flow" is that composition.
+
+## `PropertyTypeSelector`
+
+Large icon tiles, single select. Without `options` it draws Bloom's nine types
+(apartment, house, room, studio, duplex, penthouse, coliving, hostel, other)
+with English labels; pass your own `options` (`{ value, label, description?, icon }`)
+to localise or change the set — `DEFAULT_PROPERTY_TYPES` is exported to start
+from. 2 columns below 400 wide, 3 below 640, 4 from there.
+
+```tsx
+<PropertyTypeSelector value={draft.type} onValueChange={(type) => setDraft({ ...draft, type })} />
+```
+
+## `AddressPrecisionPicker`
+
+Three radio cards — exact address, street only, approximate area (~500 m) —
+each with a map preview over its explanation. `renderMap(precision)` draws a
+real static map; without it Bloom draws a placeholder street grid with a pin, a
+highlighted street or a circle.
+
+**The choice decides what is published, and enforcing that is the app's job.**
+The component only records `value`. Derive the public location on the server:
+the exact point for `exact`, the street's centreline for `street`, and a point
+jittered within about 500 m for `approximate` — and never send the exact
+coordinates to a client that should not have them. Hiding the pin in the UI
+while the API returns the coordinates publishes the address anyway.
+
+## `OfferingEditor`
+
+How the home is offered: four selectable cards — for rent, for sale, vacation
+rental, swap — any number at once. A selected card opens its fields:
+
+| kind | fields |
+| --- | --- |
+| `rent` | monthly amount, deposit in months (pills), available from (`DatePicker`), minimum stay in months |
+| `sale` | asking price, and the price per m² computed from `area` (read-only) |
+| `stay` | nightly rate, cleaning fee, minimum nights |
+| `swap` | the exchange mode: swap, host, or both |
+
+```tsx
+const [offering, setOffering] = useState<OfferingValue>({ kinds: [] });
+
+<OfferingEditor
+  value={offering}
+  onValueChange={setOffering}
+  currencySymbol="€"
+  area={96}
+  errors={submitted ? validate(offering) : undefined}
+/>
+```
+
+- `value.kinds` is the selection; each kind's fields live beside it
+  (`value.rent`, `value.sale`, …). Deselecting a kind KEEPS its fields, so
+  selecting it again restores what was typed — drop unselected kinds when you
+  save.
+- Money fields keep digits only, as strings; the currency symbol is drawn before
+  the input. Format and parse amounts in the app.
+- The price per area is the one number the component computes:
+  `price ÷ area`, rounded, formatted with `formatPricePerArea` (default
+  `€4 010 / m²`).
+- Validation is yours: `errors` is keyed by field (`'rent.amount'`,
+  `'stay.nightlyRate'`, `'swap.mode'`, …) and each message sits under its field;
+  `errors.kinds` sits under the cards.
+- `kinds` restricts or reorders the cards; `labels` localises every string.
+
+## `ListingQualityMeter`
+
+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
+  items={[
+    { key: 'photos', label: 'Add at least 5 photos', tip: 'You have 3.', done: photos.length >= 5, weight: 2, onPress: () => goTo('photos') },
+    { key: 'kitchen', label: 'Describe the kitchen', done: mentionsKitchen },
+    { key: 'energy', label: 'Add energy certificate', done: !!certificate },
+  ]}
+  tips={['Photos taken in daylight make rooms look larger.']}
+/>
+```
+
+Without `score` it is the done items' share of the total `weight`, rounded
+(`listingQualityScore(items)` is exported). The summary follows the score
+("Needs work" under 50, "Good" under 80, "Excellent") unless `summary` is given.
+A row with `onPress` is a button that takes the user to the step.
+
+## `ListingPreviewPane`
+
+A side panel with a card / page toggle. The card is Bloom's own `ListingCard`
+drawn from `listing`; the page is a compact listing page (cover photo,
+`ListingHeader`, the facts, the description and the price). Pass the draft being
+edited and the preview is live. `renderPage` replaces the built-in page; `mode`
+/ `onModeChange` control the toggle.
+
+```tsx
+<ListingPreviewPane
+  listing={{
+    photos: draft.photos.map((p) => p.uri),
+    title: draft.title,
+    subtitle: '3 bedrooms · 96 m²',
+    price: '€1,450',
+    priceUnit: 'month',
+    facts: ['3 bedrooms', '2 baths', '96 m²'],
+    description: draft.description,
+  }}
+/>
+```
+
+## Accessibility
+
+- Offering cards are `checkbox`es with `aria-checked` in a named `group`; the
+  fields sit OUTSIDE the pressable card head, so no input is nested in a control.
+- Property tiles and precision cards are `radio`s with `aria-checked` in a named
+  `radiogroup`; the deposit and swap-mode pills are `radiogroup`s too.
+- The quality ring is a `progressbar` (0..100); each row's name carries its
+  state ("Add at least 5 photos, To do").
+- The preview toggle is a `SegmentedControl` of type `tabs` over a `tabpanel`.

package/docs/lyrics.mdx

@@ -0,0 +1,107 @@
+---
+title: Lyrics
+description: Synced lyrics that follow playback, with seeking, a way back after scrolling, and a preview card.
+order: 116
+---
+
+# Lyrics
+
+`LyricsView` draws a track's lyrics and follows the player: lines already sung are dimmed, the line playing is in the full text colour and a heavier weight, and lines to come sit between the two. `LyricsPreviewCard` is the small version — a few lines around the current one and a "Show lyrics" button.
+
+```tsx
+import { LyricsPreviewCard, LyricsView, type LyricLine } from '@oxy.so/bloom/lyrics';
+
+const lines: LyricLine[] = [
+  { time: 4, text: 'Streetlights hum a quiet tune' },
+  { time: 7.5, text: 'Paper lanterns chase the moon' },
+  { time: 11, text: '' }, // an instrumental break
+  { time: 14.5, text: 'Hold the night a little longer' },
+];
+
+<LyricsView
+  lines={lines}
+  currentTime={position}
+  onSeekLine={(line) => player.seekTo(line.time ?? 0)}
+  artworkColor={track.artworkColor}
+  providerText="Lyrics licensed from the song’s publisher"
+/>
+
+<LyricsPreviewCard
+  lines={lines}
+  currentTime={position}
+  artworkColor={track.artworkColor}
+  onShowLyrics={openLyrics}
+/>
+```
+
+Both are controlled by `currentTime`: they draw where playback is and report presses. They never sample the artwork — the colour arrives as a prop.
+
+## `LyricsView`
+
+| prop                 | decides                                                                                           |
+| -------------------- | ------------------------------------------------------------------------------------------------- |
+| `lines`              | `{ time?, text, key? }[]` in any order; synced lines are sorted by `time` (seconds)               |
+| `text`               | plain unsynced lyrics as one string, used when `lines` is empty                                   |
+| `currentTime`        | the playback position in seconds                                                                   |
+| `onSeekLine`         | `(line, index)` — makes each synced line a button; seek to `line.time`                             |
+| `artworkColor`       | hex or `rgb()`; the view paints a deep shade of it (see Colour). Absent → the neutral surface       |
+| `providerText`       | the small footer under the last line, e.g. "Lyrics provided by …"                                  |
+| `footer`             | replaces that footer with your own node                                                           |
+| `emptyText`          | drawn with no lyrics at all; default "Lyrics aren’t available for this track"                      |
+| `backToCurrentLabel` | the pill after a user scroll; default "Back to current line"                                       |
+| `resumeDelay`        | ms after the last user scroll before auto-scroll resumes; default `3000`                            |
+| `anchor`             | where the active line's centre is kept, as a fraction of the height; default `1/3`                  |
+| `size`               | `'large'` display-4 32/44, `'medium'` title-1 24/34, `'small'` title-2 20/26; default by width (720 / 480) |
+| `accessibilityLabel` | the region's name; default "Lyrics"                                                                 |
+| `style`, `testID`    | the view fills its parent (`flex: 1`), so give the parent a height                                  |
+
+### Which line is active
+
+`activeLyricIndex(lines, time)` is the last line whose `time` is at or before `time` — a line becomes active exactly at its time and stays active until the next one starts. Before the first line nothing is active (`-1`), and the last line stays active to the end of the track, since lyrics carry no end time. It is a binary search over lines sorted by time; `normalizeLyricLines` produces that order (stable, so lines sharing a time keep their order and the last of them wins).
+
+A blank synced line is an instrumental break: a gap, which draws three dots while it is the active line.
+
+### Scrolling
+
+The view scrolls so the active line's centre sits `anchor` of the way down (`lyricsScrollTarget`, clamped to the content). The bottom is padded by the rest of the view's height so the last lines can reach that point too. The first placement jumps; later ones animate, and with reduced motion on they jump too.
+
+A scroll the user makes — drag, wheel, touch, or any scroll the view did not start — pauses following for `resumeDelay` and shows the "Back to current line" pill at the bottom. Pressing the pill scrolls back at once; otherwise following resumes after the delay. The pill never appears for unsynced lyrics or before the first line.
+
+Only colour and weight change with playback: no line grows, moves or scales. The active line keeps the resting line's size so the weight change is the only reflow.
+
+### Unsynced lyrics
+
+If any line has no `time`, or only `text` is given, the lyrics draw as plain text in the full colour. Nothing is active, nothing scrolls on its own, and nothing seeks.
+
+## `LyricsPreviewCard`
+
+| prop                          | decides                                                           |
+| ----------------------------- | ----------------------------------------------------------------- |
+| `lines` / `text` / `currentTime` / `artworkColor` | as on `LyricsView`                             |
+| `visibleLines`                | `5` (default) or `4`; the active line is second from the top, clamped at both ends |
+| `onShowLyrics`                | draws the "Show lyrics" pill; without it there is no button        |
+| `showLyricsLabel`             | default "Show lyrics"                                              |
+| `onSeekLine`                  | makes the lines buttons, as on `LyricsView`                        |
+| `title`                       | the heading and the region's name; default "Lyrics"                 |
+| `providerText`, `emptyText`, `style`, `testID` |                                                   |
+
+A card with a 16 radius and 20 padding, lines in title-3 (18/26). Unsynced text shows its first lines and skips the blank lines between verses.
+
+## Colour
+
+`resolveLyricsPalette(theme, artworkColor)`:
+
+- **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.
+
+`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
+
+- The view and the card are each a `region` named by `accessibilityLabel` / `title`.
+- With `onSeekLine`, each synced line is a `button` named by its words; without it lines are plain text and there is nothing to tab to.
+- The active line carries `aria-current="true"` on web.
+- Keyboard focus draws a ring in the text colour. Colour changes on hover are instant with reduced motion.

package/docs/map-marker.mdx

@@ -1,6 +1,6 @@
 ---
 title: Map Marker
-description: Price pills, cluster bubbles, the listing preview card and the search-area pill to place on an app's own map.
+description: Price pills, cluster bubbles, approximate-area circles, the listing preview card and the search-area pill to place on an app's own map.
 order: 110
 ---
 
@@ -11,6 +11,7 @@ anywhere, and the app's map library positions them.
 
 ```tsx
 import {
+  MapAreaCircle,
   MapClusterMarker,
   MapListingPreview,
   MapPriceMarker,
@@ -25,6 +26,10 @@ import {
   accessibilityLabel="€120 per night, Valdoria"
 />
 
+<MapPriceMarker price="€240K" size="compact" accessibilityLabel="€240,000, Talmar Hill" />
+
+<MapAreaCircle radius={metresToPixels(500)} label="~500 m" accessibilityLabel="Approximate location" />
+
 <MapClusterMarker count={14} onPress={zoomIn} />
 
 <MapListingPreview
@@ -54,14 +59,21 @@ Prices arrive formatted — the app owns currency and locale.
 
 | prop                 | decides                                                                  |
 | -------------------- | ------------------------------------------------------------------------ |
-| `price`              | the text in the pill ("€120")                                            |
+| `price`              | the text in the pill — SHORT: "€120", "€950/mo", "€240K", "€1.2M"         |
 | `state`              | `'default'`, `'active'` (the open one) or `'visited'` (opened before)     |
+| `size`               | `'default'` (28 tall) or `'compact'` (22 tall), for a dense map            |
 | `saved`              | a small heart before the price                                           |
 | `onPress`            |                                                                          |
 | `accessibilityLabel` | a sentence — the pill shows only a number. Defaults to `price`           |
 | `style`, `testID`    | the heart is `<testID>-saved`                                             |
 
-A 28px full pill, `body-2-semibold` tabular text, 10px sides.
+A 28px full pill, `body-2-semibold` tabular text, 10px sides; `compact` is 22px
+with `caption-1-semibold`, 8px sides and a 10px heart.
+
+**Short prices.** The pill never truncates, so the app abbreviates: whole
+currency under a thousand ("€168"), a rent with its period ("€950/mo"), sales in
+thousands or millions ("€240K", "€1.2M"). Put the full price in
+`accessibilityLabel` ("€240,000, Talmar Hill").
 
 | state    | fill                    | label             | edge / elevation            |
 | -------- | ----------------------- | ----------------- | --------------------------- |
@@ -79,6 +91,23 @@ The heart is the theme's danger red. The marker is a `button` whose
 `style`, `testID`. A 36px round bubble that widens for longer counts, painted
 like the price pill.
 
+## `MapAreaCircle`
+
+| prop                 | decides                                                                  |
+| -------------------- | ------------------------------------------------------------------------ |
+| `radius`             | the radius in PIXELS — the app converts metres with its map projection and re-renders on zoom |
+| `label`              | an optional pill at the centre ("~500 m", "Approximate area")            |
+| `accessibilityLabel` | makes it an `img` with that name; without it the circle is decorative    |
+| `style`, `testID`    | parts are `<testID>-fill`, `-edge`, `-label`                              |
+
+The approximate location of a home whose address is private: a round
+`2 × radius` box with the accent (`accent-500`; dark `accent-400`) as a fill
+layer at 15% opacity and a solid 1.5px accent edge. The fill is a separate layer
+at `opacity` rather than a colour with alpha, so the edge stays solid. The label
+is a 24px surface pill with a hairline and `shadow-s`, `caption-1-semibold`.
+It never takes a press (`pointerEvents="none"`), so the map keeps its gestures.
+Centre it on the coordinate like a marker and draw it under the markers.
+
 ## `MapListingPreview`
 
 | prop                 | decides                                                                  |
@@ -88,6 +117,9 @@ like the price pill.
 | `rating`, `reviewCount` | handed to `Rating` (`null` draws "New"); omit `rating` to hide it     |
 | `subtitle`           | the secondary line                                                       |
 | `price`, `priceDetail`, `originalPrice` | "€150 **€120** night" — the original struck through   |
+| `priceLines`         | stacked lines, as on `ListingCard`; replaces the three props above       |
+| `facts`              | the facts row, as on `ListingCard`, 14px icons                           |
+| `offerings`, `offeringLabels` | small tinted `OfferingBadge`s above the title                   |
 | `favorite`, `onFavoriteChange` | the heart; shown only with the handler                         |
 | `onClose`            | the close button; shown only with the handler                           |
 | `onPress`            | opens the listing — the whole card is the target                         |
@@ -102,6 +134,10 @@ icon button over the photo's top-left; the heart a 24px round button in the
 opposite corner (compact: heart over the photo, close in the card's top-right).
 The card never clips — the photo clips itself — so the native shadow survives.
 
+The housing parts — offerings, price lines and facts — are the SAME components
+`ListingCard` draws, at the body-2 size, so the preview and the card cannot
+drift apart. With neither `price` nor `priceLines` there is no price line.
+
 The open target is a button laid over the card BESIDE the close and heart
 buttons rather than around them, so no button nests inside another. The heart
 is a toggle with `aria-pressed` and native `accessibilityState.selected`.

package/docs/media-card.mdx

@@ -0,0 +1,110 @@
+---
+title: Media Cards
+description: Every card a music or audio app shows — songs, albums, artists, playlists, mixes, shows, episodes, audiobooks, genres, events, profiles, friend activity, quick-access tiles, recaps and share cards.
+order: 63
+---
+
+# Media Cards
+
+One anatomy — a cover, a title, a line or two under it, a play button that appears on hover and a "More options" menu — and a typed card on top of it for each kind of thing a listening app shows.
+
+```tsx
+import {
+  AlbumCard,
+  ArtistCard,
+  AudiobookCard,
+  EpisodeCard,
+  EventCard,
+  FriendActivityCard,
+  GenreCard,
+  MediaCard,
+  MixCard,
+  PlaylistCard,
+  PodcastCard,
+  ProfileCard,
+  QuickAccessTile,
+  RecapCard,
+  ShareCard,
+  SongCard,
+} from '@oxy.so/bloom/media-card';
+
+<SongCard
+  title="Night Drive"
+  artists={['Mara Vell']}
+  artwork={track.coverId}
+  explicit
+  href={`/track/${track.id}`}
+  onPlay={() => player.toggle(track.id)}
+  playing={player.id === track.id && player.playing}
+  current={player.id === track.id}
+  menuItems={[
+    { label: 'Add to queue', onPress: () => queue.add(track.id) },
+    { label: 'Go to artist', onPress: () => router.push(`/artist/${track.artistId}`) },
+  ]}
+/>
+```
+
+Every card is controlled and draws only what it is given: text arrives pre-formatted (dates, durations, counts — the app owns the locale), and the card reports presses. Colours come from the theme in light and dark; artwork-derived colours arrive as a hex prop and are never sampled from an image.
+
+## The shared props
+
+| prop | decides |
+| --- | --- |
+| `onPress` / `href` | the card is a button, or a real `<a href>` on web (native opens the URL when there is no `onPress`) |
+| `artwork`, `artworkVariant` | a URL, or an id passed to the app's `ImageResolver` with the variant |
+| `artworkColor` | the hex a missing cover's gradient is generated from; neutral without it |
+| `onPlay`, `playing`, `loading`, `current` | the play button (`PlayButton`) and its state |
+| `playButton` | `'auto'` (default), `'always'`, `'never'` — see below |
+| `menuItems` / `menu` / `menuLabel` | the "More options" menu: rows as data (`{ label, onPress, icon, disabled, destructive }`) or your own `DropdownMenuItem` nodes |
+| `size` | `'large'` 200, `'medium'` 160 (default), `'small'` 120 — the tile's cover side |
+| `layout` | `'tile'` (cover on top) or `'row'` (a 56 cover — 48 at small — on the left, then text, a trailing slot and the menu) |
+| `selected` | the selected wash; `aria-current` on web, `selected` state on native |
+| `skeleton` | the shimmering placeholder in the same geometry |
+| `accessibilityLabel` | replaces the composed name |
+
+## Hover, play and the menu
+
+- **Web.** Hovering a card paints a wash (the text colour over the page at 6%) and reveals the play button — it fades in and rises 8px at the cover's bottom-right on a tile, centred on the cover in a row — and the menu trigger. Keyboard focus anywhere inside the card reveals them too, and a right-click opens the menu. Colour, opacity and that small rise only: nothing scales. With reduced motion the rise and the transitions are dropped.
+- **Native.** There is no hover, so the play button is drawn only while the card is `playing`, `loading` or `current` (tap the card to open it), the menu trigger is always drawn, and a long press opens the menu as a sheet.
+- `playing`, `loading` and `current` keep the play button visible on both platforms. `playButton="always"` draws it at rest everywhere; `"never"` removes it.
+
+## The link sits UNDER the content
+
+The press target is a pressable that fills the card and carries its whole accessible name. The cover and the text are drawn over it with `pointerEvents="none"`, so pressing them falls through to it; the play button, the menu trigger, a like button, artist links and slot buttons are drawn over it as their own targets. That is how a card can be a real `<a href>` on web without a button nested inside an anchor (invalid HTML, and every inner press would also navigate).
+
+The name is composed from the title, the type and the lines under it — "Night Drive, Explicit, Song, Mara Vell". The menu trigger is named "More options for Night Drive".
+
+## The cards
+
+| card | cover | lines |
+| --- | --- | --- |
+| `SongCard` | square | title + `ExplicitBadge`; artists (each a link with `onPressArtist`). `current` adds `NowPlayingIndicator` and an accent title. Row: + album, `LikeButton` (`liked`/`onLikedChange`), `duration` |
+| `AlbumCard` | square, radius 8 | "2026 · Album" (`year`, `albumType`: album / single / ep / compilation, `typeLabels`), `artist` |
+| `ArtistCard` | **round** | name + accent verified mark (`verified`), "Artist", `followers` |
+| `PlaylistCard` | `artwork` → a 2×2 `mosaic` of up to four track covers → a gradient from `artworkColor` with a music note | "By Maya · 42 songs" (`owner`, `ownerPrefix`, `trackCount`), `collaborative` glyph |
+| `MixCard` | generated: the gradient, "Mix" and `coverTitle` big top-left, up to four `faces` bottom-left | `description` |
+| `PodcastCard` | rounded square, radius **12** | `publisher` |
+| `EpisodeCard` | radius 12 on top; a 112 / 96 / 72 cover on the left in a row | "12 Sep · 48 min", title (2 lines), `show`, `description` (2 lines); `progress` bar + `remaining`, or `played` check; `actions` (save, download). The row always draws the play button under the text |
+| `AudiobookCard` | **2:3** | `author`, "Narrated by …", `duration`, a full-width `progress` bar |
+| `GenreCard` | a solid `color` tile, radius 8 | the title top-left in bold light text, `artwork` rotated 25° peeking from the bottom-right |
+| `EventCard` | image with a month/day leaf; in a row the leaf is the cover | "venue · city", `time`, `action` (the tickets button) or the `soldOut` badge |
+| `ProfileCard` | round | "Profile · Follows you", `followers`, `action` (a follow button) |
+| `FriendActivityCard` | 40 round avatar, an accent dot when `live` | name + `time` (or moving bars when `live`), "Track — Artist", the `context` with a playlist or album glyph |
+| `QuickAccessTile` | 56 flush left (a 40 round photo with `round`) | bold title (2 lines) on a neutral tile; one trailing slot for the play button, which shows the now-playing bars while `current` and swaps them for pause on hover |
+| `RecapCard` | — | a big gradient card: `eyebrow`, the headline `value`, `unit`, `highlights` (cover + label + title) and a Share pill (`onShare`) |
+| `ShareCard` | full width, radius 12 | on an `artworkColor` gradient: title, artist, an optional `lyrics` excerpt block and a `footer` |
+
+`MediaCard` is the shared anatomy itself, for anything the typed cards do not cover. Beyond the shared props it takes `subtitle` (text or nodes), `meta` lines, `eyebrow`, `description`, `typeLabel`, `artworkShape`, `artworkRadius`, `artworkAspectRatio`, `artworkSize`, `renderArtwork`, `artworkOverlay`, `placeholderIcon`, `titleLeading`, `titleAccessory` (+ `titleAccessoryLabel` for the name), `titleLines`, `subtitleLines`, `interactiveSubtitle`, `trailing`, `footer`, `accessibilityDetail`, `centered` and `rowAlign`.
+
+## 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 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
+
+Tiles have a fixed width (the cover plus 12 either side), which is what a horizontal shelf wants — a plain horizontal `ScrollView` of cards works. `QuickAccessTile`, `FriendActivityCard`, `RecapCard` and rows stretch to their parent; put quick-access tiles in a 2 (narrow) to 4 (wide) column grid. `GenreCard` takes `style={{ width: '100%' }}` in a grid and keeps its square.

package/docs/media-controls.mdx

@@ -0,0 +1,124 @@
+---
+title: Media Controls
+description: Play and like buttons, the explicit badge, the now-playing bars, a playback scrubber and a volume control.
+order: 62
+---
+
+# Media Controls
+
+The small pieces every player, track row and library screen is built from.
+
+```tsx
+import {
+  ExplicitBadge,
+  formatDuration,
+  LikeButton,
+  NowPlayingIndicator,
+  PlayButton,
+  PlaybackProgress,
+  VolumeControl,
+} from '@oxy.so/bloom/media-controls';
+
+<PlayButton playing={playing} subject="Night Drive" onPress={toggle} />
+<LikeButton liked={liked} onLikedChange={setLiked} />
+<ExplicitBadge />
+<NowPlayingIndicator playing={playing} />
+<PlaybackProgress
+  value={position}
+  duration={225}
+  buffered={buffered}
+  showTimes
+  onSeekPreview={setPreview}
+  onSeek={seekTo}
+/>
+<VolumeControl volume={volume} onVolumeChange={setVolume} muted={muted} onMutedChange={setMuted} />
+
+formatDuration(83);   // "1:23"
+formatDuration(3725); // "1:02:05"
+```
+
+Every control is controlled: it draws the props it is given and reports what the user did. Colours come from the theme — the accent is the theme's `primary` — in light and dark. No control scales or bounces; hover and press change colour only.
+
+## `PlayButton`
+
+| prop                 | decides                                                                                       |
+| -------------------- | --------------------------------------------------------------------------------------------- |
+| `playing`            | draws the pause glyph and is named "Pause"; otherwise the play glyph and "Play"               |
+| `onPress`            | called on press — the button toggles nothing itself                                           |
+| `size`               | `'small'` 32, `'medium'` 48 (default), `'large'` 56 — the circle's diameter                    |
+| `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`
+
+| prop                        | decides                                                                  |
+| --------------------------- | ------------------------------------------------------------------------ |
+| `liked`, `onLikedChange`    | the state, and the callback with the next state                          |
+| `size`                      | glyph `'small'` 16 / `'medium'` 20 (default) / `'large'` 24; hit area 32 / 32 / 40 |
+| `activeColor`               | the liked heart's colour, default the theme accent                       |
+| `accessibilityLabel`        | the name, default "Save to Your Library" — fixed in both states         |
+| `disabled`, `style`, `testID` |                                                                        |
+
+A toggle with one fixed name: `aria-pressed` on web and `accessibilityState.selected` on native (React Native has no pressed state). The press does not reach a pressable row behind it.
+
+## `ExplicitBadge`
+
+`size` `'small'` (14) or `'medium'` (16, default); `letter` (default "E"); `label` (default "Explicit"). A neutral square with a small radius — a mark, not a pill. It is one `img` named by `label`; the letter is hidden from assistive tech.
+
+## `NowPlayingIndicator`
+
+`playing` (default `true`), `size` (default 16), `bars` `3 | 4` (default 4), `color` (default the accent), `label` (default "Now playing"). The bars swing on staggered periods while playing; paused, or with the system's reduced-motion setting on, they stand still at their resting heights.
+
+## `PlaybackProgress`
+
+| prop                 | decides                                                                                  |
+| -------------------- | ---------------------------------------------------------------------------------------- |
+| `value`, `duration`  | position and length, in **seconds**                                                      |
+| `buffered`           | how far the media has loaded, in seconds — drawn as a lighter segment                   |
+| `onSeekPreview`      | called while dragging with the position under the pointer; the fill and elapsed time follow it |
+| `onSeek`             | called once on release, and on each key press / accessibility action                     |
+| `showTimes`          | draws elapsed and total time (`formatDuration`)                                          |
+| `showRemaining`      | the right-hand time counts down: "−2:22"                                                 |
+| `timesPosition`      | `'inline'` (default) either side of the rail, or `'below'` under its two ends            |
+| `keyboardStep`       | seconds per arrow key, default 5                                                         |
+| `accessibilityLabel` | the slider's name, default "Seek"                                                        |
+| `formatValueText`    | `(seconds, duration) => string` — the announced value, default "1:23 of 3:45"            |
+| `disabled`, `style`, `testID` |                                                                                 |
+
+The rail is 4px inside a 16px hit area. The fill is the text colour at rest and turns accent under the pointer, while dragging and with keyboard focus; the 12px thumb shows in those same states only (on native: while dragging).
+
+It is a `slider` (`role="slider"`) with `aria-valuemin` 0, `aria-valuemax` the duration, `aria-valuenow` the position and `aria-valuetext`. On web it takes focus: arrows seek ±`keyboardStep`, Home and End jump to the ends. On native it answers the `increment` / `decrement` accessibility actions. The drawn times are hidden from assistive tech — the value text already says them.
+
+## `VolumeControl`
+
+| prop                          | decides                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| `volume`, `onVolumeChange`    | level `0`..`1`; called while dragging and on each key (5% per arrow)            |
+| `muted`, `onMutedChange`      | the speaker button toggles it; moving the slider while muted also calls `onMutedChange(false)` |
+| `sliderWidth`                 | default 96                                                                      |
+| `sliderVisibility`            | `'always'` (default) or `'hover'` — on web the slider appears on hover or keyboard focus, its width reserved; a device without hover, and native, always show it |
+| `muteLabel` / `unmuteLabel`   | the button's name, default "Mute" / "Unmute"                                    |
+| `accessibilityLabel`          | the slider's name, default "Volume"; its value text is "40%"                    |
+| `disabled`, `style`, `testID` |                                                                                 |
+
+The speaker glyph follows the level: muted or 0, under 50%, and above. While muted the slider draws 0.
+
+## `formatDuration(seconds)`
+
+`m:ss` under an hour, `h:mm:ss` from an hour. Fractions are floored; negative, `NaN` and infinite input give `0:00`.