@everfur/sdk 0.1.1 → 0.4.0

package/CHANGELOG.md

@@ -8,9 +8,708 @@ The line is deliberately pre-1.0: the API is stable enough to build against and
 is guarded by api-extractor golden reports across all eleven subpaths, but 1.0.0 is a promise about breaking
 changes that has not been earned by any production integration yet.
 
+## [0.4.0] - 2026-09-21
+
+### Changed: a press of `VetVisitButton` opens the visit IN YOUR APP, not the system browser
+
+**Who is affected: every React Native integration that has registered an in-app flow. Nobody else.** If you
+upgrade and change nothing, the button mints the handoff and opens the hosted visit exactly as 0.3.0 did.
+That is the floor, and it is tested: the member always reaches a vet, and the only thing this release can
+change is where.
+
+**Why 0.4.0 and not 0.3.1.** Semver's rule for a pre-1.0 line is that the MINOR is the compatibility signal,
+and the observable default behaviour of a published, shipping component changes here. No type was removed and
+no signature narrowed, so a 0.3.0 integration still COMPILES against 0.4.0 unchanged, which is why this is not
+a major. But "compiles unchanged" is the wrong test for a default: a partner who pins `^0.3.0` and takes this
+automatically would get a different destination on a control their users already press. A minor bump is what
+makes that an upgrade a partner chooses rather than one that arrives.
+
+**What to do.** One line in your app entry, and every `VetVisitButton` in the app opens your screen:
+
+```ts
+import { registerEverfurTelevetFlow } from '@everfur/sdk/televet';
+
+registerEverfurTelevetFlow(() => navigationRef.navigate('EverfurBooking'));
+```
+
+- **New: `registerEverfurTelevetFlow`, `hasEverfurTelevetFlow`, `presentEverfurTelevetFlow`** on
+  `@everfur/sdk/televet`. A registry rather than an import, for the same bundler reason `registerEverfurDaily`
+  is one: the booking screens enter your graph through YOUR import of `@everfur/sdk/televet/booking`, so a
+  handoff-only integration is not billed for a scheduler it never renders. The `televet` subpath is still
+  inside its 13_600 gzip budget, and the supply-chain suite still proves that chat, records and televet carry
+  none of the booking closure.
+- **New: `prefer` on `VetVisitButton`.** `'in-app'` (the default) opens the registered flow; `'redirect'` is
+  the explicit opt-in back to the browser handoff and ignores the registry entirely, which is what you want
+  for a surface you deliberately keep hosted.
+- **Unchanged: `onStartInApp`.** It still works and now takes precedence over the registry, so an integration
+  that already wired it does not change twice in one upgrade.
+- **Unchanged: `visitRef`.** A tapped push that names an existing visit still opens THAT visit through the
+  handoff. There is no in-app surface for one yet, and sending an owner into a fresh booking funnel because
+  they tapped a reminder would be the wrong screen.
+- **A presenter that throws is not a dead button.** An unmounted navigation ref or a renamed route is caught,
+  the press falls through to the hosted visit, and your engineer is told through the console that the
+  navigation did not run.
+
+**The in-app CALL needs native modules, and Expo Go cannot run it.** Booking in-app needs nothing native.
+JOINING the consult in-app is `@everfur/sdk/televet/call`, which runs on the same Daily native modules the
+Everfur consumer app uses: `@daily-co/react-native-daily-js`, `@daily-co/react-native-webrtc` and, on Expo,
+the config plugin `@daily-co/config-plugin-rn-daily-js`. It needs a native rebuild (a JS-only OTA cannot add
+a native module), camera and microphone permissions, and one `registerEverfurDaily(...)` line. **Expo Go
+cannot load it at any version** - that is a property of Expo Go, not a missing package, so the way out is a
+development build (`expo prebuild`, then run the native app) rather than another install. Until then the
+call surface reports itself unavailable and `VetVisitButton` remains the way through.
+
+### Fixed: the native-call setup message names Expo Go
+
+`EVERFUR_DAILY_SETUP`, handed to `onUnavailable` and warned once, listed the three packages and said "rebuild
+the native app". An Expo Go developer believes they have no native app to rebuild and would repeat the one
+step that cannot work, so the message now names Expo Go and the development build directly. Developer-facing
+console and callback text only; no member-facing copy changed.
+
+### Still gated: the ported booking screens
+
+`isTelevetBookingCopyReady()` continues to answer **false**, so `EverfurTelevetBooking`,
+`EverfurTelevetReschedule` and `TelevetBookedScreen` still refuse to render a ported string and hand over to
+the hosted visit. Registering a flow changes the DESTINATION; it does not open that gate. See
+"the copy gate" in `16-TELEVET-VISITS.md` for what opens it.
+
+## [0.3.0] - 2026-09-21
+
+### Fixed: the deliverability gate now imports every web entry instead of only finding it
+
+`npm run verify:pack` installs the packed tarball into a scratch React web project and, from this release,
+IMPORTS all seven browser entries there (`@everfur/sdk/web`, `/web/records`, `/web/records/depth`,
+`/web/televet`, `/web/consent`, `/web/notifications`, `/testing/web`) rather than asserting that a file
+exists. A bundle that resolves and then throws on import used to pass; it now fails the gate.
+
+The same gate read a piece of user-facing copy as an import. Its bare-specifier extractor matched the word
+"from" at the end of a sentence (`{title:"Where this reading came from",close:"Close reading details"}`),
+captured `,close:` as a package name, could not resolve it, and therefore SKIPPED executing
+`@everfur/sdk/web/records` altogether. Captures are now required to be legal module specifiers, which no
+fragment of prose is.
+
+### Changed: `EverfurChat` and `EverfurRecords` are the consumer app's screens, screen for screen
+
+The chat and records surfaces (React Native, `@everfur/sdk/web` and the two frames) were rebuilt to match the
+Everfur consumer app: no new dependency, no icon font, no clipboard, picker or camera module (those stay host
+seams). Documented in `05-SDK-INTEGRATION.md` (What `EverfurChat` carries), `13-WEB-INTEGRATION.md` and
+`08-API-REFERENCE.md`.
+
+- **Chat, built in.** The pet header with its switcher (two or more pets from `GET /widget/v1/pets`, with pet
+  discs), the quick prompts, citation cards under a reply, the footer under every settled message (its time,
+  Copy, the `Helpful` / `Neutral` / `Not helpful` thumbs recorded through
+  `POST /widget/v1/messages/{message_id}/feedback`, the reasons sheet behind a thumbs-down), the urgency banner
+  with the calm `general` tier, the saved-conversation drawer (search, unread, load-on-scroll), the follow-up
+  check-in card, the typing indicator and the app's motion. `ChatMessage` gains `createdAt` (ISO 8601: the wire
+  `created_at` on a history row, the SDK clock on a live turn).
+- **New `EverfurChat` props.** React Native: `onCopy` (your clipboard; without it no Copy control), `attachments`
+  (`{ pick(source), sources?, maxPerMessage? }`: your image picker; the queue mints the presigned policy at
+  `POST /widget/v1/uploads/initiate`, posts the bytes and sends `image_s3_keys`), `onPetChange`, `onVetPrep`,
+  `onFindVet`, `renderVetAction`. Web: `attachments` (on by default, `false` turns it off, `{ maxPerMessage }`),
+  `dictation` (Web Speech API, on by default, `false` is the kill switch; a custom iframe needs
+  `allow="microphone"`), `onPetChange`, `onVetPrep`, `onFindVet`, `renderVetAction`. The chat entry now carries
+  the televet chat-entry probe (the app's Find-a-vet CTA and vet-prep chip), which renders nothing while the
+  tenant's entry is closed; `EverfurChatAttachments` and `UrgencyDisplayLevel` are exported from the root.
+- **Fonts per face.** `fonts: { regular?, medium?, bold?, mono? }` on the `theme` prop names one registered face
+  per weight, the way the app does, and every surface sets the family alone (never a synthetic `fontWeight` on a
+  named face). The SDK bundles no font. On the web, `font_urls` may name a woff2 per face on the Everfur SDK CDN
+  only; a font you serve is `@font-face` plus `fonts`.
+- **Records.** `EverfurRecords` is the consumer records flow (dashboard, request, full record with the owner's
+  fact editor and share sheet, document, clinic picker, clinic-release consent, upload). The fact editor sends
+  the correction under the original value's typed slot (`value_num` as a number, `value_date`, `value_bool`,
+  else `value_text`); `RecordFactEditInput.correctedFields` is `Record<string, FactFieldValue>`.
+- **Frame CSP.** The chat frame's `connect-src` names the media bucket's exact upload origin beside the API
+  (the staging publisher sets staging's), never an S3 wildcard.
+- **Bundle lines.** The chat closures are raised to their measured size plus 5% (RN chat 43_000, `web/index.js`
+  74_000, `frame.js` 138_000 gzip bytes); the records lines are unchanged.
+
+### Added: push and email to your members (`@everfur/sdk/notifications`, `@everfur/sdk/web/notifications`, `@everfur/sdk/server`)
+
+Everfur now sends the notifications its own app would show a member (a records request moving, a record ready,
+a visit booked, cancelled, completed, missed, rescheduled or due for a reminder, a follow-up check-in, a
+vaccination due) to partner members itself, by push through your own provider and by email, beside the webhook
+to your server. Everything ships dark behind `partner.notifications_enabled` (every route answers `404` until
+Everfur turns it on for your client). The SDK never imports a push library: you obtain the token, it does the
+rest. Documented in `docs/partner-integration/17-NOTIFICATIONS.md`.
+
+- **New subpath `@everfur/sdk/notifications`** (React Native; `@everfur/sdk/web/notifications` is the same
+  surface for a page, with no web push in this version: pass `token: null` and use the preferences). Its own
+  entry, so the chat, records and televet closures are byte-identical to the previous build.
+- **`useEverfurNotifications({ token, provider, platform, installationId? })`** registers the token for the
+  signed-in user on login (`POST /widget/v1/me/devices`), registers again when the token changes (unregistering the
+  previous device), keeps the device id per user in the SDK's per-user storage, and unregisters BEFORE the bearer
+  drops on `logout()`, `setUser(null)` and a user switch. `status` is `signed_out | no_token | registering |
+  registered | unavailable | failed | unregistered`; `register()`, `unregister()` and `setPreferences({ pushEnabled,
+  emailEnabled })` settle to an `EverfurResult`. On React Native a retryable failure is retried on the next
+  foreground. `useEverfurNotificationsClient()` is the same client for imperative use.
+- **`createNotificationsClient(runtime)`**, bound from the subpath and not a runtime method: `registerDevice`,
+  `unregisterDevice`, `setPreferences`. A dark tenant is the ordinary not-found error; the route's own reasons
+  surface as `reasonCode`: `provider_unsupported` and `token_invalid` (`validationFailed`),
+  `device_cipher_unavailable` (`serviceUnavailable`, retryable). `NOTIFICATIONS_REASON_MESSAGES` and
+  `explainNotificationsReason(error)` give a DEVELOPER-facing sentence per reason (`credentials_missing` included);
+  `displayMessage` stays the copy a person sees. Supporting types: `NotificationsClient`, `NotificationsRuntime`,
+  `RegisterDeviceInput`, `RegisteredDevice`, `PushProvider`, `DevicePlatform`, `NotificationPreferencesInput`,
+  `NotificationPreferences`, `NotificationsReasonCode`, `EverfurNotificationsOptions`, `EverfurNotificationsState`,
+  `EverfurNotificationsStatus`.
+- **`parseEverfurNotification(payload)`**, pure and total: reads the `data.everfur` routing block out of an
+  expo-notifications `Notification` or `NotificationResponse`, a Firebase `RemoteMessage` or a raw data map (a JSON
+  string through FCM) and returns `{ eventId, eventType, target }` with `target.kind` one of `record_request`,
+  `pet`, `visit`, `case`, or `null` for anything Everfur would not send (the sender's allow-list, mirrored).
+  `EVERFUR_NOTIFICATION_EVENT_TYPES`, `EVERFUR_NOTIFICATION_TARGET_KINDS`, `EVERFUR_NOTIFICATION_VERSION`,
+  `EverfurNotification`, `EverfurNotificationTarget`, `EverfurNotificationTargetKind`, `EverfurNotificationEventType`.
+- **`setPartnerMemberNotificationProfile(client, { userRef, email, consent })`** on `@everfur/sdk/server`
+  (`PUT /partners/members/{user_ref}/notification-profile`, secret key): supplies a member's email with the consent
+  you collected (`{ givenAt, method: 'partner_attested', version }`, required) and settles to the MASKED profile.
+  Server-only by design; never on a device subpath (pinned by the supply-chain gate). Types
+  `PartnerMemberEmailConsent`, `PartnerMemberEmailConsentRecord`, `PartnerMemberNotificationProfile`,
+  `SetPartnerMemberNotificationProfileInput`.
+- **`onBeforeLogout(hook)` on `EverfurRuntime`** (`@everfur/sdk/core`), the seam the hook uses: runs before a
+  signed-in user leaves, with a grace auth that still signs the request; `logout()` awaits it up to
+  `LOGOUT_HOOK_BUDGET_MS` (3 s) and never fails on it. `BeforeLogoutContext`, `BeforeLogoutHook`. The per-user KV
+  allowlist gains its first key, `everfur.notifications.device`, swept on logout after the hooks.
+- `MockTransport` knows the three member notification routes.
+
+### Changed: the theme is resolved from four layers, and your `theme` prop now wins per field
+
+- **Precedence reversed, per field (owner decision, 18 September 2026).** The resolved theme merges the compiled
+  default, the tenant's console branding (`render_hints.branding`, wire `schema_version: 2`), your `theme` prop and
+  the user's device preferences. A field the tenant lists in `locked_fields` (plus `hide_powered_by`, always) is
+  server-wins; every other cosmetic field is client-wins: your value overrides the console value and the console
+  fills what you leave unset. Before, the server won every field. `slots` in `locked_fields` locks every slot,
+  `slots.<name>` one. A branding with an unknown `schema_version` is ignored whole (default plus your `theme`).
+  `resolveTheme` documents the rule; `ResolveThemeInput` gains `textScale`, `scaleTypeSizes` and `highContrast`.
+- **Dark palette derivation.** On the dark palette a colour with no `*_color_dark` now shows a DERIVED variant
+  (`deriveDarkVariant`, the byte-for-byte twin of the console's algorithm, pinned by shared golden vectors) rather
+  than the light colour. An explicit `primary_color_dark` / `accent_color_dark` still wins. `logo_url_dark` swaps
+  the logo on the dark palette.
+
+### Added: paint slots, the user's text size, high contrast, a preview helper
+
+- **`slots` on the `theme` prop (and on the wire):** `composerInput`, `sendButton`, `userBubble`,
+  `assistantBubble`, `recordCard`, `vetVisitButton`, `primaryButton`, `link`, each accepting `backgroundColor`,
+  `borderColor`, `borderRadius`, `textColor` (the console's snake_case keys are read too). Applied by the React
+  Native and web chat, records, record depth and vet visit surfaces at those sites; structure and copy unchanged.
+  A slot's text colour is contrast-guarded against the background it supplies. `theme.slots` carries the resolved
+  map; `THEME_SLOT_NAMES`, `THEME_SLOT_KEYS`, `EverfurThemeSlotName`, `EverfurThemeSlot`, `EverfurThemeSlots`,
+  `EverfurThemeSlotInput`, `EverfurThemeSlotsInput` are exported.
+- **Text size.** `type.scale` (the user's effective text scale) and `type.maxScale` (the cap, from
+  `accessibility_max_font_scale`, default 1.3, range 1 to 2) on the theme. React Native reads
+  `PixelRatio.getFontScale()` and every SDK `Text` / `TextInput` carries the cap as `maxFontSizeMultiplier`; the web
+  reads the root font size and the resolved `type.size` carries the scale (inline, no `<style>`).
+- **High contrast.** `prefers-contrast: more` (web) resolves through `deriveHighContrast`: text and borders pushed
+  toward 7:1, translucent washes replaced with solid fills; `theme.highContrast` reports it. React Native 0.74 has
+  no signal for it and renders the normal palette.
+- **`previewTheme(theme, hints, options?)`** on the root, `web` and `client` entries: the console's helper to
+  resolve a draft exactly as the device would.
+- **`EverfurThemeInput`** is now a typed interface (every field named, unknown keys still tolerated), shared by
+  the React Native and web providers, the runtime and the frame loader (`Everfur.init({ theme })`); the frame
+  protocol carries the nested `slots` map (an additive change: `FRAME_PROTOCOL_VERSION` stays 1, and the rule for
+  when it moves is documented in `protocol.ts`).
+- `@everfur/sdk/client` also exports `contrastRatio`, `parseThemeSlots`, `mergeThemeSlots`, `guardSlotContrast`,
+  `deriveDarkVariant`, `deriveHighContrast`, `LOCKABLE_THEME_FIELDS`, `THEME_SCHEMA_VERSIONS`,
+  `isKnownBrandingSchema`, `lockedFieldsOf`, `TEXT_SCALE_FLOOR`, `DEFAULT_MAX_FONT_SCALE`.
+
+### Added: login warm-up, so the token exchange adds no loading step of its own
+
+- **`prepare(opts?)` on `useEverfur()` (and `EverfurRuntime`).** Call it from your own login flow: it mints the
+  session token, resolves the entitlement verdict into the store every gate reads and, with `{ petRef }`, primes
+  that pet's chat (conversation and suggested prompts, held for the first mount). It registers no pet. Concurrent
+  calls coalesce onto one run, a settled `ready` is returned again without I/O until the user or pet changes, and a
+  `partial` or `failed` run is retried on the next call. It never throws: it settles to a `PrepareResult`
+  (`status: 'ready' | 'partial' | 'failed'`, `durationMs`, and `session`, `entitlements`, `chat` as the same
+  `EverfurResult` shapes the surfaces settle to). Types: `PrepareOptions`, `PrepareResult`, `PrepareStatus`.
+- **`warmUp` on `EverfurProvider`:** `'onMount'` runs `prepare({ petRef: activePet })` from the provider on mount and
+  on every user or pet change; the default `'manual'` issues nothing, so an unchanged integration behaves as before.
+- **Pre-warmed mounts have no loading phase.** `useEverfurChat` and `EverfurChat` read a controller the registry
+  already holds for their scope synchronously on the first render (`CapabilityRegistry.peekChat`), so after
+  `prepare({ petRef })` the first commit is the transcript or the empty state with its prompts: no bootstrapping
+  frame, no delayed spinner. A cold mount is unchanged (the busy view, the spinner after 300 ms). `CapabilityGate`
+  and `useCapability` already read the resolved verdict synchronously; a verdict `prepare()` resolved renders the
+  children on the first commit with no skeleton.
+- **`renderPending`** on `EverfurChat` and `EverfurRecords` (React Native and web), forwarded to their
+  `CapabilityGate`: draw your own placeholder, or nothing, where Everfur would draw its skeleton while the verdict
+  is pending, and, for chat, where it would draw its bootstrapping view. Absent, the defaults are unchanged.
+- **Proactive token refresh.** `getToken` may now return `{ token, expiresAt }` (`MintedToken`; `expiresAt` in
+  epoch seconds as `mintPartnerSession` returns them, epoch milliseconds, a `Date` or an ISO string) as well as the
+  plain string. When the expiry is known the runtime re-mints about 60 seconds before it (at half the lifetime for a
+  shorter token), silently, under any turn in flight: no request pays a 401 round trip and no stream is restarted.
+  The reactive path (401, re-mint, replay once) stays as the fallback. `createIdentityProvider` takes an optional
+  `onMinted(expiresAtMs)` third argument.
+- **`sdk.prepare.timing`** on the `telemetry` port, once per warm-up run: `{ durationMs, status }`, the
+  login-to-ready number.
+- `ChatBootstrapResult.cause`: the typed error behind `error` or `warning`, null when the conversation was primed.
+- `EntitlementPoller.prime()`: settle one verdict fetch (the poll already in flight when there is one), plus
+  `onFetch` / `onSettled` hooks on its deps.
+
+### Fixed: a cold records mount no longer flashes the off-state before the first verdict
+
+- The entitlement store started resolved at the compiled floor, so until the first poll landed `EverfurRecords`
+  (and every capability the floor does not grant) rendered the fail-closed off-state ("not available on your
+  account") and then retracted it; the skeleton `useCapability` documented never happened. The store is now
+  `isPending` while the FIRST verdict of a scope is being fetched (and again after every user or pet re-scope), and
+  `decideCapability` pends only what the decision set leaves undecided: a required key absent from the set shows
+  the gate's skeleton (or `renderPending`), a key the floor grants (chat) renders at once, a key explicitly denied
+  (a disabled runtime) is the off-state at once. Any settlement clears it: a verdict that leaves a capability off,
+  or a fetch that fails, is the fail-closed off-state, never a skeleton left up. A runtime that never fetches (an
+  injected transport without `startEntitlementPolling`) keeps its floor as before, and a verdict `prepare()`
+  resolved before mount still renders on the first commit. `EntitlementSnapshot.isPending` and
+  `DecideOptions.isPending` carry the new meaning; the gate is unchanged.
+
+### Changed: webhook event types match the wire
+
+- **`record_request.updated` carries `simple_status`, not `status`.** The PREVIEW type named a `status` field the
+  platform never emitted; the producer (`records_partner_events.py`, pinned by its tests) writes `simple_status`
+  (the seven-value records status model, typed `RecordRequestSimpleStatus`) and `simple_status_detail`. The type
+  now matches, and gains the fields the producer added: `user_ref`, `action_needed_label`, `can_retry_send`,
+  `can_update_clinic_email`, `can_revoke`, `can_convert_to_upload` and `record_updated_at`. A handler reading
+  `.status` off this payload was reading `undefined`; there is no alias because the field did not exist.
+- **Visit events name the visit `visit_ref`** (the PREVIEW type said `partner_visit_ref`, which the producer never
+  wrote), with `pet_ref` (nullable), `status` (`EverfurVisitStatus`), `scheduled_at` and `occurred_at`.
+- **Every payload carries its `object` tag** (`member`, `visit`, `record_request`, `record`, `webhook_endpoint`,
+  ...), and `webhook_endpoint.test` names its `endpoint_id`. `record.ready` gains `user_ref`.
+
+### Added: six webhook event types (preview, dark on the server)
+
+- **`pet.vaccination.due`** (`PetVaccinationDuePayload`: `vaccine` `rabies` | `dhpp`, `due_at` `YYYY-MM-DD`,
+  `stage` `due_in_14d` | `due_in_3d` | `overdue`), **`visit.rescheduled`** (`previous_scheduled_at`),
+  **`visit.reminder`** (`stage` `24h` | `30m`), **`visit.followup_sent`** (`sent_at`), **`chat.follow_up_due`**
+  (`case_ref`, `conversation_id` or null, `due_at`) and **`chat.urgency.flagged`** (`conversation_id`,
+  `message_id`, `urgency_level`; the platform writes no `pet_ref` on this one). All in
+  `EVERFUR_WEBHOOK_EVENT_TYPES` and `EverfurWebhookPayloadMap`, so `constructEvent` narrows each on `type`. Types:
+  `EverfurVaccine`, `EverfurVaccinationDueStage`, `EverfurVisitReminderStage`, `EverfurVisitStatus`,
+  `VisitRescheduledPayload`, `VisitReminderPayload`, `VisitFollowupSentPayload`, `ChatFollowUpDuePayload`,
+  `ChatUrgencyFlaggedPayload`, `RecordRequestSimpleStatus`.
+
+### Added: the consumer request fields, the request list and the step rail
+
+- **`RecordsRequestView`** gains the fields the consumer request wire carries: `wireStatus` (the server's own
+  status vocabulary, structural only), `source`, `actionNeededLabel`, `failureReason`, `failureCode`,
+  `recoveryStage`, `showClinicPhone`, `clinicName`, `clinicEmail`, `clinicPhone`, `convertedToUploadAt` and
+  `requestGroupId`. All optional on the type; the mapper always fills them.
+- **`EverfurRecords` (React Native and web) shows every request for the pet, newest first**, one card each: the
+  clinic name, the action-needed sentence in place of the status label when the request needs the member, the
+  Everfur app's step-wise rail for the request (ported from the consumer app's `requestTimeline.ts`, titles and
+  details verbatim), a tap-to-call card when the server gates the clinic phone on, and the recovery actions.
+  Exports on both records subpaths: `buildRequestTimeline`, `REQUEST_TIMELINE_TITLES`, `selectRequestList`,
+  `selectPrimaryLabel`, `selectClinicCall`, `selectRequestTitle`; types `RequestTimelineEvent`,
+  `RequestTimelineEventKey`, `RequestTimelineEventState`, `ClinicCall`.
+- `selectPopulatedBlocks` now counts any request as timeline content (the rail exists the moment a request does).
+
+### Added: several documents in one pick
+
+- **`onPickDocument` may resolve an array of `FileHandle`** (`RecordsDocumentPicker`), and the web file input is
+  `multiple`. **`uploadDocuments(requestId, files)`** on `useEverfurRecords` uploads them one at a time on one
+  request, continues past a failed file, and skips a non-PDF or oversize file with a reason before any request
+  is made; **`uploadQueue`** (`UploadQueueItem`, `UploadSkipReason`) is the row per file both surfaces render with
+  the consumer's own labels and skipped-files banner. `uploadDocument` (one file) is unchanged.
+
+### Added: recent clinics and the request group
+
+- **`recentClinics({ limit })`** on `RecordsClinicController` (`GET /widget/v1/records/clinics/recent`,
+  `RecordsRecentClinicsInput`): the clinics this member requested from before, shown as `Recently used` in both
+  clinic pickers while no search is active.
+- **`getRequestGroup(id)`** on `RecordsClinicController` (`GET /widget/v1/records/request-groups/{id}`, dark
+  behind `partner.records_multi_clinic_enabled`): the batch rollup as `RecordsRequestGroupView` (`total`,
+  `responded`, `pending`, `members` mapped like requests).
+
+### Added: the multi-clinic composer
+
+- **`EverfurClinicRequestBatch`** on `@everfur/sdk/records` and `@everfur/sdk/web/records`
+  (`EverfurClinicRequestBatchProps`, `ClinicBatchBaseProps`, `ClinicDraft`, `RegisterSignaturePng`): up to ten
+  clinics from search, the recent list or a typed name, one owner name, one signature captured at Send and
+  registered once (its id sent for every clinic), the per-clinic outcome with the consumer's sentences, then the
+  group rollup. **`useEverfurRecordsClinicBatch()`** is its client over the provider's session; the batch
+  client and its types are re-exported on both records subpaths. `CaptureRecordsSignature` may now return
+  `{ signaturePngBase64 }` as well as `{ signatureId }` (`CapturedRecordsSignature`).
+
+### Added: a built-in signature pad for React Native
+
+- **`SignaturePad`** on `@everfur/sdk/records`: draw with the finger or type the name, with no native dependency.
+  `EverfurClinicRequest` and `EverfurClinicRequestBatch` use it when the host passes no `onCaptureSignature`.
+  The drawn strokes (or the typed name, in a compact bitmap font) become a one-bit PNG through the SDK's own
+  encoder (`encodeSignaturePng`, `rasterizeStrokes`, `rasterizeTypedName`, `SIGNATURE_CANVAS` on
+  `@everfur/sdk/core`): a few hundred bytes, sent inline for one clinic and registered once
+  (`registerRnSignature`, a `data:` form part, no file-system peer) for a batch.
+
+### Added: record depth on its own subpaths (preview, dark on the server)
+
+- **`@everfur/sdk/records/depth`** and **`@everfur/sdk/web/records/depth`**: `EverfurRecordsTimeline`,
+  `EverfurRecordDepth` (lab work, visits, physical exams, visit notes) and `EverfurDocumentContributions`, with
+  `useRecordsDepthRead`, `useEverfurRecordsDepthClient`, `buildTimelineRows` and the mappers. The client is
+  **`createRecordsDepthClient`** on `@everfur/sdk/core` (`getRecordDepth`, `getTimeline`,
+  `getDocumentContributions`). Everything answers not found (or `available:false` on the record read) until
+  Everfur switches `partner.records_full_depth_enabled` on; a withheld answer renders nothing. Types:
+  `RecordDepthView`, `RecordsTimelineView`, `RecordDocumentContributionsView`, `RecordLabMarker`,
+  `RecordLabPoint`, `RecordEncounter`, `RecordClinicianNote`, `RecordClinicianNoteSection`,
+  `RecordPhysicalExam`, `RecordExamSystem`, `RecordsTimelineVisit`, `RecordsTimelineVaccine`,
+  `RecordsTimelineWeight`, `RecordsTimelineMedication`, `RecordsDepthClient`, `TimelineRow`,
+  `TimelineRowKind`, `UseRecordsDepthState`, `RecordsDepthStatus`.
+
+### Fixed: follow-up prompts follow each reply
+
+- **`suggestedPrompts` now carries the reply's own follow-ups.** The done frame's `follow_up_questions` were
+  parsed (`DoneFrame.followUpQuestions`) and then dropped, so `EverfurChat` on both hosts kept offering the
+  bootstrap prompts after every reply. After a reply, `ChatSnapshot.suggestedPrompts` (and the hook's
+  `suggestedPrompts`) is that reply's list, trimmed and de-duplicated like the bootstrap set; a reply without any
+  falls back to the bootstrap prompts. A bootstrap that settles after the first reply becomes the fallback rather
+  than replacing what the reply offered.
+
+### Added: follow-up check-ins in the thread (preview, dark on the server)
+
+- **`ChatMessage.proactiveOriginRef` and `ChatMessage.checkin`.** The platform's follow-up check-in ("How are
+  those ears doing?") arrives as an assistant message carrying `proactive_origin_ref`
+  (`checkin:<case_id>:<YYYY-MM-DD>`); history used to drop it. The raw ref stays on the message and `checkin`
+  (`ChatCheckin`: `caseId`, `answer`, `resolutionText`) names the answerable case. A ref that is not a well-formed
+  check-in leaves an ordinary message.
+- **`EverfurChat` renders a check-in as an answerable card** on React Native and the web: the question verbatim,
+  the consumer app's Better / Same / Worse answers, the in-flight answer busy with the row disabled, an answered
+  card settled with the confirmation and the server's own resolution line, a failed tap's safe `displayMessage`
+  with the row still answerable. The answer is recorded, never posted into the thread. A surface with no pet in
+  scope shows the question without answers, because the route is pet-scoped.
+- **`answerCheckin(caseId, answer, opts?)`** on `ChatController` and `useEverfurChat`: posts
+  `POST /widget/v1/pets/{pet_ref}/cases/{case_id}/checkin` (`{ response }`) for the scoped pet (or `opts.petRef`)
+  and reflects the outcome on the message. A stale, closed or foreign case is the ordinary not-found error;
+  without a pet it settles to `validationFailed` before any I/O.
+- **`createCasesRepository(auth)`** on `@everfur/sdk/client` (`CasesRepository`: `list(petRef)`,
+  `checkin(petRef, caseId, answer)`), the typed client for `GET /widget/v1/pets/{pet_ref}/cases` and the check-in
+  route, with `CHECKIN_ANSWERS`. Types: `CheckinAnswer`, `CheckinOutcome` (`case`, `ctaDeepLink`, set only on a
+  WORSE escalation), `WatchCase`. The routes are dark until Everfur switches the partner flag on; the wire shapes
+  follow the consumer `memory_watch_case_router.py` and are to be reconciled against the widget serializer.
+- **`petRef`** on `useEverfurChat`'s state: the pet the surface is scoped to, null when unscoped.
+
+### Added: unread (preview, dark on the server)
+
+- **`ChatConversation.unreadCount`** from the list's `unread_message_count` (null when the wire does not carry
+  it, which is not "all read"), **`ChatSnapshot.unreadCount`** for the active thread (the count the list last
+  reported for it, 0 once read), and **`markRead()`** on `ChatController` and `useEverfurChat`:
+  `POST /widget/v1/conversations/{id}/read`, idempotent, zeroes the count; a missing or foreign thread is the
+  ordinary not-found error. `resumeConversation` marks a thread read when the list had reported it unread; a
+  thread the list never named sends no receipt.
+
+### Added: server pet writes (preview, dark on the server)
+
+- **`upsertPartnerPet`, `updatePartnerPet` and `deletePartnerPet`** on `@everfur/sdk/server`, next to
+  `mintPartnerSession`: create, change and delete a member's pet profile from your backend with your secret key
+  (`PUT`, `PATCH` and `DELETE /partners/members/{user_ref}/pets/{pet_ref}`), no user session needed.
+  `upsertPartnerPet` creates the member on first use; the other two never do. A restricted key needs
+  `pets.profile.update` (upsert, update) or `pets.profile.delete`. Every call answers not found until Everfur
+  switches the server pet API on. Types: `PartnerServerClient`, `PartnerPetTarget`, `PartnerPetProfile`,
+  `PartnerPet`.
+
+### Added: multi-clinic records request
+
+- **`createRecordsClinicBatchClient(deps)`** on `@everfur/sdk/core`: the typed client for
+  `POST /widget/v1/records/clinic-requests/batch`, one signed owner action for one pet and 1 to 10 clinics,
+  each with its own clinic, signature and idempotency key, answered per clinic (`created` with the mapped
+  request, or `failureCode` and `failureReason`) under a shared `requestGroupId`. Published on `core` rather
+  than the records subpaths, whose closure is at its size budget; it rides the same auth, funnel and error
+  policy as `useEverfurRecordsClinic`. The route is dark until Everfur switches
+  `partner.records_multi_clinic_enabled` on. Types: `CreateClinicRequestBatchInput`, `RecordsClinicBatchItem`,
+  `RecordsClinicBatch`, `RecordsClinicBatchResult`, `RecordsClinicBatchClient`, `RECORDS_CLINIC_BATCH_MAX`.
+
+### Added: React Native records upload
+
+- **`createRnRecordsUploadTransport(options?)`** on the root `@everfur/sdk`: the React Native `UploadTransport`
+  for records. It posts the picked document from its local file `uri` to the presigned upload with `fetch` and
+  `FormData` (`{ uri, name, type }`), with no native dependency. Pass it as `uploadTransport` on `EverfurConfig`.
+  It is exported from the root rather than `@everfur/sdk/records` because that subpath's bundle budget has no
+  room for it. `onProgress` reports completion only.
+- **`EverfurRecords` (`@everfur/sdk/records`) takes an `uploadTransport` prop**, overriding the config one for
+  that surface. `useEverfurRecords` takes the same `uploadTransport` option. The upload control is enabled
+  only when both `onPickDocument` and a transport are wired.
+- **`RecordsDocumentPicker`** (type, on `@everfur/sdk` and `@everfur/sdk/records`): the contract
+  `onPickDocument` implements with the host app's own picker. Resolve `null` on cancel, otherwise a
+  `FileHandle` with the local `uri`, `mimeType: 'application/pdf'` and `sizeBytes`. The SDK does not depend on
+  a document picker.
+
+### Added: records test mode (sandbox tenants only)
+
+- **`useEverfurRecordsSandbox()`** on `@everfur/sdk/testing/rn` and `@everfur/sdk/testing/web` returns a
+  `RecordsSandboxController`: `simulateClinicReply(requestId, 'records' | 'no_records' | 'declined')` and
+  `publishSampleRecord(requestId)`, each settling to `{ result: 'applied' | 'already_applied' | 'not_applicable',
+  request }`. They call `POST /widget/v1/records/sandbox/requests/{request_id}/clinic-reply` and
+  `.../publish-sample`, which answer only a sandbox tenant's signed user for that user's own request; anywhere
+  else the call settles to the ordinary not-found error. Types: `RecordsSandboxController`,
+  `RecordsSandboxClinicReply`, `RecordsSandboxResult`, `RecordsSandboxActionResult`. Kept off the production
+  records entries.
+
+### Added: vet visit test mode (sandbox tenants only)
+
+- **`useEverfurVetVisitSandbox()`** on `@everfur/sdk/testing/rn` and `@everfur/sdk/testing/web` returns a
+  `VetVisitSandboxController`: `createVisit(petRef)` and `advanceVisit(visitRef, 'booked' | 'cancelled' |
+  'completed' | 'no_show')`, each settling to `{ result: 'applied' | 'already_applied' | 'not_applicable', visit }`.
+  They call `POST /widget/v1/televet/sandbox/visits` and `.../visits/{visit_ref}/advance`, which answer only a
+  sandbox tenant's signed user for that user's own pets and visits; anywhere else the call settles to the ordinary
+  not-found error. A simulated visit has no payment, vet or appointment, and sends the real `visit.*` webhooks
+  with `livemode: false`. Types: `VetVisitSandboxController`, `VetVisitSandboxStatus`, `VetVisitSandboxResult`,
+  `VetVisitSandboxVisit`, `VetVisitSandboxActionResult`. Kept off the production televet entries.
+
+### Added: pet update, pet delete and user erasure
+
+- **`updatePet(pet, patch)`**, **`deletePet(pet)`** and **`eraseUserData()`** on the `useEverfur()` handle
+  (and `EverfurRuntime`), next to `registerPet`, and on `PetsRepository` (`@everfur/sdk/client`).
+  `updatePet` sends `PATCH /widget/v1/pets/{pet_ref}`: an omitted field is unchanged and `null` clears it
+  (new type `PetProfilePatch`); an empty change is refused before the request. `deletePet` sends
+  `DELETE /widget/v1/pets/{pet_ref}`. `eraseUserData` sends `DELETE /widget/v1/me`, once per call with a
+  60 second deadline; a failure (503) is retryable and a repeat call resumes the erasure. It does not sign the
+  user out. An unknown pet settles to the not-found error.
+
+### Changed: version
+
+- `package.json` and `SDK_VERSION` (the `X-Everfur-SDK-Version` header) are `0.3.0`.
+
+### Changed: potentially breaking for exhaustive switches
+
+- `RecordsRequestStatus` gains `'requested'` and `'awaiting_clinic'`, the two clinic-request stages before a
+  document arrives. The wire change is additive, but a host `switch` that is exhaustive over the old seven
+  members stops compiling (or falls through at runtime). Give such a switch a default branch.
+- `CapabilityName` gains `'recordsClinic'` (see below). The same note applies to an exhaustive switch over it.
+
+### Added: vet visit return, state check and Chat entry (preview, dark on the server)
+
+- `useVetVisit` and `VetVisitButton` (`@everfur/sdk/televet`, `@everfur/sdk/web/televet`) take three optional
+  settings. Each is off on the Everfur side until Everfur switches it on for your tenant, and none changes a
+  visit started without it.
+  - `returnTo`: the key of a return destination your tenant registered with Everfur (never a URL). The handoff
+    then carries an opaque `flowId`, `open()` settles with `{ opened: true, flowId }` and `onOpened` receives
+    it. `parseVetVisitReturn(url)` reads the flow id back off your destination URL and returns nothing about
+    the visit, the pet or the account.
+  - `usState`: the user's US state. `available` (and the button) waits for Everfur to confirm a visit is
+    available there. The answer is only available or not.
+  - `entry: 'chat'`: the vet entry inside Chat, for the pet the chat is about (`petRef` is required). It is the
+    same button, label, hosted visit and checkout, shown only while Everfur has the Chat entry switched on.
+    Nothing is written back into the chat.
+- `VetVisitController.createHandoff(petRef, options?)` gains the optional `options`, and the interface gains
+  the optional `checkAvailability(state)` and `chatEntryOpen()`. An injected controller without them keeps
+  working; wherever the hook needs their answer it treats the entry as unavailable.
+- `onOpened` now receives `flowId: string | null`. A callback that takes no argument is unaffected.
+- Types `VetVisitAvailability`, `VetVisitEntry`, `VetVisitHandoffOptions` and `VetVisitReturn`, and
+  `VetVisitHandoff.flowId`, are exported from both televet subpaths.
+
+### Added: chat history
+
+- `useEverfurChat` and the chat controller gain `listConversations(options?)` (optionally filtered by
+  `petRef`), `getMessages(id, options?)`, `resumeConversation(id)` and `loadOlderMessages()`, plus
+  `historyCursor` and `isLoadingHistory`. They call the existing `GET /widget/v1/conversations` and
+  `GET /widget/v1/conversations/{id}/messages` routes. Cursors are opaque and older pages load backwards.
+- A supplied `conversationId` now loads that thread instead of starting from an empty transcript.
+- The prebuilt React Native and web chat surfaces gain a history panel. Nothing is fetched until it is opened.
+  On the web it is a dialog that keeps Tab inside it and returns focus to its trigger when it closes.
+- Switching the user, the pet or the thread hides the previous transcript on the same render, and late
+  results or callbacks from the previous scope are dropped. Unsent drafts are kept per user, pet and thread.
+- The urgency of the final assistant reply, and of saved history, is shown with the existing consumer labels.
+  It never opens a vet visit or an emergency action by itself.
+- Types `ChatConversation`, `ChatConversationListOptions`, `ChatConversationPage`, `ChatHistoryOptions` and
+  `ChatMessagePage` are exported from the root, `@everfur/sdk/chat` and `@everfur/sdk/web`.
+
+### Added: clinic record requests and request recovery (preview)
+
+- **`EverfurClinicRequest`** (`@everfur/sdk/records` and `@everfur/sdk/web/records`) and
+  **`useEverfurRecordsClinic`** (a `RecordsClinicController`): search the clinic directory, show the
+  authorization text and version the server serves, and send a signed request to a clinic for one pet.
+  Nothing is sent on mount, and the owner signs only after pressing Send. The web surface draws or types the
+  signature and uploads it through the two-phase signature upload; React Native asks the host's
+  `onCaptureSignature` for a registered signature id, so no native dependency is added. One request keeps
+  one idempotency key across uncertain retries, and non-idempotent writes are never retried automatically.
+- **New capability `recordsClinic`** (`records.clinic.create`). Contacting a clinic is a separate grant from
+  owner uploads, so the clinic form renders the deliberate off state unless it is granted, while
+  `EverfurRecords` keeps following `records`.
+- Request views gain the server's own recovery decisions: `canRetrySend`, `canUpdateClinicEmail`,
+  `canRevoke` and `canConvertToUpload`, with `dispatchStatus`, `reminderCount`, `lastReminderAt`,
+  `waitingExpectation`, `simpleStatus` and `simpleStatusDetail`. The prebuilt records surfaces offer an
+  action only when the server allows it. After a request is converted to an upload, the next upload fills
+  that same request.
+
+### Fixed and changed: partner events inbound (preview)
+
+- **Fixed:** `sendPartnerEvent` posts to `POST {apiBaseUrl}/partners/events`, the route the platform serves. It
+  used `/partner-events/v1/inbound`, which does not exist.
+- **Changed (breaking for this preview API):** `PartnerInboundEvent` is a union keyed on `type`. Each type's
+  `data` is typed to the platform's closed schema through `PartnerInboundEventOf`, `PartnerInboundEventDataMap`
+  and the seven `...Data` interfaces, and `schemaVersion` is `1`.
+- **Changed:** `sendPartnerEvent` throws `EverfurConfigError` before sending for an idempotency key that is not
+  1 to 255 visible ASCII characters, a secret key that is not `sk_partner_` or `rk_partner_`, a pet event without
+  `petRef` or a member event with one, a `petRef` that breaks the user_ref rule, an `occurredAt` string without an
+  explicit offset, `data` that cannot be serialized, or a body over 32 KB.
+- **Added:** `PartnerEventReceipt` carries `type`, `schemaVersion`, `userRef`, `petRef`, `occurredAt` and
+  `livemode`.
+- Docs: chapter 15 documents the served inbound route, each type's fields, the receipt, every error code with
+  its normalized `result.error.code`, and the retry hazard of omitting the idempotency key. It also corrects
+  the outbound list path to `GET /api/v1/partners/events`. Chapter 09 gains "Records in Chat".
+
+### Added: error reason codes
+
+- `EverfurError.reasonCode` (optional): the server's stable `reason_code` sub-reason when a response carries one,
+  for example `pet_not_registered` or `species_unsupported` on the records routes. Safe to branch on. Only a
+  lowercase snake_case token is kept.
+
+### Changed
+
+- The contract snapshot is re-vendored from the platform's public projection (digest `008a6b67...`). The
+  wire codes `insufficientCapability`, `idempotency_key_reused`, `idempotency_key_invalid`,
+  `idempotency_key_required`, `payload_too_large`, `event_cursor_invalid`, `event_filter_invalid`,
+  `event_payload_invalid` and `event_type_unknown` now fold to `accessDenied`, `idempotencyConflict` or
+  `validationFailed`. `televet.visit.create` is declared by the contract, so the SDK no longer carries it
+  as a pending key.
+- Published bundles are minified with function and class names and legal comments kept. Source maps are
+  still built privately and still excluded from the package.
+
+### Added: vet visits (dark)
+
+- **`@everfur/sdk/web/televet`** and **`@everfur/sdk/televet`**: `VetVisitButton`, `useVetVisit` and
+  `vetVisitErrorReasonOf`. A tap mints a single-use handoff (`POST /widget/v1/televet/handoffs`, signed
+  session only) and opens the hosted Everfur visit: a tab opened synchronously inside the click on the web,
+  the system browser (or a host `openUrl`) on React Native. No retry, and the URL never reaches telemetry.
+  Behind the new `televet` capability (`televet.visit.create`), which no tenant is granted yet, so the button
+  renders nothing; it also renders nothing without a `user`, since the route refuses a publishable-key caller.
+  The web entry is separate from `@everfur/sdk/web`, which carries none of it.
+- `CapabilityName` gains `'televet'`. `requires('televet')` names `televet.visit.create`, which the public
+  contract now declares.
+- Docs chapter 16, vet visits (draft for owner approval).
+
+### Added: records in frame mode, and the records web docs
+
+- **`surface: 'records'` on `Everfur.init`** (and `data-surface="records"` on the script tag) opens the
+  records surface in frame mode. It has its own frame document and bundle on the CDN (`records.html`,
+  `records-frame.js`, beside `frame.html` and `frame.js` of the same build): the same fence, the same
+  private channel and the same token channel, with the upload host (the media bucket the API presigns to)
+  in the document's `connect-src` beside the API. The chat document keeps its narrower policy and carries
+  none of the records code (its bundle ceiling is unchanged). `consentVersion` (`data-consent-version`)
+  travels with the init so the frame can render the Allow control; `activePet` names the pet whose
+  records the frame shows, and `setActivePet` moves it. Without a user the frame shows the sign-in state,
+  without a pet the empty state, and until Everfur enables records for the account the off-state; none of
+  these issues a records request.
+- **Protocol:** `ef:init` gains optional `surface` (`chat` or `records`; absent means chat) and
+  `consentVersion`; a frame document asked for the surface it does not serve refuses with the new
+  `surfaceMismatch` code before the fence is asked, and the loader treats it as fail-closed (the frame is
+  hidden). The protocol version stays 1: loader and frames ship as one build.
+- **CDN build:** `EVERFUR_UPLOAD_ORIGIN` (`scripts/cdn-build-env.mjs`) names the one bucket origin the
+  records document may POST to; production's by default, the staging publisher sets staging's. It must be
+  an exact https origin, never a wildcard or the bare S3 service host. Both publish workflows verify and
+  publish the two new artifacts.
+- Docs: chapter 09 gains the web section, chapter 13 the `@everfur/sdk/web/records` in-page section and
+  the records frame snippet, and "React Native only" no longer covers records. `examples/minimal-web-records.tsx`
+  is the copy-paste shape, type-checked by `docs:check`. The prod CDN publish of the records document waits
+  for the media bucket CORS rule for `sdk.everfur.com` (EFBackend INFRA-1); staging is unaffected.
+
+### Added: records on the web (preview)
+
+- **`@everfur/sdk/web/records`**, an opt-in subpath: `EverfurRecords` (the four-state DOM surface: consent,
+  upload, request timeline, record view), `useEverfurRecords` (the hook React Native already uses),
+  `createWebRecordsUploadTransport` for `EverfurConfig.uploadTransport`, and `fileToHandle` / `pickDocument`.
+  Its own entry so a chat-only page downloads none of it. The subpath maps the `react-native` condition to
+  null like `./web`. The surface renders the gate's off state until Everfur enables records for the account,
+  and needs a signed-in user. Its upload control is disabled until the host sets
+  `uploadTransport: createWebRecordsUploadTransport()` on the config, and it comes back after a failed
+  upload so the next pick fills the same request rather than creating a second one.
+- **`FileHandle.blob`** (optional, additive): the bytes of a browser `File`. The type of an uploaded
+  document is read from its first bytes (`%PDF-`), not from the file name, so a renamed image is refused
+  before any request is made. No object URL is created for a picked document.
+
+### Added: partner events on `@everfur/sdk/server/events` (preview)
+
+- **`constructEvent(payload, signatureHeader, secrets, options?)`** verifies an Everfur webhook delivery and
+  returns the typed event. It checks the `Everfur-Signature: t=<unix>,v1=<hex>` header (HMAC-SHA256 over
+  `t.` plus the raw body, keyed by the whole `whsec_` secret) in constant time, accepts any `v1` against any
+  of several secrets so a rotation never drops a delivery, and refuses a timestamp more than 300 seconds off
+  in either direction. Refusals throw `EverfurWebhookVerificationError` with a typed `code`
+  (`malformed_header`, `timestamp_outside_tolerance`, `no_matching_signature`, `malformed_payload`); a call
+  that can never succeed (no secret, a parsed body) throws `EverfurConfigError`. Pinned by the platform's own
+  fixed signature vectors. `generateTestSignatureHeader` signs a body the same way for a partner's tests.
+- **Typed events:** `EverfurWebhookEvent` covers `member.linked`, `member.unlinked`, `visit.booked`,
+  `visit.cancelled`, `visit.completed`, `visit.no_show` (keyed by `partner_visit_ref`), `record_request.updated`, `record.ready` and
+  `webhook_endpoint.test`; `isEverfurWebhookEvent` separates a type added after this version shipped. Payload
+  fields are preview.
+- **`sendPartnerEvent(client, event, idempotencyKey?)`** (preview) sends one event to
+  `POST /partner-events/v1/inbound` with the partner secret key and an `Idempotency-Key` (generated and
+  returned when omitted), and settles to an `EverfurResult`. The route is not served yet.
+- **New subpath `@everfur/sdk/server/events`.** Server-only and Node-only (it loads Node's `crypto`), blocked
+  for React Native like `./server`. `@everfur/sdk/server` is unchanged and still loads no `node:` built-in, so
+  `mintPartnerSession` keeps running on edge runtimes.
+- Docs: new chapter 15, Events and webhooks; chapter 09 no longer says polling is the only mechanism forever.
+
+## [0.2.0] - 2026-09-14
+
+### Added: the web
+
+- **`@everfur/sdk/web`**, the browser entry: `EverfurProvider`, `CapabilityGate`, `EverfurChat`,
+  `useEverfurChat` and the theme hook, rendered with `react-dom` (peer, 18 or newer). The provider
+  lifecycle, the context, the theme resolution and the headless chat hook are one host-agnostic React layer
+  shared with React Native; the DOM leaves are new. Styling is inline from the theme tokens through the
+  CSSOM, so a strict `style-src` on the host page cannot strip it and a host stylesheet cannot collide with
+  it; motion runs on the Web Animations API and goes static under `prefers-reduced-motion`; brightness
+  follows `prefers-color-scheme`. The subpath withholds the `react-native` export condition and ships a
+  guard that throws on a resolver that ignores conditions, the way `./server` does.
+- **The chat surface on the DOM.** Enter sends and Shift+Enter breaks the line (an IME Enter passes
+  through); the transcript stays pinned to the newest message unless the reader scrolled up; a tapped
+  prompt returns focus to the composer; one persistent status region announces "Assistant is typing" and
+  then the settled reply once (the transcript is deliberately not a live region); errors are alerts; every
+  control is 44 px and keeps the UA focus ring. Assistant replies render as text nodes with `strong` /
+  `em` / `code` runs, never as HTML.
+- **Frame mode.** A React-free loader (`https://sdk.everfur.com/v1/everfur.js`, 2.5 KB gzip, the
+  `Everfur` global, an async pre-load queue and data-attribute auto-init) puts the surface in an iframe on
+  `sdk.everfur.com`. The frame refuses to initialise unless the Everfur API confirms that the embedding
+  page's origin is registered for the key the page names (`GET /widget/v1/embed-config`, exact match,
+  asked of the API and never read from the page); it fails closed when the API cannot be asked. After the
+  handshake, configuration, commands and short-lived session tokens travel on a private `MessageChannel`
+  only the loader holds, so other scripts on the page can neither read the conversation nor speak to the
+  frame; the frame never holds a partner secret, and the host's `getToken` answers the frame's token
+  requests. The frame document carries its own Content Security Policy and is never blank (a waiting card
+  from first paint). Requires an API with the embed-config route. `npm run build:cdn` emits the artifacts;
+  the release workflow publishes them to `/<version>/` (immutable) and `/v1/` (the channel) after every
+  gate, behind a reviewed environment. `sdk-staging.everfur.com` tracks `main`: the same artifacts built
+  for staging (the frame talks to the staging API, the loader opens the staging frame), published by
+  `publish-staging.yml` on every push. Chapter 14 covers a Shopify storefront: the Everfur app's theme
+  block and Shopify vouching for the signed-in customer through the app proxy.
+- `X-Everfur-SDK-Platform` names the host (`react-native` | `web`) on every request; the platform is a
+  facade seam, never partner-configurable.
+- `@everfur/sdk/testing/web`: `useEverfurTestEntitlements` for a web harness (the twin of `./testing/rn`,
+  now one shared hook); withheld from React Native bundles like `./web`.
+- `examples/minimal-web.tsx` and `examples/frame-embed.html`, both pinned by the build; chapter
+  `docs/partner-integration/13-WEB-INTEGRATION.md`; `RELEASING.md` and `.github/workflows/release.yml`
+  (npm and the CDN, from one tag, after every gate).
+
+### Changed
+
+- `react-native` and `react-native-safe-area-context` are declared **optional** peers (`react-dom` joins them),
+  so npm 7+ no longer installs React Native into a web project that installs the package. The React Native
+  entry points still need both. **Upgrading a React Native app from 0.1.x:** if `react-native-safe-area-context`
+  is not in your app's own `package.json` (npm installed it for you as a required peer), add it:
+  `npx expo install react-native-safe-area-context` in an Expo project, `npm i react-native-safe-area-context`
+  otherwise. Until you do, Metro cannot resolve it. An app that followed the 0.1.x quickstart already lists it.
+- **Potentially breaking: "powered by everfur" is server-only.** `hide_powered_by` / `hidePoweredBy` in the
+  client `theme` prop is ignored; only the server branding (which carries the partner plan's decision) can
+  hide the attribution.
+- Server branding: the chat renders the branding `logo_url` above the transcript (web and React Native), and
+  the web SDK loads the branding `font_url` when it is an allowlisted woff2 on `sdk.everfur.com` or
+  `sdk-staging.everfur.com`. The parser reads four more keys: `surface_style` (`white` / `cream` / `subtle`),
+  `radius_scale` (`sharp` / `default` / `round`), `primary_color_dark` and `accent_color_dark` (used on the
+  dark palette). A server `brightness` no longer drops the client `theme` prop's other fields. The frame
+  document's policy admits fonts from its own origin (`font-src 'self'`).
+
+### Fixed
+
+- User message bubbles draw their text in the foreground computed for the primary fill they are painted with
+  (`onPrimary`), not the accent's, so a branding whose primary and accent differ stays legible.
+
+- The contract error table knows the session mints' `authRejected` (the non-retryable 401, never a token
+  refresh) and `rateLimited` (429) by name; the vendored registry and generated contract are synced to the
+  platform, where they had been added, instead of both folding to `unknown`.
+- `SDK_VERSION` (the `X-Everfur-SDK-Version` header) said `0.1.0` while `0.1.1` shipped; a test now pins it
+  to `package.json`.
+- The frozen clinical disclaimer copy lives once (`src/react/disclaimer/copy.ts`) and both host bands import
+  it; the coverage guard pins that no band carries wording of its own.
+
+### Internal
+
+- `src/react/` is the host-agnostic React layer (provider core with `HostSeams`, context, theme core,
+  `useCapability`, `useEverfurChat`); `src/rn/` and `src/web/` are thin facades over it. Layer boundaries
+  are enforced by lint (`react` may not import a host; `web` may not import `react-native`; `rn` may not
+  import `web`) and by the supply-chain suites (host isolation, `./web` blocked at resolve time for RN).
+
 ## [0.1.1] - 2026-09-03
 
-### Fixed — privacy
+### Fixed: privacy
 
 - **An anonymous logout left mounted surfaces on the previous visitor's session.** `logout()` from an
   already-anonymous state compared `userRef` to `userRef`, saw null-to-null, and took its same-identity
@@ -23,7 +722,7 @@ changes that has not been earned by any production integration yet.
 
 ## [0.1.0] - 2026-08-23
 
-### Fixed — correctness
+### Fixed: correctness
 
 - **Anonymous mode could never send a message.** The SDK never sent `x-everfur-session-id`, and the server
   derives the anonymous identity from it, minting a fresh one per request. A conversation was created as one
@@ -46,7 +745,7 @@ changes that has not been earned by any production integration yet.
 - Neither `POST /conversations` nor the SSE send is auto-replayed: the widget lane does not read
   `Idempotency-Key`, so a retry was a second row, not a dedup.
 
-### Fixed — security
+### Fixed: security
 
 - **`@everfur/sdk/server` is no longer resolvable from a React Native bundle.** The subpath merely omitted a
   `react-native` export condition, which is not a block; it now maps to `null`. This is the module carrying
@@ -69,7 +768,7 @@ changes that has not been earned by any production integration yet.
   exported and documented while reaching no request in the SDK. Both narrow only: neither can make a spent
   daily quota retryable nor resurrect a terminal code, and an SDK per-call cap still outranks them.
 
-### Changed — potentially breaking
+### Changed: potentially breaking
 
 - **`DisabledLevel` gained an `sdk_config` member.** A consumer with an exhaustive `switch` over that union
   will no longer compile. This is the one deliberate widening in this set.