@wireai/activation 0.13.0 → 0.13.3

package/AGENTS.md

@@ -32,7 +32,7 @@ Everything an integration needs lives on the ROOT import (`@wireai/activation`).
 subpaths are optional secondary feature modules; import one only if you use it.
 
 - `@wireai/activation` (root): `WireOnboarding`, the helpers/types below, and the device-only event reporters (`reportClientEvent`, `makeSessionId`, `WIRE_ONBOARDING_EVENTS`, see "App events" below).
-- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`. These are NOT root exports; importing them from the root does not compile.
+- `@wireai/activation/analytics`: the analytics FACADE and its queue: `createAnalytics`, `useAnalytics`, `createScreenTracker`, `reportAppEvent`, `createEventQueue`, `clearUserContext`. Except for `clearUserContext`, these are NOT root exports; importing them from the root does not compile. `clearUserContext` IS also a root export (`import { clearUserContext } from "@wireai/activation"`), which is the form the README teaches for the sign-out purge.
 - `@wireai/activation/coachmarks`: in-app coachmark tour (`CoachmarkProvider`, `useCoachmarkTour`).
 - `@wireai/activation/showcase`: post-onboarding feature showcase (`FeatureShowcase`).
 - `@wireai/activation/reviews`: store-review gating (`ReviewGate`, `ReviewModal`, `useReviewGate`, `fetchReviewDecision`).
@@ -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"`. |
@@ -98,7 +100,7 @@ FACADE (`createAnalytics` and friends) is a different surface and lives on `@wir
 - `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)`: canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
 - `reportClientEvent(target, event)` / `reportClientEvents(target, events)`: report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`. `target = { serverUrl, apiKey }` is derived from `WireOnboardingConfig`. Fire-and-forget: never throws into the UI.
 - `makeSessionId()`: a unique-per-onboarding session id (also seeds the A2A `contextId` so client and server events correlate).
-- `ClientEventType` is `"screen_skipped" | "dropped" | "client_fallback" | "identify"`. `<WireOnboarding>` auto-reports `dropped` (unmount without complete) and `client_fallback` (degrade to static). Hosts must NOT double-report fallback.
+- `ClientEventType` is `"screen_skipped" | "dropped" | "client_fallback" | "identify" | "app_event"` (`app_event` is the type the whole `wire.track` / `reportAppEvent` surface rides on). `<WireOnboarding>` auto-reports `dropped` (unmount without complete) and `client_fallback` (degrade to static). Hosts must NOT double-report fallback.
 
 ## Integration steps (ordered)
 
@@ -115,7 +117,8 @@ FACADE (`createAnalytics` and friends) is a different surface and lives on `@wir
 ## Review firing (do not hand-roll the decision fetch)
 
 If you gate the review prompt on the server, call **`fetchReviewDecision(target, { deviceKey })`**
-from `@wireai/activation/reviews` and pass the result to `useReviewGate({ decision })`. Never
+from `@wireai/activation/reviews` and pass the result to `useReviewGate({ config, decision })`.
+`config` is REQUIRED (the hook reads `config.id`); `decision` alone does not compile. Never
 write your own fetch.
 
 - It returns the FULL `{ fire, reason, arm }` on 2xx, and `null` ONLY when the server is

package/CHANGELOG.md

@@ -3,6 +3,340 @@
 All notable changes to `@wireai/activation` (formerly `wireai-onboarding`).
 Historical entries below the rename keep the old package name on purpose.
 
+## [0.13.3] — 2026-08-02
+
+The headline is a fix nobody could see from inside the kit: **on the DEFAULT configuration, a
+backend that never answered left the user on the loading screen forever.** Everything else in this
+release is the machinery that let a defect that severe stay invisible to a 638-test suite.
+
+### Fixed
+
+- **A retry could be recorded as the user's FIRST ANSWER.** Caught pre-publish, and like the double
+  review row it was NEW in this release — the retry-budget fix below is what made it reachable. The
+  auto-start effect keyed the kickoff payload on `resumed`, a MOUNT-time prop, so a retry inside a
+  fresh run re-sent `startMessage`. The server records any non-empty message that arrives while a
+  question is pending as that question's answer (`if user_message and pending and not
+  _stop_requested(...)` → appends `{key, question, answer}` to `session["answers"]`). The trigger
+  is not an outage: the watchdog fires at `startTimeoutMs` (15s default) while a slow LLM is still
+  generating card 1, the server already has that card pending, and the retry lands as its answer.
+  The user's first onboarding answer silently becomes the literal kickoff string — and answer data
+  is the product. On 0.13.2 this was unreachable because no second kickoff could ever fire.
+
+  Only the first attempt of a fresh session now sends `startMessage`; a resumed mount and every
+  retry (auto, timeout-driven, and the "Try again" button) send the skip sentinel, which is safe in
+  both server states — with a pending question it skips one card recording nothing, with no pending
+  it is zeroed and behaves as a normal kickoff.
+
+  ⚠️ **The cost, stated rather than hidden: when the server DID hold card 1 pending, the retry now
+  SKIPS that card — the user loses one question.** That is deliberate. A skipped card emits
+  `screen_skipped` and is visible in the funnel; a kickoff string stored as an answer is invisible
+  and corrupts the data every downstream decision reads. Losing a question beats inventing one.
+
+- **A lost ack wrote TWO review rows.** Caught pre-publish, and it was NEW in this release: reading
+  the submit response is what made it possible, so 0.13.2 could not double-post. `submitReview`
+  returned `false` for two materially different outcomes — *nothing reached the server* and *the
+  server answered non-2xx* — and `ReviewGate.postOnce` un-latches on `false`, so the abandonment net
+  re-posted the identical body. A gateway 502 that arrives AFTER the row commits therefore wrote a
+  second review row, double-counting `count` and corrupting `avg`: the exact corruption the one-row
+  latch exists to prevent, on the code path added to protect the data. There is no idempotency key
+  on the wire (`create_review` mints the row id; `CreateReviewRequest` has no id field), so the kit
+  cannot tell the two apart after the fact — it has to stop guessing.
+
+  `submitReview` now resolves **`ReviewSubmitResult`** — `"accepted"` / `"rejected"` / `"unsent"` —
+  instead of a boolean, and `postOnce` un-latches on `"unsent"` alone. A response of ANY status
+  proves the server was reached, and a row the server answered for is the server's problem. The
+  shape change is free: 0.13.3 was never published. Still non-throwing, still fired synchronously —
+  the caller never awaits.
+
+  ⚠️ **Honest residual: this is safer, not safe.** `"unsent"` is not proof the server never got the
+  row either — a connection dropped after the insert committed throws exactly like an offline
+  device, so the single in-process re-post can still duplicate in that narrow window. Closing it
+  needs a **client-minted idempotency key the server upserts on**, which is a server change and is
+  not something the kit can fake. Until then the kit prefers losing a row to inventing one: a lost
+  detractor is a gap in the data, a duplicated one is a lie in it.
+
+- **The questionnaire had the same hole, and it was worse.** The review fix above landed and its
+  semantic twin got none of it. `submitQuestionnaireResponse` returned `void` over a body of
+  `void fetch(...).catch(() => {})`, so the response was never read at all, and
+  `QuestionnaireGate.finish` set `submittedRef`, fired `questionnaire_submitted` and showed the
+  thank-you unconditionally. `onResolved` → `markResolved` then writes the permanent
+  `wire_questionnaire_<id>_<ver>_seen` key. The questionnaire is the only surface that both burns a
+  permanent once-gate **and** had zero evidence of delivery: a user who answered offline lost their
+  answers and was never asked again. The CHANGELOG's own justification for the review fix applies
+  word for word.
+
+  `submitQuestionnaireResponse` now resolves **`QuestionnaireSubmitResult`** (the shared
+  `SubmitResult`: `"accepted"` / `"rejected"` / `"unsent"`), and the gate posts through a `postOnce`
+  latch that un-latches on `"unsent"` alone, with one in-process re-post when the gate unmounts.
+  Both surfaces now import the verdict from one place, so the retry rule cannot drift between them: a
+  server that ANSWERED, even non-2xx, is never retried, because the response id is server-minted and
+  the wire has no idempotency key. The signature change is free: 0.13.3 was never published. Still
+  non-throwing, still fired synchronously, the caller never awaits.
+
+  ⚠️ **Same honest ceiling as reviews:** recovery is in-process only. A run answered offline and
+  never recovered before the app is killed is still lost, and the host still writes the once-gate on
+  `onResolved`. Durable cross-launch retry needs new public API and is deliberately not in this
+  release.
+
+- **The theme context was not shared across the built subpath bundles.** `OnboardingThemeContext`
+  was a plain `createContext(...)` and tsup inlines it into five bundles, so `dist/index.js`,
+  `dist/reviews/index.js`, `dist/questionnaire/index.js`, `dist/coachmarks/index.js` and
+  `dist/showcase/index.js` each carried their own instance. `OnboardingThemeProvider` is exported
+  only from the root barrel, so on any `dist` resolution path (plain RN CLI,
+  `unstable_enablePackageExports: false`, node, jest, SSR) a host that wrapped its tree in
+  `<OnboardingThemeProvider>` and rendered `<ReviewGate>` from `@wireai/activation/reviews` wrote
+  one context and read another. Nothing crashed: `useOnboardingTheme`'s `ctx ?? mergeTheme()`
+  fallback served the neutral default theme, so the tenant's brand silently did not apply. Metro
+  masked it on-device by collapsing every subpath back to one source file, the same bundler accident
+  behind the coachmark-runtime split and the optional-peers bug fixed above.
+
+  The context now lives on a `globalThis` slot keyed by
+  `Symbol.for("@wireai/activation:themeContext")`, exactly as `coachmarks/runtime`,
+  `analytics/currentSession`, `context/deviceId` and `features/WireFeaturesProvider` already did.
+  Measured in the built artifact, before and after: the root provider reached **0** of the four
+  subpath bundles' theme contexts before, and exactly **1 shared instance** after.
+  `test/canary/themeContextIdentity.test.tsx` loads the real bundles and pins it.
+
+- **`WireFeaturesProvider` read `global` where the other nine symbol slots read `globalThis`.**
+  `global` does not exist in a plain browser, so that line was a `ReferenceError` waiting for the
+  first RN-web or browser-SSR host to mount the provider.
+
+- **`maxRetries` never re-armed, so the fallback was unreachable on every host running the default.**
+  `maxRetries` defaults to `1`, and `1` and `2` behaved *identically*: exactly one retry fired, ever,
+  and no terminal state was ever reached. Measured before the fix — `0` → `{kickoffs:1, fallback:1}`,
+  `1` → `{kickoffs:1, fallback:0}`, `2` → `{kickoffs:1, fallback:0}`. Only `maxRetries={0}` reached
+  the fallback, which is the one value that trades the retry away entirely. A backend hung at start
+  therefore produced a 15s loader and then a permanent "Getting started…": no error, no fallback, no
+  way out. The "Try again" button was dead from the same cause, sending `1 → 1`.
+
+  Two causes, both required. `restartThread()` reset a **ref**, and a ref cannot re-trigger an
+  effect — the auto-start effect's deps held only stable values. And the startup watchdog keyed on
+  `lastCard`, which is still `undefined` after a retry, so no new timer ever armed and `timedOut`
+  could not become true a second time. Both effects now key on an incrementing `runId` held in
+  **state**, so a retry genuinely re-arms both; `started`/`resumed` deliberately do **not** re-fire,
+  so a retry cannot double-count a session in the host's funnel. After the fix, `maxRetries` means
+  what it says: `1` → `{kickoffs:2, fallback:1}`, `2` → `{kickoffs:3, fallback:1}`.
+
+  It survived a 638-test suite because the canary's `wireai-rn` mock hardcoded `error: undefined`,
+  leaving the entire error/retry/fallback state machine with **zero render coverage**. The mock
+  gained an error mode and the budget is now asserted for 0, 1 and 2 along with the timeout path
+  and the "Try again" button.
+
+- **A slow cold-start storage read silently destroyed the persisted analytics backlog.** The
+  hydration read races a 1500 ms deadline, and the loser resolved to `undefined` — indistinguishable
+  from "the adapter answered, there is no backlog". Hydration took its empty early return, the
+  surrounding `catch` never ran, and the next `persist()` wrote the in-memory list over the blob
+  nobody had read; with nothing pending it deleted the blob outright. Up to `maxSize` = **200**
+  real events lost on nothing worse than a cold start where storage took two seconds, with no error,
+  no log and nothing to grep for. A timeout is now a distinct sentinel, persistence is suppressed
+  until the read settles, and the original read is still awaited — the late backlog is merged and
+  flushed rather than abandoned. No test injected a slow adapter; one does now.
+
+- **A review rating was latched as posted before the request settled.** The once-gate was written
+  regardless, and the transport was a fire-and-forget `fetch` whose response was never read — so a
+  1-4 star rating with mandatory free text travelled the kit's least durable path while
+  `analytics.track` got a persisted queue with backoff and six retries. A detractor who rated
+  offline was dropped *and* never asked again. `submitReview` now reports delivery, the latch is
+  released when the row did not land, and the undelivered body is re-posted by the existing
+  abandonment net. ⚠️ Recovery is in-process only: a rating taken offline and then killed with the
+  app is still lost. A persisted review outbox is deliberately left for a later release.
+
+- **The coachmarks kill switch could leave a tour unable to finish.** The flag is a mutable global
+  read once with no subscription: the arm effect omitted it from its deps and the drive effect never
+  read it, so flipping it mid-tour made `show()` a silent no-op and left `finish()`/`onComplete`
+  unreachable. It is now subscribable and read through `useSyncExternalStore` in both effects, and a
+  mid-tour disable exits terminally **without** writing the once-gate, so the tour is not consumed.
+
+- **Four of the six optional peers were missing from the published bundle entirely.** Measured with
+  Metro's own dependency collector, the 0.13.2 tarball's `dist/` collected **2 of 6**
+  `OPTIONAL_MODULES` while the same collector over `src/` collected **6 of 6** — so on every
+  resolution path that lands on `dist/` (plain RN CLI, `unstable_enablePackageExports: false`, node,
+  jest) `@expo/vector-icons`, `expo-constants`, `expo-application` and `expo-device` were not in the
+  bundle at all: `WireIcon` renders null and `by_model` / `by_app_version` stay empty, with the
+  guard's own `catch` hiding it. Source consumers (both monorepo apps, and anything else taking
+  the `react-native` condition) were never affected, which is why a green suite and two shipping
+  apps said nothing. Two independent build-config faults, both silent at exit 0 with zero warnings:
+  - `tsup.config.ts` `external` was a hand-maintained list covering 2 of the 6. The consequence
+    depended on the BUILD MACHINE: a module that happened to resolve in the kit's own
+    `node_modules` (`expo-constants`, pulled in transitively) was **inlined whole** into the bundle,
+    so the host's copy went unused; one that did not resolve was left as an orphan call. `external`
+    is now **derived from `metro/index.js`'s `OPTIONAL_MODULES`** — the same list the Metro helper
+    already treats as the source of truth — plus the statically-imported peers, with a build-time
+    throw if the two ever diverge. The output no longer depends on what is installed here.
+  - Marking them `external` was necessary and **not sufficient**. `treeshake: true` is not an
+    esbuild flag; tsup implements it as a Rollup pass whose ESM output is then re-derived into CJS,
+    and in that conversion esbuild renames `require("expo-device")` to `__require("expo-device")`,
+    external or not. Metro's collector matches only a callee literally named `require`, so a
+    renamed call is collected nowhere — the 0.8.0 bug, reintroduced by a build flag rather than by
+    source. The build now carries a small `renderChunk` hook that restores the literal `require`
+    for exactly the `OPTIONAL_MODULES` specifiers, and only in CJS output, where the rewrite is an
+    identity (esbuild defines `__require` as `typeof require !== "undefined" ? require : …`, so in
+    a CJS chunk it already *is* `require`). `treeshake` stays on and every other byte of the bundle
+    keeps its current shape — `dist/index.js` is 218.6 KB, down from 232.2 KB purely because
+    `expo-constants` is no longer inlined. `dist/*.mjs` keeps `__require`: ESM has no `require` to
+    preserve, and no React Native path reads it (`react-native` → `src/`, `main` / the `require`
+    condition → `dist/*.js`).
+
+  `test/canary/metroResolution.test.tsx` ran Metro's collector over `src/` only, which is how a
+  publish-surface defect stayed invisible to the test that owns exactly this property. It now runs
+  the same assertions over the BUILT `dist/` (build-if-stale, never skipped), with its own negative
+  control pinning that a `__require`-shaped call collects nothing. Verified against the pre-fix
+  config: the new assertion goes red and names all four missing modules.
+
+- **The banned-name canary now actually gates a publish.** It was documented as a "build-time canary
+  that fails the pack" and it was neither: `prepack` was `npm run build` and ran no test at all, so a
+  planted banned name packed at **exit 0**, inside the tarball. The second half compounded it
+  — the canary derives its scan set from `package.json` `files`, which includes `dist`, but `dist` is
+  gitignored and sits in the scanner's `OPTIONAL_WHEN_ABSENT` list, so on an unbuilt tree the suite
+  was **6/6 green while covering none of the built output that ships**. Fixing either half alone
+  still ships a name under some ordering. The gate is now one script that closes both:
+  `prepublishOnly` = `npm run build && npm run test:canary`. It fires on `npm publish`, and it fires
+  *after* the build, so `dist/` is on disk and inside the scan. `test:canary` is a new script that
+  runs `test/canary/**` on its own, and `bannedNames.test.tsx` gained a test that asserts this wiring
+  from inside the suite, so deleting the gate goes red instead of silently reopening the hole.
+  ⚠️ `npm pack` on its own still does not run the canary — the honest verb is *publish*, not *pack*.
+
+### Changed
+
+- **Test integrity.** `npm test` now builds first (`pretest`), because the new `dist/` assertions
+  shell out to a build with `clean: true` while other test files walk `dist/` in parallel — that
+  race could redden CI for a reason unrelated to any change. Separately, the pre-existing
+  `DE-DUP: re-enqueuing an identical pending event is collapsed` test was **flaky on `main`**: it
+  fires three synchronous enqueues against a live clock while the queue stamps `ts` into the de-dup
+  signature, so a millisecond boundary between them makes the third a genuine repeat by the queue's
+  own rules. Measured at 0.32% of runs on an untouched `main`, 0/6000 with the clock frozen; it is
+  now pinned exactly as its three sibling tests already were. And `mergePersisted`'s de-dup branch
+  had **zero coverage** — it could be deleted with the whole suite green — which matters precisely
+  because the backlog fix above newly merges a late read into a pending list that may already hold
+  the same event. It is covered now.
+
+- **Four guards this release relies on had no test at all**, found by mutating the suite. Each one
+  was a promise made in writing and enforced by nothing, so each could be deleted with a fully green
+  run: (1) `started`/`resumed` not re-firing on a retry — stated right here as *"a retry cannot
+  double-count a session"*, and in tension with the `runId` re-arm by construction, so a host funnel
+  would have read one flaky cold start as three sessions; (2) `pretest` itself, whose removal
+  silently reopens the `clean: true` race described above; (3) both build-time throws in
+  `tsup.config.ts`, which are the only thing standing between a refactor of the `external`
+  derivation and a bundle that silently inlines or orphans every guarded optional peer at exit 0;
+  and (4) the dist half of `metroResolution`'s HARD-dependency check, which its own
+  `.filter((m) => !collected.has(m))` had rendered unfailable — a module collected optional in one
+  chunk excused a hard require of it in another, and Metro resolves per call site, not per package.
+
+## [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 rides a canary that fails the run if the
+name ever reappears.
+
+> ⚠️ **Corrected 2026-08-02.** This paragraph originally said the canary "fails the pack". It did
+> not: at 0.13.2 nothing ran it on `npm pack` or `npm publish`, and on an unbuilt tree it did not
+> scan `dist/` either. The 0.13.2 tarball is still clean — that was verified by hand — but it was
+> clean without a gate holding it. See the 0.13.3 entry above for the fix.
+
+### 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:
@@ -35,8 +369,11 @@ direction: the kit now declines and says so, where it used to fabricate and retu
   `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. Against a server that
-  never sends it, every path degrades to byte-identical 0.12.2 behaviour. Every fallback is decided
+  ⚠️ ~~**INERT UNTIL THE SERVER EMITS IT.** No deployed server sends `slot_id` today.~~
+  ✅ **CORRECTED 2026-07-28: this is LIVE.** The deployed server 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
@@ -280,7 +617,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).
 
@@ -386,7 +723,7 @@ Architecture-audit fixes (#50/#51). One BEHAVIOR CHANGE, called out below.
   store-declaration implications). The blanket "No PII / nothing identifies a device" claims are
   scoped to the onboarding `userContext` prop + the `collectDeviceContext()` snapshot. `llms.txt`
   now lists the `/analytics`, `/reviews`, `/questionnaire` subpath surfaces.
-- Added the `session/sessionIdentity.integration.test.ts` dist-canary (PR #47/#48).
+- Added the `session/sessionIdentity.integration.test.ts` dist-canary.
 
 ## [0.10.0] - 2026-07-20
 

package/README.md

@@ -235,8 +235,11 @@ import { WireOnboarding } from "@wireai/activation";
 | `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. 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. |
+| `onError` | `(err) => void` | Backend error or first-card timeout, fired **after retries are exhausted**, not on the first failure. When `fallbackFlow` is not supplied, the host owns recovery (e.g. route to a static flow). With neither, the kit shows an inline retry. `fallbackFlow` takes precedence over this. |
+| `fallbackFlow` | `ReactNode` | Your predefined STATIC onboarding, rendered in place once the AI flow fails and retries are exhausted. **Takes precedence over `onError`.** This is the "it can never break your onboarding" guarantee: pass the same flow you shipped before adding Wire AI and the user always keeps moving. |
+| `maxRetries` | `number` | Consecutive failures to auto-retry before degrading to `fallbackFlow`/`onError`. Default `1` (one silent retry, then degrade). `0` degrades on the first failure. Budget it deliberately: each retry restarts the flow, so with `startTimeoutMs` at its `15000` default the default `maxRetries` puts 30s of loader in front of a user before they see the fallback. A retry also sends a skip sentinel, so the user loses one question and a retry is never recorded as their first answer. |
 | `onEvent` | `(e: OnboardingEvent) => void` | `started` / `turn` / `error` — recover per-turn analytics since the kit owns the loop. |
 | `copy` | `Partial<OnboardingCopy>` | Localize the kit's built-in English loader/completion strings. |
 | `approxScreens` | `number` | Approx total screens — paces the bar as `step/total` (capped, never shown). A backend `progress.total` (the screen budget, sent every turn incl. init) wins, so usually unnecessary. |
@@ -608,6 +611,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
@@ -832,6 +916,18 @@ the "personalize from context" thesis. The once-gate
 It reads the active `OnboardingThemeProvider` theme; pass `theme` to override just
 the showcase, or `storage` / `isTesting` to gate independently of the provider.
 
+Until 0.13.3 that sentence only held on a phone. `OnboardingThemeProvider` ships from
+the root barrel, every subpath builds as its own bundle, and each of those bundles
+carried a private copy of the theme context. Metro hid it: its `react-native` export
+condition collapses all five subpaths back to one source file, so on-device the copies
+were the same object by accident. Everywhere else (plain RN CLI,
+`unstable_enablePackageExports: false`, node, jest, SSR) the provider wrote one context
+while the gate read another, and `useOnboardingTheme` quietly falls back to the neutral
+default theme instead of crashing. No error, no warning, wrong brand colors. The context
+now lives in one `Symbol.for` slot on `globalThis`, next to the feature flags and the
+coachmark runtime that already sat there, so a single provider themes every surface on
+every resolution path.
+
 **v2 server seam (future, not built).** The onboarding server's final turn will
 later return an ordered `showcase: string[]` slide-key list chosen server-side from
 the same answers; the host passes it straight in as the `selection` argument.
@@ -1211,7 +1307,7 @@ Least privilege: for the read-only loop, hand the agent just `WIREAI_SERVER_URL`
 A pure-Markdown Claude skill for *using* Wire AI easily: install the kit + wire the
 `WireOnboarding` provider, read your insights (via the MCP or `/v1/insights.md`), and run
 the improve loop (read insights, then adjust the app description / first question /
-generation context). It also carries the `BOILERPLATE20` credit note. For the full
+generation context). For the full
 scaffold-the-screen integration job, the [`wire-rn-integration`](./INTEGRATION_PROMPT.md)
 skill drives it end to end.
 

package/dist/analytics/index.d.mts

@@ -1,7 +1,7 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CF_eHwzC.mjs';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-_GynvhzT.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-_GynvhzT.mjs';
-import '../types-CNUqMK0D.mjs';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-CefdERPs.mjs';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-BoWtr3Jp.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-BoWtr3Jp.mjs';
+import '../types-l2tfg23P.mjs';
 import '../types-BKfpdZzX.mjs';
 import '../types-BcmagF6K.mjs';
 import '../types-CKFhyrMu.mjs';

package/dist/analytics/index.d.ts

@@ -1,7 +1,7 @@
-export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DsRe4epC.js';
-import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-D7zabMXK.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-D7zabMXK.js';
-import '../types-Buj9Lw9t.js';
+export { R as ReportAppEventOptions, r as reportAppEvent } from '../transport-DFuPyCoJ.js';
+import { W as WireUserContext, E as EventQueueOptions } from '../currentSession-CCOMlaQ2.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-CCOMlaQ2.js';
+import '../types-UVYt9BJe.js';
 import '../types-BKfpdZzX.js';
 import '../types-BcmagF6K.js';
 import '../types-CKFhyrMu.js';