@oxy.so/bloom 3.6.0 → 4.1.0

package/docs/job-board.mdx

@@ -0,0 +1,82 @@
+---
+title: Job board
+description: Work a courier can take — what a job pays, where it starts and ends, how long the offer stands, and the board it sits on with the four filters that matter, a sort, a refresh and an empty state.
+order: 137
+---
+
+# Job board
+
+```tsx
+import { JobBoard, JobCard } from '@oxy.so/bloom/job-board';
+
+<JobBoard
+  jobs={jobs}
+  payBands={payBands}
+  onTake={take}
+  onPass={hide}
+  onRefresh={pull}
+/>
+```
+
+`JobCard` is one piece of work. `JobBoard` is the work on offer, filtered, ordered and counted.
+
+## It is the offer card seen from the other side
+
+`carrier-quote`'s `CarrierQuoteCard` is a carrier saying what they would charge to move something. This is the same object read by the person who would move it: the same blocks in the same order, the same tile row, the same 420 threshold at which the actions drop their labels, the same footer over a hairline. Both were built from the same measurements on purpose — a courier app shows one of these on the board and the other in the customer's app, and two different geometries would make them look like two products.
+
+What differs is only whose number the headline is, and what stands where the person does:
+
+| | `CarrierQuoteCard` | `JobCard` |
+| --- | --- | --- |
+| the mark | the carrier's 48 avatar | the 48 vehicle tile |
+| the identity | the carrier's name and rating | what is being moved |
+| the headline | the price asked | the pay offered |
+| the middle | three tiles | the route, then three tiles |
+| the footer | decline · message · accept | pass · take |
+
+## The geometry
+
+- **Card.** Outlined, radius 20, 16 inset, 16 between blocks. Chosen, it takes a 2px border and gives the pixel back out of its own inset, so nothing inside moves.
+- **Mark.** 48 comfortable, 36 compact, radius 12, at the surface's next fill up. It carries the glyph for `vehicleKind`, or `vehicleIcon` when the app names one. With neither it is the route glyph — a marketplace that routes five bodies has five glyphs, and guessing between them is worse than not drawing one.
+- **Tiles.** Distance, time, window. One row over 420, two columns under it, an odd tile keeping its half.
+- **Compact.** 64 tall, the mark, the load, one meta line, the pay. No route, no tiles, no breakdown: that density is a LIST ROW, and a list row that drew a route would be a card with the padding taken out.
+
+## The route is `RouteStops`, not a second pin column
+
+`pickup`, `via` and `dropoff` become that family's stops, at its `compact` density. It already owns the marker shapes, the connector that fills behind a journey, the position words and the announced name; a second column drawn here would be a fourth marker vocabulary in one library.
+
+## What a job is CLOSED does not remove it
+
+`state` is `open`, `taken` or `expired`. A closed job keeps its place, dims to the disabled opacity, and says which of the two happened — as a `Badge` beside the load and again where the take action was. The take action is GONE rather than greyed out: a dimmed primary button invites a press that can never succeed.
+
+This is the one behaviour the board exists to get right. A row that vanishes under a thumb is indistinguishable from a mis-tap, and the reader is left unsure whether they took the job or lost it. `filterJobOffers` answers the reader's four questions and nothing else, so nothing about a job's state can make it disappear.
+
+## The filters
+
+Four independent questions, combined with AND, each a sideways-scrolling `ChipRow`:
+
+| | reads | default bands |
+| --- | --- | --- |
+| distance | `distanceKm` | `JOB_DISTANCE_BANDS` — any, 3, 10, 25 km |
+| pay | `payValue` | **none** |
+| when | `startsInMinutes` | `JOB_WHEN_BANDS` — any, hour, 4 hours, today |
+| vehicle | `vehicleKind` | the five `vehicle-picker` knows |
+
+**`payBands` has no default and will not get one.** A band is words plus an amount, and the amount is a currency. A kilometre and a minute are nobody's; twenty euros is somebody's.
+
+**A filter cannot exclude what it cannot measure.** A job with no `distanceKm` survives every distance band; one with no `payValue` survives every pay floor. Treating a missing value as zero is how a filter hides work from a courier because the app omitted a field.
+
+**Vehicle is a set of toggles, not a radiogroup.** A courier with a van can take a bike job, and "van or box truck" is a sentence the board has to be able to say. Pressing the only selected vehicle clears the dimension.
+
+## The order
+
+`sortJobOffers` is stable, and PAY sorts high first while distance, start and expiry sort low first — a courier scanning for money wants the biggest number and scanning for distance wants the smallest, so one direction would be wrong three times. A job with no number for the current key goes LAST, keeping the caller's order inside that group: there is nothing left to sort it on, and re-shuffling a group of equals makes a board jump for no visible reason.
+
+## Traps
+
+- **Money is never parsed.** `pay`, `payNote` and every `payLines` amount are drawn exactly as given. `payValue` is a separate number for ordering and the pay filter, and it is never drawn. Nothing here adds, converts or rounds.
+- **The card is not one big button.** `onPressJob` is bound to the load block; the actions sit outside it. A control inside a control is invalid on web and renders fine either way.
+- **The actions lose their labels, never their names.** Under 420 each drops to a glyph and keeps `"<action> <load>"`.
+- **`disabled` is a constraint, not a default.** It combines with the job's own state, so a caller cannot re-enable a job the marketplace has already given away.
+- **The refresh control does not spin.** Bloom draws no press animations; while `refreshing` it is inert, because a second pull would race the first.
+- **The empty state offers the undo it caused.** With a filter narrowed and no `emptyAction`, the clear control is drawn there.

package/docs/label.mdx

@@ -14,7 +14,7 @@ import { Label } from '@oxy.so/bloom/label';
 
 <Label nativeID="workspace-name" required>Workspace name</Label>
 <TextField>
-  <TextFieldInput nativeID="workspace-name" label="Workspace name" value={name} onChangeText={setName} />
+  <TextFieldInput nativeID="workspace-name" label="Workspace name" value={name} onValueChange={setName} />
 </TextField>
 ```
 

package/docs/layout.mdx

@@ -50,21 +50,23 @@ double-counts the home indicator and strands a band of dead space.
 
 ## `useBottomEdgeInset` / `useClaimBottomEdge` — what is already there
 
-Knowing where the edge is does not tell a FAB that a tab bar is already parked
-on it. A surface that parks there **claims** its footprint; a surface that wants
-to avoid it **reads** the total.
+The registry remains a low-level geometry API for independently positioned surfaces.
+A surface **claims** its footprint; another surface can **read** the occupied extent.
+`Fab` no longer reads this registry: it is a static action positioned by `Screen`
+or beside navigation by `BottomBar`.
 
 ```tsx
 // The surface that parks there — a floating tab bar.
 useClaimBottomEdge(gap + barHeight);
 
-// The surface that avoids it — Bloom's Fab does this for you.
+// A custom independently anchored surface that avoids the claimed region.
 const occupied = useBottomEdgeInset();
 <View style={{ position: 'absolute', bottom: windowEdgeGap(insets.bottom) + occupied }} />
 ```
 
-Neither imports the other, so any combination composes: a tab bar with no FAB, a
-FAB with no tab bar, both, or a surface written later.
+Claims remain independent of their readers. For built-in screen composition, use
+`Screen` and `BottomBar`: the owner reserves geometry and renders the FAB as a
+sibling of the navigation capsule, above their shared blur.
 
 `BloomProvider` mounts the registry. Outside one, `useBottomEdgeInset()` returns
 `0` and `useClaimBottomEdge` is a no-op, so a surface stays usable standalone.
@@ -179,10 +181,12 @@ A collapse is **motion**, and motion that must stay locked to a reanimated
 animation has to travel as a shared value on the UI thread. React state is the
 wrong transport for it at any width, so it is not offered here.
 
-The **app** owns that signal. Mention drives its header, its tab bar and its FAB
-from one `SharedValue` through `useAnimatedStyle`, and everything moves together
-because nothing crosses a thread. This registry stays what it is good at:
-**geometry** — where things are, not when they move.
+`Screen` now owns the coordinated signal locally. `useScreen()` exposes
+`collapseProgress`; `AppShell` passes it to `BottomBar.minimizeProgress`, and
+`BottomBar` animates its navigation and action together. Custom chrome reads the
+same shared value. The historical workaround in Mention did this at app level;
+the shared composition now supplies that ownership. The registry still carries
+**geometry**, never animated collapse or a React boolean mirror.
 
 ## Things that are easy to get wrong
 
@@ -192,7 +196,8 @@ strand a reader at twice the height, floating mid-screen.
 
 **A z-index cannot substitute for the offset.** A tab bar host is typically the
 last sibling of the app shell, so it paints over every descendant no matter what
-they claim. The FAB has to be somewhere *else*, not merely on top.
+they claim. A separate anchored action must avoid that band; the current BottomBar instead
+places the action beside navigation in the same host, above their blur.
 
 **A modal surface should not read the registry.** A detached `BottomSheet`
 renders above the tab bar and covers it; offsetting it by a bar it is already

package/docs/lead-score.mdx

@@ -0,0 +1,153 @@
+---
+title: LeadScoreCard
+description: How good a lead is and why — the verdict and the score on a tinted panel, and the factors that make it up on a neutral one.
+order: 126
+---
+
+# LeadScoreCard
+
+```tsx
+import { LeadScoreCard } from '@oxy.so/bloom';
+
+<LeadScoreCard
+  score={82}
+  accessibilityLabel="Lead score for Larkspur Freight"
+  valueText="82 of 100, hot"
+  factors={[
+    { label: 'Fits the ideal profile', contribution: 24, detail: 'Logistics, 200–500 people' },
+    { label: 'No decision-maker', contribution: -9, detail: 'One contact, no budget owner' },
+  ]}
+  trend={{ label: '+8 against last week', direction: 'up' }}
+/>
+```
+
+## Two panels in one card
+
+It is drawn the way Bloom draws a SCORE — `chart-cards`' `SleepScoreCard` is the
+register, and the `BesideTheReference` story puts the two in one shot at the
+same width:
+
+| panel | what it holds |
+| --- | --- |
+| header | washed in the band's tone: the quiet `body-medium` label over the `title-1-medium` verdict with the band's glyph, the trend as a quiet icon-and-label line, and the ring — 132 across, CENTRED, the score at `display-4-medium` inside it |
+| factors | neutral, padded on the LEFT only so the rules run to its right edge: one row per factor — a 10 mark, the label and its detail as one reading line, and the signed contribution right-aligned and tabular |
+
+The card itself is 10 padding and a 10 gap; both panels take `radius-16` inside
+its `radius-20`.
+
+## There are no bars
+
+Every factor used to be a `Meter`. Five bars stacked down a card is a chart
+pretending to be a measurement — a CHART colours by WHICH datum it is, and these
+are all the same datum at different sizes — and it was the single thing that
+made this card read as a dashboard from another product rather than as Bloom.
+
+A contribution is a NUMBER. It is printed (`+24`, `-9`), it is tabular so the
+column lines up, and the MARK beside the label says which way it pulls: the
+accent for a factor that pushes the score up, the quiet graphical neutral for
+one that pulls it down. Five bars also announced `progressbar` five more times;
+`LeadScore.test.tsx` now asserts that the card emits exactly ONE, and that it is
+the ring.
+
+The one measurement on the card is the score, and it is a ring, because there is
+one of it.
+
+## The ring
+
+`MeterRing` from `stat-bar` owns the geometry and the FLAT `aria-value*` props.
+The arc is the meter's own accent fill whatever band the score falls in: that is
+what a meter means in Bloom — how much of one thing there is. A green ring
+claims "healthy", which is not the claim "82 of 100" makes.
+
+**The TRACK is read off the header wash, not from `stat-bar`'s default rail.**
+That rail is a neutral computed for the page; on a tinted panel it reads as a
+foreign grey ring rather than as the empty part of this one. `resolveLeadScorePaint`
+takes it from `hairlineOn(theme, header)`.
+
+It is 132 across, centred, with the number at `display-4-medium` — larger than
+the verdict word beside it. At 72 in a corner it was a widget, and the one fact
+the card exists to state was smaller than the label.
+
+## The tint is FLATTENED before anything is derived from it
+
+The header is `resolveAccentColors(colors, tone, 'subtle').background` —
+composited over the card, not painted raw.
+
+The `*Subtle` members are `rgba()` on purpose, and painting one renders
+correctly. What does not work is DERIVING off it: every reader in
+`styles/color-contrast.ts` treats a colour as opaque, so a text rung or a
+hairline read from `rgba(16 185 129 / 0.24)` is computed against solid emerald
+and lands on a panel that is nothing like it. Measured here before the flatten:
+the header's secondary label came back at **1.96:1** against its own panel in
+dark mode, and the card rendered perfectly.
+
+So `flattenOver` composites the tint ONCE (parse-and-re-emit, the same move
+`chip/hue-colors.ts` makes for a translucent hue), the panel paints the
+flattened colour, and every rung is read off that — the two can then never
+disagree. Flattened, the worst secondary label over the whole
+`preset × mode × band` sweep measures 6.1:1.
+
+Both panels publish themselves with `SurfaceLevelProvider` and
+`surfaceFillVars`, so anything nested inside either one steps off the right
+parent.
+
+## The band is the VERDICT, and it is the tint
+
+`cold` / `warm` / `hot` map to the `info` / `warning` / `success` tones in
+`LEAD_SCORE_BAND`. The tone paints the header wash and the band's glyph; the
+word beside it is the reading colour of that wash. A pill saying the same word
+would say it twice.
+
+**`hot` is the SUCCESS tone, not the error one.** A hot lead is the good
+outcome; reading temperature as danger is exactly the confusion a tone
+vocabulary exists to prevent.
+
+The band is DERIVED from the score as a fraction of `max`
+(`LEAD_SCORE_THRESHOLDS`: warm at 0.4, hot at 0.7), so a 0–100 score and a 0–5
+one land in the same places. Boundaries are inclusive upward — exactly 0.4 is
+warm — because a score sitting on a threshold has reached it. An app with its
+own thresholds passes `band`, which moves the WASH with it; `bandLabel` renames
+the verdict without changing the tone.
+
+A non-positive `max` has no scale to divide, so the band is `cold` rather than
+`NaN`: the card renders data it did not choose instead of throwing over it.
+
+## The name is a required prop
+
+`accessibilityLabel` is required at the type level. ARIA computes no name for a
+`progressbar` from its contents, and the ring draws a bare number — so without
+it the card announces "progress bar, 82%" and never says whose lead it is. A
+heading beside the ring does not name it either; that is a SIBLING.
+
+`valueText` is what a screen reader says instead of the raw number: without it
+`82` of `100` is announced as a percentage, which is right by accident here and
+wrong the moment `max` is 5.
+
+react-native-web reads `aria-*` and never `accessibilityValue`, so a ring that
+set only the object announces its role and no value — in a screenshot, in a
+browser and in a prop-level test it looks perfect. `LeadScore.test.tsx` reads
+the emitted attributes instead.
+
+## The factors
+
+Each factor is a signed contribution. `factorLine` joins the label and its
+`detail` into ONE string, because the row truncates as a sentence: two
+independently shrinking texts drop the label to "Fits the ide…" while the detail
+beside it still has room.
+
+A zero factor draws a row with `0` in it rather than being hidden: "this counted
+for nothing" is a fact about the lead. The signed number is printed in the
+READING colour, not a status one — the sign is what says which way it went, and
+a red `-9` beside a grey mark would be two spellings of one fact.
+
+`factorsLabel` is the panel's header row, above the first factor and sharing its
+rule.
+
+## The trend
+
+`trend` is a pre-formatted label plus a direction. The card does no arithmetic
+and does not know what "last period" means — a week, a quarter, since the deal
+opened — so it draws what it is handed with the direction's arrow, as a quiet
+line on the wash. `LEAD_SCORE_TREND` carries the glyph and nothing else: the
+arrow is the direction, and the card keeps one tinted thing rather than three
+competing ones.

package/docs/loading.mdx

@@ -23,7 +23,7 @@ so the variant is gone.
 import { Loading } from '@oxy.so/bloom';
 
 <Loading variant="spinner" />
-<Loading variant="spinner" size="large" />
+<Loading variant="spinner" size="lg" />
 <Loading variant="spinner" text="Loading…" />
 <Loading variant="spinner" text="Saving…" iconSize={32} />
 ```
@@ -59,7 +59,7 @@ For native-tailwind users, `className` overrides `color`:
 | Prop | Type | Description |
 |------|------|-------------|
 | `variant?` | `'spinner' \| 'top' \| 'inline'` | Default: `'spinner'`. |
-| `size?` | `'small' \| 'medium' \| 'large'` | Default: `'medium'`. |
+| `size?` | `'sm' \| 'md' \| 'lg'` | Default: `'md'`. |
 | `color?` | `string` | Spinner color. Defaults to theme primary. |
 | `className?` | `string` | NativeWind class. Overrides `color`. |
 | `style?` | `ViewStyle` | Container style. |

package/docs/location-puck.mdx

@@ -0,0 +1,160 @@
+---
+title: LocationPuck
+description: Where you are, on a map Bloom does not own — the dot, the accuracy halo, the heading cone and the navigating chevron.
+order: 137
+---
+
+# LocationPuck
+
+`@oxy.so/bloom/location-puck`
+
+Everything else in Bloom's maps set is chrome AROUND a map: a place card, a
+route summary, the controls that float on top. This is the one thing drawn ON
+it, and it answers one question — where are you, how sure are we, and which way
+are you facing.
+
+```tsx
+import { LocationPuck } from '@oxy.so/bloom/location-puck';
+
+<LocationPuck
+  state="located"
+  heading={heading}
+  headingAccuracy={headingAccuracy}
+  accuracyRadius={metresToPixels(accuracy)}
+/>
+```
+
+## It positions nothing
+
+The same contract `map-marker` publishes, and for the same reason: Bloom has no
+projection, no tile source and no opinion about which map library you use. The
+puck draws ONE square box with every layer centred in it, and the app centres
+that box on the coordinate — the dot lands on the coordinate because it is at
+the centre of the box, not because of an offset.
+
+The box's size is whichever layer reaches furthest: `2 × accuracyRadius`,
+`2 × coneLength`, or the puck itself. It takes no presses
+(`pointerEvents="none"`), so a halo that happens to cover a third of the screen
+never eats a pan the map was meant to receive.
+
+`accuracyRadius` is in PIXELS, computed by the app from metres at this latitude
+and zoom, and re-passed on every zoom. Without it no halo is drawn at all: a
+halo of an invented size is a claim about precision nobody measured.
+
+## The layers
+
+| layer | what it is |
+| --- | --- |
+| halo | `MapAreaCircle` — literally the approximate-area circle `map-marker` publishes, at the radius the app gave |
+| cone | a wedge from the dot, fading along its length, as wide as the device is unsure |
+| puck | an 18 dot in the accent inside a 3 ring, `shadow-m`; a chevron while navigating |
+
+The halo is not a second implementation of a translucent accent circle. It IS
+the one `map-marker` already draws — the accent at 15% with a 1.5 edge — so a
+preset change moves the halo with every other circle on the map.
+
+## The cone is the uncertainty, drawn
+
+`headingAccuracy` is the platform's own ± reading in DEGREES and it is the
+cone's half-width, clamped into `[14°, 55°]`. Narrow means "this way"; wide
+means "roughly this way"; there is no third vocabulary and no separate
+confidence prop, because the device already reports the number.
+
+`headingUnknown` draws **no cone** and speaks no bearing. A cone at a default
+angle would be a confident claim about the one thing the device could not
+measure, and a reader who cannot see the screen would be told a heading that
+does not exist.
+
+### The gradient is the trap
+
+`react-native-svg` reads `stopColor` for its RGB and **discards any alpha inside
+it**. A stop written as `rgba(…, 0.45)` renders correctly in a browser and
+FULLY OPAQUE on a device — a hard-edged accent wedge lying over half the map —
+and a gate that pinned both platforms to the same colour token would stay green,
+because the two agree about every value and only the renderer's reading differs.
+That exact defect shipped once in `theme/glass-colors.ts`.
+
+So `LOCATION_PUCK_CONE_STOPS` holds an OFFSET and an OPACITY in separate fields,
+and the cone hands `color` to `stopColor` and `opacity` to `stopOpacity`, which
+are the two props SVG actually defines. `LocationPuck.test.tsx` asserts every
+rendered `<stop>` carries a `stop-opacity` and that no `stop-color` contains an
+alpha channel.
+
+The gradient is also `gradientUnits="userSpaceOnUse"`. The default,
+`objectBoundingBox`, resolves against the bounding box of the element that
+REFERENCES the gradient — the wedge, not the square — so `cx/cy = 0.5` lands
+somewhere out along the cone and moves as the angle widens. Measured in a
+browser before it was fixed: the fade started partway down the cone and was
+brightest off to one side of it.
+
+## `following`, `compass`, `navigating`
+
+The mode decides how much the puck turns, and the component owns that decision
+rather than making every caller repeat it:
+
+- **`following`** — the map is north-up, so the cone turns by `heading`.
+- **`compass`** — the app has already rotated the MAP so the heading is up, so
+  the cone turns by **nothing**. Passing the heading here as well would apply
+  the rotation twice; it is the mirror of the correction `MapCompass` makes for
+  its needle.
+- **`navigating`** — the dot becomes a chevron pointing along the route, and the
+  cone disappears with it. The chevron IS the direction; a cone beside it is a
+  second arrow saying the same thing.
+
+The chevron has no drop shadow, on purpose. A drop shadow is the shadow of a
+node's BOX, and the chevron's box is a square containing a wedge — so a shadow
+on it draws a rectangle floating under a triangle. It is separated from the map
+by its ring-coloured stroke, which traces the shape it actually has.
+
+## The ring is the dot's own on-colour
+
+A ring has one job: make the dot read as a deliberate object over tiles Bloom
+cannot see. Bloom cannot measure anything against those tiles, but every fill in
+the library already ships with the colour that reads ON it — so the live ring is
+the accent's solid `foreground` (white for most seeds, black for a light one
+like yellow or peach; the pair adapts, a hardcoded white ring does not), and the
+stale ring is the map-chrome surface, because the stale dot is a text rung
+floored against exactly that surface.
+
+Measured over a dark tile: the chrome surface as the LIVE ring disappeared
+entirely in dark mode — a dark ring on a dark map.
+
+## States, and what they say out loud
+
+| state | drawn | announced |
+| --- | --- | --- |
+| `locating` | the dot swells 18%, the halo breathes | "Finding your location" |
+| `located` | still | "Your location" |
+| `stale` | the accent gone, the halo at half | "Your last known location" |
+
+`stale` is the one that must be a sentence rather than a shade. A dimmer dot
+tells a sighted reader something is different and tells everybody else nothing,
+and "the map is showing where you were" is not recoverable by looking harder.
+
+Every state adds the bearing when there is one — "Your location, facing 41
+degrees" — and none of them adds it when there is not.
+
+## Motion
+
+Only `locating` moves, out of one shared driver: the dot swells and the halo
+breathes over 1600ms. A pulse that never stops is a battery cost and a
+distraction, so it stops the moment there is a fix, and `useReducedMotion()` —
+or the `reducedMotion` prop — stops it outright.
+
+The driver is written IMPERATIVELY from an effect and only READ in
+`useAnimatedStyle`, with every shared value in the deps array. Both halves are
+load-bearing on web: an animation returned from a mapper never ticks, and
+without the worklets Babel plugin a mapper re-runs on its deps array rather than
+on auto-tracked reads. See `docs/motion.mdx`.
+
+Jest cannot see the pulse at all — the reanimated mock resolves a sequence to
+its last value, so the driver reads 0 whether or not it was started. The suite
+pins what IS asymmetric (an animating halo sits at the trough of its breath, a
+still one at its resting opacity), and the motion itself is measured in a real
+browser by sampling the dot's box over ten frames.
+
+## What is not here
+
+No engine, no tiles, no projection, no geolocation. `LocationPuck` is given a
+state, a heading and a radius in pixels; it reads no sensor and subscribes to
+nothing.

package/docs/mail-compose.mdx

@@ -0,0 +1,123 @@
+---
+title: Mail Compose
+description: Writing a message — recipients as chips inside a Field contract, the cc/bcc reveal, and a frame that is a sheet on a phone and a docked panel on a desktop.
+order: 66
+---
+
+# Mail Compose
+
+`MailRecipientField` is one addressing row, `MailComposeHeader` is the block of
+them plus the subject, and `MailComposeSurface` is the frame around the whole
+thing.
+
+```tsx
+import { MailComposeHeader, MailComposeSurface } from '@oxy.so/bloom';
+
+<MailComposeSurface
+  variant="docked"
+  header={<MailComposeHeader to={to} onToChange={setTo} subject={subject} onSubjectChange={setSubject} />}
+  attachments={pending}
+  onAttachmentRemove={remove}
+  toolbar={<NoteEditorToolbar {...editor} />}
+  onSend={send}
+  onAttach={pick}
+  onDiscard={discard}
+  onClose={close}
+>
+  <YourEditor />
+</MailComposeSurface>;
+```
+
+## What this family does NOT write
+
+- **A rich-text engine.** `children` is a slot. The body is your editor.
+- **A formatting toolbar.** `toolbar` is a slot, and the toolbar Bloom ships is
+  `note-editor`'s `NoteEditorToolbar`. A second one grown here would be a second
+  one to keep in step with the first, in a library where the whole point is that
+  there is one of each thing.
+- **An attachment strip.** `attachments` goes to `chat-composer`'s
+  `ComposerAttachmentStrip`, imported rather than rebuilt. A pending attachment
+  is a pending attachment: a thumbnail, an upload ring and a remove, with the
+  ring drawn from ONE rounded-rect path helper. Two strips mean two rings that
+  close at different angles.
+- **An overlay.** There is no `position: fixed` here and no portal. See below.
+- **An address parser.** `onSubmit` hands you the typed string. Only the app
+  knows its directory and its address grammar.
+
+## The surface positions nothing
+
+`variant="sheet"` draws no frame at all — no surface, no border, no radius —
+because whatever presented it already did. Mount it as a `Dialog`'s child in its
+sheet placement, or inside a `BottomSheet`, or as a full-screen route.
+
+`variant="docked"` is the desktop panel: it paints the card rung, its own
+hairline and its own radius, and it publishes that fill with
+`SurfaceLevelProvider` so the chips, hairlines and quiet text inside it step off
+what is really behind them. WHERE it sits is your shell's decision.
+
+A compose window that placed itself would fight the app's layout in one app out
+of three, and Bloom already owns exactly one overlay stack — this is not a
+second one.
+
+`minimized` collapses a docked panel to its title bar. It is ignored by `sheet`,
+where there is nothing to minimise into.
+
+## `MailRecipientField` is a `Field` member
+
+It calls `useFieldMembership()`, which is the only supported way to join a
+`Field` — the four decisions it resolves each have a direction that is silently
+wrong the other way round (`composition.mdx` §Field).
+
+The choice this family makes is `labelPlacement: 'adjacent'`. The "To" in the
+gutter is the words the reader reads AS the control, so it keeps its own name
+and an enclosing `Field` only fills a gap. A `stacked` control would announce
+the field's label while the eye reads "To", which is exactly the disagreement
+that rule exists to prevent.
+
+Invalidity COMBINES, it does not replace: `recipientsInvalid(recipients, own)`
+is `own || any recipient invalid`. A field told it is invalid stays invalid
+however good its recipients look, and a good field holding one rejected address
+is not a good field. The chip that is wrong paints the error tone through
+`resolveAccentColors`, so the `Field`'s error text and the chip that caused it
+say the same thing.
+
+## Why this is not the generic tag input
+
+A recipient is a PERSON: a face, a name, an address and a verdict on whether
+that address will deliver. A tag has none of those four, and a tag field that
+grew them would be a contact picker wearing a tag field's name.
+
+What the two share is the part worth sharing — they are both built on `Chip` and
+they both answer the `Field` contract the same way — so if they ever converge,
+unifying them is a rename rather than a rewrite. Until then they are two things.
+
+## The cc/bcc reveal is not a plain toggle
+
+`copiesOpen(visible, cc, bcc)` forces the rows open whenever a cc or a bcc
+arrives non-empty, whatever the reveal last said. A reply-all whose copies were
+hidden is a message going to people the writer cannot see, and that is not a
+state `MailComposeHeader` will render.
+
+## Every row is a gutter, not a box
+
+The four rows — `To`, `Cc`, `Bcc`, `Subject` — share one label column
+(`MAIL_COMPOSE_GEOMETRY.gutter`) and one hairline, so the chips and the subject
+sit on a single left margin.
+
+This is deliberately not four `TextField`s. A stack of bordered boxes draws five
+rectangles where the writer is filling in one form, and the recipient chips
+would then be a control inside a box inside a box. `TextField`'s chrome is right
+for a field in a form and wrong for a mail header, which is the only place in
+this family where a base-layer control was passed over on purpose.
+
+## Known gaps
+
+- `Chip`'s remove button is named "Remove" and takes no per-chip name, so a
+  recipient chip's remove announces "Remove" rather than "Remove Mireia Solans".
+  Closing it means a `closeLabel` prop on `Chip`, which is a base-layer change
+  this family did not make. `MailComposeStrings.removeRecipient` is here and
+  ready for it.
+- The suggestion list renders inline under the row, not in a floating surface.
+  Anchoring it would make the field a `Popover` owner, and a popover inside a
+  docked panel inside a dialog is a stacking question worth answering once, on
+  purpose, rather than in passing here.