@marktiderman/genesis-native 0.2.0 → 0.3.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,303 @@ 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).
+
+```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`.
+
+## 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 +603,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

package/dist/block-C5-noMhB.d.ts

@@ -0,0 +1,223 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { N as NativeBlock, n as ErrorReport, x as NativeBlockRootProps } from './blocks-a1YQ1Elf.js';
+
+/**
+ * Typed analytics events: the app lists every event and the props each may
+ * carry once, and `track(name, props)` accepts nothing else. A prop is a
+ * closed list of strings, a number or a boolean, never free text, so an
+ * event can't carry a name, an email or a message someone typed.
+ *
+ * ```ts
+ * export const events = defineEvents({
+ *   "auth.signed_in": { method: ["email", "apple"] },
+ *   "settings.opened": {},
+ *   "checkin.saved": { mood: "number", first: "boolean" },
+ * });
+ * ```
+ *
+ * At run time an unknown event, an unknown prop or a value outside its list
+ * is dropped and reported (a `console.warn` in development, `onInvalid`
+ * always), so a bad call is loud and still sends nothing.
+ */
+/** A closed list of strings, `"number"` (finite) or `"boolean"`. */
+type EventPropSpec = readonly string[] | "number" | "boolean";
+/** Every event, by name, with the props it may carry. */
+type EventSchema = Readonly<Record<string, Readonly<Record<string, EventPropSpec>>>>;
+type PropValue<S> = S extends readonly (infer L)[] ? L : S extends "number" ? number : S extends "boolean" ? boolean : never;
+/** The props of one event: every prop optional, each its spec's type. */
+type EventProps<S extends Readonly<Record<string, EventPropSpec>>> = {
+    readonly [K in keyof S]?: PropValue<S[K]>;
+};
+/** What a sink receives: the checked props. */
+type EventValues = Readonly<Record<string, string | number | boolean>>;
+/**
+ * Declare the app's events. Checks names (lower-case, dot-separated), prop
+ * names, and that each list has at least one short value, and throws listing
+ * every problem, so a bad schema fails where it is written.
+ *
+ * @stability Beta
+ */
+declare function defineEvents<const E extends EventSchema>(schema: E): E;
+type EventCheck = {
+    ok: true;
+    props: EventValues;
+} | {
+    ok: false;
+    problem: string;
+};
+/** Check one call against the schema: the props to send, or why nothing is sent. */
+declare function checkEvent(schema: EventSchema, name: string, props: Readonly<Record<string, unknown>> | undefined): EventCheck;
+
+/**
+ * The vendor-neutral seam: a sink is where errors, breadcrumbs, the user id,
+ * analytics events and timings go. `createObservability` fans every call out
+ * to its sinks, scrubbed first; a sink that throws is reported to
+ * `onSinkError` and never takes the others (or the app) down with it.
+ *
+ * Shipped sinks: `sentrySink` (Sentry), `observeSink` (EAS Observe) and
+ * `consoleSink` (development). A vendor adapter (PostHog, Datadog…) is one
+ * object with the methods it supports.
+ */
+
+/** Where a caught error came from and whether the app could go on. */
+interface ErrorContext {
+    /** True when the app could not go on (a render error, a failed boot, a fatal global error). */
+    fatal: boolean;
+    /** `boundary`, `global`, `boot`, `rejection` (the shell's), or the app's own (`updates:policy`, `sync`). */
+    source: string;
+    componentStack?: string;
+    /** The route pattern on screen (`/(app)/settings`), when known. */
+    route?: string | null;
+}
+type BreadcrumbLevel = "debug" | "info" | "warning" | "error";
+/** One step that led up to an error: a navigation, a tap, a request. */
+interface Breadcrumb {
+    /** `navigation`, `ui`, `http`, `event`, or the app's own. */
+    category: string;
+    message?: string;
+    level?: BreadcrumbLevel;
+    data?: Readonly<Record<string, unknown>>;
+    /** Milliseconds since the epoch. Default now. */
+    timestamp?: number;
+}
+/** Low-cardinality labels on a timing (`route`, `step`), never ids or text someone typed. */
+type TimingTags = Readonly<Record<string, string>>;
+/**
+ * One destination. Every method is optional: a sink takes what its vendor
+ * supports. Errors arrive as an `Error` whose message is already scrubbed,
+ * unless the sink sets `scrubsErrors` (it scrubs the whole event itself and
+ * needs the original object, as Sentry does to deduplicate).
+ *
+ * @stability Beta
+ */
+interface ObservabilitySink {
+    readonly name: string;
+    /** The sink scrubs error events itself; give it the original `Error`. */
+    readonly scrubsErrors?: boolean;
+    captureError?(error: Error, context: ErrorContext): void;
+    breadcrumb?(crumb: Breadcrumb): void;
+    /** The signed-in login's id, or `null` when signed out. Never an email or a name. */
+    setUser?(id: string | null): void;
+    /** An analytics event, its props checked against the schema. */
+    event?(name: string, props: EventValues): void;
+    timing?(name: string, ms: number, tags?: TimingTags): void;
+    /** Wraps the root layout (Sentry's `wrap`, EAS Observe's `ObserveRoot.wrap`). */
+    wrap?<P extends Record<string, unknown>>(root: ComponentType<P>): ComponentType<P>;
+}
+/** A copy of `error` whose message and stack have been scrubbed (for sinks that don't scrub themselves). */
+declare function scrubbedError(error: Error): Error;
+interface ConsoleSinkOptions {
+    /** Default `console`. */
+    console?: Pick<Console, "log" | "warn" | "error">;
+    /** Also log breadcrumbs (noisy). Default false. */
+    breadcrumbs?: boolean;
+}
+/**
+ * Logs what would be sent, for development: fatal errors with `console.error`, others with `console.warn`,
+ * events and timings with `console.log`. Already scrubbed, so what you read
+ * is what a vendor sink would get.
+ *
+ * @stability Beta
+ */
+declare function consoleSink(options?: ConsoleSinkOptions): ObservabilitySink;
+/**
+ * `expo-observe`'s `Observe` (SDK 56+), or a stand-in: the calls `observeSink`
+ * uses. Pass `import { Observe } from "expo-observe"`.
+ */
+interface ObserveLike {
+    logEvent(name: string, options?: {
+        severity?: "debug" | "info" | "warn" | "error";
+        body?: string;
+        attributes?: Record<string, unknown>;
+    }): void;
+    /** Error reporting, in preview on SDK 57+. */
+    reportError?(error: unknown): void;
+}
+interface ObserveSinkOptions {
+    /** Report caught errors with `Observe.reportError` (in preview). Default false: Sentry is the error tracker. */
+    errors?: boolean;
+}
+/**
+ * EAS Observe. It measures launch (cold, warm, bundle load, first render),
+ * time to interactive and, with its Expo Router integration, per-route
+ * render times on its own; it has no API for a custom timing metric, so
+ * `timing` is logged as an event (`timing.<name>` with `duration_ms`) and
+ * shows on the Events page, not as a metric. Analytics events go to
+ * `Observe.logEvent` as they are.
+ *
+ * @stability Beta
+ */
+declare function observeSink(observe: ObserveLike, options?: ObserveSinkOptions): ObservabilitySink;
+/** Breadcrumb data scrubbed and made plain (for sinks and the devtools overlay). */
+declare function scrubBreadcrumb(crumb: Breadcrumb): Breadcrumb;
+
+/** The FeatureId of the observability block. */
+declare const OBSERVABILITY_BLOCK_ID = "observability";
+/** A caught error as the devtools overlay shows it (scrubbed). */
+interface RecentError {
+    at: number;
+    name: string;
+    message: string;
+    source: string;
+    fatal: boolean;
+}
+interface RecentActivity {
+    /** Oldest first. Navigation, events and the app's breadcrumbs. */
+    breadcrumbs: readonly Breadcrumb[];
+    /** Oldest first. */
+    errors: readonly RecentError[];
+}
+interface RecentStore {
+    getState(): RecentActivity;
+    subscribe(listener: () => void): () => void;
+    clear(): void;
+}
+interface ObservabilityOptions<E extends EventSchema = EventSchema> {
+    /** Where everything goes: `sentrySink(Sentry, …)`, `consoleSink()` in development, `observeSink(Observe)`. */
+    sinks: readonly (ObservabilitySink | null | undefined | false)[];
+    /** The app's analytics events (`defineEvents`). Without it, `track` accepts nothing. */
+    events?: E;
+    /** `useSegments` from expo-router: route breadcrumbs and `route.time_on_screen` timings. */
+    useSegments?: () => readonly string[];
+    /** How many breadcrumbs and errors `recent` keeps. Default 50 and 20. */
+    recent?: {
+        breadcrumbs?: number;
+        errors?: number;
+    };
+    /** A sink threw, or `track` was called with something the schema doesn't allow. Default `console.warn` in development. */
+    onProblem?: (problem: string, error?: unknown) => void;
+    now?: () => number;
+}
+interface ObservabilityBlock<E extends EventSchema = EventSchema> extends NativeBlock<typeof OBSERVABILITY_BLOCK_ID> {
+    readonly sinks: readonly ObservabilitySink[];
+    readonly events: E | undefined;
+    /** Report an error. The shell calls it for every error it catches. */
+    captureError(error: unknown, context?: Partial<ErrorContext>): void;
+    breadcrumb(crumb: Breadcrumb): void;
+    /** The login's id only. The block's root sets it from the session. */
+    setUser(id: string | null): void;
+    /** An analytics event from the schema. Anything else is dropped and reported. */
+    track<N extends keyof E & string>(name: N, props?: EventProps<E[N]>): void;
+    timing(name: string, ms: number, tags?: TimingTags): void;
+    /** The root layout wrapped by each sink that wraps (Sentry's `wrap`). Use once: `export default observability.wrap(RootLayout)`. */
+    wrap<P extends Record<string, unknown>>(root: ComponentType<P>): ComponentType<P>;
+    /** The last breadcrumbs and errors, scrubbed, for the devtools overlay. */
+    readonly recent: RecentStore;
+    /** For the shell: every error it catches. */
+    readonly onError: (error: Error, report: ErrorReport) => void;
+    readonly Root: ComponentType<NativeBlockRootProps>;
+}
+/** Build the block once, at module scope, before the root layout renders. @stability Beta */
+declare function createObservability<const E extends EventSchema = EventSchema>(options: ObservabilityOptions<E>): ObservabilityBlock<E>;
+/** Provides a block to the hooks without its root (rung 4). @stability Beta */
+declare function ObservabilityProvider({ block, children }: {
+    block: ObservabilityBlock;
+    children?: ReactNode;
+}): react.JSX.Element;
+/** The block, or `null` when it is off (so a screen can call it whether or not the block is on). @stability Beta */
+declare function useObservability(): ObservabilityBlock | null;
+/** The last breadcrumbs and errors, scrubbed; empty when the block is off. @stability Beta */
+declare function useRecentActivity(block?: ObservabilityBlock | null): RecentActivity;
+
+export { type Breadcrumb as B, type ConsoleSinkOptions as C, type ErrorContext as E, type ObservabilityBlock as O, type RecentActivity as R, type TimingTags as T, type ObservabilitySink as a, type BreadcrumbLevel as b, type EventCheck as c, type EventPropSpec as d, type EventProps as e, type EventSchema as f, type EventValues as g, OBSERVABILITY_BLOCK_ID as h, type ObservabilityOptions as i, ObservabilityProvider as j, type ObserveLike as k, type ObserveSinkOptions as l, type RecentError as m, type RecentStore as n, checkEvent as o, consoleSink as p, createObservability as q, defineEvents as r, observeSink as s, scrubBreadcrumb as t, scrubbedError as u, useObservability as v, useRecentActivity as w };