@wireai/activation 0.1.1 → 0.2.0

package/src/session-analytics/lifecycle.ts

@@ -0,0 +1,236 @@
+/**
+ * lifecycle — the TOP-OF-FUNNEL app lifecycle events that sit ABOVE onboarding: `app.first_open`
+ * (once ever per install) and `app.session_started` (per app-open). They compose with, and never
+ * duplicate, the events the funnel already records.
+ *
+ * WHERE THIS FITS (one funnel, no double counting):
+ *   • `app.first_open`      → THIS module, once ever (persisted flag). The in-app "install" proxy.
+ *   • `app.session_started` → the EXISTING {@link reportSessionStart} emitter (per app-open). This
+ *                             module REUSES it (routed through the offline queue), never re-emits.
+ *   • onboarding started / completed / activated → ALREADY recorded: the server writes
+ *     `session_started` + `completed` during the A2A flow, and the client reports `dropped` /
+ *     `client_fallback` / `identify` via `reportClientEvent`. This module does NOT touch them —
+ *     emitting them here would double-count. It only ADDS the two lifecycle events above them.
+ *
+ * WIRE CONTRACT (identical to `app.session_started`): both lifecycle events are stored as
+ * `event_type='app_event'` with the name in `question_key` (the server's `_event_name` returns
+ * `question_key` for an `app_event`, which a trigger matches). `app.first_open` uses the SAME
+ * `app.*` namespace + the SAME event shape as `app.session_started` — no bespoke `event_type`,
+ * no invented contract. `device_key` rides in the non-PII `user_context` bucket; `app_id` +
+ * `environment` are filled server-side.
+ *
+ * TWO FIRST-CLASS ENTRY POINTS (mirrors reportSessionStart vs useSessionStart):
+ *   • `reportFirstOpen(...)` / `wireLifecycleEvents(...)` — pure, React-free, for a host that owns
+ *     its own app-open path.
+ *   • `useLifecycleEvents(...)` — the batteries-included React hook (in `useLifecycleEvents.ts`).
+ *
+ * OFFLINE-FIRST: pass the Brief-01 event queue's `enqueue` as the `sink` and every lifecycle event
+ * is buffered + persisted + retried instead of a blind fetch. Without a sink they degrade to a
+ * direct fire-and-forget POST.
+ *
+ * PRIVACY (hard rule, same as the rest of the kit): NO GPS/location, NO advertising id. Nothing
+ * here carries a coordinate or an ad id — a host adopting it changes no store privacy declaration.
+ *
+ * FIRE-AND-FORGET: like every analytics path in the kit, nothing here throws into the UI, awaits
+ * in the caller, or hangs the app — storage reads race a short timeout, writes swallow errors.
+ */
+import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
+import type { DeviceContext } from "../device/deviceContext";
+import { sanitizeUserId } from "../identity/userIdentity";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+import { reportSessionStart, SESSION_STARTED_EVENT } from "./reportSessionStart";
+
+/** The canonical event name for the first-ever app open. Same `app.*` namespace as
+ *  {@link SESSION_STARTED_EVENT}; a trigger keys off this exact string. */
+export const FIRST_OPEN_EVENT = "app.first_open" as const;
+
+/** Storage key for the once-ever first-open flag, e.g. `wireai:first_open:myelino`. Mirrors the
+ *  `wireai:<concern>:<appId>` namespacing of {@link sessionStorageKey}. */
+export const firstOpenStorageKey = (appId: string): string => `wireai:first_open:${appId}`;
+
+/** Ceiling on the flag read — a hung adapter degrades to the in-memory latch, never a stuck gate. */
+const READ_TIMEOUT_MS = 1_500;
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+  let timer: ReturnType<typeof setTimeout>;
+  const timeout = new Promise<undefined>((resolve) => {
+    timer = setTimeout(() => resolve(undefined), ms);
+  });
+  return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+};
+
+// ── First-open in-memory latch ───────────────────────────────────────────────
+// Covers TWO cases the persisted flag can't: (1) two near-simultaneous calls in one process (the
+// flag read is async, so a synchronous latch is what guarantees at-most-one before any await), and
+// (2) the documented DEGRADED no-storage mode (fires once per process). Keyed by appId.
+const _firstOpenLatched = new Set<string>();
+
+/** Test-only: forget the first-open latch so a unit test starts from a clean process state. */
+export const resetFirstOpenLatch = (): void => {
+  _firstOpenLatched.clear();
+};
+
+/** Shared inputs for a lifecycle event. Everything is optional except a transport (`target` for the
+ *  direct-POST fallback, or a `sink`). A pre-auth open (no user yet) is a valid device-only event. */
+export interface LifecycleEventInput {
+  /** Where to POST if no `sink` is wired (the tenant transport, same as `WireOnboardingConfig`). */
+  target?: ClientEventTarget;
+  /** Preferred transport: route the built event HERE (the offline queue's `enqueue`). */
+  sink?: (event: ClientEvent) => void;
+  /** The per-open session id. Defaults to a fresh `makeSessionId()`. */
+  sessionId?: string;
+  /** The host's OPAQUE pseudonymous user id (NOT PII). Sanitized + capped; omitted pre-auth. */
+  userId?: string;
+  /** A stable, non-PII device id the host owns. Rides in `user_context.device_key`. */
+  deviceKey?: string;
+  /** The host's local open-counter value. Drives `returning` + "Nth session". */
+  sessionCount?: number;
+  /** Host app version (e.g. "1.4.2"), if cheaply available. */
+  appVersion?: string;
+  /** Platform string (e.g. "ios"), if cheaply available. */
+  platform?: string;
+  /** An optional richer device snapshot (from `collectDeviceContext()`); the hook fills this. */
+  device?: DeviceContext;
+  /** Small non-PII extras, stored as a JSON string in the event `meta`. */
+  meta?: Record<string, unknown>;
+}
+
+/** Options for {@link reportFirstOpen}. Adds the once-ever persistence inputs on top of the shared
+ *  lifecycle inputs. Without `storage` it degrades to the in-memory latch (once per process). */
+export interface ReportFirstOpenOptions extends LifecycleEventInput {
+  /** Host persistence (AsyncStorage subset). The once-ever flag lives here — it is what survives an
+   *  app kill. Omit it for the documented degraded (in-memory, once-per-process) mode. */
+  storage?: WireOnboardingStorage;
+  /** Tenant/app id — namespaces the persisted flag (`wireai:first_open:<appId>`). */
+  appId?: string;
+}
+
+/**
+ * Build the `app_event` payload shared by `app.first_open` and `app.session_started`. This is a
+ * BYTE-FOR-BYTE mirror of the field logic in {@link reportSessionStart} — same `event_type`, same
+ * `question_key`-as-name contract, same `user_context` bucket, same optional fields — so the two
+ * lifecycle events are one contract with two names. Do NOT let these diverge (see lifecycle.test).
+ */
+const buildLifecycleEvent = (questionKey: string, opts: LifecycleEventInput): Record<string, unknown> => {
+  const userContext: Record<string, string | number | boolean> = {};
+  if (opts.deviceKey) userContext.device_key = opts.deviceKey;
+  if (typeof opts.sessionCount === "number" && Number.isFinite(opts.sessionCount)) {
+    userContext.session_count = opts.sessionCount;
+    userContext.returning = opts.sessionCount > 1;
+  }
+  if (opts.appVersion) userContext.app_version = opts.appVersion;
+  if (opts.platform) userContext.platform = opts.platform;
+
+  const event: Record<string, unknown> = {
+    event_type: "app_event",
+    question_key: questionKey,
+    session_id: opts.sessionId ?? makeSessionId(),
+  };
+  const userId = sanitizeUserId(opts.userId);
+  if (userId) event.user_id = userId;
+  if (Object.keys(userContext).length > 0) event.user_context = userContext;
+  if (opts.device) event.device = opts.device;
+  if (opts.meta && Object.keys(opts.meta).length > 0) event.meta = JSON.stringify(opts.meta);
+  return event;
+};
+
+/** Route a built event to the wired sink, else a direct fire-and-forget POST. Never throws. */
+const routeLifecycleEvent = (event: Record<string, unknown>, opts: LifecycleEventInput): void => {
+  try {
+    if (opts.sink) {
+      opts.sink(event as ClientEvent);
+      return;
+    }
+    const target = opts.target;
+    if (!target?.serverUrl) return;
+    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
+    void fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ events: [event] }),
+    }).catch(() => {
+      // Network/transport error — analytics is best-effort, swallow.
+    });
+  } catch {
+    // A throwing sink, URL/JSON error, or a missing fetch — swallow.
+  }
+};
+
+const emitFirstOpen = (opts: ReportFirstOpenOptions): void => {
+  routeLifecycleEvent(buildLifecycleEvent(FIRST_OPEN_EVENT, opts), opts);
+};
+
+/**
+ * Emit `app.first_open` EXACTLY ONCE EVER per install. Fire-and-forget; returns immediately.
+ *
+ *   • With `storage`: reads the persisted flag (`wireai:first_open:<appId>`). Absent → emit, then
+ *     write the flag (survives app kills, so a second launch is a no-op). Present → no-op.
+ *   • Race guard: an in-memory latch is set SYNCHRONOUSLY before the async read, so two
+ *     near-simultaneous calls fire at most once.
+ *   • Without `storage`: degraded mode — fires once per PROCESS via the latch only (documented).
+ */
+export const reportFirstOpen = (opts: ReportFirstOpenOptions): void => {
+  const appId = opts.appId ?? "default";
+
+  // Synchronous latch FIRST: guarantees at-most-one before any await (same-process race guard) and
+  // is the sole guard in the no-storage degraded mode.
+  if (_firstOpenLatched.has(appId)) return;
+  _firstOpenLatched.add(appId);
+
+  const storage = opts.storage;
+  if (!storage) {
+    // Degraded: no persistence to survive a kill → the latch fires it once per process.
+    emitFirstOpen(opts);
+    return;
+  }
+
+  const key = firstOpenStorageKey(appId);
+  void (async () => {
+    try {
+      const seen = await withTimeout(storage.getItem(key), READ_TIMEOUT_MS);
+      // A prior launch already fired + wrote the flag → once-ever satisfied, no-op.
+      if (seen) return;
+      emitFirstOpen(opts);
+      try {
+        // Best-effort persist: a failed write just means the next launch may re-fire once.
+        void storage.setItem(key, JSON.stringify({ ts: Date.now() })).catch(() => {});
+      } catch {
+        // Missing/broken storage write — swallow.
+      }
+    } catch {
+      // Unreadable flag → the in-memory latch still caps us at one fire this process.
+      emitFirstOpen(opts);
+    }
+  })();
+};
+
+/** Options for {@link wireLifecycleEvents}: the shared lifecycle inputs + first-open persistence. */
+export interface WireLifecycleOptions extends ReportFirstOpenOptions {}
+
+/**
+ * Wire BOTH lifecycle events in one call for a host that owns its own app-open path (the non-hook
+ * counterpart to {@link useLifecycleEvents}). Fires `app.first_open` (once ever) and one
+ * `app.session_started` for THIS open through the EXISTING {@link reportSessionStart} emitter (so
+ * the once-per-open guard still applies — pass the same `sessionId` and it never double-fires).
+ * Route both through the same `sink` (the offline queue) to buffer them. Fire-and-forget.
+ */
+export const wireLifecycleEvents = (opts: WireLifecycleOptions): void => {
+  reportFirstOpen(opts);
+  reportSessionStart({
+    target: opts.target,
+    sink: opts.sink,
+    sessionId: opts.sessionId,
+    userId: opts.userId,
+    deviceKey: opts.deviceKey,
+    sessionCount: opts.sessionCount,
+    appVersion: opts.appVersion,
+    platform: opts.platform,
+    device: opts.device,
+    meta: opts.meta,
+  });
+};
+
+// Re-exported so callers wiring lifecycle events have the session name alongside the first-open one.
+export { SESSION_STARTED_EVENT };

package/src/session-analytics/reportSessionStart.ts

@@ -31,7 +31,7 @@
  * awaits, and swallows a missing target / bad URL / missing fetch / network error. Analytics must
  * never be able to break the app.
  */
-import { makeSessionId, type ClientEventTarget } from "../analytics/reportClientEvent";
+import { makeSessionId, type ClientEvent, type ClientEventTarget } from "../analytics/reportClientEvent";
 import type { DeviceContext } from "../device/deviceContext";
 import { sanitizeUserId } from "../identity/userIdentity";
 
@@ -68,6 +68,15 @@ export interface ReportSessionStartOptions {
   meta?: Record<string, unknown>;
   /** Set `false` to bypass the once-per-open guard (default on). See {@link resetSessionStartGuard}. */
   once?: boolean;
+  /**
+   * OPTIONAL transport sink. When provided, the built `app.session_started` event is routed HERE
+   * (e.g. the offline-first event queue's `enqueue`) INSTEAD of this emitter's own direct `fetch`,
+   * while KEEPING the once-per-open guard above. This is how the lifecycle wiring
+   * (`useLifecycleEvents` / `wireLifecycleEvents`) offline-buffers session-start WITHOUT adding a
+   * second session emitter: one emitter, one guard, now durable. Omit it for the direct-POST path.
+   * A throwing sink is swallowed — analytics must never surface into the UI.
+   */
+  sink?: (event: ClientEvent) => void;
 }
 
 // ── Once-per-open guard ──────────────────────────────────────────────────────
@@ -89,7 +98,9 @@ export const resetSessionStartGuard = (): void => {
  */
 export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
   const target = opts.target;
-  if (!target?.serverUrl) return;
+  // A wired sink is a valid transport on its own — it owns the target (the queue's serverUrl), so
+  // this emitter needs its own `target` ONLY for the direct-fetch fallback.
+  if (!opts.sink && !target?.serverUrl) return;
 
   const sessionId = opts.sessionId ?? makeSessionId();
 
@@ -105,10 +116,6 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
   }
 
   try {
-    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
-    const headers: Record<string, string> = { "Content-Type": "application/json" };
-    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
-
     // Non-PII correlation bucket. device_key is read by the server to group a device's sessions;
     // session_count / returning / app_version / platform feed per-user retention analytics.
     const userContext: Record<string, string | number | boolean> = {};
@@ -131,6 +138,19 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
     if (opts.device) event.device = opts.device;
     if (opts.meta && Object.keys(opts.meta).length > 0) event.meta = JSON.stringify(opts.meta);
 
+    // Preferred transport: an injected sink (the offline-first event queue's `enqueue`), which
+    // buffers + persists + retries. The once-guard above already ran, so this stays the single
+    // session emitter with a single guard — now durable.
+    if (opts.sink) {
+      opts.sink(event as ClientEvent);
+      return;
+    }
+
+    // Fallback: this emitter's own direct POST when no sink is wired.
+    if (!target?.serverUrl) return;
+    const url = `${target.serverUrl.replace(/\/$/, "")}/v1/events`;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (target.apiKey) headers.Authorization = `Bearer ${target.apiKey}`;
     void fetch(url, {
       method: "POST",
       headers,
@@ -139,6 +159,6 @@ export const reportSessionStart = (opts: ReportSessionStartOptions): void => {
       // Network/transport error — analytics is best-effort, swallow.
     });
   } catch {
-    // URL construction, JSON serialization, or a missing fetch — swallow.
+    // URL construction, JSON serialization, a throwing sink, or a missing fetch — swallow.
   }
 };

package/src/session-analytics/useLifecycleEvents.ts

@@ -0,0 +1,184 @@
+/**
+ * useLifecycleEvents — the batteries-included React hook that wires the TOP-OF-FUNNEL lifecycle
+ * events in ONE place: `app.first_open` (once ever) on mount, and `app.session_started` on every
+ * real app-open, both offline-buffered through the Brief-01 event queue.
+ *
+ * ONE emitter, one guard, no double-emit: session-start goes through the EXISTING
+ * {@link reportSessionStart} emitter (routed via a `sink`), NOT a second session emitter — so a
+ * host must use EITHER this hook OR `useSessionStart`, never both (both would fire an app-open).
+ * The once-per-open guard dedupes re-renders within this hook.
+ *
+ * Firing moments mirror {@link useSessionStart} exactly:
+ *   • ON MOUNT — the app opened (cold start / provider first render). `app.first_open` fires here
+ *     too (once ever, gated by the persisted flag in `reportFirstOpen`).
+ *   • ON FOREGROUND after a real background of at least {@link BACKGROUND_SESSION_MS} (30 min) — a
+ *     new app-open, so a fresh `app.session_started` fires. A quick app-switch does NOT count.
+ *
+ * OFFLINE-FIRST by default: pass your shared {@link EventQueue}'s `enqueue` as `options.sink` to
+ * route both events through your one queue. If you pass no sink, the hook lazily creates its OWN
+ * offline queue (dedicated storage key, so it never collides with your main queue) from the config
+ * + storage. Either way lifecycle events are buffered + persisted + retried, never lost offline.
+ *
+ * Dependency policy: `AppState` + `Platform` are RN built-ins (no new dep); the device snapshot is
+ * the kit's own dependency-free `collectDeviceContext()`; the queue is the dependency-free Brief-01
+ * `createEventQueue`. The pure `reportFirstOpen` / `wireLifecycleEvents` (in lifecycle.ts) import no
+ * React — this hook is the only React surface.
+ */
+import { useEffect, useRef } from "react";
+import { AppState, Platform, type AppStateStatus } from "react-native";
+
+import { createEventQueue, type EnvelopeSource, type EventQueue } from "../analytics/eventQueue";
+import type { ClientEvent, ClientEventTarget } from "../analytics/reportClientEvent";
+import { collectDeviceContext } from "../device/deviceContext";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+import { reportFirstOpen } from "./lifecycle";
+import { reportSessionStart } from "./reportSessionStart";
+import { BACKGROUND_SESSION_MS } from "./useSessionStart";
+
+/** Tenant transport + host persistence for the lifecycle wiring. Same creds as `WireOnboardingConfig`. */
+export interface LifecycleConfig {
+  /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+  serverUrl?: string;
+  /** Tenant API key; sent as `Authorization: Bearer`. */
+  apiKey?: string;
+  /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
+  appVersion?: string;
+  /** Tenant/app id — namespaces the first-open flag AND the hook's internal queue storage key. */
+  appId?: string;
+  /** Host storage (AsyncStorage subset). Enables the persisted once-ever first-open flag AND the
+   *  offline durability of the hook's internal queue. Omit it and both degrade to in-memory. */
+  storage?: WireOnboardingStorage;
+}
+
+/** Per-open identity + wiring the host supplies. All optional: a pre-auth open is device-only. */
+export interface UseLifecycleEventsOptions {
+  /** The host's opaque pseudonymous user id (NOT PII). Omitted before the user authenticates. */
+  userId?: string;
+  /** The host's local open-counter value for this open. Drives `returning` + "Nth session". */
+  sessionCount?: number;
+  /** A stable, non-PII device id the host owns. Groups this device's sessions server-side. */
+  deviceKey?: string;
+  /** Small non-PII extras forwarded on the event `meta`. */
+  meta?: Record<string, unknown>;
+  /** Set `false` to disable firing (e.g. behind a consent gate). Default enabled. */
+  enabled?: boolean;
+  /**
+   * Explicit transport sink (e.g. an existing shared `EventQueue.enqueue`). When provided, BOTH
+   * lifecycle events route here and the hook does NOT create its own queue — pass this to share ONE
+   * offline queue across the kit's analytics (screen tracking + lifecycle).
+   */
+  sink?: (event: ClientEvent) => void;
+  /**
+   * Context envelope (or provider) for the hook's internally-created queue. Ignored when `sink` is
+   * supplied (the host's queue owns envelope stamping).
+   */
+  envelope?: EnvelopeSource;
+}
+
+/**
+ * Fire `app.first_open` (once ever) + `app.session_started` (per open), offline-buffered. Returns
+ * nothing — a side-effecting hook. Safe to call with inline options (read through a ref, so
+ * changing `userId`/`sessionCount` never re-fires a session).
+ */
+export const useLifecycleEvents = (
+  config: LifecycleConfig | undefined,
+  options: UseLifecycleEventsOptions = {},
+): void => {
+  // Latest options/config through a ref so the mount/resume fires read fresh values without listing
+  // them as effect deps (which would re-fire a session on every prop change).
+  const latest = useRef({ config, options });
+  latest.current = { config, options };
+
+  // The resolved sink is created at most once and reused for every fire this mount.
+  const queueRef = useRef<EventQueue | undefined>(undefined);
+
+  useEffect(() => {
+    const resolveSink = (): ((event: ClientEvent) => void) | undefined => {
+      const { config: cfg, options: opts } = latest.current;
+      // Host-owned shared queue wins — one queue across the whole kit.
+      if (opts.sink) return opts.sink;
+      // No transport → no sink (events no-op rather than buffer forever against a dead target).
+      if (!cfg?.serverUrl) return undefined;
+      if (!queueRef.current) {
+        queueRef.current = createEventQueue({
+          target: { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" },
+          storage: cfg.storage,
+          // Dedicated key so the hook's internal queue never collides with a host's main queue.
+          storageKey: `wireai:evtq:lifecycle:${cfg.appId ?? "default"}`,
+          envelope: opts.envelope,
+        });
+      }
+      return queueRef.current.enqueue;
+    };
+
+    const targetOf = (cfg: LifecycleConfig | undefined): ClientEventTarget | undefined =>
+      cfg?.serverUrl ? { serverUrl: cfg.serverUrl, apiKey: cfg.apiKey ?? "" } : undefined;
+
+    // 1) first_open — once ever (persisted flag + in-memory latch inside reportFirstOpen).
+    {
+      const { config: cfg, options: opts } = latest.current;
+      if (opts.enabled !== false) {
+        const device = collectDeviceContext();
+        if (cfg?.appVersion && !device.appVersion) device.appVersion = cfg.appVersion;
+        reportFirstOpen({
+          target: targetOf(cfg),
+          sink: resolveSink(),
+          storage: cfg?.storage,
+          appId: cfg?.appId,
+          userId: opts.userId,
+          deviceKey: opts.deviceKey,
+          sessionCount: opts.sessionCount,
+          appVersion: cfg?.appVersion ?? device.appVersion,
+          platform: Platform.OS,
+          device,
+          meta: opts.meta,
+        });
+      }
+    }
+
+    // 2) session_start — the EXISTING emitter routed through the sink (offline-buffered, one guard).
+    const fireSession = () => {
+      const { config: cfg, options: opts } = latest.current;
+      if (opts.enabled === false) return;
+      if (!cfg?.serverUrl && !opts.sink) return;
+      const device = collectDeviceContext();
+      if (cfg?.appVersion && !device.appVersion) device.appVersion = cfg.appVersion;
+      reportSessionStart({
+        target: targetOf(cfg),
+        sink: resolveSink(),
+        // A fresh per-open id each fire; the emitter's once-guard dedupes within the open.
+        userId: opts.userId,
+        deviceKey: opts.deviceKey,
+        sessionCount: opts.sessionCount,
+        appVersion: cfg?.appVersion ?? device.appVersion,
+        platform: Platform.OS,
+        device,
+        meta: opts.meta,
+      });
+    };
+
+    // Mount = an app-open.
+    fireSession();
+
+    // Foreground after a real background = a new app-open.
+    let backgroundedAt: number | null = null;
+    const onChange = (state: AppStateStatus) => {
+      if (state === "background" || state === "inactive") {
+        if (backgroundedAt == null) backgroundedAt = Date.now();
+        return;
+      }
+      if (state === "active") {
+        const since = backgroundedAt;
+        backgroundedAt = null;
+        if (since != null && Date.now() - since >= BACKGROUND_SESSION_MS) fireSession();
+      }
+    };
+    const sub = AppState.addEventListener("change", onChange);
+    return () => {
+      // RN >= 0.65 returns a subscription with remove(); guard for older shims.
+      if (sub && typeof (sub as { remove?: () => void }).remove === "function") sub.remove();
+    };
+    // Mount-only effect: firing reads fresh values via `latest`, so no reactive deps.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+};