@wireai/activation 0.13.2 → 0.13.5

package/src/analytics/wireDoctor.ts

@@ -0,0 +1,330 @@
+/**
+ * wireDoctor: a DEV-ONLY, opt-in self-check that proves a fresh integration end to end before the
+ * first real user ever runs it.
+ *
+ * WHY IT EXISTS: the `/v1/events` endpoint answers HTTP **200** for a batch it throws away. It
+ * reports the refusal in the response body (`{written, skipped, errors:[{reason, field}]}`), so a
+ * mis-wired integration looks perfectly healthy from the outside while every event evaporates. A
+ * numeric `ts` did exactly that through 0.13.0. This turns that class of loss from something you
+ * discover in a funnel report weeks later into something the first run tells you.
+ *
+ * SHAPE: four independent checks, each a `{name, ok, detail}` unit that can be read (and tested)
+ * without the others. The report is data, never a thrown error and never a side effect on the host:
+ *
+ *   1. `target`      : is there a server URL and a key, and do they look like a key and a URL?
+ *   2. `reachability`: is the server actually there? (`GET /v1/events/contract`, public and cheap)
+ *   3. `storage`      : can the offline queue persist? (a write / read / delete probe)
+ *   4. `round_trip`   : does a REAL event survive REAL server validation? (a `dry_run` POST)
+ *
+ * NEVER THROWS, under any input, any network condition, or any hostile response object. A doctor
+ * that can crash the screen it is diagnosing is worse than no doctor.
+ *
+ * ⛔ NEVER PRINTS A SECRET. The `target` check reports the key's SHAPE (present / absent, length,
+ * whether the prefix is the expected one) and never any character of the key itself, in any
+ * `detail`, any log line, or any error. `wireDoctor.test.ts` asserts that with a sentinel key.
+ *
+ * COSTS A NON-CALLER NOTHING: it is a plain function behind the `./analytics` subpath, the package
+ * is `sideEffects: false`, and this module has no top-level side effects, so a host that never
+ * imports it never bundles it. It also mints no `globalThis` slot and retains no timer or listener.
+ *
+ * USAGE (dev builds only):
+ *
+ *   import { wireDoctor } from "@wireai/activation/analytics";
+ *
+ *   const report = await wireDoctor({
+ *     target: { serverUrl: "https://api.example.com", apiKey: DRIVELINE_KEY },
+ *     storage: AsyncStorage,
+ *   });
+ *   console.log(report.ok, report.checks);
+ */
+// Imported DIRECTLY from the transport module, never through `./index`: the barrel would pull the
+// whole analytics surface into anything that touches the doctor. `readEventsAck` is module-exported
+// for exactly this, so the doctor reads an ack with the SAME reader the send paths use rather than
+// growing a second one to drift.
+import {
+  buildEventsRequest,
+  makeSessionId,
+  readEventsAck,
+  type ClientEvent,
+  type ClientEventTarget,
+} from "./reportClientEvent";
+import type { WireOnboardingStorage } from "../session/persistedSession";
+
+/** RN sets this global; absent under node/SSR. Read defensively, exactly as `warnOnSkippedEvents` does. */
+declare const __DEV__: boolean | undefined;
+
+/** One diagnosis. `name` is stable and machine-readable; `detail` is for a human reading a console. */
+export type WireDoctorCheck = {
+  /**
+   * Stable id: `target` | `reachability` | `storage` | `round_trip` | `dev_only` | `internal_error`.
+   *
+   * `dev_only` means ONE thing and only that thing: `__DEV__` is unset or false, so nothing ran.
+   * `internal_error` is the separate catch-all for a failure that got past every check's own
+   * swallow. They are distinct names because a consumer branching on `dev_only` would otherwise
+   * read an internal fault as "this is a release build" and report a healthy skip.
+   */
+  name: string;
+  ok: boolean;
+  /** Human-readable result. ⛔ Never contains any part of an API key. */
+  detail: string;
+};
+
+/** What {@link wireDoctor} resolves to. `ok` is true only when EVERY check passed. */
+export type WireDoctorReport = {
+  ok: boolean;
+  checks: WireDoctorCheck[];
+};
+
+/** Input for {@link wireDoctor}. `storage` is optional: without it the queue runs in-memory only. */
+export type WireDoctorOptions = {
+  /** The same `{serverUrl, apiKey}` the kit is configured with. */
+  target: ClientEventTarget | undefined;
+  /**
+   * The host storage the offline queue would use (AsyncStorage-compatible). Omit it and the storage
+   * check reports the DEGRADED in-memory mode rather than failing.
+   */
+  storage?: WireOnboardingStorage;
+};
+
+/**
+ * The probe's own storage key. Deliberately NOT under the queue's `wireai:evtq:` namespace, so a
+ * doctor run can never read, overwrite or delete a pending backlog. A diagnostic that eats a user's
+ * unsent events is a worse bug than the one it was written to find.
+ */
+const PROBE_STORAGE_KEY = "wireai:doctor:probe";
+
+/** The `question_key` the synthetic round-trip event carries. `dry_run` means it is never written. */
+const PROBE_QUESTION_KEY = "wire_doctor_probe";
+
+/** Tenant keys start with this. Used ONLY for a boolean comparison; ⛔ never interpolated into a detail. */
+const EXPECTED_KEY_PREFIX = "wai_";
+
+/** Ceiling on each network check, so a hung server degrades to a failed check, never a hung caller. */
+const NETWORK_TIMEOUT_MS = 10_000;
+
+const check = (name: string, ok: boolean, detail: string): WireDoctorCheck => ({ name, ok, detail });
+
+/**
+ * `fetch` with a timeout that is ALWAYS cleared, including on rejection. Resolves `undefined`
+ * instead of throwing, so every caller stays on the happy path. Returns no timer to the caller and
+ * leaves none pending: a diagnostic must not keep the JS thread alive after it has answered.
+ */
+const fetchWithTimeout = async (url: string, init?: RequestInit): Promise<Response | undefined> => {
+  if (typeof fetch === "undefined") return undefined;
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  const timer = setTimeout(() => controller?.abort(), NETWORK_TIMEOUT_MS);
+  try {
+    return await fetch(url, controller ? { ...init, signal: controller.signal } : init);
+  } catch {
+    // Unreachable host, DNS failure, abort, or a missing fetch implementation.
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+/**
+ * CHECK 1: is the target usable at all?
+ *
+ * Reports the key's shape and NEVER its content: present/absent, character length, and whether the
+ * prefix matches what a tenant key starts with. Length and a yes/no are enough to tell "you pasted
+ * the wrong string" from "you pasted nothing", which is the entire diagnostic value here.
+ */
+const checkTarget = (target: ClientEventTarget | undefined): WireDoctorCheck => {
+  const serverUrl = target?.serverUrl;
+  if (typeof serverUrl !== "string" || serverUrl.trim().length === 0) {
+    return check("target", false, "no serverUrl configured: set `serverUrl` on the kit config.");
+  }
+  let parsedHost = false;
+  try {
+    const parsed = new URL(serverUrl);
+    parsedHost = parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    parsedHost = false;
+  }
+  if (!parsedHost) {
+    return check("target", false, "serverUrl is not a valid http(s) URL.");
+  }
+  const apiKey = target?.apiKey;
+  if (typeof apiKey !== "string" || apiKey.length === 0) {
+    return check("target", false, "serverUrl looks valid, but no apiKey is configured.");
+  }
+  // ⛔ `EXPECTED_KEY_PREFIX` is compared, never printed: it is itself a substring of a real key.
+  const prefixOk = apiKey.startsWith(EXPECTED_KEY_PREFIX);
+  return check(
+    "target",
+    true,
+    `serverUrl is a valid http(s) URL; apiKey present (${apiKey.length} chars, expected prefix: ${
+      prefixOk ? "yes" : "no"
+    }).`,
+  );
+};
+
+/**
+ * CHECK 2: is the server there, and is it a Wire server?
+ *
+ * `GET /v1/events/contract` is public, cheap, and it answers the question the round-trip check
+ * cannot answer on its own: a failure here means "wrong URL / server down", not "bad payload".
+ */
+const checkReachability = async (serverUrl: string): Promise<WireDoctorCheck> => {
+  const url = `${serverUrl.replace(/\/$/, "")}/v1/events/contract`;
+  const res = await fetchWithTimeout(url, { method: "GET" });
+  if (!res) {
+    return check("reachability", false, "could not reach the server (network error or timeout).");
+  }
+  const status = (res as { status?: unknown }).status;
+  const ok = !!(res as { ok?: boolean }).ok;
+  if (!ok) {
+    return check(
+      "reachability",
+      false,
+      `the server answered ${typeof status === "number" ? status : "an error"} for the events contract; ` +
+        "check the serverUrl points at a Wire server.",
+    );
+  }
+  return check("reachability", true, "the server answered the events contract.");
+};
+
+/**
+ * CHECK 3: can the offline queue actually persist?
+ *
+ * Write, read back, compare. Without working storage the queue silently degrades to in-memory only,
+ * so a backgrounded app loses whatever it had not flushed, and nothing anywhere says so.
+ *
+ * The probe key is REMOVED in a `finally`, so a failing read or a throwing adapter still cleans up.
+ */
+const checkStorage = async (storage: WireOnboardingStorage | undefined): Promise<WireDoctorCheck> => {
+  if (!storage) {
+    return check(
+      "storage",
+      true,
+      "no storage injected: the queue runs in DEGRADED in-memory mode and loses pending events on an app kill. " +
+        "Pass AsyncStorage (or an MMKV wrapper) to make it durable.",
+    );
+  }
+  const token = `probe_${Date.now().toString(36)}`;
+  try {
+    await storage.setItem(PROBE_STORAGE_KEY, token);
+    const read = await storage.getItem(PROBE_STORAGE_KEY);
+    if (read !== token) {
+      return check(
+        "storage",
+        false,
+        "the storage adapter accepted a write but did not read the same value back, so the queue cannot persist.",
+      );
+    }
+    // ⚠️ "write / read" only: this returns BEFORE the `finally` runs its delete, and a throwing
+    // `removeItem` is deliberately swallowed there, so the delete is attempted, never asserted.
+    return check("storage", true, "storage write / read round trip succeeded.");
+  } catch {
+    return check("storage", false, "the storage adapter threw, so the queue cannot persist events.");
+  } finally {
+    // Always, including after a failed write or read: never leave the probe key behind.
+    try {
+      await storage.removeItem(PROBE_STORAGE_KEY);
+    } catch {
+      // A remove that throws is not worth failing the run over; nothing else depends on it.
+    }
+  }
+};
+
+/**
+ * CHECK 4: does a real event survive real server validation?
+ *
+ * POSTs ONE synthetic event through the REAL {@link buildEventsRequest} with `dry_run: true`, so it
+ * travels the exact bytes a production event travels and the server validates it exactly the same
+ * way, but writes nothing. The probe is inert: it pollutes no funnel and no metric.
+ *
+ * ⚠️ The verdict is `written === 1 && skipped === 0`, read from the ACK BODY. A 200 is not a
+ * receipt here: the endpoint returns 200 for a batch it discarded. A `ts`-shaped drift shows up as
+ * `skipped: 1` with the server's own `field: "ts"`, which is the whole point of this check.
+ */
+const checkRoundTrip = async (target: ClientEventTarget): Promise<WireDoctorCheck> => {
+  const event: ClientEvent = {
+    event_type: "app_event",
+    session_id: makeSessionId(),
+    question_key: PROBE_QUESTION_KEY,
+  };
+  const req = buildEventsRequest(target, [event], { dryRun: true });
+  if (!req) {
+    return check("round_trip", false, "could not build the events request from this target.");
+  }
+  const res = await fetchWithTimeout(req.url, req.init);
+  if (!res) {
+    return check("round_trip", false, "the events POST failed (network error or timeout).");
+  }
+  if (!(res as { ok?: boolean }).ok) {
+    const status = (res as { status?: unknown }).status;
+    return check(
+      "round_trip",
+      false,
+      `the events endpoint answered ${typeof status === "number" ? status : "an error"}; ` +
+        "a 401 here means the apiKey is not accepted.",
+    );
+  }
+  const ack = await readEventsAck(res);
+  if (!ack) {
+    return check(
+      "round_trip",
+      false,
+      "the server answered 2xx but sent no readable ack body, so it is unknown whether the event validated.",
+    );
+  }
+  if (ack.written === 1 && ack.skipped === 0) {
+    return check("round_trip", true, "the server validated the probe event: written=1, skipped=0.");
+  }
+  // The server's own reasons, verbatim, each already carrying the field it refused.
+  return check(
+    "round_trip",
+    false,
+    `the server DISCARDED the probe event: written=${ack.written ?? "unknown"}, skipped=${ack.skipped}` +
+      (ack.reasons.length > 0
+        ? `, reasons: ${ack.reasons.join(", ")}.`
+        : ". It gave no reason; check the server's ingest log for this request."),
+  );
+};
+
+/**
+ * Run the full diagnosis. Resolves a report; NEVER throws and NEVER rejects.
+ *
+ * DEV-ONLY BY CONTRACT: the `__DEV__` guard is the FIRST statement, so a release build performs no
+ * network call, no storage write, and no work at all. The report says it was skipped rather than
+ * pretending everything passed, because a green report that never ran is the exact failure mode
+ * this whole feature exists to remove.
+ */
+export const wireDoctor = async (options: WireDoctorOptions): Promise<WireDoctorReport> => {
+  if (typeof __DEV__ === "undefined" || !__DEV__) {
+    return {
+      ok: false,
+      checks: [
+        check(
+          "dev_only",
+          false,
+          "wireDoctor is dev-only and did NOT run: __DEV__ is unset or false. Nothing was checked.",
+        ),
+      ],
+    };
+  }
+  try {
+    const target = options?.target;
+    const checks: WireDoctorCheck[] = [checkTarget(target)];
+    // Reachability and the round trip both need a usable target; running them against a broken one
+    // would report a network failure and bury the real cause, which check 1 already named.
+    if (checks[0]!.ok && target) {
+      checks.push(await checkReachability(target.serverUrl));
+      checks.push(await checkStorage(options?.storage));
+      checks.push(await checkRoundTrip(target));
+    } else {
+      checks.push(await checkStorage(options?.storage));
+    }
+    return { ok: checks.every((c) => c.ok), checks };
+  } catch {
+    // Belt and braces: every check above already swallows its own failures, so reaching here means
+    // something hostile got past them. Still a report, still not a throw. The name is
+    // `internal_error`, NOT `dev_only`: this ran and broke, which is the opposite of "never ran".
+    return {
+      ok: false,
+      checks: [check("internal_error", false, "wireDoctor could not complete: an unexpected error was swallowed.")],
+    };
+  }
+};

package/src/cards/CardGridSelectCard.tsx

@@ -104,7 +104,7 @@ const _OptionCard: React.FC<OptionCardProps> = ({ opt, isSelected, multiSelect,
   const handlePressOut = useCallback(() => pressTo(1), [pressTo]);
 
   // Selected fill: accent border + tinted wash on an absolute overlay whose opacity crossfades
-  // (native driver — see EXTRACTED-SPEC.md D7). Reduce motion: snap.
+  // (native driver, never a color interpolation). Reduce motion: snap.
   const selectT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
   useEffect(() => {
     const anim = Animated.timing(selectT, {

package/src/cards/ChipSelectCard.tsx

@@ -80,7 +80,7 @@ const _ChipItem: React.FC<ChipItemProps> = ({ chip, isSelected, multiSelect, onT
   const handlePressOut = useCallback(() => pressTo(1), [pressTo]);
 
   // Selected fill: full accent pill, crossfaded in over 160ms on a native-driver
-  // opacity overlay (EXTRACTED-SPEC.md D7). Reduce motion: instant swap.
+  // opacity overlay, never a color interpolation. Reduce motion: instant swap.
   const fillT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
   useEffect(() => {
     const anim = Animated.timing(fillT, {
@@ -94,7 +94,7 @@ const _ChipItem: React.FC<ChipItemProps> = ({ chip, isSelected, multiSelect, onT
   }, [isSelected, reduced, fillT]);
 
   // Check pop on select (the width-slide of the canvas is a layout animation the
-  // native driver can't express — see EXTRACTED-SPEC.md D4).
+  // native driver can't express, so it stays on the JS driver deliberately).
   const checkT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
   useEffect(() => {
     if (!isSelected) {

package/src/cards/SelectionCard.tsx

@@ -80,7 +80,7 @@ const _OptionRow: React.FC<OptionRowProps> = ({ opt, isSelected, multiSelect, on
 
   // Selected fill: the selected border+bg live on an absolute overlay whose opacity
   // crossfades in 180ms ease-wire — same visual as a color interpolation, but it
-  // stays on the native driver (see EXTRACTED-SPEC.md D7). Reduce motion: snap.
+  // stays on the native driver. Reduce motion: snap.
   const selectT = useRef(new Animated.Value(isSelected ? 1 : 0)).current;
   useEffect(() => {
     const anim = Animated.timing(selectT, {

package/src/coachmarks/runtime.ts

@@ -27,7 +27,16 @@
  */
 import type { CoachmarkStorage } from "./types";
 
-/** Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles. */
+/**
+ * Well-known key into the runtime-global symbol registry — one coachmark runtime across bundles.
+ *
+ * @globalSlot LATCH — the RUNTIME RECORD is created once and its identity is then stable. A second
+ * write replaces the record `subscribeCoachmarksEnabled` registered its listeners on, so a
+ * kill-switch flip notifies an orphaned set while a tour that believes it is running paints nothing
+ * — the exact limbo `coachmarkKillSwitch` canaries. Its FIELDS (`storage`, `testing`,
+ * `coachmarksEnabled`, `listeners`) are live, which is why every accessor calls `coachmarkRuntime()`
+ * instead of holding the record, and why `coachmarksEnabled` is subscribable rather than sampled.
+ */
 const COACHMARK_RUNTIME_SLOT: unique symbol = Symbol.for("@wireai/activation:coachmarkRuntime");
 
 /** The shared runtime: the provider-injected storage, the QA replay flag, and the kill switch. */
@@ -39,6 +48,10 @@ type CoachmarkRuntime = {
   // resolved flags. Disabled → the tour never ARMS and the overlay `show()` is a no-op, so nothing
   // paints and — critically — no once-gate is written, so re-enabling replays the tour correctly.
   coachmarksEnabled: boolean;
+  // Subscribers to the kill switch. OPTIONAL on the type (never on the behaviour) so a record left
+  // in the registry by an inlined copy from an OLDER kit version — which had no listener set — is
+  // upgraded in place rather than read as corrupt.
+  listeners?: Set<() => void>;
 };
 
 type GlobalWithCoachmarkRuntime = typeof globalThis & {
@@ -55,17 +68,73 @@ const coachmarkRuntime = (): CoachmarkRuntime => {
   return created;
 };
 
+const enabledListeners = (): Set<() => void> => {
+  const runtime = coachmarkRuntime();
+  if (!runtime.listeners) runtime.listeners = new Set();
+  return runtime.listeners;
+};
+
+/**
+ * Wake the subscribers on a MICROTASK, never synchronously.
+ *
+ * `CoachmarkProvider` writes this flag during its RENDER phase on purpose (so a child's mount
+ * effect already sees the resolved value). Notifying from there synchronously would schedule a
+ * React update while a *different* component is rendering. Every subscriber reads the value
+ * through `areCoachmarksEnabled()` at render time anyway, so the notification only has to wake
+ * the components that are not already re-rendering — one microtask later is soon enough, and it
+ * keeps the write side legal from anywhere.
+ */
+const notifyCoachmarksEnabled = (): void => {
+  if (enabledListeners().size === 0) return;
+  void Promise.resolve().then(() => {
+    for (const listener of [...enabledListeners()]) {
+      try {
+        listener();
+      } catch {
+        // A broken subscriber must never break the kill switch for the others.
+      }
+    }
+  });
+};
+
 /**
  * Set the coachmarks master switch (from the resolved feature flags). Default true (fail-open).
- * Written by CoachmarkProvider; read imperatively by the tour arm + the overlay store.
+ * Written by CoachmarkProvider; read imperatively by the tour arm + the overlay store, and
+ * SUBSCRIBED to by `useCoachmarkTour` (see `subscribeCoachmarksEnabled`).
+ *
+ * No-ops when the value is unchanged, which matters because the provider writes it on every
+ * render — without that guard every render would fan out a notification.
  */
 export const setCoachmarksEnabled = (value: boolean): void => {
-  coachmarkRuntime().coachmarksEnabled = value;
+  const runtime = coachmarkRuntime();
+  if (runtime.coachmarksEnabled === value) return;
+  runtime.coachmarksEnabled = value;
+  notifyCoachmarksEnabled();
 };
 
 /** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */
 export const areCoachmarksEnabled = (): boolean => coachmarkRuntime().coachmarksEnabled;
 
+/**
+ * Subscribe to kill-switch flips. Returns the unsubscribe function — the `useSyncExternalStore`
+ * contract, and deliberately the SAME shape as `coachmarkOverlay.subscribe` next door rather than
+ * a second pattern to keep correct.
+ *
+ * WHY IT EXISTS: the flag is a mutable `globalThis` value, so on its own it can only be SAMPLED.
+ * A tour that samples it cannot notice a tenant flipping it off mid-flight — the overlay's
+ * `show()` quietly becomes a no-op while the tour still believes it is running, so nothing paints,
+ * nothing can be tapped to advance, and no terminal path is reachable. `useCoachmarkTour`
+ * subscribes instead. The listener set lives in the SAME `globalThis` record as the flag, so every
+ * inlined copy of this module shares one subscriber list.
+ */
+export const subscribeCoachmarksEnabled = (listener: () => void): (() => void) => {
+  const listeners = enabledListeners();
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
 /** Set (or clear) the injected sync gate storage. Called by CoachmarkProvider. */
 export const setCoachmarkStorage = (storage: CoachmarkStorage | null): void => {
   coachmarkRuntime().storage = storage;

package/src/coachmarks/useCoachmarkTour.ts

@@ -1,8 +1,14 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
 
 import { coachmarkAnchors } from "./coachmarkAnchorRegistry";
 import { coachmarkOverlay } from "./coachmarkOverlayStore";
-import { areCoachmarksEnabled, coachmarkGateKey, hasSeenGate, markSeenGate } from "./runtime";
+import {
+  areCoachmarksEnabled,
+  coachmarkGateKey,
+  hasSeenGate,
+  markSeenGate,
+  subscribeCoachmarksEnabled,
+} from "./runtime";
 import type { CoachmarkStep } from "./types";
 
 export interface UseCoachmarkTourOptions {
@@ -61,6 +67,15 @@ const DEFAULT_START_DELAY_MS = 3000;
  * target is picked up. `onStepShown` is suppressed on that resume (last-shown
  * step id is tracked in a ref) so a pause/resume never double-counts a step.
  *
+ * KILL SWITCH vs PAUSE — two different gates, two different endings. `enabled` is the host's
+ * domain gate and PAUSES (position kept, gate unwritten, resumes on the same step). The tenant's
+ * coachmarks feature flag (`setCoachmarksEnabled`, from GET /v1/features) is TERMINAL: flipped off
+ * mid-tour it ends the tour and fires `onComplete`, but does NOT write the once-gate, so the tour
+ * replays on the next mount once the flag is back on. It is read through a subscription rather
+ * than sampled, because the flip has to reach a tour that is already in flight: the overlay's
+ * `show()` is a no-op while the flag is off, so a tour that carried on would paint nothing, could
+ * not be tapped to advance, and would never reach a terminal state.
+ *
  * IMPORTANT: `steps` MUST be a stable (memoized) array. If a new array identity
  * is passed on every render the drive effect re-runs and re-shows the current
  * step (wasteful anchor re-resolves / overlay churn), and analytics can
@@ -97,34 +112,67 @@ export const useCoachmarkTour = (
   const callbacksRef = useRef({ onStepShown, onStepEngaged, onStepDismissed });
   callbacksRef.current = { onStepShown, onStepEngaged, onStepDismissed };
 
-  const finish = useCallback(() => {
-    if (finishedRef.current) return;
-    finishedRef.current = true;
-    if (showOnce) markSeenGate(coachmarkGateKey(tourId));
-    coachmarkOverlay.hide();
-    setActiveIndex(null);
-    onComplete?.();
-  }, [onComplete, showOnce, tourId]);
+  // The tenant's coachmarks kill switch, SUBSCRIBED rather than sampled so a mid-tour flip reaches
+  // a tour already in flight. See the KILL SWITCH vs PAUSE note above.
+  const coachmarksOn = useSyncExternalStore(
+    subscribeCoachmarksEnabled,
+    areCoachmarksEnabled,
+    areCoachmarksEnabled,
+  );
+
+  /**
+   * The single terminal exit. `writeGate` is what separates the two ways a tour can end:
+   *   • the user reached the end (or dismissed the last step) → the once-gate IS written, so a
+   *     finished tour never nags again;
+   *   • the kill switch went off mid-tour → the gate is NOT written. That gate belongs to a tour
+   *     the user actually saw, and the module's whole kill-switch contract is that disabling
+   *     never consumes it, so re-enabling replays the tour.
+   * Either way `onComplete` fires: a host that gates its own UI on the tour finishing must not be
+   * left waiting on a callback that can no longer arrive.
+   */
+  const exit = useCallback(
+    (writeGate: boolean) => {
+      if (finishedRef.current) return;
+      finishedRef.current = true;
+      if (writeGate && showOnce) markSeenGate(coachmarkGateKey(tourId));
+      coachmarkOverlay.hide();
+      setActiveIndex(null);
+      onComplete?.();
+    },
+    [onComplete, showOnce, tourId],
+  );
+
+  const finish = useCallback(() => exit(true), [exit]);
 
   // Arm once, after the delay, when enabled and the gate is unseen.
   useEffect(() => {
     if (!enabled || startedRef.current) return undefined;
     // Feature kill switch: never arm while coachmarks are disabled, so no timer starts, no
-    // overlay shows, and the once-gate is NOT consumed — re-enabling replays the tour.
-    if (!areCoachmarksEnabled()) return undefined;
+    // overlay shows, and the once-gate is NOT consumed — re-enabling replays the tour. Reading
+    // the SUBSCRIBED value (and listing it in the deps) is what makes that last clause true
+    // without a remount: flipping it off clears a pending arm timer, flipping it back on re-arms.
+    if (!coachmarksOn) return undefined;
     if (showOnce && hasSeenGate(coachmarkGateKey(tourId))) return undefined;
     const timer = setTimeout(() => {
       startedRef.current = true;
       setActiveIndex(0);
     }, startDelayMs);
     return () => clearTimeout(timer);
-  }, [enabled, startDelayMs, showOnce, tourId]);
+  }, [enabled, coachmarksOn, startDelayMs, showOnce, tourId]);
 
   // Drive the active step. Keyed on `enabled` too, so a mid-tour focus loss
   // pauses (hide, keep position) and a return to focus resumes the same step.
   useEffect(() => {
     if (activeIndex === null) return undefined;
 
+    // KILL SWITCH, mid-tour: exit terminally, WITHOUT writing the once-gate, so the tour replays
+    // when it is switched back on. Checked BEFORE the pause branch below — a disable is terminal,
+    // a focus loss is not.
+    if (!coachmarksOn) {
+      exit(false);
+      return undefined;
+    }
+
     // PAUSE: armed but the screen lost focus (enabled flipped false while in
     // flight). Hide the overlay so a stale rect can't float over the wrong
     // screen, but KEEP activeIndex and DON'T write the gate. When enabled
@@ -188,7 +236,7 @@ export const useCoachmarkTour = (
     return () => {
       cancelled = true;
     };
-  }, [activeIndex, steps, finish, enabled]);
+  }, [activeIndex, steps, finish, exit, enabled, coachmarksOn]);
 
   // Safety: clear the overlay if the screen unmounts mid-tour.
   useEffect(

package/src/context/deviceId.ts

@@ -68,13 +68,22 @@ export const mintDeviceId = (): string => {
 // events are the ONLY ones the server counts `min_sessions` from, so a per-launch id there is not a
 // millisecond of noise, it is a counter that can never exceed 1.
 
-/** Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle. */
+/**
+ * Well-known key into the runtime-global symbol registry — one auto-id registry across every bundle.
+ *
+ * @globalSlot LATCH — the REGISTRY OBJECT is created once and its identity is then stable. A second
+ * write empties `keys`/`hydrating`/`pending`, so the next surface mints a SECOND auto id for one
+ * install and the `device_key` the server joins sessions on splits in two — the halved-counter
+ * defect this registry exists to close. Its CONTENTS are live (the id per `appId` is replaced when
+ * an async hydration adopts a persisted value), so callers must re-read through
+ * `resolveAutoDeviceKey()` rather than hold the string a mount happened to see first.
+ */
 const AUTO_DEVICE_KEY_SLOT: unique symbol = Symbol.for("@wireai/activation:autoDeviceKeys");
 
 /** What a hydration settled on: the id, and whether persistence actually CONFIRMED it.
  *
  *  `durable: false` means the id lives only in this process's memory — the adapter rejected, threw,
- *  or there was no adapter at all. That distinction is the whole of K1: a string is a string, so
+ *  or there was no adapter at all. That distinction is the whole point here: a string is a string, so
  *  before 0.13.0 a caller could not tell a persisted id from a per-launch mint, and the auto-join
  *  gate (`Boolean(storage)`) was reading the PRESENCE of the prop rather than the SUCCESS of the
  *  write. See {@link hydrateDeviceIdentity}. */
@@ -131,7 +140,7 @@ export interface ResolveAutoDeviceKeyOptions {
  *                                   the write. The id is real but PROCESS-scoped, so anything that
  *                                   counts a device across launches must refuse it.
  *
- * A DEGRADED outcome also drops the registry latches so the NEXT caller starts a fresh read (K8). A
+ * A DEGRADED outcome also drops the registry latches so the NEXT caller starts a fresh read. A
  * cold-boot storage lock is transient; caching it as a verdict for the process lifetime turned a
  * one-second problem into a whole-launch one, and nothing ever retried.
  */
@@ -170,7 +179,7 @@ const startHydration = (
     run = Promise.resolve(degraded());
   }
   registry.pending.set(appId, run);
-  // Retry-on-failure (K8): release the latches once a degraded outcome settles, so a later caller
+  // Retry-on-failure: release the latches once a degraded outcome settles, so a later caller
   // is not permanently bound to one bad read. Registered AFTER the `set` above, so the clean-up can
   // never race ahead of the entry it is clearing.
   void run.then((outcome) => {
@@ -238,7 +247,7 @@ export const hydrateAutoDeviceKey = async (
  * The PROVENANCE-CARRYING sibling of {@link hydrateAutoDeviceKey}: the same awaited read, but it
  * answers "is this id one this install will KEEP?" instead of only "what is the id?".
  *
- * WHY IT EXISTS (K1). `<WireOnboarding>` gated auto-injection on `Boolean(storage)` — the presence of
+ * WHY IT EXISTS. `<WireOnboarding>` gated auto-injection on `Boolean(storage)` — the presence of
  * the prop — because a string carries no provenance and there was nothing better to gate on. A
  * REJECTING adapter therefore injected a fresh `wdev_*` on every launch: strictly worse than
  * injecting nothing, since the server counts `min_sessions` by distinct opens grouped on `device_key`,

package/src/features/WireFeaturesProvider.tsx

@@ -18,8 +18,19 @@ import { defaultWireFeatures } from "./defaults";
 import { useWireFeatures } from "./useWireFeatures";
 import type { WireFeatures, WireFeaturesConfig } from "./types";
 
+/**
+ * @globalSlot LATCH — the React context object is minted by the first copy of this module to load
+ * and every later copy ADOPTS it (the `if (!…)` guard below). A second write would re-split the
+ * identity the guard exists to keep whole: the provider would publish into one context while a
+ * subpath bundle's `useContext` read another, and `useResolvedFeatures`' null fallback would serve
+ * the all-on defaults with no crash and no warning. Because it is a latch, and only because of
+ * that, the module-local `const WireFeaturesContext` below may cache it.
+ */
 const CONTEXT_SYMBOL = Symbol.for("wireai.features.context");
-const globalObj = global as any;
+// `globalThis`, not `global`: the other nine `Symbol.for` slots in this kit all use it, and `global`
+// simply does not exist in a plain browser (RN-web / SSR-in-the-browser), where this line would
+// throw a ReferenceError before the provider could render anything.
+const globalObj = globalThis as any;
 
 if (!globalObj[CONTEXT_SYMBOL]) {
   globalObj[CONTEXT_SYMBOL] = createContext<WireFeatures | null>(null);