@wireai/activation 0.12.2 → 0.13.2

package/AGENTS.md

@@ -48,6 +48,7 @@ subpaths are optional secondary feature modules; import one only if you use it.
 - `themeFromBrand({ primary })`: derive a full theme from one brand color.
 - `mergeTheme`, `defaultOnboardingTheme`, `OnboardingThemeProvider`, `useOnboardingTheme`.
 - `defaultIllustrations`: dependency-free fallback art; spread your own over it.
+- `WIRE_PERMISSION_EVENTS`, `resolvePermissionCopy(...)`: the canonical permission-funnel names and the shipped rationale copy behind `permissionScreens` (see the prop below). The kit imports no native permission module; the host injects `request`.
 - `createRevenueCatBridge({ analytics, entitlementId })`: the RevenueCat purchase funnel (see "RevenueCat" below).
 - `activationJoinContext(deviceKey)`: builds the `userContext` value that joins an onboarding session to the app's later events. Every `<WireOnboarding>` needs it (see step 7).
 - `resolveAutoDeviceKey({ appId, storage })`: the kit's own persisted per-install `device_key`, for a host that owns none.
@@ -65,9 +66,10 @@ subpaths are optional secondary feature modules; import one only if you use it.
 | `illustrations` | `Record<string, ReactNode>` | no | Host artwork for `InterstitialCard`, keyed by name. `{ ...defaultIllustrations, ...myArt }`. |
 | `icons` | `Record<string, ReactNode>` | no | Host icon nodes keyed by the semantic vocabulary name the AI emits (`{ instagram: <BrandIg/> }`). Checked FIRST: use it to brand an icon, to add names of your own, or to supply icons without installing `@expo/vector-icons`. Unlisted names fall back to that optional peer, then to no icon. |
 | `validators` | `Record<string, StepValidator>` | no | Per base-question key (e.g. `username`). Blocks advance + inline error. |
+| `permissionScreens` | `PermissionScreenConfig[]` | no | Priming screens injected mid-flow (notifications first). `{ permission, placement?, request, getStatus?, openSettings?, copy?, illustration?, onResult? }`. The OS dialog opens ONLY on the primary tap, never on mount; "Maybe later" advances without spending the one native prompt. `placement` is `"start"`, `{ afterCard: n }` or `"beforeEnd"` (default), and an `afterCard` past the end of the stream clamps to `"beforeEnd"`. Zero new dependencies: the host injects `request`, the kit imports no native permission module. Shown once per session and, with `storage`, across an app kill. Not a question: no `key`/`slot_id`, nothing in `answers`, completion never blocks on a grant. |
 | `onSkip` | `() => void` | no | Retained for back-compat. Per-question Skip is now internal (the kit advances one question on `skippable` screens), so this is no longer wired to that control. |
 | `onError` | `(err) => void` | no | Backend error/timeout after retries. Host recovery (e.g. static onboarding). `fallbackFlow` takes precedence over it. |
-| `onEvent` | `(e: OnboardingEvent) => void` | no | Lifecycle events for analytics (kit owns the loop). Variants: `started`, `resumed`, `turn`, `error`, `retry`, `fallback` (see `OnboardingEvent`). |
+| `onEvent` | `(e: OnboardingEvent) => void` | no | Lifecycle events for analytics (kit owns the loop). Variants: `started`, `resumed`, `turn`, `error`, `retry`, `fallback`, `permission` (see `OnboardingEvent`). |
 | `copy` | `Partial<OnboardingCopy>` | no | Localize built-in English strings. |
 | `approxScreens` | `number` | no | Paces the bar; backend `progress.total` wins, so usually unneeded. |
 | `startMessage` | `string` | no | First backend message. Default `"start"`. |

package/CHANGELOG.md

@@ -3,6 +3,264 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.13.2] — 2026-07-31
+
+The headline is a fix: every `track()` / `screen()` `app_event` was being silently discarded by the
+server behind an HTTP 200, on every kit version since 0.11.0. This release also ships the injectable
+mid-flow permission screens below, and it is the FIRST version whose published tarball is clean of
+the banned client name — the 0.13.0 publish-surface scrub now rides a build-time canary that fails
+the pack if the name ever reappears.
+
+### Fixed
+
+- **`ts` crosses the wire as ISO8601, so `app_event`s actually land.**
+  (`analytics/reportClientEvent.ts`) The server's event model declares `ts: str | None` and pydantic
+  v2 does not coerce a number into it, while the offline queue has stamped `ts = Date.now()` (epoch
+  ms) on every queued event since 0.11.0 — so `POST /v1/events` answered HTTP 200 with
+  `{written: 0, skipped: N, errors: [{field: "ts", reason: "validation_error"}]}` and 100% of
+  `track()` / `screen()` analytics evaporated behind a green response. `buildEventsRequest` — the
+  single choke point all four send paths share (offline queue, fire-and-forget, awaitable,
+  session-start) — now serializes a numeric `ts` to an ISO8601 UTC string on its way out. The queue
+  keeps its numeric stamp (the identical-JSON de-dup signature depends on it), a persisted 0.13.0
+  backlog is converted as it drains, a caller-set ISO string passes through untouched, and a
+  non-finite or out-of-range number drops the field from that one event instead of killing the batch.
+- **The discard warning names the field the server refused.** (`readEventsAck`) The server's
+  `errors[]` entries carry a `field` alongside `reason`; the ack reader threw it away, so a dev build
+  warned `validation_error` with no address. It now prints `validation_error (field: ts)` — the
+  difference between a one-line fix and an investigation.
+
+### Added
+
+Injectable mid-flow permission screens, starting with notifications.
+
+Onboarding is where apps ask for notifications and where most of them lose the ask: iOS grants an
+app exactly ONE native prompt for its entire lifetime, so firing it from a mount effect on screen
+one spends it on a user who has been told nothing, and the only route back is a Settings trip almost
+nobody makes. This release ships the priming pattern as a first-class part of the flow. You declare
+a screen, it explains why in your words, and the OS dialog opens only on the user's primary tap.
+"Maybe later" advances the flow with the prompt unspent.
+
+Nothing changes for a host that configures no screen: the prop is optional and every path around it
+is byte-identical.
+
+- **`permissionScreens` on `<WireOnboarding>`** (`permissions/types.ts`, `cards/PermissionCard.tsx`) -
+  one or more priming screens injected into the server-driven card stream at a position you choose.
+  The screen carries customizable rationale copy, kit-quality defaults for notifications, optional
+  artwork through the existing illustrations registry, and an `onResult` callback per screen.
+  **DEPENDENCY-FREE, the RevenueCat-bridge idiom:** the kit imports no `expo-notifications`, no
+  `react-native-permissions`, nothing native. The host injects `request` and optionally `getStatus`
+  and `openSettings`, exactly the way it hands the RevenueCat bridge real RevenueCat objects. The
+  README shows the five-line wiring.
+- **The priming rule, enforced in code and pinned by a canary.** There is no path from mount, from
+  an effect, from a timer or from render to the host's `request`; only the primary press handler
+  reaches it. The optional `getStatus` probe is a READ that never prompts, and all it decides is
+  which primary the screen offers: ask, open settings (status `blocked`, where an ask would show
+  nothing at all), or a plain continue (already granted, or a host that supplied no `request`, where
+  the kit declines rather than fabricating a button that does nothing).
+- **A watchdog on the host's `request`, which fabricates nothing.** Asking sets a busy state that
+  disables both controls, which is right while an OS dialog may be open and fatal if the host's
+  `request` never settles at all (a swallowed native callback, a promise nobody resolves): the
+  screen would be a dead end with nothing tappable, and completion could never fire. A generous 90
+  second ceiling now hands the controls back so the user can retry or skip. On expiry it records NO
+  outcome and emits NO event, only a dev warning, because a pending request is not a denial and a
+  person can legitimately sit on a permission dialog for minutes. First settlement wins: if the
+  original request answers late, after the controls were handed back and possibly after a second
+  attempt already resolved, it advances nothing and emits nothing.
+- **Placement semantics with a clamp** (`DEFAULT_PERMISSION_PLACEMENT`, `selectDuePermissionScreen`)
+  - `"start"`, `{ afterCard: n }` and `"beforeEnd"` (the default), resolved against the card about
+  to render, because the stream length is server-driven and varies per user. An `afterCard` the flow
+  never reaches degrades to `"beforeEnd"` instead of silently never showing, which is the failure
+  mode that raises no error anywhere and leaves the host looking at a funnel that reads zero.
+- **`WIRE_PERMISSION_EVENTS`** plus `permissionEventName`, `permissionEventProps` and
+  `normalizePermissionStatus` (`permissions/permissionEvents.ts`) - the canonical funnel names
+  (`wire_permission_screen_shown`, `wire_permission_primer_accepted`, `wire_permission_granted`,
+  `wire_permission_denied`, `wire_permission_skipped`, `wire_permission_settings_opened`), mirroring
+  `WIRE_PURCHASE_EVENTS`. They land as `app_event` `question_key` values on the same `/v1/events`
+  path, carrying the same device snapshot and `user_context`, so the `device_key` join that makes
+  every other number real covers these too. Each moment is also surfaced on `onEvent` as
+  `{ type: "permission", ... }`.
+- **`resolvePermissionCopy`, `NOTIFICATIONS_PERMISSION_COPY`, `GENERIC_PERMISSION_COPY`,
+  `DEFAULT_PERMISSION_COPY`** - the shipped English plus per-line overrides. An override that is
+  `undefined` or empty is IGNORED rather than allowed to blank a button, because hosts build this
+  object from an i18n layer where a missing translation resolves to `undefined`.
+- **Once per session, kept true across an app KILL** (`permissionStorageKey`,
+  `loadSettledPermissions`, `saveSettledPermissions`, `readSettledPermissions`,
+  `clearSettledPermissions`). The kit resumes a killed onboarding into the SAME backend session, so
+  without a persisted record the resumed mount would re-show a screen the user already answered,
+  which on the ask path means a second attempt at the one prompt iOS grants. The record is scoped to
+  the session id, one entry, so a genuinely new onboarding still starts clean with nothing having to
+  expire it. Same host-injected `storage`, same read ceiling, same best-effort discipline: a
+  rejecting adapter costs a re-ask on resume, never a broken or gated flow.
+- **`PermissionCard` and `PERMISSION_CARD_NAME`** - the screen registered as an SDK component, so a
+  later server-emitted placement (AI-chosen timing) adopts this exact screen with no rewrite.
+  Deliberately NOT part of `onboardingComponents`: that array is what the device advertises as
+  renderable, and a backend told it may emit a permission screen could emit one into a host that
+  injected no `request`.
+- **A `notifications` entry in `defaultIllustrations`** so a notification screen is never a blank
+  box with no host wiring. Register your own under the same name to override it.
+
+### Changed
+
+- **`OnboardingEvent` gains a `permission` variant** and `toAnalyticsEvent` maps it to its own
+  canonical `wire_permission_*` name rather than folding it into an onboarding one. Additive: a host
+  that ignores the new variant is unaffected, and every existing variant maps exactly as before.
+- **A permission screen is NOT a question, structurally.** It sends nothing to the backend, appends
+  nothing to the thread, mints no `key` and no `slot_id`, and never touches the progress step, so
+  `deriveAnswers`, `readProgress` and the completion semantics cannot tell it happened. Completion
+  never blocks on a grant: grant, deny, skip and blocked all continue the flow, and a host callback
+  that throws (a native module blowing up, a failed scheduling call) is caught rather than allowed
+  to strand the user on the screen.
+- **Notification SCHEDULING is deliberately out of scope.** `onResult` is the seam: schedule your
+  first local reminder there, with your own call, the moment a grant lands.
+
+## [0.13.0] — 2026-07-27
+
+The identity-provenance release. Every id-layer defect fixed here is one omission wearing five faces:
+`session_id` and `device_key` are bare `string`s minted independently by four subsystems, and nothing
+anywhere recorded WHERE a given id came from. So a rejecting storage adapter's in-memory id was
+indistinguishable from a persisted one, an app-OPEN session id could be posted into a field meaning the
+ONBOARDING session, an auto-minted key could be injected beside a device id the host demonstrably owned
+on another surface, and the join key could change identity mid-mount — each of them silently, each of
+them returning success. This release gives ids provenance and teaches every consumer to refuse a
+fabricated one.
+
+Nothing here changes the wire for a correctly-wired host. The behaviour changes all move in one
+direction: the kit now declines and says so, where it used to fabricate and return `true`.
+
+### Added
+
+- **`resolveIdentity(...)`, `hostIdentity(...)` and the `IdentityRecord` type** (`identity/identityRecord.ts`) —
+  the substrate. One record, `{ value, space, source, durable }`, parked on the same `Symbol.for`
+  registry pattern the repo already uses for the current session id, the auto device key and activation
+  revalidation, so every inlined bundle copy addresses ONE registry. `space` is
+  `onboarding-session | app-session | device`, `source` is `host | auto`, and `durable` says whether the
+  value was actually persisted. A host-sourced record is recorded on a process-wide registry, which is
+  what lets one surface notice that another surface owns a device key it was not given.
+  ⚠️ Deliberately NOT a branded-types refactor — `OnboardingSessionId` / `AppSessionId` / `DeviceKey`
+  across every signature is real value and is deferred, because it touches every file.
+- **`hydrateDeviceIdentity(...)`** (`context/deviceId.ts`) — the provenance-carrying sibling of
+  `hydrateAutoDeviceKey`. Same awaited read, but it answers "is this an id this install will KEEP?"
+  instead of only "what is the id?". `hydrateAutoDeviceKey` is unchanged and still returns a bare string.
+- **`OnboardingProgress.slot_id`** — an optional STABLE per-slot identity for a screen, read off
+  `props.progress` by `readProgress` and preferred over `key` by `deriveAnswers`. `key` is authored from
+  the question's prompt text (tenant flows slugify it and cut at 32 chars), so re-wording a question mints
+  a NEW key and a host reading `answers.interests` silently starts reading `undefined`.
+  ⚠️ ~~**INERT UNTIL THE SERVER EMITS IT.** No deployed server sends `slot_id` today.~~
+  ✅ **CORRECTED 2026-07-28: this is LIVE.** The deployed server (`47dae92`) sends `slot_id` on
+  `progress` for every AI-generated question, as `adaptive_<n>`, and for a configured question
+  whenever the tenant set one. Where no slot is configured the field is absent and
+  every path degrades to byte-identical 0.12.2 behaviour. Every fallback is decided
+  PER CARD, never cached as a per-session "this backend supports slots" verdict, so a thread that mixes
+  slotted and unslotted cards — the real shape during a rollout — keys each card correctly.
+- **`allowAppSessionFallback` on `identifyOnboarding`** — the opt-in switch for the tier-3 behaviour
+  described under Changed. Default `false`.
+- **`resetEventQueueKeys()`** (`@wireai/activation/analytics`, test-only) — clears
+  the claimed-queue-key registry. A real relaunch is a new process; a test that simulates one in-process
+  needs this or its second queue reads as a concurrent sibling.
+- **A first test file for `deriveAnswers`** (`utils/deriveAnswers.test.ts`), table-driven over real thread
+  shapes: progress key present and absent, slugified prose, multi-select, every NL wrapper the SDK
+  produces, and the threads that must produce NO entry.
+
+### Changed
+
+- **⚠️ BEHAVIOR CHANGE: a `storage` adapter that FAILS no longer earns an injected join key.** The
+  auto-join gate was a bare presence check on the `storage` prop — never the SUCCESS of the write — and
+  `hydrateAutoDeviceKey` resolves to the in-memory mint on every failure branch, so a REJECTING adapter
+  (a locked / full / permission-denied AsyncStorage, the most common real breakage) injected a FRESH
+  `wdev_*` on every launch. Probe-verified: two launches, two different keys. That is strictly worse than
+  injecting nothing — the server counts `min_sessions` by distinct opens grouped on `device_key`, so a
+  per-launch key makes that counter structurally incapable of exceeding 1 AND inflates distinct-device
+  counts. The gate now reads `IdentityRecord.durable`, true only when the id was adopted from storage or
+  written to it successfully, so a broken adapter lands on the same "declined, and here is why" path as
+  no adapter at all. The existing dev warning was widened to name this third reason.
+  Who this changes: a host whose storage was silently broken. It was already getting corrupt data; it now
+  gets no join key and a warning that names the cause.
+- **⚠️ BEHAVIOR CHANGE: `identifyOnboarding` no longer binds to the app-open session by default, and its
+  return type widened to `"onboarding" | "app_session" | false`.** Tier 3 fell back to
+  `getCurrentSessionId()` — the per-OPEN session — and posted it in the `session_id` field, which on this
+  endpoint means the ONBOARDING session, then returned `true`. Two disjoint id spaces share that field, so
+  the row it wrote could never join the onboarding funnel while the host was told it had worked. It fired
+  in exactly the DOCUMENTED post-completion case, because completion clears the persisted session. The
+  fallback is now behind `allowAppSessionFallback` and, when it does fire, says so in the return value.
+  ⚠️ `"onboarding"` is truthy, so `if (await identifyOnboarding(...))` behaves identically at runtime;
+  only an explicit `: boolean` annotation needs updating.
+- **⚠️ BEHAVIOR CHANGE: `wire.track()` returns `false` for an event the server DISCARDED.**
+  `POST /v1/events` answers HTTP 200 with `{ ok, written, skipped }` and counts a refused event in
+  `skipped`, so `reportClientEventsAwait` — which read `res.ok` alone — resolved `true` for an event that
+  was thrown away, and `wire.track` then bumped decision revalidation, making every subscribed gate
+  re-fetch against a stream the action never entered. It now reads the ack. Backward compatible by
+  construction: ONLY an explicit positive `skipped` demotes a 200, so an old server that sends no such
+  field, an unparseable body, or a response with no `.json` at all still resolves `true` — the change can
+  produce no false negatives.
+- **The join decision is FROZEN at the moment the loader gate opens.** `userContext` feeds the `llm` memo
+  and wireai-rn recreates its A2A adapter whenever that identity changes, resetting `contextId`. So a host
+  resolving its device key ASYNCHRONOUSLY — the default shape of any host reading its id out of async
+  storage — rendered once without it, got `wdev_*` injected, then had the real key land a tick later and
+  rebuild the adapter, DROPPING the server-learned session id and RESTARTING the user's onboarding
+  mid-flow with an orphaned session left behind. The session-start metadata now reads a frozen snapshot,
+  exactly as `startupUserIdRef` already did for the user id. Client events deliberately keep reading the
+  LIVE context: they carry no adapter, so late host context enriches them at no risk.
+- **A host device key on ANOTHER surface is no longer silent.** 0.12.2 suppressed the missing-join-key
+  warning whenever injection succeeded — right when the host genuinely owns no device id, wrong when it
+  owns one and forgot it on this mount. That host went from a loud warning to a silent THIRD id space. Any
+  surface constructed with a host-supplied device key (`createAnalytics`, `createWireActivation`,
+  `useLifecycleEvents`, `<WireOnboarding userContext={...}>`) now records it, scoped per `appId`, and a mount
+  that injected its own key while the process demonstrably owns a host one warns and prints both. It warns
+  rather than declining, because declining would leave the onboarding side with no key at all; it does not
+  silently ADOPT the other key, because that is the kit guessing which of two ids a host meant on the
+  strength of construction order.
+- **Two event queues for one `appId` no longer share one storage slot.** The default key was derived from
+  `appId` alone, so two `createAnalytics` instances for one tenant — the documented double-wiring — shared
+  ONE persisted backlog while keeping SEPARATE in-memory buffers: each `persist()` overwrote the other's
+  blob, a queue draining to empty called `removeItem` and DELETED a sibling's still-pending events, and on
+  relaunch the survivors were loaded by both and sent twice. The second claimant of a default key now gets
+  `…#2` and a dev warning naming the fix. Only the appId-derived DEFAULT is ever rotated — an EXPLICIT
+  `storageKey` is a host declaring which slot it owns (`useLifecycleEvents` does exactly that and
+  re-creates its queue on every remount, where rotation would be a worse bug). Only claimed when there IS
+  storage; a storage-less queue never touches the key.
+- **A failed device-key hydration is retried instead of cached for the process lifetime.** A transient
+  cold-boot storage lock used to be permanent: the settled failure stayed parked on the registry and every
+  later caller joined it. A degraded outcome now releases its latches so the next caller starts a fresh read.
+- **The DISCARDED warning covers all FOUR send paths and stops naming a cause the kit never checked.** It
+  used to end "the usual cause is an event with a missing or empty `session_id`" — but since
+  `ensureCurrentSessionId` shipped, no kit path can emit an event without one, making that the LEAST likely
+  explanation and sending every reader to the one place the problem is not. It now reports what the server
+  actually said (`skipped`, `written`, and any per-event `reasons` once the server sends them) and admits
+  when the endpoint gave no reason. The two `reportClientEvent*` paths — which carry `dropped`, `identify`,
+  `client_fallback` and every `wire.track` — join the offline queue and session-start in consuming the ack.
+- **`validators` are looked up by `slot_id` first, then `progress.key`.** Host validators live in the SAME
+  key namespace `deriveAnswers` files answers under, so moving the answer key to the slot without moving
+  this lookup would have silently UNBOUND every host validator: no error, no warning, values simply stop
+  being checked. The fallback keeps a validator map written against today's keys working while a server
+  rolls slots out.
+
+### Removed
+
+- **`DoneBlock`** — self-`@deprecated` since 0.1.x, unused internally since the terminal screen became
+  `CompletionView`, and referenced by nothing in `src/` or the playground. The component file is deleted.
+- **`RESERVED_USER_CONTEXT_KEYS`** — read by nothing, including its own module: the namespacing it claims
+  to govern is enforced by `EXTRA_KEY_PREFIX`. It was a documentation constant shaped like an invariant.
+
+### Internal
+
+- The FOUR duplicate `warnInDev` copies (`WireOnboarding`, `config/wireConfigFromEnv`,
+  `analytics/analyticsFacade`, `analytics/currentSession`) collapse into `utils/warnInDev`, which returns
+  whether it ACTUALLY warned — the property `currentSession`'s once-flag depends on, and the only reason
+  its copy differed. The stated rationale for that copy (keeping the module import-free for the
+  tree-shaken analytics bundle) had already lapsed: it imports `makeSessionId` from a sibling. The new
+  module has no imports of its own, and the `treeShake` canary still holds the real guarantee.
+- The two byte-identical trim helpers (`context/userContext.cleanString`, `activation/wireActivation.clean`)
+  collapse into one shared `cleanString`, not re-exported from the barrel.
+- **The canary suite can observe a payload for the first time.** Every `onComplete` mock was typed with
+  ZERO parameters, so `OnboardingResult` was structurally unobservable and every assertion could only be a
+  call count — the mechanism behind "500 green tests, zero data". `flow.test.tsx` now captures the argument
+  and asserts the answers map end to end. The scripted `wireai-rn` mock also appends the USER turn to the
+  thread, as the real SDK does; without it the mocked thread was assistant-only, so `deriveAnswers` had
+  nothing to pair and `answers` was always `{}` under test regardless of the implementation.
+- `mountCanary` gained `rerender()`, the seam for a prop that arrives LATE. The churn loop runs entirely
+  inside the initial `act`, so without it there was no way to re-render a mount after an async gate had
+  settled — and the whole "value changed mid-flow" defect class was untestable.
+
 ## [0.12.2] — 2026-07-27
 
 The auto-join patch. 0.12.1 taught the kit to complain about a missing join key; this one teaches it
@@ -135,7 +393,7 @@ or a client-side default.
 
 ## [0.12.0] — 2026-07-27
 
-The release Myelino 2.2.0 pins. Ships the RevenueCat path (#52), the identity/counting audit,
+The release the first production consumer pins. Ships the RevenueCat path (#52), the identity/counting audit,
 the session-id fallback contract, and the transport/config fixes behind a silently dead lifecycle
 stream (a consumer's `first_open` read 6 all-time while the emitting code was deployed).
 

package/README.md

@@ -234,7 +234,8 @@ import { WireOnboarding } from "@wireai/activation";
 | `onComplete` | `(result: { answers, raw }) => void` | Fires when the user taps the terminal recap's CTA. **Required.** |
 | `theme` | `Partial<OnboardingTheme>` | Brand colors/fonts/radius/spacing, deep-merged over a neutral default. |
 | `illustrations` | `Record<string, ReactNode>` | App artwork for `InterstitialCard`, keyed by name. |
-| `validators` | `Record<string, StepValidator>` | Per-step, keyed by base-question key (e.g. `username`). Blocks advance + shows an inline error. |
+| `validators` | `Record<string, StepValidator>` | Per-step, keyed by base-question key (e.g. `username`). Blocks advance + shows an inline error. When the backend sends a `progress.slot_id` for a screen, the kit looks up that slot FIRST and falls back to the question key, so a validator map written against today's keys keeps working. |
+| `permissionScreens` | `PermissionScreenConfig[]` | Priming screens injected mid-flow, starting with notifications. The screen explains why, and the OS dialog opens **only** on the primary tap, never on mount. Zero new dependencies: you inject `request`. See [Permission screens](#permission-screens-the-priming-pattern). |
 | `onSkip` | `() => void` | User skipped. |
 | `onError` | `(err) => void` | Backend error/timeout — host owns recovery (e.g. route to a static flow). Without it, the kit shows an inline retry. |
 | `onEvent` | `(e: OnboardingEvent) => void` | `started` / `turn` / `error` — recover per-turn analytics since the kit owns the loop. |
@@ -247,7 +248,7 @@ import { WireOnboarding } from "@wireai/activation";
 | `sessionTtlMs` | `number` | How long a persisted session id stays resumable. Default `3600000` (1h, the backend's session TTL). With `storage` only. |
 | `persistKey` | `string` | Override the storage key (default `wireai:session:<appId>`). Scope per-user if one device can onboard multiple accounts mid-flow. With `storage` only. |
 | `userContext` | `Record<string, string \| number \| boolean>` | **This is where the join key goes.** `user_context.device_key` is the only thing that joins this onboarding session to the app's later events, so pass `userContext={activationJoinContext(deviceKey)}` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` if your app owns no device id). Since 0.12.2, omitting it no longer empties the funnel silently: with `storage`, the kit injects its own key (see [The join key](#the-join-key-device_key-never-session_id) and `autoJoinKey` below). Second job: any other non-PII context the app already knows (signup method, referral, plan, a HASHED user id), forwarded on session metadata + client events for funnel segmentation. **No PII on THIS prop** (no raw emails/names); primitives only; the server caps size/keys. See [Device & user context](#device--user-context). ⚠️ Distinct from the analytics/activation **`WireUserContext`** object (`createAnalytics` / `useWireActivation`), which additionally accepts an opt-in raw `userEmail` — see [Rich user context & PII](#rich-user-context--pii). |
-| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present, and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
+| `autoJoinKey` | `boolean` | Opt OUT of the automatic join key. Default `true`. When this prop is left alone, `storage` is present **and actually persists** (0.13.0: a `storage` adapter that rejects or throws is treated exactly like no `storage` — the kit declines and says so, because a key it cannot persist is a different key on every launch, which corrupts `min_sessions` rather than merely leaving the join empty), and `userContext` carries no `device_key`, the kit injects its own per-install key (the same id `createAnalytics` / `createWireActivation` mint and persist), so the `activated` funnel joins with no host wiring. Pass `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session: that restores the pre-0.12.2 behavior exactly, and the dev warning fires again. It never overrides a `device_key` you passed, and it cannot inject without `storage` (see [The join key](#the-join-key-device_key-never-session_id)). |
 | `userId` | `string` | Your own OPAQUE user id, so onboarding sessions reconcile to real users later (console sessions to your user table / GA4 users). Optional and supports **late binding**: present at mount it rides the session-start metadata; if it changes mid-session (the user just registered) the kit emits an `identify` event; available only after the flow, use `identifyOnboarding(...)`. **No PII** (not an email/name/phone); trimmed and capped at 128 chars. See [User identity](#user-identity). |
 
 ## Helpers (the reusable substrate)
@@ -340,7 +341,9 @@ const contextIdRef = useRef<string>();
 await identifyOnboarding({ config, userId: newUser.id, contextId: contextIdRef.current });
 ```
 
-If you passed `storage` to `<WireOnboarding>`, you can omit `contextId` and hand `identifyOnboarding` the same `storage` (plus `appId` or `persistKey`) and it recovers the persisted session id itself. That works while the session is still persisted (before completion clears it), so the captured-`contextId` path above is the safe one post-completion. `identifyOnboarding` is fire-and-forget and never throws; it resolves `true` when it dispatched an `identify` and `false` when it could not (no user id, no server url, or no resolvable session).
+If you passed `storage` to `<WireOnboarding>`, you can omit `contextId` and hand `identifyOnboarding` the same `storage` (plus `appId` or `persistKey`) and it recovers the persisted session id itself. That works while the session is still persisted (before completion clears it), so the captured-`contextId` path above is the safe one post-completion. `identifyOnboarding` is fire-and-forget and never throws. Since 0.13.0 it resolves the id SPACE it bound rather than a bare boolean: `"onboarding"` when it attached to the A2A `contextId` (the one that attributes the funnel), `"app_session"` when you opted into `allowAppSessionFallback` and it fell back to the live per-open app session, and `false` when it could not bind at all (no user id, no server url, or no resolvable session). `"onboarding"` is truthy, so an existing `if (await identifyOnboarding(...))` behaves identically.
+
+⚠️ **The app-session fallback is now opt-in and off by default.** Before 0.13.0 it ran unconditionally: with no captured `contextId` it posted the per-OPEN session id in the `session_id` field — which on this endpoint means the ONBOARDING session — and returned `true`. Those are two different id spaces sharing one wire field, so the row it wrote could never join the onboarding funnel while the caller was told it had worked.
 
 **No PII.** The onboarding `userId` prop is length-bound only; the kit cannot detect an email for you. Keep it opaque, the same rule as the onboarding `userContext` prop.
 
@@ -606,6 +609,87 @@ icons={{
 Icons are decorative: the label carries the meaning, so an icon stays hidden from screen readers
 and never becomes an option's accessible name.
 
+## Permission screens (the priming pattern)
+
+Onboarding is where apps ask for notifications, and it is where most of them lose the ask. iOS gives an app **one** native notification prompt for its entire lifetime. Fire it from a mount effect on screen one and you have spent it on a user who has been told nothing, and the only route back is a trip through the Settings app that almost nobody makes.
+
+So the kit ships the priming pattern. You inject a screen into the flow, it explains why in your words, and the OS dialog opens **only** when the user taps the primary button. "Maybe later" advances the flow with the prompt still unspent, so you can ask again in a better moment.
+
+```tsx
+import * as Notifications from "expo-notifications";
+import { WireOnboarding } from "@wireai/activation";
+
+<WireOnboarding
+  config={config}
+  onComplete={persist}
+  permissionScreens={[
+    {
+      permission: "notifications",
+      placement: "beforeEnd",
+      request: async () => {
+        const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+        return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+      },
+      getStatus: async () => {
+        const { status, canAskAgain } = await Notifications.getPermissionsAsync();
+        return status === "granted" ? "granted" : canAskAgain ? "denied" : "blocked";
+      },
+      onResult: (_permission, outcome) => {
+        if (outcome === "granted") scheduleFirstReminder();
+      },
+    },
+  ]}
+/>
+```
+
+That is the whole integration, and **the kit adds no dependency for it**. It imports no `expo-notifications`, no `react-native-permissions`, nothing native, the same way the RevenueCat bridge takes real RevenueCat objects without depending on `react-native-purchases`. You own the native call; the kit owns the screen, the timing, and the funnel.
+
+### Where the screen lands
+
+The stream is server-driven, so its length changes per user. A placement is therefore resolved against the card about to render, not against a fixed index:
+
+| `placement` | Where it shows |
+|---|---|
+| `"beforeEnd"` (default) | Right before the terminal recap, once the user has invested in the flow. |
+| `"start"` | Before the first question. |
+| `{ afterCard: 2 }` | After two questions, so between card 2 and card 3. |
+
+An `afterCard` the flow never reaches **clamps to `"beforeEnd"`** instead of silently never showing. That matters more than it sounds: a screen that never appears raises no error anywhere, and the only evidence is a permission funnel that reads zero forever.
+
+### What it guarantees
+
+- **The dialog is only ever reached from the primary tap.** No mount effect, no timer, no auto-fire. `getStatus` is a read and never prompts; it only decides which primary the screen offers.
+- **Already blocked?** The primary becomes "Open settings", because an `ask` there would open nothing at all.
+- **Once per session, and it survives an app kill.** With `storage`, a resumed session does not re-ask (the record is keyed to the session id, so a genuinely new onboarding still starts clean).
+- **Completion never blocks on a grant.** Grant, deny, skip and blocked all continue the flow.
+- **It is not a question.** Nothing is sent to the backend, nothing enters the thread, no `key` or `slot_id` is minted, and `onComplete`'s `answers` are identical to the same flow with no screen configured.
+
+### Copy and artwork
+
+The kit ships English good enough to ship. Override any single line and the rest of the default stays:
+
+```tsx
+copy: { title: "Never miss a session", primaryLabel: "Turn on reminders" }
+```
+
+Artwork comes from the same `illustrations` registry the cards use, keyed by the permission name, so `illustrations={{ notifications: <MyBell /> }}` is enough. The kit's dependency-free default is used when you register nothing.
+
+### The numbers
+
+Each screen reports through the same `/v1/events` path and the same `device_key` join as the rest of the funnel, and every moment is also surfaced on `onEvent` as `{ type: "permission", ... }`:
+
+| Event | Fires when |
+|---|---|
+| `wire_permission_screen_shown` | The primer became visible. The denominator. |
+| `wire_permission_primer_accepted` | The primary was tapped, so the OS dialog is about to open. |
+| `wire_permission_granted` / `wire_permission_denied` | What the OS answered (a permanently blocked answer reports as denied with `status: "blocked"`). |
+| `wire_permission_skipped` | "Maybe later". The one native prompt was not spent. |
+| `wire_permission_settings_opened` | A blocked user was sent to Settings. |
+
+The gap between `wire_permission_screen_shown` and `wire_permission_primer_accepted` is the number worth watching: it tells you whether your rationale copy works, and it costs nothing to be wrong about, because a user who does not tap has not burned anything.
+
+**Scheduling notifications is deliberately out of scope.** `onResult` is the seam: schedule your first local reminder there, with your own `expo-notifications` call, the moment a grant lands.
+
 ## Backend coupling
 
 The backend (`wire-rn/examples/dynamic-onboarding/server`) is the source of truth

package/dist/analytics/index.d.mts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CF_eHwzC.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BlCeDP0f.mjs';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BlCeDP0f.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-ClkLjcJ0.mjs';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-ClkLjcJ0.mjs';
 import '../types-CNUqMK0D.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';

package/dist/analytics/index.d.ts

@@ -1,6 +1,6 @@
 export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DsRe4epC.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BxEB37xt.js';
-export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resolveAutoDeviceKey, F as setCurrentSessionId, G as toAnalyticsEvent } from '../currentSession-BxEB37xt.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-DOVZEWJl.js';
+export { A as AUTO_DEVICE_ID_PREFIX, a as AnalyticsEvent, C as ClearUserContextOptions, b as ClientEvent, c as ClientEventTarget, d as ClientEventType, e as ContextEnvelope, f as ContextEnvelopeInput, D as DeviceKeyStorage, g as EnvelopeSource, h as EventQueue, R as ResolveAutoDeviceKeyOptions, i as WIRE_ONBOARDING_EVENTS, j as WireOnboardingEventName, k as analyticsUserIdStorageKey, l as buildContextEnvelope, m as clearPiiFromContext, n as clearUserContext, o as createEventQueue, p as deviceIdStorageKey, q as ensureCurrentSessionId, r as getCurrentSessionId, s as looksLikeEmail, t as makeSessionId, u as reportClientEvent, v as reportClientEventAwait, w as reportClientEvents, x as reportClientEventsAwait, y as resetAutoDeviceKeys, z as resetCurrentSessionId, B as resetEventQueueKeys, F as resolveAutoDeviceKey, G as setCurrentSessionId, H as toAnalyticsEvent } from '../currentSession-DOVZEWJl.js';
 import '../types-Buj9Lw9t.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';