@wireai/activation 0.15.0 → 0.16.0

package/llms.txt

@@ -8,19 +8,19 @@
 
 ## What an agent needs to know
 
-- **Install:** `npm install @wireai/activation wireai-rn` (react + react-native are peers).
+- **Install:** `npm install @wireai/activation wireai-rn zod react-native-safe-area-context` (react + react-native are peers).
 - **Metro (required):** `module.exports = withWireOnboarding(getDefaultConfig(__dirname))` from `@wireai/activation/metro`, which pins one copy of react/react-native/wireai-rn/zod (prevents the dual-React crash).
-- **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Created in the getwireai console or via the backend's `register_<app>.py`. Nothing renders without both.
-- **Render:** drop `<WireOnboarding config={wireConfigFromEnv({ appId })} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} />` into the signup flow.
+- **Two secrets:** an app `apiKey` (a `wai_…` key that resolves the tenant server-side) and the backend `serverUrl`. Both come from the console: sign up at https://getwireai.com/signup (app name + email; the confirmation link is where you choose a password, and that one step creates your first app and its key and lands you in the console already signed in), then read both off that app's Integrate tab at `https://getwireai.com/console/<app-id>/integrate`, where the key is a copy field and the server URL is the `serverUrl` line of the init snippet. The key stays readable there on every visit. Sign back in later at https://getwireai.com/login; register further apps at https://getwireai.com/console/register. Keys are per environment (dev / prod / staging). Nothing renders without both.
+- **Render:** build the config once and gate on it (`wireConfigFromEnv` returns `null` when the env is unset, and `config` is a required non-null prop), then drop `<WireOnboarding config={config} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} ... />` into the signup flow.
 - **The join key.** Pass `userContext={activationJoinContext(deviceKey)}` on `<WireOnboarding>`, or, when the app owns no device id, pass a working `storage` and leave `userContext` alone so the kit injects its own (⛔ never hand-build it from the synchronous `resolveAutoDeviceKey`, which cannot report whether the id survives the launch). `user_context.device_key` is the ONLY thing that joins an onboarding session to the app's later events; omit it and the `activated` funnel reads zero with no error.
-- **Lifecycle (mount it once):** `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the persisted auto `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. Storage that throws or rejects counts as no storage since 0.14.0: the events fire with no auto key rather than a per-launch one. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and `useSessionStart` follows the same auto-key rule since 0.14.0.
+- **Lifecycle (mount it once):** `useLifecycleEvents({ serverUrl, apiKey, appId, storage }, { deviceKey, sessionCount, userId })` at the app root, before anything else touches analytics. The first argument is a `LifecycleConfig` built from explicit fields, NOT the `WireOnboardingConfig` (`wireConfigFromEnv` can return `null`, and `storage` is not a config field). It is the only path that emits `app.first_open`, it registers the per-open session id `createAnalytics` / `wire.track` / the gates all correlate to, and with a `storage` adapter in that first argument it stamps the persisted auto `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. Storage that throws or rejects counts as no storage since 0.14.0: the events fire with no auto key rather than a per-launch one. `sessionCount` in the second argument is the HOST's obligation: a counter the app persists and increments once per open, starting at 1. A hardcoded `1` compiles and pins every user at `returning: false` forever with no error anywhere. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`, and `useSessionStart` follows the same auto-key rule since 0.14.0.
 - **Capture is deterministic.** `onComplete` returns an `OnboardingResult`: `answers` and `raw` always, plus (since 0.13.6) `plan` when the backend sent an onboarding plan and `variant` when the tenant runs an experiment and the backend assigned an arm. No second LLM call. Persist all answers through the app's normal profile-update path. Those two extra keys are set ONLY when the backend actually sent them, so a run without them returns exactly the object earlier versions returned, and the kit interprets neither: validate `plan` before applying it.
 - **It can never break onboarding.** Pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
 
 ## Helpers (the reusable substrate)
 
 - `wireConfigFromEnv({ appId, metadata? })` → config or null (reads `EXPO_PUBLIC_WIREAI_API_KEY`/`_SERVER_URL`/`_APP_ID`).
-- `isOnboardingEnabled({ remote? })` → the standard gate (transport present: apiKey + serverUrl). No on/off env flag; `remote` is an optional kill-switch the app passes in.
+- `isOnboardingEnabled({ remote?, config? })` → the standard gate (transport present: apiKey + serverUrl). No on/off env flag; `remote` is an optional kill-switch the app passes in, and `config` forwards `WireConfigOverrides` (a programmatic apiKey/serverUrl) to the transport-present check.
 - `WIRE_ONBOARDING_EVENTS` + `toAnalyticsEvent(event)` → canonical `wire_onboarding_*` funnel names; log via the app's own analytics.
 - `attributionMetadata(a)` → shape install/ad attribution into `config.metadata` (forwarded to the agent).
 - `reportClientEvent(target, event)` / `reportClientEvents` / `makeSessionId` (ROOT-exported, not a subpath) → report device-only funnel events. Contract: `POST {serverUrl}/v1/events`, header `Authorization: Bearer {apiKey}`, body `{ "events": [ ... ] }`; `target = { serverUrl, apiKey }` from the config. `<WireOnboarding>` does this automatically: `dropped` on unmount-without-complete, `client_fallback` on degrade-to-static. Hosts must not double-report fallback.
@@ -30,10 +30,10 @@
 
 The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (each keeps the onboarding UI out of an analytics-only bundle):
 
-- `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section. Also `wireDoctor({ target, storage })`, the DEV-ONLY self-check: four `{name, ok, detail}` checks (target shape, server reachability, storage writability, and a `dry_run` round trip whose verdict is `written === 1 && skipped === 0` read from the ack body, because `/v1/events` answers 200 for a batch it discards). It never throws, never prints any part of the apiKey, and does nothing at all when `__DEV__` is unset.
-- `@wireai/activation/reviews`: the in-app review gate. `useReviewGate`, `fetchReviewDecision` (server AI seam; a `{fire:false}` survives intact), `ReviewGate` UI. `minSessions` defaults to 2 (never prompts on the first session; a server decision still overrides).
+- `@wireai/activation/analytics`: `createAnalytics({ serverUrl, apiKey, storage })` (Segment/PostHog-shaped `track` / `screen` / `identify` / `setUserContext` / `reset` over an offline-first queue), `createScreenTracker` / `screenTrackingHandler` (auto screen views), `reportAppEvent`, `createEventQueue`, `clearUserContext` (logout). Rich `WireUserContext` supports an opt-in `userEmail` (raw by default, `hashEmail` to fold) and auto-mints a persisted per-install `device_key`. `identify` refuses email-shaped ids unless `allowEmailAsUserId`. See the README "Rich user context & PII" section. Also `wireDoctor({ target, storage, join })`, the DEV-ONLY self-check: five `{name, ok, detail}` checks (target shape, server reachability, storage writability, a `dry_run` round trip whose verdict is `written === 1 && skipped === 0` read from the ack body because `/v1/events` answers 200 for a batch it discards, and `join_key`). It never throws, never prints any part of the apiKey or the device key, and does nothing at all when `__DEV__` is unset. `join_key` answers whether the session will carry a `user_context.device_key` (host-supplied or the kit's auto-injected one), and it needs the `join: { appId, userContext, autoJoinKey }` argument; omitting `join` FAILS that check rather than skipping it. It is strictly read-only: no mint, no identity-registry write, nothing persisted. Read the scope of a green report: it now says events reach the server AND can be joined. `wireDoctor` still does not check that the lifecycle hook is mounted and does not check `min_sessions`, so an integration missing either reports all-green while its `activated` funnel stays permanently at zero.
+- `@wireai/activation/reviews`: the in-app review gate. `useReviewGate`, `fetchReviewDecision` (server AI seam; a `{fire:false}` survives intact), `ReviewGate` UI. `minSessions` defaults to 2 (never prompts on the first session; a server decision still overrides). THE GATE NEEDS SYNCHRONOUS STORAGE: pass `storage` to the hook, or mount `CoachmarkProvider` with one, as a `CoachmarkStorage` whose `getItem(key)` returns `string | null` and not a Promise. That is a DIFFERENT shape from `<WireOnboarding storage>`, which takes the AsyncStorage-style adapter. Without it the app-open counter is pinned at 1 forever, the fail-closed `minSessions` rule can never be met, and the gate silently never fires; an async adapter is detected and substituted with a fail-closed store, same outcome. The hook's `config` is the GATE's config (it needs an `id`), not the transport config, and `decision` takes `served ?? undefined` because the fetch resolves `ReviewDecisionResponse | null`. `<ReviewGate>` has no `gate` prop: render it on `gate.visible` and pass `onShown={gate.markShown}` + `onResolved={gate.markResolved}`, which are what persist the cooldown and the once-per-version seen gate. Omit them and it compiles, shows, and re-prompts forever. Full wiring: the "Wiring `<ReviewGate>`" block in AGENTS.md.
 - `@wireai/activation/questionnaire`: the pre-onboarding questionnaire gate. `useQuestionnaireGate`, `fetchQuestionnaireDecision` (same server seam; a body without a boolean `fire` resolves to null, never shows).
-- `createRevenueCatBridge({ analytics, entitlementId })` (ROOT-exported) → the RevenueCat purchase funnel: `paywallShown` / `checkoutStarted` / `purchaseCompleted` / `purchaseFailed` / `purchasesRestored` / `syncPlanTier`, emitting the canonical `wire_paywall_shown` / `wire_checkout_started` / `wire_purchase_completed` / `wire_purchase_failed` / `wire_purchase_restored` names. The kit does NOT depend on `react-native-purchases` (a native module); the RevenueCat objects are typed structurally, so a host passes the real ones. THE JOIN KEY between a purchase and an onboarding is `user_context.device_key`, never `session_id` (an onboarding session id is the A2A contextId, an app-event session id is the per-open id, and they are separate spaces): pass the same device key to `createAnalytics`/`createWireActivation` AND to `<WireOnboarding userContext={activationJoinContext(deviceKey)} />`.
+- `createRevenueCatBridge({ analytics, entitlementId })` (ROOT-exported) → the RevenueCat purchase funnel: `paywallShown` / `checkoutStarted` / `purchaseCompleted` / `purchaseFailed` / `purchasesRestored` / `syncPlanTier`, emitting the canonical `wire_paywall_shown` / `wire_checkout_started` / `wire_purchase_completed` / `wire_purchase_failed` / `wire_purchase_restored` names. The kit does NOT depend on `react-native-purchases` (a native module); the RevenueCat objects are typed structurally, so a host passes the real ones. THE JOIN KEY between a purchase and an onboarding is `user_context.device_key`, never `session_id` (an onboarding session id is the A2A contextId, an app-event session id is the per-open id, and they are separate spaces): pass the same device key to `createAnalytics`/`createWireActivation` AND to `<WireOnboarding userContext={activationJoinContext(deviceKey)} ... />`.
 - `useWireActivation({ serverUrl, apiKey, deviceKey? })` → `{ track, sessionId, revalidation }` (ROOT-exported; React-free factory `createWireActivation(config)`). `await track(name, meta?)` POSTs an `app_event` (`question_key=name`) under the current session, resolves `true` on 2xx, and bumps `revalidation`; list `revalidation` in a `fetchReviewDecision` / `fetchQuestionnaireDecision` effect's deps so a review/questionnaire gate re-fetches and fires off an in-app action instead of the host hand-rolling session-id + await-POST + revalidate.
 
 ## Files
@@ -45,4 +45,4 @@ The package is more than `<WireOnboarding>`. Tree-shakeable subpath exports (eac
 
 ## Fastest path
 
-Run the `wire-rn-integration` Claude skill. It detects the app's conventions, wires Metro, derives a theme, scaffolds the screen, wires a fallback, and type-checks. Otherwise use INTEGRATION_PROMPT.md.
+Paste [INTEGRATION_PROMPT.md](./INTEGRATION_PROMPT.md) into a coding agent. It ships in this package and drives the whole integration: detect the app's conventions, wire Metro, derive a theme, scaffold the screen, wire a fallback, and type-check.

package/package.json

@@ -1,17 +1,14 @@
 {
   "name": "@wireai/activation",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "private": false,
   "description": "Premium, fully-themable drop-in AI onboarding kit for React Native / Expo, on top of the open-source wireai-rn SDK.",
   "author": "Malik Chohra <malik@getwireai.com>",
   "license": "MIT",
-  "homepage": "https://github.com/chohra-med/wireai-onboarding#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/chohra-med/wireai-onboarding.git"
-  },
+  "homepage": "https://getwireai.com",
   "bugs": {
-    "url": "https://github.com/chohra-med/wireai-onboarding/issues"
+    "url": "https://getwireai.com/console/support",
+    "email": "malik@getwireai.com"
   },
   "keywords": [
     "react-native",
@@ -137,12 +134,12 @@
   "scripts": {
     "build": "tsup",
     "prepack": "npm run build",
-    "prepublishOnly": "npm run build && npm run test:canary",
+    "prepublishOnly": "npm run build && npm test",
     "typecheck": "tsc --noEmit",
     "pretest": "npm run build",
     "test": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"src/**/*.test.ts\" \"test/canary/**/*.test.tsx\"",
     "test:canary": "node --test --experimental-strip-types --import ./test/register-ts-resolver.mjs \"test/canary/**/*.test.tsx\"",
-    "check:contract": "node --no-warnings --experimental-strip-types scripts/check-events-contract.mjs",
+    "check:contract": "node --no-warnings --experimental-strip-types --import ./test/register-ts-resolver.mjs scripts/check-events-contract.mjs",
     "pack:tarball": "npm pack"
   },
   "peerDependencies": {

package/src/analytics/currentSession.ts

@@ -77,13 +77,93 @@ type GlobalWithSlot = typeof globalThis & {
 
 const globalSlot = globalThis as GlobalWithSlot;
 
+/**
+ * Subscribers to be told when the id above CHANGES.
+ *
+ * ── WHY A REGISTRY THAT ONLY EMITS IS NOT ENOUGH ─────────────────────────────────────────────────
+ * The gates' app-open counter is bumped from a `useState` INITIALIZER, i.e. exactly once per
+ * component instance. `bumpSessionCount` itself follows real app-opens correctly, but nothing ever
+ * calls it a second time on a screen that stays mounted — and iOS suspends rather than kills, so a
+ * home screen holding `useReviewGate` outlives many opens. `useLifecycleEvents` registers each one
+ * here and the SERVER's `min_sessions` advances, while `wire_review_<id>_sessions` sits at its launch
+ * value and the LOCAL `minSessions` rule is unsatisfiable for the life of the process. Silent, and
+ * fails toward a prompt that never shows.
+ *
+ * The fix is not a second counter: it is that this module — the one place that knows an open was
+ * registered — says so. The gates subscribe (through `useSyncExternalStore`) and re-ask
+ * `bumpSessionCount`, which was already idempotent per open, so a notification that names the SAME
+ * open changes nothing.
+ *
+ * EVERY write to the id slot notifies, including `ensureCurrentSessionId`'s mint and the test-only
+ * reset: `getCurrentSessionId` is the `useSyncExternalStore` snapshot, and a snapshot that can change
+ * without a notification is a torn read, not an optimisation.
+ *
+ * @globalSlot LATCH — the listener SET is created once and its identity is then stable, for the same
+ * reason `activation/revalidation`'s store is: a second write replaces the set every existing
+ * subscriber registered in, so their unsubscribes free the wrong set and a registration reaches
+ * nobody — silently, which is the whole failure class this seam exists to close. Its CONTENTS are
+ * live and mutated in place, which is why every accessor goes through `listeners()`.
+ */
+const SESSION_ID_LISTENERS_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:currentSessionIdListeners",
+);
+
+type GlobalWithListeners = typeof globalThis & {
+  [SESSION_ID_LISTENERS_SLOT]?: Set<() => void>;
+};
+
+const listenerSlot = globalThis as GlobalWithListeners;
+
+/** The ONE shared listener set, lazily created on the runtime global (never a second copy per bundle). */
+const listeners = (): Set<() => void> => {
+  const existing = listenerSlot[SESSION_ID_LISTENERS_SLOT];
+  if (existing) return existing;
+  const created = new Set<() => void>();
+  listenerSlot[SESSION_ID_LISTENERS_SLOT] = created;
+  return created;
+};
+
+/**
+ * Write the slot and, only on a REAL change, tell every subscriber. The single writer for all three
+ * public entry points, so "the snapshot moved" and "the subscribers were told" can never drift.
+ */
+const writeCurrentSessionId = (id: string | undefined): void => {
+  if (globalSlot[CURRENT_SESSION_ID_SLOT] === id) return;
+  globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+  // Iterate a snapshot so a listener that (un)subscribes during notify never corrupts the walk, and
+  // isolate each one: a throwing subscriber must not stop the others (fail-safe).
+  for (const listener of Array.from(listeners())) {
+    try {
+      listener();
+    } catch {
+      /* a subscriber's failure is not this registry's business */
+    }
+  }
+};
+
+/**
+ * Subscribe to app-open registrations. Returns an unsubscribe fn. Shaped for `useSyncExternalStore`
+ * over {@link getCurrentSessionId} — that pairing is what makes a mounted gate follow real opens
+ * instead of the one it sampled at mount.
+ *
+ * Internal seam — deliberately NOT on the public barrels (same as {@link isMintedSessionId}); the
+ * callers are `useReviewGate` / `useQuestionnaireGate`.
+ */
+export const subscribeCurrentSessionId = (listener: () => void): (() => void) => {
+  const set = listeners();
+  set.add(listener);
+  return () => {
+    set.delete(listener);
+  };
+};
+
 /**
  * Record the current per-open `session_id`. Called by `reportSessionStart` when it emits an
  * app-open. A blank / non-string id is ignored (the previous id stays current). Idempotent.
  */
 export const setCurrentSessionId = (id: string | undefined): void => {
   if (typeof id === "string" && id.length > 0) {
-    globalSlot[CURRENT_SESSION_ID_SLOT] = id;
+    writeCurrentSessionId(id);
   }
 };
 
@@ -91,9 +171,17 @@ export const setCurrentSessionId = (id: string | undefined): void => {
 export const getCurrentSessionId = (): string | undefined =>
   globalSlot[CURRENT_SESSION_ID_SLOT];
 
-/** Test-only: forget the current session id so a unit test starts from a clean registry. */
+/** Test-only: forget the current session id so a unit test starts from a clean registry. Does NOT
+ *  clear the MINTED-id record (see `isMintedSessionId`), for the same reason the warn latch below is
+ *  not cleared: `makeSessionId()` never repeats, so a remembered fallback id can never again equal a
+ *  live one, and the record is overwritten by the next mint anyway. */
 export const resetCurrentSessionId = (): void => {
-  globalSlot[CURRENT_SESSION_ID_SLOT] = undefined;
+  writeCurrentSessionId(undefined);
+};
+
+/** Test-only: drop every subscriber so one case's mounted gate cannot be notified by the next. */
+export const resetCurrentSessionIdListeners = (): void => {
+  listeners().clear();
 };
 
 /** The one-time message. Hoisted so a prod mint does not rebuild a string nobody will read. */
@@ -120,6 +208,52 @@ type GlobalWithWarnSlot = typeof globalThis & { [MINT_WARNED_SLOT]?: boolean };
 
 const warnSlot = globalThis as GlobalWithWarnSlot;
 
+/**
+ * The id THIS PROCESS minted, so a reader can tell a fallback id from a real app-open.
+ *
+ * WHY IT HAS TO EXIST. A mint means "no app-open was registered and something still needed a
+ * `session_id`". It is a fallback for the wire, NOT evidence that the app was opened. But the mint
+ * writes the shared slot above (it must — see the header: every later event has to correlate to the
+ * same id), so a reader of `getCurrentSessionId()` cannot tell the two apart. `reviews/runtime`'s
+ * `currentOpenId` could not, and that cost an app-open: it pinned the launch with
+ * `observed = <the minted id>`, so its cold-start adopt branch (which keys off `observed ===
+ * undefined`) never fired and the REAL `app.session_started` that followed read as a genuinely NEW
+ * open. One launch counted as TWO, making the fail-closed `minSessions: 2` default — the guard from
+ * the 2026-07-16 one-star incident — satisfiable inside a user's FIRST session. It failed in the
+ * UNSAFE direction.
+ *
+ * Its OWN `Symbol.for` slot, for the same cross-bundle reason as the id itself: a plain module
+ * `let` would be per inlined bundle copy, so a mint reached through `./analytics` would be invisible
+ * to the gate reading through `.`.
+ *
+ * @globalSlot LIVE — a real process mints at most once (the mint only fires when the id slot is
+ * EMPTY), but a process that clears the id and mints again — `resetCurrentSessionId` in the suite —
+ * MOVES this, and it must move: a record still naming the previous launch's fallback would make the
+ * new one unrecognisable, and a fallback id would be counted as an app-open again. So a reader that
+ * caches this answers
+ * for a launch that is over. Read it at the moment of use, through `isMintedSessionId()`.
+ */
+const MINTED_SESSION_ID_SLOT: unique symbol = Symbol.for(
+  "@wireai/activation:mintedSessionId",
+);
+
+type GlobalWithMintedSlot = typeof globalThis & {
+  [MINTED_SESSION_ID_SLOT]?: string | undefined;
+};
+
+const mintedSlot = globalThis as GlobalWithMintedSlot;
+
+/**
+ * Was `id` MINTED by this process rather than registered as a real app-open?
+ *
+ * `false` for `undefined`, for any id a host registered through `setCurrentSessionId`, and for
+ * every id once the launch has moved on. Internal seam — deliberately NOT on the public barrels;
+ * the only caller is `reviews/runtime`'s `currentOpenId`, which must not count a fallback id as an
+ * app-open.
+ */
+export const isMintedSessionId = (id: string | undefined): boolean =>
+  id !== undefined && id === mintedSlot[MINTED_SESSION_ID_SLOT];
+
 /**
  * The current per-open `session_id`, MINTING and registering one when no app-open has been
  * registered yet. Always returns a non-empty string. Idempotent (a second call returns the same id)
@@ -141,7 +275,10 @@ export const ensureCurrentSessionId = (): string => {
   const existing = globalSlot[CURRENT_SESSION_ID_SLOT];
   if (typeof existing === "string" && existing.length > 0) return existing;
   const minted = makeSessionId();
-  globalSlot[CURRENT_SESSION_ID_SLOT] = minted;
+  writeCurrentSessionId(minted);
+  // Remember that WE minted it. A fallback id is not an app-open, and `reviews/runtime` has to be
+  // able to tell the difference or the real registration that follows counts as a second open.
+  mintedSlot[MINTED_SESSION_ID_SLOT] = minted;
   if (!warnSlot[MINT_WARNED_SLOT] && warnInDev(MINT_WARNING)) {
     warnSlot[MINT_WARNED_SLOT] = true;
   }

package/src/analytics/index.ts

@@ -44,7 +44,12 @@ export type { ClientEvent, ClientEventType, ClientEventTarget } from "./reportCl
 // `readEventsAck` is deliberately NOT re-exported here: the doctor imports it from the transport
 // module directly, so reuse costs nothing and the package's public surface stays as it was.
 export { wireDoctor } from "./wireDoctor";
-export type { WireDoctorCheck, WireDoctorReport, WireDoctorOptions } from "./wireDoctor";
+export type {
+  WireDoctorCheck,
+  WireDoctorReport,
+  WireDoctorOptions,
+  WireDoctorJoinTarget,
+} from "./wireDoctor";
 
 // ─── Canonical onboarding funnel names + kit-event mapper ──────────────────────
 export { WIRE_ONBOARDING_EVENTS, toAnalyticsEvent } from "./analyticsEvent";

package/src/analytics/reportClientEvent.ts

@@ -24,6 +24,7 @@
  * Fire-and-forget: this never throws into the UI and never awaits — analytics must never
  * be able to break onboarding.
  */
+import { DEADLINE_EXPIRED, withDeadline } from "../utils/withDeadline";
 import type { DeviceContext } from "../device/deviceContext";
 
 /** Event types a CLIENT may report. The rest of the funnel is server-side; sending those
@@ -368,16 +369,24 @@ export const reportClientEventsOutcome = async (
     const req = buildEventsRequest(target, events);
     // No target / nothing serializable: there is no endpoint to retry against.
     if (!req) return "refused";
-    const res = await fetch(req.url, req.init);
-    if (!res || !res.ok) return "unreachable";
-    // ONE body read, used for both the verdict and the dev warning — it can only be read once.
-    const ack = await readEventsAck(res);
-    if (!ack || ack.skipped <= 0) return "delivered";
-    if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
-      console.warn(describeDiscarded(ack));
-    }
-    // The server answered and declined THIS event. A retry is a re-decline.
-    return "refused";
+    // Under a deadline, BODY READ INCLUDED (see `utils/withDeadline`): this is the awaited path a
+    // host's `await wire.track()` sits on, and without a ceiling a hung POST parks it for the ~60s
+    // platform default. A ceiling cleared when the headers land would leave `readEventsAck` — which
+    // reads the body — uncapped, which is the `fetchWireFeatures` defect in a second place.
+    const outcome = await withDeadline(async (signal): Promise<SendOutcome> => {
+      const res = await fetch(req.url, { ...req.init, signal });
+      if (!res || !res.ok) return "unreachable";
+      // ONE body read, used for both the verdict and the dev warning — it can only be read once.
+      const ack = await readEventsAck(res);
+      if (!ack || ack.skipped <= 0) return "delivered";
+      if (typeof __DEV__ !== "undefined" && __DEV__ && typeof console !== "undefined" && console.warn) {
+        console.warn(describeDiscarded(ack));
+      }
+      // The server answered and declined THIS event. A retry is a re-decline.
+      return "refused";
+    });
+    // A deadline that expired means nothing came back — retryable, exactly like a network error.
+    return outcome === DEADLINE_EXPIRED ? "unreachable" : outcome;
   } catch {
     // Unreachable / missing-fetch / network — best-effort, and retryable.
     return "unreachable";

package/src/analytics/useAnalytics.ts

@@ -1,8 +1,8 @@
 /**
  * useAnalytics — a THIN optional React hook over the pure {@link createAnalytics} factory.
  *
- * It builds ONE analytics instance for the component's lifetime and returns it, so re-renders
- * never rebuild the queue or lose the in-memory user binding. React is a REQUIRED peer of the
+ * It builds ONE analytics instance for the component's lifetime and returns a STABLE FACADE over
+ * it (see below), so re-renders never rebuild the queue or lose the in-memory user binding. React is a REQUIRED peer of the
  * kit, so importing it here is allowed; the hook adds NO other dependency. Mirrors the existing
  * `createScreenTracker` / `useScreenTracking` split — the factory stays React-free, this is the
  * glue.
@@ -25,6 +25,45 @@ import {
  * instance is stable for the component's lifetime, held in a ref). Returns the {@link Analytics}
  * surface so the component can `track` / `screen` / `identify` and drive `notifyOnline` on reconnect.
  */
+/**
+ * The STABLE object the host holds, delegating to whatever instance is live AT CALL TIME.
+ *
+ * ── WHY THE HOOK CANNOT JUST RETURN THE INSTANCE ─────────────────────────────────────────────────
+ * React's StrictMode dev remount runs a mount effect **setup → cleanup → setup with no intervening
+ * render**. The cleanup below disposes the instance and nulls the ref; the component is still
+ * mounted, and no render happens to rebuild it. So the object the host was handed at render is a
+ * DISPOSED one: `EventQueue.enqueue` returns early when disposed, which makes every `track()` on it
+ * a silent no-op — no error, no warning, `size()` stays 0 — until the host's next render. Dev builds
+ * only (production `<StrictMode>` is a passthrough), but dev is where a developer verifies that
+ * their analytics work.
+ *
+ * ── WHY THIS SHAPE AND NOT THE TWO OBVIOUS ALTERNATIVES ──────────────────────────────────────────
+ * • Stop nulling the ref in the cleanup → the render guard reads `!ref.current`, so a real
+ *   credentials change would never rebuild. That trades a dev-only silence for a production one.
+ * • A `disposedRef` the render guard reads → the defining property of this window is that NO RENDER
+ *   HAPPENS in it. Any repair spelled at render time re-closes the same hole one line lower.
+ * What has to keep working is the reference the host is ALREADY HOLDING, and only a stable
+ * indirection can do that. It also fixes the ordinary credentials-swap case for free: a host that
+ * captured the instance in a callback used to hold the pre-swap queue.
+ *
+ * ⚠️ A facade is safe only while it is COMPLETE. `Analytics` growing a member this forgets would be
+ * `undefined` on the object every host holds — a TypeError with a green typecheck, since the facade
+ * is written against the very declaration that changed. `test/canary/strictModeInstanceHandoff`
+ * compares the runtime key sets against `createAnalytics` and goes red the day they drift.
+ */
+const stableAnalyticsFacade = (live: () => Analytics | undefined): Analytics => ({
+  track: (event, props) => live()?.track(event, props),
+  screen: (name, props) => live()?.screen(name, props),
+  identify: (userId, traits) => live()?.identify(userId, traits),
+  setUserContext: (partial) => live()?.setUserContext(partial),
+  reset: () => live()?.reset(),
+  flush: () => live()?.flush(),
+  notifyOnline: () => live()?.notifyOnline(),
+  // After a real unmount there is no instance and nothing pending on it — 0 is the honest answer.
+  size: () => live()?.size() ?? 0,
+  dispose: () => live()?.dispose(),
+});
+
 export const useAnalytics = (
   config: CreateAnalyticsConfig,
   options: AnalyticsOptions = {},
@@ -32,6 +71,10 @@ export const useAnalytics = (
   // One instance per mount; kept in a ref so re-renders never rebuild the queue or drop the binding.
   const ref = useRef<Analytics | undefined>(undefined);
   const prevKeys = useRef<string>("");
+  // The construction inputs, read fresh, so the rebuild below uses the CURRENT config rather than
+  // the first render's closure.
+  const inputs = useRef({ config, options });
+  inputs.current = { config, options };
 
   const currentKeys = `${config.serverUrl}|${config.apiKey}|${config.appId}`;
   if (!ref.current || prevKeys.current !== currentKeys) {
@@ -44,6 +87,34 @@ export const useAnalytics = (
     ref.current = createAnalytics(config, options);
   }
 
+  // Built once and never replaced: it is the whole point that the host's reference outlives every
+  // instance behind it.
+  const facade = useRef<Analytics | undefined>(undefined);
+  if (!facade.current) facade.current = stableAnalyticsFacade(() => ref.current);
+
+  // ⛔ DECLARED FIRST, AND THAT ORDER IS LOAD-BEARING. React runs every cleanup, then every setup.
+  // With the device-key effect below declared first, its second setup would run while `ref.current`
+  // was still `undefined` (this effect not having re-run yet), `?.setUserContext` would silently
+  // no-op, and the host's real device key would be dropped for the life of the mount — which is the
+  // very defect the paragraph below exists to describe.
+  //
+  // SETUP: rebuild the instance this effect's own cleanup disposed. On a first mount there is
+  // nothing to do (render just built one); after StrictMode's cleanup→setup there is, and no render
+  // is coming to do it.
+  // UNMOUNT: give the storage claim and the retry timer back. A screen that mounts this hook is
+  // built and torn down repeatedly (navigation, Fast Refresh, StrictMode's double-invoke), and each
+  // rebuild used to leave the previous queue holding the appId's slot — so every remount after the
+  // first persisted into `…#2`, `…#3`, and the next launch read none of them.
+  useEffect(() => {
+    if (!ref.current) {
+      ref.current = createAnalytics(inputs.current.config, inputs.current.options);
+    }
+    return () => {
+      ref.current?.dispose();
+      ref.current = undefined;
+    };
+  }, []);
+
   // A LATE-ARRIVING host device key must still reach the instance.
   //
   // `createAnalytics` copies `config.userContext` into a closure at construction and never re-reads
@@ -64,17 +135,5 @@ export const useAnalytics = (
     if (hostDeviceKey) ref.current?.setUserContext({ deviceKey: hostDeviceKey });
   }, [hostDeviceKey]);
 
-  // UNMOUNT: give the storage claim and the retry timer back. A screen that mounts this hook is
-  // built and torn down repeatedly (navigation, Fast Refresh, StrictMode's double-invoke), and each
-  // rebuild used to leave the previous queue holding the appId's slot — so every remount after the
-  // first persisted into `…#2`, `…#3`, and the next launch read none of them.
-  useEffect(
-    () => () => {
-      ref.current?.dispose();
-      ref.current = undefined;
-    },
-    [],
-  );
-
-  return ref.current;
+  return facade.current;
 };