@marktiderman/genesis-native 0.2.0 → 0.4.0

package/README.md

@@ -6,7 +6,7 @@ everything above your screens, so the root layout is a few lines:
 ```tsx
 // app/_layout.tsx
 import * as SplashScreen from "expo-splash-screen";
-import { KeyboardAwareScrollView } from "react-native-keyboard-controller";
+import { KeyboardAwareScrollView, KeyboardProvider } from "react-native-keyboard-controller";
 import { Stack, router } from "expo-router";
 import { GenesisNativeApp } from "@marktiderman/genesis-native";
 import { brand, supabase, steps, persist, linkHold } from "../lib/app";
@@ -16,7 +16,7 @@ SplashScreen.preventAutoHideAsync();
 export default function RootLayout() {
   return (
     <GenesisNativeApp brand={brand} supabase={supabase} splash={SplashScreen} steps={steps} persist={persist}
-      keyboardScroll={KeyboardAwareScrollView} links={{ hold: linkHold, onRelease: (path) => router.replace(path) }}>
+      keyboardProvider={KeyboardProvider} keyboardScroll={KeyboardAwareScrollView} links={{ hold: linkHold, onRelease: (path) => router.replace(path) }}>
       <Stack />
     </GenesisNativeApp>
   );
@@ -36,8 +36,21 @@ From the outside in:
    `fatal` slot itself throws, this is what shows, and "Try again" starts over.
 2. **Theme**: `GenesisThemeProvider` with `syncNativeAppearance` on, so the
    root owns the platform color scheme.
-3. **Keyboard**: `KeyboardScrollProvider` with your `keyboardScroll`, so
-   Genesis form screens scroll the focused field into view.
+3. **Keyboard**: your `keyboardProvider` (react-native-keyboard-controller's
+   `KeyboardProvider`), mounted once, then `KeyboardScrollProvider` with your
+   `keyboardScroll`, so Genesis form screens scroll the focused field into
+   view. The scroll view does nothing without the provider: give both. In
+   development, `keyboardScroll` without `keyboardProvider` logs an error.
+   `keyboardToolbar` (`KeyboardToolbar`) adds the previous / next / done bar
+   above the keyboard on Genesis's form layouts (`AuthScreen`,
+   `SettingsSubPage`); it needs `keyboardScroll`, and logs an error in
+   development without it.
+   Then `modules`, the optional native modules your app installed
+   (`GenesisModulesProvider` from `@marktiderman/genesis-ui-native`: FlashList,
+   expo-image, Reanimated, expo-glass-effect, expo-symbols, a lucide icon
+   set, the @expo/ui date picker). Each one you leave out falls back to plain
+   React Native. Read once. The update banner is Liquid Glass on iOS 26 when
+   `modules.glass` is given. See that package's README.
 4. **Data**: `GenesisProvider` over `createSupabaseProvider(supabase)` (or
    your `provider`) and the shell's QueryClient.
 5. **Boot**: your `steps` (wipe a session left by a reinstall, hydrate stores,
@@ -55,16 +68,21 @@ From the outside in:
    while the fatal screen is up goes to React Native's default handler, which
    ends the app so it restarts clean. Unhandled promise rejections never reach
    `ErrorUtils` in React Native, so on Hermes the shell installs its rejection
-   tracker (`rejectionTracker`, `null` turns it off). `onError` gets all of
-   these, for reporting.
+   tracker (`rejectionTracker`, `null` turns it off). Every block's `onError`
+   (the observability block's, which reports to Sentry) and then your
+   `onError` get all of these; a reporter that throws is ignored.
 7. **Session, offline included**: `useSession()` is `loading`, `signedIn` or
    `signedOut`, with `userId` and `offline`. Offline with an expired access
    token, Supabase's `getSession()` can spend about 30 seconds on a refresh
    and then fail; the shell waits at most `sessionWaitMs` (5 s) and on a
    timeout or a network error carries on with the session stored on the
    phone (`offline: true`). Supabase's own events correct it once online.
-8. **Query**: `networkMode: "always"` so offline queries fail instead of
-   hanging. With `persist`, the query-key roots you list are saved to the
+8. **Query**: `networkMode: "offlineFirst"`: a query or mutation runs once,
+   then its retries pause while NetInfo says offline and continue when the
+   network is back, and stale queries refetch on reconnect. Offline, saved
+   data stays on screen; a query with nothing saved is `pending` with
+   `isPaused` (show "offline", not a spinner); a mutation fails at once (no
+   retries by default). With `persist`, the query-key roots you list are saved to the
    phone for 24 hours (`maxAge`), discarded when `buster` (your app version)
    changes, and **scoped to the signed-in user**: the user id is part of what
    is saved, a cache saved for anyone else is deleted instead of restored, and
@@ -116,6 +134,31 @@ From the outside in:
     A path the map doesn't know, or one with a `.` or `..` segment, goes to
     `"/"` and `onUnknown`; `ignore` patterns return `null` so the router
     leaves them alone (an auth callback).
+11. **Sheets**: `NativeSheet` (what's new, the push prompt) is React Native's
+    own `Modal` and needs nothing above it: the system page sheet on iOS, a
+    bottom panel on Android. To use `@gorhom/bottom-sheet` instead (snap
+    points), pass it: `import * as BottomSheet from "@gorhom/bottom-sheet"`,
+    then `bottomSheet={BottomSheet}`. The shell mounts its
+    `BottomSheetModalProvider` inside the data, session and blocks providers,
+    so sheet content can read them. The library also needs gesture-handler's
+    `GestureHandlerRootView` around the app and Reanimated set up; without
+    them it throws when a sheet opens.
+12. **Toasts**: `NativeToastProvider` is mounted around the screens, so
+    `useToast()` from genesis-ui-native works on any screen. Toasts show at
+    the top (a bottom toast would sit on a tab bar), below the safe area;
+    `toast={{ position: "bottom" }}` moves them, and `toast={null}` leaves
+    the provider to the app (one the app mounts inside the shell is the one
+    `useToast()` finds either way).
+13. **Development warnings**: in React Native 0.88 the first `console.warn`
+    pins LogBox's "Open debugger to view warnings." pill over the bottom of
+    the screen, where a native tab bar's first tap lands on it. The warnings
+    the app can't act on (React Native's `ImageBackground` deprecation, set
+    off by NativeWind's runtime) are kept out by
+    `ignoreKnownDependencyWarnings(LogBox, __DEV__)` from
+    `@marktiderman/genesis-native/dev-warnings`, called from the app's entry
+    file before `require("expo-router/entry")` (it has to run before any
+    library loads; see the starter's `index.ts`). It removes that trigger
+    only: any other warning, the app's own included, still shows the pill.
 
 ## Slots
 
@@ -131,6 +174,7 @@ From the outside in:
 | `maintenance` | `MaintenanceScreen` (with `updates`) | `{ message, retry, retrying }` |
 | `updateBanner` | `UpdateBanner` (with `updates`) | `{ reload, dismiss, canReload, blocked, reloading }` |
 | `whatsNew` | `WhatsNewSheet` (with `updates`) | `{ notes, version, dismiss }` |
+| `devtoolsFeedback` | nothing (in the devtools overlay; the support block fills it) | `{ debugInfo, close }` (`close()` resolves once the sheet has slid away) |
 
 The last four render only when the `updates` prop is given. Ejecting a
 blocking one (`forceUpgrade: null`, `maintenance: null`) shows your screens
@@ -230,6 +274,419 @@ imported: without `updates` there is no banner and no channel switching;
 without `application` nothing is forced and no notes show. The banner uses
 `react-native-safe-area-context`, a peer (genesis-ui-native needs it too).
 
+## Observability: errors, breadcrumbs, events, timings
+
+`@marktiderman/genesis-native/observability` is the observability block. It is vendor-neutral:
+everything goes through sinks, and the Sentry one is an adapter.
+
+```ts
+// lib/observability.ts: imported first by the module that builds GenesisNativeApp's props
+import * as Sentry from "@sentry/react-native";
+import * as Application from "expo-application";
+import * as Updates from "expo-updates";
+import { useSegments } from "expo-router";
+import { Platform } from "react-native";
+import { consoleSink, createObservability, defineEvents, sentrySink } from "@marktiderman/genesis-native/observability";
+import { versionSignature } from "@marktiderman/genesis-native/updates";
+
+export const events = defineEvents({
+  "auth.signed_in": { method: ["email", "apple"] },
+  "checkin.saved": { mood: "number", first: "boolean" },
+});
+
+export const observability = createObservability({
+  events,
+  useSegments,
+  sinks: [
+    __DEV__ && consoleSink(),
+    sentrySink(Sentry, {
+      dsn: process.env.EXPO_PUBLIC_SENTRY_DSN,
+      signature: versionSignature({ application: Application, updates: Updates, platform: Platform.OS }),
+      applicationId: Application.applicationId,
+    }),
+  ],
+});
+
+// app/_layout.tsx
+function RootLayout() {
+  return <GenesisNativeApp {...shell} blocks={[observability]}>…</GenesisNativeApp>;
+}
+export default observability.wrap(RootLayout); // Sentry.wrap: touch and profiler boundaries
+```
+
+- **One error path.** Every error the shell catches (a render error in either boundary, a global
+  error, a failed boot, an unhandled rejection) goes to the block's `onError` and then to yours.
+  A sink that throws is reported to `onProblem` and never stops the other sinks or the fatal screen.
+  `observability.captureError(error, { source: "sync" })` reports one you caught yourself.
+- **Init order.** `sentrySink` runs `Sentry.init` when it is called, so build the block at module
+  scope, in a module the root layout imports before anything else: errors while the app's modules
+  load are caught too. A second call in the same process (Fast Refresh) reuses the client.
+  Sentry's own global handler stays installed for errors before the shell mounts; once the shell
+  is up, its handler runs first and hands the same `Error` object on, which Sentry's deduplication
+  (`__sentry_captured__`) sends once. A thrown value that isn't an `Error` can be reported twice.
+- **PII is scrubbed on the device, by default.** Emails (percent-encoded too), phone numbers,
+  JWTs (Supabase access tokens and keys), Supabase `sb_secret_` / `sb_publishable_` keys, bearer
+  tokens, tokens in query strings, row values in PostgreSQL errors (`Failing row contains (…)`)
+  and long hex secrets are replaced in every string; values under keys naming a secret or a
+  contact detail (`authorization`, `cookie`, `apikey`, anything with `token`, `secret`, `email` or
+  `phone` in it) are replaced whole; every URL (web, deep link or path) loses its query and
+  fragment (PostgREST filters carry record ids); request bodies, cookies and PostgREST `details`
+  are dropped. Strings are cut at 4 KB first, so a huge log can't stall the JS thread. Sentry's
+  own ids (`event_id`, `trace_id`, `debug_id`, …) and processing metadata are left alone, since
+  its envelope is built from them. Sentry gets the scrubber in `beforeSend`,
+  `beforeSendTransaction`, `beforeSendSpan`, `beforeBreadcrumb`, `beforeSendLog` and
+  `beforeSendMetric` (yours run after, on the scrubbed value), plus `sendDefaultPii: false`, no
+  screenshots, view hierarchy or accessibility labels, and touch breadcrumbs without the touched
+  element's label. The user is an id only. If scrubbing throws, the event is dropped. Other sinks
+  get scrubbed errors, breadcrumbs and tags.
+- **What it can't catch:** a person's name in free text (an error message that says "Jane
+  Doe"), and native crashes, which sentry-cocoa and sentry-android build without these
+  JavaScript hooks. Keep names out of messages; use ids.
+- **Typed analytics.** `observability.track("auth.signed_in", { method: "apple" })` is checked
+  against `defineEvents` at compile time and at run time. A prop is a closed list of strings, a
+  number or a boolean, never free text; an unknown event, prop or value is dropped and reported.
+- **Routes.** With `useSegments` from expo-router, each route change leaves a `navigation`
+  breadcrumb and a `route.time_on_screen` timing for the route left, by route pattern
+  (`/(app)/clients/[id]`), never the values in it. Sentry's `expoRouterIntegration` (on by
+  default in `sentrySink`) records its own navigation spans and time to initial display, so the
+  Sentry sink skips the block's navigation breadcrumbs.
+- **Crashes count.** A fatal error (the fatal screen, a failed boot) is sent as unhandled,
+  so Sentry's release health counts it as a crash; a non-fatal one as handled.
+- **Environments.** `development` in `__DEV__`; otherwise one per kind of build from the channel:
+  `production`, `preview` (`preview` and `pr-<number>`), `development`. Override with `environment`.
+- **Releases.** `sentrySink` sets `release` to `<applicationId>@<version>+<build>` and `dist` to the
+  build (Sentry's own format) from the version signature, and tags every event with
+  `update.id`, `update.channel`, `update.runtime` and `update.launch`, so an over-the-air update is
+  told apart from the binary it runs on. Without an application id or version, it leaves the
+  release to Sentry rather than guess.
+- **Without a DSN** `sentrySink` starts nothing (a warning outside development).
+- `useRecentActivity()` gives the last breadcrumbs and errors, scrubbed (the devtools overlay
+  shows them).
+
+**Source maps (Sentry).** Optional: add the `@sentry/react-native/expo` config plugin with your
+organization and project, put `SENTRY_AUTH_TOKEN` in EAS secrets, use `getSentryExpoConfig` from
+`@sentry/react-native/metro` in `metro.config.js` (Debug IDs), and for `eas update` run
+`npx @sentry/expo-upload-sourcemaps dist` after the update. In this monorepo also set
+`"@sentry/cli": true` under `allowBuilds` in `pnpm-workspace.yaml`, so the upload binary installs.
+
+**EAS Observe.** EAS Observe (`expo-observe`) measures cold and warm launch, bundle load, time to
+first render and EAS Update download time on its own once the root is wrapped
+(`ObserveRoot.wrap`); time to interactive when you call `useObserve().markInteractive()` on your
+entry screens; and, with `Observe.configure({ integrations: { "expo-router": true } })` at module
+scope, per-route render and interactive times. It has no API for a custom timing metric, so
+`observeSink(Observe)` sends `timing` as an event (`timing.<name>` with `duration_ms`, on the
+Events page) and analytics events with `Observe.logEvent`. Its error reporting is in preview; the
+sink leaves errors to Sentry unless `errors: true`.
+
+`@sentry/react-native` and `expo-observe` are optional peers, passed in rather than imported, so an
+app without them never bundles them.
+
+## Devtools overlay
+
+`@marktiderman/genesis-native/devtools` is a debug sheet for development, preview and internal
+builds. It opens with a three-finger hold (every build, no native module), a shake (pass
+`accelerometer: Accelerometer` from expo-sensors), or "Open devtools" in React Native's dev menu
+(`devSettings: DevSettings`), and shows:
+
+- the version signature, the update channel and a channel switch (the updates block's guarded
+  `channels`: off where that block has it off; "Back to the build's channel" always works);
+- the signed-in user's id, the server's base URL, the blocks in effect (`useBlocks`) and your flags;
+- the recent errors and breadcrumbs from the observability block (scrubbed);
+- "Copy debug info" (your `copy`, else the share sheet), "Crash test" (a render error, to check the
+  fatal screen and reporting end to end), "Clear cache" (the query cache, then your `clearCache`)
+  and "Sign out" (your `signOut`);
+- the `devtoolsFeedback` slot, which the support block fills with "Send feedback" (an annotated
+  screenshot); empty by default. `close()` (the block's, and the slot's) resolves once the sheet
+  has finished sliding away (its `onDismiss`, iOS), or after 800 ms where the platform doesn't
+  report it (Android), so a screenshot taken after it shows the app, not the sheet.
+
+**Keep it out of production.** Import the entry only behind a condition Metro folds at build time.
+Metro inlines `__DEV__`, babel-preset-expo inlines `process.env.EXPO_PUBLIC_*`, and in a
+production bundle the dead branch is dropped before dependencies are collected, so the overlay's
+code isn't in the bundle at all:
+
+```ts
+// lib/devtools.ts: the condition must be written out here (a variable or a helper stops the folding)
+export const devtools =
+  __DEV__ || process.env.EXPO_PUBLIC_APP_VARIANT === "development" || process.env.EXPO_PUBLIC_APP_VARIANT === "preview"
+    ? require("./devtools-overlay").createAppDevtools()
+    : undefined;
+
+// lib/devtools-overlay.ts
+export const createAppDevtools = () =>
+  createDevtools({ enabled: __DEV__ || /\.(dev|preview)$/.test(Application.applicationId ?? ""), updates, observability, … });
+```
+
+Set `EXPO_PUBLIC_APP_VARIANT` wherever `APP_VARIANT` is set (eas.json build profiles and the EAS
+workflow jobs do, in `templates/eas`); unset, the overlay is left out. `enabled` is the second
+lock, a fact of the binary: with it false the block mounts nothing and listens to nothing.
+## Push: registration, taps, the badge, notification settings
+
+`@marktiderman/genesis-native/push` is the push block, a `defineBlock`
+declaration (`id: "push"`). Build it once and put it in `blocks`; taking it
+out turns it off. It contributes a Settings row (`useBlockSettings`: title
+"Notifications", section `notifications`, href `/settings/notifications`, the
+permission as its subtitle; `settingsRow` changes or drops it) and a boot step
+that reads the permission behind the splash (a second at most; it never fails
+the boot), and names its migration. It runs on migration
+0005 and the `genesis-push-send` function of
+[`@marktiderman/genesis-supabase`](../supabase/README.md#push-the-push-block),
+or on [`@marktiderman/genesis-notifications`](../notifications/README.md), which
+now owns the server side of push (it adopts 0005's tables and sends through
+one runner). With the notifier, pass its backend and the registry's categories:
+
+```ts
+import * as Crypto from "expo-crypto";
+import { notificationsPushBackend, pushOptionsFrom } from "@marktiderman/genesis-notifications/native";
+
+createPush({
+  …,
+  backend: notificationsPushBackend(supabase), // registers with this install's id
+  ...pushOptionsFrom(notifications),           // categories (Android channels) and device categories (action buttons)
+  randomUUID: Crypto.randomUUID,               // the install id; Hermes has no crypto.randomUUID
+});
+```
+
+`deviceCategories` registers notification categories with their buttons (Reply
+with a text field, Mark as read) when the block starts; a button tap reaches
+`onResponse`, and `notificationAction(response)` reads it: the action id, the
+typed text, the link and the notifier's notification id. A backend that sets
+`usesInstallationId` gets this install's id (made once, kept across sign-ins)
+as `register`'s fourth argument; `supabasePushBackend` doesn't.
+
+```ts
+// lib/push.ts
+import * as Notifications from "expo-notifications";
+import * as Application from "expo-application";
+import Constants from "expo-constants";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { router } from "expo-router";
+import { AppState, Linking, Platform } from "react-native";
+import { createPush, supabasePushBackend } from "@marktiderman/genesis-native/push";
+
+export const push = createPush({
+  notifications: Notifications,
+  platform: Platform.OS,
+  projectId: Constants.expoConfig?.extra?.eas?.projectId,
+  appVersion: Application.nativeApplicationVersion,
+  backend: supabasePushBackend(supabase),
+  categories: [{ id: "messages", title: "Messages" }, { id: "digest", title: "Weekly digest", defaultOn: false }],
+  storage: AsyncStorage,
+  appState: AppState,
+  openSettings: Linking.openSettings,
+  links, // the same LinkOptions as +native-intent
+  hold: linkHold, // the same hold as GenesisNativeApp's links
+  onOpen: (path) => router.push(path),
+});
+
+// app/_layout.tsx
+<GenesisNativeApp blocks={[push]} links={{ hold: linkHold, onRelease: router.replace }} … />
+
+// app/settings/notifications.tsx
+<NotificationSettings />
+```
+
+- **Permission, asked well.** The block never asks at launch. Call
+  `usePushPrompt().offer("when someone replies")` at the moment push is worth
+  it; the `pushPrompt` slot (default `PushPromptSheet`) says why first, and only
+  its "Turn on" brings up the system prompt. `offer` is ignored for
+  `prompt.launchGraceMs` (10 s) after start (so offer on a screen's focus, not
+  only its mount), while signed out, once the system
+  can't ask again, for `cooldownMs` (3 days) after "Not now", and for good
+  after `maxDeclines` (3). A tap on "Allow notifications" in
+  `NotificationSettings` asks straight away (the tap is the intent); once the
+  system won't ask, it opens Settings (`openSettings`). iOS provisional
+  permission counts as granted.
+- **The token follows the session.** Once permission is granted, a signed-in
+  person's Expo push token (`getExpoPushTokenAsync({ projectId })`) is
+  registered with `genesis_push_register`, again when the OS rotates it
+  (`addPushTokenListener`) and at most hourly otherwise. Sign-out, an account
+  switch and deleting the account forget it (`genesis_push_forget`, which works
+  without a session: holding the token is the proof); a forget that fails
+  offline is kept on the phone and retried each time the app comes to the
+  front, and never undoes a later registration of the same token. Coming to the
+  front also registers again when the last try failed, and at most hourly
+  otherwise (so a token another login took comes back). Without a `projectId` there is no
+  token: the block says so once through `onError`, and Settings says so on
+  screen.
+- **Android channels.** A `default` channel, one per category (named after it,
+  so a person can mute a category in Android's own settings) and any
+  `channels` you add, all with private lock-screen visibility, made before the
+  permission prompt and the token (Android 13 shows its prompt only once a
+  channel exists). The sender uses the category as the channel id.
+- **While the app is open** the foreground handler shows a notification
+  (banner, list, sound, badge) unless `foreground(notification)` says no or a
+  screen hides its kind: `useSuppressNotifications((data) => data.threadId === id)`.
+  Signed out, nothing shows.
+- **Taps.** `data.url` of a tapped notification (and of the one that launched
+  the app, `getLastNotificationResponse`) goes through `normalizeLink` with
+  `links`, once per notification: an unknown path opens `/`, another app's URL
+  never opens. Signed in, `onOpen(path)` runs after the navigator mounts;
+  signed out, the path is held in `hold` (the same `linkHold` as
+  GenesisNativeApp's `links.hold`) and followed after sign-in. Without `onOpen`
+  or `hold`, a tap opens nothing and says so through `onError`. Action buttons
+  go to `onResponse`.
+- **Badge.** `useBadge().set(n)` / `clear()`; the sender can set it too. It is
+  cleared on sign-out (`clearBadgeOnForeground` clears it on every return to
+  the front).
+- **NotificationSettings** is a `SettingsPage` with four parts, each a slot and
+  a hook: `permission` (`usePushPermission`), `categories`
+  (`useNotificationCategories`, a switch per category), `quietHours`
+  (`useQuietHours`: a switch, from and to times with `NativeTimePicker`, and
+  the time zone; turning it on fills in the phone's zone, and a phone that has
+  travelled offers its new one) and `privacy` (`usePrivacyPreviews`: "Show
+  previews"). `slots={{ quietHours: Mine }}` renders yours in the same section
+  with the same props; `null` drops the section. Nothing can be changed until
+  the saved settings have loaded (a change on top of the defaults would save
+  them over the person's choices); a failed load says so and is tried again
+  when the screen opens. Changes save at once and are put back, with a note,
+  when the save fails. The words are
+  `notificationSettingsCopy`, replaced with `copy`. The time pickers need
+  `@react-native-community/datetimepicker`; without it the times are shown, not
+  editable.
+- **What the server decides.** Quiet hours and hidden previews are applied by
+  the sender (`genesis_push_targets`), in the person's saved time zone, so a
+  phone with a wrong clock can't change them, and hidden previews never leave
+  the server. The phone only shows them (`isQuietAt`, by time of day; the
+  server's window also handles clock-change nights). Android's private
+  lock-screen channel setting hides content only when the phone's own "hide
+  sensitive content" is on, and a channel's settings are the person's once it
+  exists: the server's hidden previews are the guarantee, not the channel.
+
+Rung 3: `createPermissionStore`, `createPromptStore`, `createRegistration`,
+`createPreferencesStore`, `supabasePushBackend` (or your own `PushBackend`),
+`pathForResponse`, the row builders (`permissionRows`, …). Rung 4: the hooks
+under `PushProvider`, and `PushRoot` to mount the block without
+GenesisNativeApp (inside a `SessionProvider`).
+
+Not covered: delivery through Apple's and Google's push services hasn't been
+tried (it needs an EAS project with APNs and FCM credentials), and there is no
+in-app inbox: that is `inbox-thread` in the repo's `features.ts`.
+
+### iOS rich push: photos, the sender's avatar, Communication Notifications
+
+`@marktiderman/genesis-native/rich-push-plugin` is an Expo config plugin that
+adds a Notification Service Extension to the iOS app. iOS runs the extension
+on each push that says `mutable-content: 1`, before it is shown, for up to
+about 30 seconds. The extension:
+
+- **attaches pictures.** It downloads `data.image` and `data.senderAvatar`
+  when they are https URLs (no credentials, at most 1024 characters; JPEG, PNG
+  or GIF; at most 10 MB) and attaches them. Only the avatar is read into memory
+  (at most 1 MB; a bigger one is still attached, but not drawn as the sender),
+  because the extension gets about 24 MB. A download that fails or is
+  late is skipped. The notification is always shown, with what the payload
+  already said, and is never dropped.
+- **makes chat pushes Communication Notifications.** A push in the `messages`
+  category with a `senderName` becomes an incoming `INSendMessageIntent`. It
+  carries the sender (`senderName`, `senderAvatar`, and `senderId` as the
+  handle), the conversation (`threadId`, else `data.conversationId`) and, in a
+  group, `groupName` (iOS draws its generic group picture). The extension then
+  calls `content.updating(from:)`. The
+  sender's photo shows on the notification, and Focus treats it as a message
+  (a person can let a Focus through). On a `messages` push the avatar is the
+  sender's photo; on any other push it is attached.
+- **downloads only what you allow.** With `imageHosts`, images come only from
+  those hosts and their subdomains. Without it, any https host is used. Set it
+  when a URL in a push can be one a person chose (an avatar URL they typed),
+  because that host would otherwise see each delivery.
+- **never fetches content.** It reads only the payload. With hidden previews
+  (`hidePreviews`, applied by the sender), the server sends neutral text and no
+  sender, group or picture fields, so there is nothing to show. If the
+  communication update is refused (for example, no entitlement), the plain
+  notification shows instead.
+
+**Setup.** Add the plugin after any plugin that changes the bundle id (the
+Genesis plugin's `APP_VARIANT` suffix), then prebuild:
+
+```ts
+plugins: [
+  "expo-notifications",
+  "@marktiderman/genesis-cli",
+  ["@marktiderman/genesis-native/rich-push-plugin", { imageHosts: ["yourproject.supabase.co"] }], // also: targetName, bundleIdSuffix, communication, deploymentTarget
+],
+```
+
+It runs on the app's own `expo` (`expo/config-plugins`), so it needs nothing
+else installed.
+
+What it sets:
+
+- **App:** the `com.apple.developer.usernotifications.communication`
+  entitlement and `NSUserActivityTypes: ["INSendMessageIntent"]` in
+  Info.plist. Both are skipped with `communication: false`, which keeps
+  attachments only.
+- **Extension:** a target named `GenesisNotificationService` in
+  `ios/GenesisNotificationService/` (the Swift from this package's
+  `ios/notification-service/`, an Info.plist declaring `INSendMessageIntent`
+  and `GenesisRichPushImageHosts`, and entitlements). Its bundle id
+  is `<app id>.NotificationService`. It uses the app's version, build number,
+  minimum iOS and team. The app embeds it and depends on it.
+- **EAS:** `extra.eas.build.experimental.ios.appExtensions`. The extension is
+  a separate bundle id, so it needs its own provisioning profile. EAS Build
+  reads this entry and creates the App ID, its capability and the profile with
+  the app's. You don't create them by hand. A local `expo run:ios` on a device
+  needs an Apple team (`ios.appleTeamId`) that can sign both.
+
+**The payload contract.** The sender sets `mutableContent: true`, or the
+extension never runs. `richPushMessage(message, { image, senderAvatar })`
+(also exported from `/push-payload`, which imports no React, for servers and
+edge functions) sets it and drops image URLs that aren't https. For chat,
+`chatPushPayload` from `@marktiderman/genesis-chat/push` builds the whole set:
+
+| Field | Where | Read by |
+| --- | --- | --- |
+| `mutableContent: true` | message (`mutable-content: 1`) | iOS: runs the extension |
+| `categoryId: "messages"` | message (`aps.category`) | the extension (Communication Notification), Reply and Mark read |
+| `threadId` | message (`aps.thread-id`), the conversation id | grouping, and the intent's conversation |
+| `data.image` | https | attached |
+| `data.senderAvatar` | https | the sender's photo (`messages`), else attached |
+| `data.senderName`, `data.senderId` | text, an opaque id | the intent's sender; without a name the push stays plain |
+| `data.groupName` | text, groups only | the intent's group name |
+| `data.conversationId`, `data.url`, `data.seq`, `data.messageId` | ids and the link | tap routing, Reply, Mark read |
+
+APNs takes 4 KB per push, so keep the URLs short (a storage path, not a long
+signed URL). Expo's push service delivers `data` under the APNs payload's
+`body` key. The
+extension reads it there, or from the payload's top level for a push sent to
+APNs directly.
+
+Not covered: the extension has been built and run on the iOS Simulator only.
+It hasn't been run on a device or from an EAS build. Whether EAS's build number
+increment reaches the extension (its `CURRENT_PROJECT_VERSION` is set at
+prebuild) hasn't been checked either. Donated conversations stay in Siri's
+suggestions after a person turns previews off.
+
+## Blocks
+
+`blocks` takes `defineBlock` declarations (`@marktiderman/genesis-features/blocks`) a native shell
+can run: a `NativeBlock` may also carry `bootSteps` (run behind the splash after your `steps`,
+before the session) and a `Root` (mounted around your screens, inside the error boundary). The
+updates block is one, so these are the same:
+
+```tsx
+<GenesisNativeApp {...shell} updates={updates}>   // as before
+<GenesisNativeApp {...shell} blocks={[updates]}>  // the same block, as a block
+```
+
+The shell resolves the blocks once, at start (`resolveBlocks` with `platform: "native"`). Then:
+
+- their boot steps run in dependency order, and their roots wrap your screens, the first block's outermost;
+- their `contributes.slots` fill the shell's slots by name, under yours: your `slots` (a component
+  or `null`) always win;
+- `useBlocks()` returns the resolved blocks (ids, nav entries, routes, migrations…), each
+  contribution tagged with its FeatureId;
+- `useBlockSettings(sections, { navigate })` returns your Settings sections with every block's
+  rows added to the section they name (an unknown section is added at the end), live subtitles
+  included. The updates block adds the version signature to `about` (`versionRow` in
+  `createUpdates` sets its title and section, or `false` turns it off). Call it at the top of the
+  Settings screen and pass the result to `SettingsPage`.
+
+A block may require your own features that aren't blocks: list them in `appFeatures`. Blocks that
+don't resolve (a required block that wasn't passed or is off, an unknown slot name, two blocks
+filling one slot) hide the splash, show the fatal screen and report a `BlockError` to `onError`:
+a set-up mistake, found at launch.
+
 ## Each part on its own
 
 `createBoot` + `BootProvider` + `useBoot`; `GenesisErrorBoundary` +
@@ -262,7 +719,10 @@ splash (`expo-splash-screen`), storage (AsyncStorage or MMKV), `ErrorUtils`
 (the global by default), the rejection tracker (Hermes's by default),
 `AppState` and NetInfo are passed in, so it runs in tests with fakes. Peers:
 `react`, `react-native`, `@tanstack/react-query`, for `/persist` the two
-TanStack persister packages, and for `/updates` `react-native-safe-area-context`
-(with `expo-updates` and `expo-application` passed in).
+TanStack persister packages, for `/updates` `react-native-safe-area-context`
+(with `expo-updates` and `expo-application` passed in), and for `/push`
+`expo-notifications`, passed in too.
+`/observability` takes `@sentry/react-native` and `expo-observe` passed in;
+`/devtools` takes expo-sensors' `Accelerometer` and React Native's `DevSettings` passed in.
 
 @stability Beta