@oxy.so/bloom 4.0.0 → 4.1.0

package/docs/place-card.mdx

@@ -0,0 +1,121 @@
+---
+title: Place card
+description: A place on a map — the result row in a list and the detail header of the sheet it opens, as one component, with the name, category, rating, open/closed state, hours, distance, photo and the four actions.
+order: 134
+---
+
+# Place card
+
+```tsx
+import { PlaceCard, PlaceActions } from '@oxy.so/bloom/place-card';
+
+<PlaceCard
+  name="Forner de la Plaça"
+  category="Bakery · €€"
+  photo={photo}
+  rating={4.6}
+  reviewCount={318}
+  openState="open"
+  hours="Open until 20:00"
+  address="Plaça de les Bruixes 4"
+  facts={[{ icon: RiWalkLine, label: '6 min' }, { label: '450 m' }]}
+  onPress={open}
+/>
+```
+
+## Two densities, one component
+
+`density="row"` is the result in a list over the map. `density="detail"` is the header of
+the sheet that opens when the result is picked. They are ONE component because they carry
+the same facts in the same order — a name, what the place is, how well it is thought of,
+whether it is open, how far away it is and what you can do with it. A second component
+would be a second place for "open until eight" to be spelled, and two spellings drift.
+
+Only the arrangement differs:
+
+| | row | detail |
+| --- | --- | --- |
+| photo | 112 square thumbnail, radius 12 | a 165 cover across the top |
+| name | `body-semibold` | `title-2-medium` |
+| rating | `Rating` at `small`, beside the name | `Rating` at `medium`, beside the name |
+| figure | — | a quiet label over a tabular `title-1` reading |
+| tiles | — | `stats`, one row from 640 wide, two columns below |
+| actions | under the row | under the figure block |
+
+## Nothing here is drawn twice
+
+Every part of this card already existed, and this family composes them rather than
+redrawing them:
+
+- the stars are **`Rating`**, exactly as `ListingCard` uses it — beside the title, never
+  pushing it out;
+- the open/closed pill is **`Badge`** on a tone (`success` / `warning` / `error`), which is
+  the library's one labelled status pill;
+- the distance chip on the detail header is **`Chip`**;
+- the address line and the facts row are **`listing-card`'s own parts**
+  (`ListingLocationLine`, `ListingFacts`), imported, so a pin and a clipped fact row look
+  the same in a place card and in a listing card because they are the same code;
+- the row's 112 thumbnail is `listing-card`'s `COMPACT_PHOTO_SIZE` and
+  `COMPACT_PHOTO_RADIUS`, not a second pair of numbers;
+- the heart is **`FavoriteButton`**;
+- the actions are Bloom **`Button`s** through `PlaceActions`;
+- every colour is read off the surface the card was dropped on
+  (`styles/surface-levels.ts`), so the card is right on the page, in a sheet and inside a
+  `ContentPanel` without being told which.
+
+The REVIEWS are not here either. [`place-reviews`](/docs/place-reviews) already draws the
+summary, the review cards and the write-a-review prompt; a sheet renders
+`PlaceReviewSummary` under this header rather than this header growing a second one.
+
+## The detail header is `ai-profile-card`'s register
+
+A cover band, a name at title weight, a quiet label over a figure, tiles, and labelled
+`secondary` actions. That is deliberate: a place sheet and a profile card are the same
+shape of object — a picture, a name, one number that matters and a row of things to do —
+and Bloom should not have two registers for it.
+
+The one thing it does NOT copy is the avatar. A profile has a face over the cover; a place
+has only its photograph, so the cover IS the photo and the content starts under it.
+
+## Open, closing soon, closed, opens soon
+
+Four states rather than a boolean, because "closes in fifteen minutes" is a different
+answer from "open" and an app that can only say `true` says the reassuring one. The word
+comes from `PLACE_OPEN_LABELS` (or `openLabel`), the tone from `PLACE_OPEN_TONE`.
+
+**The pill and the hours are separate lines.** The pill is a WORD ("Open") and the hours
+are a SENTENCE ("Open until 20:00"). Pushed onto one line the sentence truncates first and
+leaves the pill saying half of what the app knows.
+
+## The row is a link and the controls are its siblings
+
+The thumbnail and the text sit inside ONE pressable — a real `<a href>` on web when `href`
+is set. The heart is laid over its corner and the actions sit under it, both from OUTSIDE
+that pressable. A button inside an anchor is invalid HTML, and on web a click on the heart
+would ALSO open the place.
+
+The row is one press target, so it carries one composed name — `composePlaceName` puts the
+name, the badge, the category, the rating as a sentence, the state, the hours, the address
+and the facts in reading order. Without it a screen reader reads "Forner de la Plaça Bakery
+€€ Open Open until twenty hundred" as one run, with the rating announced as "star four
+point six paren three one eight".
+
+## Known gap: an action has no pressed state
+
+"Save" is a toggle in every maps app, and Bloom's `Button` declares no `aria-pressed` and no
+`accessibilityState` — a component with a closed prop list drops what it does not name. So a
+saved place is expressed by the action's own WORDS and glyph ("Save" → "Saved",
+`RiBookmarkLine` → `RiBookmarkFill`), which is the one spelling that reaches both platforms
+today.
+
+That is a real shortfall and it is recorded rather than worked around: `PlaceActions` does
+not hand-roll a second labelled button to get the attribute. The fix belongs on `Button`
+(`pressed?: boolean`, emitting both spellings, exactly as `GlyphButton` already does).
+
+The heart is not affected — `FavoriteButton` carries both spellings itself.
+
+## Geometry
+
+`PLACE_CARD_GEOMETRY` holds the detail side: the 165 cover, the 24 radius, 16 of padding,
+15 between blocks, 10 for a tile's corner and padding, 10 between actions. The row side has
+no geometry of its own on purpose — it is `listing-card`'s compact row, part for part.

package/docs/place-details.mdx

@@ -0,0 +1,202 @@
+---
+title: Place details
+description: The body of a place's screen — the rows you act on, the hours by day, what the place has, how busy it is by the hour, and the transit around it, under PlaceCard's detail header.
+order: 137
+---
+
+# Place details
+
+```tsx
+import {
+  PlaceAmenities,
+  PlaceHours,
+  PlaceInfoList,
+  PlacePopularTimes,
+  PlaceTransit,
+} from '@oxy.so/bloom/place-details';
+```
+
+[`PlaceCard`](/docs/place-card) at `density="detail"` draws the HEADER of a place — the
+photo, the name, the rating, the figure and the four actions. This family is everything
+under it. Together they are the screen a maps app opens when a result is picked; neither
+half is a screen on its own.
+
+## What composes the screen
+
+| the part | what draws it |
+| --- | --- |
+| the header | `PlaceCard density="detail"` |
+| the hours | `PlaceHours` |
+| the photos | [`ListingPhotoGrid`](/docs/listing-details) + [`ZoomableMediaGallery`](/docs/zoomable-media-gallery) |
+| the address, phone, website | `PlaceInfoList` |
+| how busy it is | `PlacePopularTimes` |
+| what it has | `PlaceAmenities` |
+| the stops around it | `PlaceTransit` |
+| the reviews | [`place-reviews`](/docs/place-reviews) |
+| the section frames | [`ListingSection`](/docs/listing-details) |
+
+The sections are `ListingSection` and not a `PlaceSection`: a home's detail page and a
+place's detail screen stack sections the same way — a hairline, 32 above and below, a
+title at `title-3-semibold` — and a second component for that is a second set of numbers
+to keep equal.
+
+```tsx
+<ScrollView>
+  <PlaceCard density="detail" {...place} actions={actions} />
+  <PlaceHours state="open" summary="Open until 20:00" days={week} />
+
+  <ListingSection title="About">
+    <PlaceInfoList items={info} />
+  </ListingSection>
+
+  <ListingSection title="Popular times">
+    <PlacePopularTimes days={popular} />
+  </ListingSection>
+</ScrollView>
+```
+
+On a phone that goes inside a `BottomSheet` over the map; on a desktop inside a
+`ContentPanel` beside it. Nothing in this family knows which — every block reads the
+surface it was dropped on (`styles/surface-levels.ts`), so a sheet that publishes its own
+fill gets a settings card, a chart track and hairlines resolved against the sheet rather
+than against the page:
+
+```tsx
+<SurfaceLevelProvider level={1} fill={colors.card}>
+  <View style={[{ backgroundColor: colors.card }, surfaceFillVars(colors.card)]}>
+    …
+  </View>
+</SurfaceLevelProvider>
+```
+
+## `PlaceInfoList` is `settings-list`, row for row
+
+A place's contact block and a settings screen are the same object: a short card of rows,
+each carrying one value and one thing that happens when you press it. So this is
+`SettingsListGroup` and `SettingsListItem` — the glyph well, the 44 minimum height, the
+hairline between rows, and the surface the group resolves from whatever is behind it.
+
+Two decisions of its own:
+
+- **The VALUE is the first line and the kind is the second.** A reader scanning a place
+  sheet is looking for the address, not for the word "Address". The announcement inverts
+  that — "Address: Plaça de les Bruixes 4" — because a list of five rows is *listened* to
+  by kind, and five values with no labels cannot be told apart.
+- **The trailing glyph is not a button.** `action` picks it (a copy sheet, a handset, an
+  arrow out of the box) so the press is legible before it is made, and the row stays ONE
+  press target with ONE announcement. A second control inside a pressable row is a second
+  tab stop saying the same word, and on web it is a button inside a button.
+- **The action's WORD is in the name, not in a hint.** The first version put it on
+  `accessibilityHint`, and react-native-web drops that prop entirely — no `title`, no
+  `aria-description`, no `aria-describedby` — so on web the row announced a fact and never
+  said it could be pressed, while native read it correctly. Same class as
+  `accessibilityState`, same fix: the name is the one spelling that reaches both. It goes
+  last ("Address: Plaça de les Bruixes 4, Copy"), because the fact is what the reader came
+  for. `PLACE_INFO_ACTION_LABELS` holds the English words; `actionLabels` replaces them.
+
+`action` is a closed list rather than a slot for the same reason: one row, one action.
+Nothing here touches the clipboard, the dialler or the browser — `onPress` is handed the
+row's id and the app does the rest.
+
+`numberOfLines` defaults to **2**, because a postal address does not fit on one across a
+phone and the tail that would be cut is the part that identifies it. A settings row's
+title is a noun and fits on one; this one's title is the row's content.
+
+## `PlaceHours` says what the app tells it
+
+**Nothing here reads a clock.** `summary` is the app's whole sentence ("Open until 20:00",
+"Closes soon", "Closed — opens 07:30 tomorrow") and `today` is the app's flag. A place's
+hours are in the place's timezone, the reader is in another, and whether a Tuesday is open
+also depends on a holiday calendar Bloom has never heard of. A component that guessed would
+be wrong twice a year, quietly.
+
+The state pill and the state word are `PlaceCard`'s own — `PLACE_OPEN_TONE` and
+`openLabelFor` — so a place cannot be "Open" on the header of a sheet and "Closing soon" in
+the body of it.
+
+The disclosure is Bloom's `Accordion`: it owns the chevron, the `aria-expanded` and the
+reveal. One trap comes with it — `AccordionContent` keeps its children mounted while shut
+(it animates `maxHeight` to 0), so the week would still be read out under a trigger that
+says it is collapsed. `PlaceHours` hides its week from assistive tech while shut; nothing
+in there takes focus, so it costs nothing.
+
+**A split day stays on one line** (`07:30 – 14:00, 17:00 – 20:00`). The week is read as a
+column of days, and a day that takes two rows breaks the alignment that makes the column
+scannable. Both stretches are short, and the pair fits where one does.
+
+A day with no `intervals` is CLOSED — that is the whole encoding, so an app cannot say
+"closed" and list hours at the same time. `exception` puts a `warning` badge on the row
+("Public holiday", "Market day") and adds it to the row's announcement, because a badge is
+silent.
+
+## `PlaceAmenities` is the listing amenity block, called
+
+`layout="list"` **is** [`AmenityList`](/docs/listing-details), handed the same items — not
+a copy of it and not a port. Icon, label, an optional second line, a struck-through label
+for what the place does not have, the two-column split from 560 wide and the "Show all"
+button are all that component's. The only difference between a home's amenities and a
+place's was the noun, and a noun is not a component.
+
+`layout="chips"` is the one thing a listing page does not have: a wrapping strip of `Chip`s
+for the top of a sheet, where four attributes have to read at a glance. Same items, same
+unavailable treatment, different density.
+
+The name sits on the strip's `listitem` and not on the chip, because a non-pressable `Chip`
+is a plain `View` — and on web a `div` carrying an `aria-label` and no role is not
+announced at all.
+
+## `PlacePopularTimes` is a chart
+
+A meter answers "how full is this one thing". Every reading here only means something
+against the twenty-three beside it, so it is a chart, drawn the way Bloom draws charts:
+`react-native-svg` bars on `chart-cards`' own bar geometry (`singleBarSlot`,
+`roundedBarPath`) in one of its nine series hues, over its chart track colour.
+
+**Which chart card this is not.** `StepsCard` draws exactly these bars — inside the medical
+card's fixed height, under its own headline, its week pill and its count-up, with seven
+labelled bands. A place sheet already has a section header and needs twenty-four bands with
+a day switch, so reusing that card would have meant suppressing four of its five parts. The
+bar maths is what was worth sharing, and that is what is imported.
+
+Three decisions:
+
+- **The domain is a fixed 0–100.** A per-day maximum would make Tuesday's quiet peak as
+  tall as Saturday's queue, which is the one comparison the chart exists to allow.
+- **The track is drawn behind every hour**, so a quiet hour is still a shape and a CLOSED
+  hour reads as a gap rather than as a missing one.
+- **`currentHourIndex` belongs to a DAY.** Switching to Tuesday drops the "now" marker and
+  the live line with it, because Tuesday has no now.
+
+The chart is ONE image with one name ("Wednesday, busiest at 9, now 18, busier than usual").
+Twenty-four bars two pixels wide would be twenty-four tab stops saying a number each, which
+is not a reading of anything. The axis labels every hour that fits and every second or third
+below that — twenty-four labels across a phone is sixteen pixels each — and the current
+hour keeps its label whatever the step.
+
+`PLACE_BUSY_LABELS` holds the three English trend sentences; `trendLabel` replaces one.
+
+## `PlaceTransit` reuses the line badge
+
+The line pills are `directions`' own [`TransitLineBadge`](/docs/directions), imported. An
+operator's line colour is data the app owns, and that badge already knows how to *measure* a
+readable label against an arbitrary fill in both modes. A second badge here would be a second
+answer to that question, and they would drift.
+
+A departure is ONE utterance — "Line L4 to Pla del Bosc, 4 min, live" — because read part by
+part, a column of three badges and three times is six announcements the listener has to pair
+up themselves.
+
+**`realtime` is a colour AND a word.** The dot and the green time are what a sighted reader
+sees; `live` is in the row's name for everyone else. Green alone says nothing to a reader who
+cannot see it, and it is the first thing a high-contrast mode takes away.
+
+The stop header is pressable only when `onPressStop` is given (an app pans its map to the
+stop). It takes the library's one hover wash and one focus ring, built by
+`interactiveWebCss` rather than hand-written.
+
+## Geometry
+
+`PLACE_DETAILS_GEOMETRY` holds the numbers: 16 between blocks, 12 between rows, a 20 glyph,
+a 120 plot with a 22 axis under it, a 4 bar radius. The gaps are `listing-details`' own
+rungs, so a place's section and a home's section stack identically; only the chart has
+measurements of its own, because nothing else in Bloom draws a day of hours.

package/docs/place-list.mdx

@@ -0,0 +1,101 @@
+---
+title: Place list
+description: A saved list of places — the list as a card with its cover strip, count, collaborators and visibility, and the places inside it as PlaceCard rows with a note each, reorderable and removable.
+order: 138
+---
+
+# Place list
+
+```tsx
+import { PlaceList, PlaceListCard } from '@oxy.so/bloom/place-list';
+```
+
+"Want to go", "Favourites", "Coffee, ranked". `PlaceListCard` is the list seen from
+outside; `PlaceList` is what is inside it.
+
+## `PlaceListCard`
+
+```tsx
+<PlaceListCard
+  name="Want to go"
+  count={12}
+  photos={[a, b, c, d]}
+  icon={RiFlagLine}
+  visibility="shared"
+  collaborators={people}
+  onPress={open}
+/>
+```
+
+- **The cover is a STRIP, not a square.** 112 tall — `listing-card`'s compact thumbnail
+  height, which is the height of the place rows the list is made of, so a list's cover and
+  the first place under it agree. The first tile takes two shares of the row and the rest
+  one each, with 2px seams.
+- **The count and the sharing are ONE line.** A saved list is scanned in a grid of them,
+  and the only questions asked of a card in that grid are "which list is this" and "how
+  much is in it".
+- **`color` is the person's, not a token.** A list's colour is a choice, and Bloom has no
+  ramp for it. It paints the glyph and tints the empty strip; nothing derives anything from
+  it.
+- **The card is one press target, so it announces one sentence** — "Want to go, 12 places,
+  Shared with 3, Shared". Left to ARIA's contents algorithm it is four runs with no commas.
+- **`AvatarGroup` takes no `onPressItem` here.** A button inside the card's own press target
+  is the nested control this library refuses everywhere else; a collaborator's profile
+  belongs on the list's own screen.
+
+It is deliberately NOT `listing-card`'s `WishlistCard`. That card is a square 2×2 mosaic
+with its text underneath, built for a grid of wishlists; this one is a wide card with a body
+that has to carry a count, three faces and a visibility badge. They share the idea and none
+of the geometry, so sharing the component would have meant a second layout inside it.
+
+## `PlaceList`
+
+The places inside are `PlaceCard` at `density="row"`, untouched — a saved place and a search
+result are the same object, so this list draws no row of its own and inherits the thumbnail,
+the rating, the open state and the composed announcement with it.
+
+**The note is a sibling of the place, not part of it.** The place is the place; the note is
+what someone said about it. It is announced as "Note: get the sourdough before noon", after
+the row.
+
+### Reordering is buttons, and the buttons are the accessible path
+
+`moveItem` (`hooks/list-reorder`) is the same list maths the track list, the queue and the
+photo grid use, so "move" means one thing in this package.
+
+There is no pointer drag. `SortablePhotoGrid`'s drag is GRID geometry — a point resolved to
+a cell in a fixed row of columns — and a column of rows of different heights is a different
+problem, not a smaller one. Buttons are also what a keyboard and a screen reader get out of
+a drag surface anyway, so the list is fully operable with the half that exists. If you want
+a swipe to delete on touch, wrap a row in [`SwipeRow`](/docs/swipe-row) — that is the app's
+call, not this component's.
+
+Two properties that are easy to lose:
+
+- **Every row is keyed by its id**, so on web the button that was just pressed keeps focus
+  and travels with its row. A reader can press "move later" three times without hunting for
+  the control again.
+- **The ends are DISABLED, not absent.** The first row's "move earlier" and the last row's
+  "move later" stay in place; a control that disappears at the end of its travel moves the
+  two beside it under the pointer.
+
+Every move is announced politely through a visually hidden live region, because a reorder
+draws nothing new — the rows just swap, and a screen reader would otherwise hear nothing at
+all.
+
+### Controls are 44
+
+The move and remove controls are `GlyphButton`s at 44 with a 20 glyph, right-aligned under
+the row rather than stacked beside it: three 44 boxes do not fit in the 112 a place row is
+tall, and a column of controls narrower than that is not a thumb target.
+
+## Geometry
+
+`PLACE_LIST_GEOMETRY`: a 112 cover at radius 12 with 2px seams and at most four photos, 12
+between blocks, 44 controls with a 20 glyph.
+
+## Labels
+
+Every word `PlaceList` speaks that is not in the data is in `PlaceListLabels`, with
+`DEFAULT_PLACE_LIST_LABELS` as the English set. `PLACE_LIST_VISIBILITY_LABELS` and
+`PLACE_LIST_VISIBILITY_ICON` carry the three visibility words and their glyphs.

package/docs/progressive-blur.mdx

@@ -10,6 +10,10 @@ A blur that is strongest at one edge and fades to nothing. Put it behind a
 floating tab bar or a transparent header so scrolling content dissolves rather
 than hitting a hard blur boundary halfway up a word.
 
+The tint follows the nearest published surface fill (`SurfaceLevelProvider`),
+falling back to the theme background outside a surface. A blur inside a tonal
+panel therefore fades into that panel's color.
+
 ```tsx
 import { ProgressiveBlur } from '@oxy.so/bloom/progressive-blur';
 

package/docs/proof-of-delivery.mdx

@@ -0,0 +1,82 @@
+---
+title: Proof of delivery
+description: The proofs an app asks for at the door — a signature drawn with a finger or typed, a photo of where it was left, a code the recipient reads out, who took it and a note — each optional, all of them one result.
+order: 139
+---
+
+# Proof of delivery
+
+```tsx
+import { ProofOfDelivery, SignaturePad } from '@oxy.so/bloom/proof-of-delivery';
+
+<ProofOfDelivery
+  proofs={['recipient', 'signature', 'photo']}
+  required={['recipient', 'signature']}
+  onAddPhoto={openCamera}
+  onSubmit={(result) => result.missing.length === 0 && record(result)}
+/>
+```
+
+## Five proofs, five existing controls, one new surface
+
+| proof | control |
+| --- | --- |
+| `recipient` | `TextFieldInput` |
+| `signature` | `SignaturePad` — the one thing this family adds |
+| `code` | `InputOtp`, which already cleans, pads and reports completion |
+| `photo` | `SortablePhotoGrid` |
+| `note` | `Textarea` |
+
+Every one is a `Field`, so the label, the hint, the required mark, the error and the association with the control are said once (`docs/composition.mdx`). Two of the five draw SEVERAL controls — the signature is a pad and a name, the photo is a grid — so those fields are `multiple`: one id on three inputs is invalid HTML, and one error described by three inputs is announced three times.
+
+### Why the photo is not `FileUpload`
+
+`FileUpload` is a DROP ZONE with an upload lifecycle of its own. That is right for a document on a desktop and wrong at a door: the photo comes from a camera the app opens, and what has to be on screen afterwards is the picture, its upload state and a way to take another. `SortablePhotoGrid` is that — the app owns the picker, the grid owns the order, the per-photo progress and the retry.
+
+## The order is the door's, not the caller's
+
+`PROOF_ORDER` is recipient, signature, code, photo, note, and `proofs` is filtered through it whatever order it arrives in. Recipient first because it is the question the courier asks out loud and the answer decides the rest; then the two proofs the RECIPIENT takes part in; then the photo, taken after they have gone; then the note, written about everything above it.
+
+## The confirm control is never disabled
+
+It fires `onSubmit` on every press, with `missing` filled in. Pressing with something outstanding puts the error on each missing field AND an `error` `Admonition` in a `role="alert"` at the bottom naming them, so the answer arrives in the same gesture that asked the question.
+
+A disabled confirm is the failure mode this avoids: the reader presses, nothing happens, and nothing on screen says why — least of all to a screen reader, which is told only that a button is dimmed.
+
+The errors appear only after the first press. A form that is red before it has been filled in is a form that is wrong about the reader.
+
+`submitting` is the one thing that does stop the press, because a second confirm would record the same delivery twice.
+
+**A proof that is required but not DRAWN cannot be missing.** `missingProofs` intersects `required` with `proofs`, so an app that requires a control it never showed cannot refuse a delivery over it.
+
+## `SignaturePad`
+
+- **The pad** is a filled surface at the next level up, radius 12, with a baseline hairline at 72% of its height. A signature is written ON a line; without one a finger starts wherever it lands and the capture reads as a doodle.
+- **The ink** is one `<Path>` per stroke, quadratic through the MIDPOINTS of the samples, round caps and joins, painted in the TEXT colour — a signature is writing, not a brand mark.
+- **The pointer** is one `PanResponder`, which react-native-web routes from real mouse, touch and pen events through its own responder system. The same file draws on both platforms and there is no `.web` fork to keep in step. Points arrive in the pad's own coordinates (`locationX` / `locationY`, measured against the responder node), so a scrolled or transformed page needs no correction.
+- **The pad KEEPS the gesture** (`onPanResponderTerminationRequest: () => false`). A signature crosses a scroller, and an ancestor that stole the gesture mid-word would break the stroke in half and leave the second half unrecorded.
+- Samples closer together than 2px are dropped. A resting finger reports the same coordinate many times a second, and every repeat is a zero-length curve the smoothing then has to average out.
+- **A single tap lays down a DOT.** `signaturePath` emits `M… l0 0` for one point, which a round cap paints as a dot — a full stop in a signature is exactly that. Without it a tap draws nothing and the reader taps harder.
+
+### The typed field is the other half of the control, not a fallback
+
+A pad is a pointer affordance: there is no keyboard gesture for it, a screen reader has nothing to announce but an empty box, and a motor impairment makes it unusable. So both paths are drawn AT ONCE rather than behind a mode switch — a mode a reader has to find is a mode most readers never find — and `isSignatureGiven` treats ink and a typed name as the same answer.
+
+`typed={false}` removes it. That is a deliberate escape hatch for an app collecting the name in a field of its own on the same screen, and it is the only way to ship this control with no accessible path at all.
+
+The pad itself announces as `role="img"` named "Signature" (and "Signature, Signed" once there is ink). The drawn signature IS an image: not operable by keyboard, holding no state ARIA can read.
+
+## What jest cannot see, and where it is checked instead
+
+**A jest test cannot see a canvas.** react-native-svg renders to a native view on one platform and to a `<path>` on the other, and jsdom paints neither.
+
+So the split is deliberate:
+
+- `signaturePath`, `shouldKeepSignaturePoint`, `isProofGiven` and `missingProofs` are PURE, and `src/__tests__/ProofOfDelivery.test.tsx` walks their boundaries — no points, one point, two, a code half entered, a required proof that was never drawn.
+- That ink actually lands under a real pointer is `scripts/verify-signature-pad.mjs`: a real Chrome, `page.mouse.down/move/up` through the browser's own hit testing, reading the emitted `<path d>`. It also runs the negative control — a press with no movement, which must still leave a dot, and a press on a `disabled` pad, which must leave nothing.
+
+## Traps
+
+- **The code counts only once it is FULL.** `InputOtp` reports every keystroke, and "2 of 4 digits" is not a code the recipient read out, so `codeLength` is part of the question rather than something the caller checks after.
+- **`value` is partial and `onChange` is not.** A caller may control one field; the component fills the rest from `EMPTY_PROOF` and always reports the whole thing.
+- **`onAddPhoto` is the app's picker.** Without it the grid draws no add tile — the component opens no camera of its own on either platform.

package/docs/screen.mdx

@@ -43,10 +43,30 @@ defaults match Bloom's 56-point header and 58-point bottom bar plus safe area.
 Measured heights replace those estimates. Custom chrome should declare its height
 to prevent the first layout changing the content's padding.
 
-`documentScroll` enables web sticky chrome for a document virtualizer.
-`VirtualList screen={{ active, restoration }}` connects both platforms to the
-screen without a surrounding ScrollView. Use `useScreenWindowScroll` for another
-window virtualizer; `useScreenScroll` remains the animated native/container binding.
+On web, `documentScroll` makes the document the scroller: Screen grows with its
+children and automatically observes `window.scrollY`. Do not wrap ordinary
+content in a ScrollView or constrain Screen to a fixed-height flex slot.
+
+```tsx
+<Screen documentScroll header={<PageHeader title="Home" />} bottomBar={<Navigation />}>
+  <LongContent />
+</Screen>
+```
+
+Header and bottom chrome stay sticky within the Screen column's width. Screen
+reserves their measured footprints in document flow, including bottom clearance;
+content can scroll fully above the bottom bar. The initial declared heights still
+apply before measurement. Without chrome slots Screen adds no content padding,
+so a composed shell can own those slots and their spacing itself.
+
+`VirtualList screen={{ active, restoration }}` connects both platforms without a
+surrounding ScrollView. Use `useScreenWindowScroll` for another window virtualizer;
+its explicit writer takes priority over Screen's automatic listener. During a
+pending restoration it updates the offset without collapsing navigation. When
+that binding unmounts, automatic window tracking resumes. Returned `contentInsets`
+are zero in document mode because Screen already reserves the spacing; applying
+them does not add a second footprint. `useScreenScroll` remains the animated
+native/container binding. Only one explicit scroller should be active per scope.
 
 When navigation retains whole screens, set `Screen active={focused}` (or
 `AppShell active={focused}`). That boundary disables every descendant scroll
@@ -59,3 +79,12 @@ AppShell establishes `navigationScope="shared"`. Route Screens use the default
 `inherit`: their local header offset is independent, while the focused list owns
 the shared navigation progress. Set every retained route's `active` explicitly;
 use `navigationScope="isolated"` for modal screens that cover the shell navigation.
+
+
+### Storybook document hosts
+
+Full-screen stories that demonstrate document scrolling declare
+`parameters: { layout: 'fullscreen', bloomScroll: 'document' }`. The preview then
+uses a minimum viewport height, allowing the document to grow. Contained demos
+keep a bounded height. This is a preview host choice, not an application prop;
+consumer roots must likewise allow the document to grow.