@wireai/activation 0.13.2 → 0.13.3

package/dist/{types-CNUqMK0D.d.mts → types-l2tfg23P.d.mts}

@@ -2,6 +2,46 @@ import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
 import { C as CoachmarkStorage } from './types-BcmagF6K.mjs';
 import { W as WireFeatures, a as WireFeaturesConfig } from './types-CKFhyrMu.mjs';
 
+/**
+ * submitResult — the ONE delivery verdict every user-payload POST in this kit reports back.
+ *
+ * WHY IT IS SHARED, AND WHY IT IS NOT A BOOLEAN. Two surfaces post a payload the user typed —
+ * `submitReview` (`reviews/transport.ts`) and `submitQuestionnaireResponse`
+ * (`questionnaire/transport.ts`) — and NEITHER has a persisted queue behind it (unlike
+ * `analytics/eventQueue`, with its `maxSize`/`maxRetries`/backoff). Both sit behind a permanent
+ * once-gate: the host writes `wire_review_<id>_seen` / `wire_questionnaire_<id>_<ver>_seen` when the
+ * gate resolves, so a payload that dies in the socket is lost AND the user is never asked again.
+ * Reading the fate of the request is the only thing that lets a caller keep an undelivered payload
+ * recoverable, so the two surfaces must answer the same question in the same words.
+ *
+ *   • `accepted` — the server answered 2xx. Stored.
+ *   • `rejected` — the server ANSWERED, non-2xx. It was reached; it either stored the payload and
+ *                  lost the ack (a gateway 502 after the write commits) or deliberately refused it.
+ *                  Either way the server owns the outcome and a re-post risks a SECOND row.
+ *   • `unsent`   — nothing came back at all: no target, a missing/throwing `fetch`, a rejected
+ *                  request. **This is the ONLY outcome a caller may retry on.**
+ *
+ * ── WHY THREE VALUES AND NOT TWO (pinned here so the defect cannot move surface) ───────────────
+ *
+ * `submitReview` was a boolean for exactly one unpublished release, and the boolean WAS the bug.
+ * `false` meant both "nothing reached the server" and "the server answered non-2xx", and the caller
+ * treats `false` as "still owed" and re-posts. But the server mints its own row id
+ * (`create_review` / `_new_id()`), and neither `CreateReviewRequest` nor the questionnaire response
+ * body carries a client id, so there is NO idempotency key on the wire: a 502 returned AFTER the
+ * insert commits means the re-post writes a SECOND row. A response of any status proves the server
+ * was reached, and that is a different question from whether it liked the payload.
+ *
+ * ── THE RESIDUAL, STATED HONESTLY ─────────────────────────────────────────────────────────────
+ *
+ * `unsent` is not proof the server never got it. A connection dropped after the request was written
+ * — or after the row committed — surfaces as a thrown/rejected `fetch`, exactly like an offline
+ * device. Retrying only on `unsent` is therefore SAFER, not SAFE. Closing that window needs a
+ * CLIENT-MINTED IDEMPOTENCY KEY the server upserts on, which is a server change and not something
+ * the kit can fake. Until it exists, prefer losing a row over inventing one: a lost detractor is a
+ * gap in the data, a duplicated one is a lie in the data.
+ */
+type SubmitResult = "accepted" | "rejected" | "unsent";
+
 /**
  * The firing verdict — the SAME contract on both sides of the seam. `decideReview`
  * turns local rules into one of these; a server `{fire, reason}` (from
@@ -161,4 +201,4 @@ interface ReviewGateController {
     markResolved: () => void;
 }
 
-export type { ReviewGateProps as R, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewDecisionResponse as g, ReviewGateEvent as h, ReviewGateEventName as i, ReviewSubmission as j, ReviewTarget as k };
+export type { ReviewGateProps as R, SubmitResult as S, UseReviewGateOptions as U, ReviewPresentation as a, ReviewGateController as b, ReviewDecision as c, ReviewStoreConfig as d, RatingRoute as e, ReviewConfig as f, ReviewDecisionResponse as g, ReviewGateEvent as h, ReviewGateEventName as i, ReviewSubmission as j, ReviewTarget as k };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.13.2",
+  "version": "0.13.3",
   "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>",
@@ -137,8 +137,11 @@
   "scripts": {
     "build": "tsup",
     "prepack": "npm run build",
+    "prepublishOnly": "npm run build && npm run test:canary",
     "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\"",
     "pack:tarball": "npm pack"
   },
   "peerDependencies": {

package/src/OnboardingFlow.tsx

@@ -179,7 +179,17 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // Trailing-edge debounce timer for prefetch-on-select (see previewOnSelect below).
   const previewTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
-  const started = useRef(false);
+  // The attempt generation. It lives in STATE, not in a ref, and both the auto-start effect and
+  // the startup watchdog list it in their deps — a retry has to genuinely RE-ARM both, and a ref
+  // cannot re-trigger an effect. Nothing else in those deps moves on a retry: `sendMessage` is
+  // memoized in wireai-rn on [registry, provider, model], and `lastCard` is still `undefined`
+  // because no card ever arrived. Without the generation the kickoff is never re-sent, `timedOut`
+  // can never become true a second time, and the retry budget can never be spent — which leaves a
+  // backend that never answers sitting on the loader forever.
+  const [runId, setRunId] = useState(0);
+  // The generation whose kickoff has already been sent. -1 = nothing sent yet (so the very first
+  // run can be told apart from a retry, which must NOT re-fire `started`/`resumed`).
+  const startedRunRef = useRef(-1);
   const finished = useRef(false);
   const errored = useRef(false);
   const attempts = useRef(0);
@@ -210,33 +220,50 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const progress = useMemo(() => readProgress(lastCard?.response), [lastCard]);
 
   // 1. Auto-start: the backend treats the first inbound message as "begin".
-  //    On a RESUMED session (persisted id restored after an app kill) the kickoff is
-  //    the skip sentinel instead: the server has this session mid-flow with a pending
-  //    question, and would record `startMessage`'s literal text as its ANSWER — the
-  //    sentinel advances one card recording nothing (a `screen_skipped`). On a session
-  //    the server no longer knows (restart/expiry), the sentinel degrades cleanly to a
-  //    normal kickoff under the same id. Retries re-send the same kickoff.
+  //    ONLY the very first attempt of a fresh session sends `startMessage`. Every other kickoff
+  //    — a RESUMED session (persisted id restored after an app kill) and every RETRY — sends the
+  //    skip sentinel, because both can reach a server that already has a question PENDING on this
+  //    session, and a non-empty message arriving against a pending question is recorded as that
+  //    question's ANSWER (server engine dispatch: `if user_message and pending and not
+  //    _stop_requested(...)` appends `{key, question, answer}` to `session["answers"]`). For a
+  //    retry that is not hypothetical: the watchdog fires at `startTimeoutMs` while a slow LLM is
+  //    still generating, so the server can genuinely hold card 1 pending when the retry lands, and
+  //    the user's first onboarding answer becomes the literal kickoff text — silently.
+  //    THE COST, stated plainly: when the server DID have card 1 pending, the sentinel SKIPS that
+  //    card — the user loses one question and the server logs a `screen_skipped`. Deliberate. A
+  //    skipped question is visible in the funnel and recorded as nothing; a kickoff string stored
+  //    as the user's first answer is invisible and poisons the data the product is built on.
+  //    When the server has no pending (restart/expiry, or a retry whose predecessor never landed)
+  //    the sentinel is zeroed and falls through — it degrades cleanly to a normal kickoff under
+  //    the same id, which is what makes it safe to send on an attempt that may be either.
   useEffect(() => {
-    if (started.current) return;
-    started.current = true;
-    sendMessage(resumed ? SKIP_ONE_SENTINEL : startMessage);
+    if (startedRunRef.current === runId) return;
+    const isFirstRun = startedRunRef.current < 0;
+    startedRunRef.current = runId;
+    sendMessage(isFirstRun && !resumed ? startMessage : SKIP_ONE_SENTINEL);
+    // Only the FIRST run is a session start. A retry re-kicks the flow (with the sentinel) but
+    // must not re-fire `started`/`resumed`, or every host funnel double-counts the session; the
+    // retry itself is already surfaced as a `retry` event by the error effect below.
+    if (!isFirstRun) return;
     // Surface the session id (the A2A contextId) on the start event so a host can capture it
     // and bind a user AFTER the flow via `identifyOnboarding({ contextId })` — completion clears
     // the persisted session, so the in-flight event is the reliable post-flow handle. sessionId
-    // is stable for the whole session (minted before this subtree mounts), so this stays mount-once.
+    // is stable for the whole session (minted before this subtree mounts), so this stays once
+    // per session.
     onEventRef.current?.(
       resumed
         ? { type: "resumed", contextId: sessionId }
         : { type: "started", contextId: sessionId },
     );
-  }, [sendMessage, startMessage, resumed, sessionId]);
+  }, [sendMessage, startMessage, resumed, sessionId, runId]);
 
-  // 2. Startup watchdog.
+  // 2. Startup watchdog. `runId` is load-bearing in these deps: after a retry there is still no
+  //    card, so `lastCard` does not change and nothing else would re-arm the timer.
   useEffect(() => {
     if (lastCard) return;
     const timer = setTimeout(() => setTimedOut(true), startTimeoutMs);
     return () => clearTimeout(timer);
-  }, [lastCard, startTimeoutMs]);
+  }, [lastCard, startTimeoutMs, runId]);
 
   // A new card arrived → clear any prior inline validation error + emit a turn event.
   useEffect(() => {
@@ -287,8 +314,10 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // Does NOT clear the attempt counter or the degraded flag — the caller decides that.
   const restartThread = useCallback(() => {
     setTimedOut(false);
-    started.current = false;
     errored.current = false;
+    // Bumping the generation IN STATE is what actually re-runs the kickoff effect and re-arms the
+    // watchdog. Flipping a ref here would re-trigger neither.
+    setRunId((n) => n + 1);
     reset();
   }, [reset]);
 

package/src/WireOnboarding.tsx

@@ -114,7 +114,8 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // `activated` funnel rather than an error. Two real consumers shipped without it.
   //
   // A host-supplied key is also RECORDED on the process-wide provenance registry, so a sibling
-  // surface can later ask "does this app own a device id?" — see the K9 warning below. The registry
+  // surface can later ask "does this app own a device id?" — see the third-id-space warning below.
+  // The registry
   // write is idempotent (same key, same value), so running it from a memo is safe under StrictMode's
   // double-invoke; it lives here rather than in an effect so the answer is already true for any
   // surface constructed later in the same tick.
@@ -143,7 +144,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //     counter rather than leaving it empty, and it inflates distinct-device counts on top. Same
   //     reason `useLifecycleEvents` gates its own fallback on storage.
   //
-  // ⚠️ 0.13.0 (K1): the third condition used to be `Boolean(storage)` — the PRESENCE of the prop,
+  // ⚠️ 0.13.0: the third condition used to be `Boolean(storage)` — the PRESENCE of the prop,
   // never the SUCCESS of the write. A REJECTING adapter (a locked / full / permission-denied
   // AsyncStorage, the most common real breakage) therefore walked the per-launch key in through the
   // front door: `hydrateAutoDeviceKey` resolves to the in-memory mint on every failure branch, and a
@@ -153,8 +154,8 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   //
   // It resolves through `hydrateDeviceIdentity`, never the sync `resolveAutoDeviceKey`: the sync
   // contract returns the freshly minted id and adopts the persisted one milliseconds later, which
-  // is exactly the 0.12.1 H1 defect — the key stamped here must be the one the analytics side
-  // stamps, not a fresh mint per launch. The value is therefore awaited BEHIND THE LOADER GATE
+  // is exactly the split-identity defect 0.12.1 shipped — the key stamped here must be the one the
+  // analytics side stamps, not a fresh mint per launch. It is therefore awaited BEHIND THE LOADER GATE
   // below (the same gate the persisted-session read already holds, and it is only ever open when
   // `storage` is present anyway), because `userContext` feeds the `llm` memo: swapping it after the
   // provider mounted would recreate the A2A adapter and drop the server-learned `contextId`.
@@ -201,7 +202,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     [userContextStable, injectedJoinKey],
   );
 
-  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS (K5), exactly as `startupUserIdRef`
+  // THE JOIN DECISION IS FROZEN AT THE MOMENT THE GATE OPENS, exactly as `startupUserIdRef`
   // below freezes the user id, and for the identical reason: `userContext` feeds the `llm` memo, and
   // wireai-rn recreates its A2A adapter whenever the `llm` identity changes — the adapter ctor resets
   // `contextId` (`this.contextId = void 0`), so the server-learned session id is dropped.
@@ -261,7 +262,7 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
     );
   }, [warnMissingJoinKey, autoJoinReason]);
 
-  // THE SECOND CASE AUTO-JOIN WOULD OTHERWISE SILENCE (K9). 0.12.2 suppressed the missing-join-key
+  // THE SECOND CASE AUTO-JOIN WOULD OTHERWISE SILENCE. 0.12.2 suppressed the missing-join-key
   // warning whenever injection succeeded, which is right when the host genuinely owns no device id —
   // and wrong when it owns one and simply forgot it HERE. That host used to get a loud warning and
   // now gets a silent third id space: its app events under its own key, this onboarding session under

package/src/activation/wireActivation.ts

@@ -5,8 +5,8 @@
  * because the kit didn't own them — an awaitable action POST (`wireTrackActionAwait`), its OWN
  * per-open session id (`getWireSessionId`, minted because the kit's `getCurrentSessionId` desynced
  * cross-bundle — defect B), and an await-then-bump revalidation dance (`bumpActivationDecision`).
- * Defect B is fixed (PR #48: `getCurrentSessionId` is a `globalThis` singleton, reliable under
- * `dist`), so the kit can now own all three behind one thin surface:
+ * Defect B is fixed — `getCurrentSessionId` is now a `globalThis` singleton, reliable under
+ * `dist` — so the kit can own all three behind one thin surface:
  *
  *   const wire = createWireActivation({ serverUrl, apiKey });   // or useWireActivation(...)
  *   await wire.track("journal_done");                            // awaitable POST + auto-revalidate
@@ -108,7 +108,7 @@ export const createWireActivation = (config: WireActivationConfig): WireActivati
   const explicitDeviceKey = clean(config.deviceKey) ?? clean(config.userContext?.deviceKey);
   // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
   // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
-  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it on this path.
+  // and forgot it here" (the silent third id space). Recording only; nothing reads it on this path.
   resolveIdentity({
     value: explicitDeviceKey,
     space: "device",

package/src/analytics/analyticsFacade.ts

@@ -198,7 +198,7 @@ export const createAnalytics = (
       : undefined;
   // Record a HOST-supplied key on the process provenance registry, so a `<WireOnboarding>` mount that
   // was NOT given one can tell "this app owns no device id" (fine, inject) from "this app owns one
-  // and forgot it here" (the silent third id space — K9). Recording only; nothing reads it here.
+  // and forgot it here" (the silent third id space). Recording only; nothing reads it here.
   resolveIdentity({
     value: hostDeviceKeyAtInit,
     space: "device",
@@ -333,7 +333,7 @@ export const createAnalytics = (
 
   const screen = (name: string, props?: AnalyticsProps): void => {
     if (!name) return;
-    // Reuse the K6 screen event shape (question_key='screen'); route through the queue for offline-first.
+    // Reuse the existing screen event shape (question_key='screen'); route through the queue for offline-first.
     const meta = { screen: name, ...(props ?? {}) };
     const clientEvent: ClientEvent = {
       event_type: "app_event",

package/src/analytics/eventQueue.ts

@@ -86,7 +86,7 @@ const DEFAULTS = {
 /** Ceiling on the persisted-backlog read — a hung adapter degrades to an empty start, never a stall. */
 const READ_TIMEOUT_MS = 1500;
 
-// ── One storage slot per QUEUE, not per appId (K4) ───────────────────────────────────────────────
+// ── One storage slot per QUEUE, not per appId ────────────────────────────────────────────────────
 //
 // The default key was derived from `appId` alone, so two `createAnalytics` instances for one tenant —
 // the documented double-wiring, a façade for `track`/`screen` plus an activation instance — shared ONE
@@ -153,10 +153,19 @@ type QueuedItem = { id: number; event: ClientEvent; sig: string };
 /** Persisted shape — the local id + the (already envelope-stamped) event. `sig` is recomputed on load. */
 type PersistedItem = { id: number; event: ClientEvent };
 
-const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | undefined> => {
+/**
+ * The verdict of a read that ran out of time. A DISTINCT value, and never `undefined` — an
+ * `undefined` here is byte-identical to "the adapter answered, there is no backlog", and that
+ * conflation destroys data silently: `parsePersisted(undefined)` gives `[]`, hydration takes its
+ * `length === 0` early return without throwing, and the next `persist()` writes the in-memory
+ * pending list over a blob nobody has read — or, with nothing pending, `removeItem`s it outright.
+ */
+const READ_TIMED_OUT: unique symbol = Symbol("wireai:storage-read-timeout");
+
+const withTimeout = <T>(p: Promise<T>, ms: number): Promise<T | typeof READ_TIMED_OUT> => {
   let timer: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<undefined>((resolve) => {
-    timer = setTimeout(() => resolve(undefined), ms);
+  const timeout = new Promise<typeof READ_TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(READ_TIMED_OUT), ms);
   });
   return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
 };
@@ -198,7 +207,7 @@ const parsePersisted = (raw: string | null | undefined): PersistedItem[] => {
 export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   const target = options.target;
   const storage = options.storage;
-  // One slot per QUEUE (K4): an explicit key is taken verbatim; the appId-derived default is rotated
+  // One slot per QUEUE: an explicit key is taken verbatim; the appId-derived default is rotated
   // to `…#2` when a live queue already holds it, so two instances can never share one backlog.
   //
   // Only claimed when there IS storage. The defect is entirely about the persisted slot, and a
@@ -217,6 +226,13 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
   let flushing = false;
   let attempt = 0;
   let retryTimer: ReturnType<typeof setTimeout> | undefined;
+  // The persisted blob exists but has NOT been read yet (the cold-start read blew its deadline and
+  // is still in flight). While this is true every write is suppressed: the only thing the queue
+  // could write is a view of `pending` that does not include the backlog it has not seen, and
+  // `setItem`/`removeItem` would destroy it. Cleared as soon as the slow read settles, whichever
+  // way it settles, so a read that ultimately fails resumes normal persistence rather than
+  // suppressing it for the life of the process.
+  let backlogUnread = false;
 
   const resolveEnvelope = (): ContextEnvelope | undefined => {
     try {
@@ -254,6 +270,8 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
 
   const persist = (): void => {
     if (!storage) return;
+    // NEVER write over a blob that has not been read yet. See `backlogUnread`.
+    if (backlogUnread) return;
     try {
       if (pending.length === 0) {
         void storage.removeItem(key).catch(() => {});
@@ -280,25 +298,70 @@ export const createEventQueue = (options: EventQueueOptions): EventQueue => {
     }
   };
 
-  // Load any persisted backlog. Anything enqueued before this settles stays in memory; we merge
-  // persisted (older) ahead of it and reassign monotonic ids so dequeue-after-ack is deterministic.
+  /**
+   * Merge a loaded backlog into the in-memory buffer: persisted (older) events go AHEAD of
+   * whatever was enqueued while the read was in flight, duplicates collapse, and the size cap
+   * applies as usual.
+   *
+   * Ids are minted FRESH from the running `nextId` rather than reset to 0. A drain may already be
+   * in flight holding a batch of ids it will filter out on ack, and re-numbering from 0 would make
+   * those ids point at different events — the ack would then dequeue (silently drop) whichever
+   * events happened to inherit them. Monotonic ids are never reused, so an in-flight ack stays
+   * correct whatever lands in between.
+   */
+  const mergePersisted = (persistedItems: PersistedItem[]): void => {
+    if (persistedItems.length === 0) return;
+    const seen = new Set(pending.map((item) => item.sig));
+    const restored: QueuedItem[] = [];
+    for (const persisted of persistedItems) {
+      const sig = safeSig(persisted.event);
+      if (seen.has(sig)) continue; // already in memory — collapse the duplicate
+      seen.add(sig);
+      restored.push({ id: nextId++, event: persisted.event, sig });
+    }
+    if (restored.length === 0) return;
+    pending = [...restored, ...pending];
+    enforceSizeCap();
+    persist();
+  };
+
+  // Load any persisted backlog. Anything enqueued before this settles stays in memory; the merge
+  // above puts persisted (older) events ahead of it.
+  //
+  // A read that blows READ_TIMEOUT_MS is NOT treated as "no backlog". The race only unblocks the
+  // DRAIN — the original read is kept and merged whenever it lands, and until then every write is
+  // suppressed so the unread blob survives intact.
   const loadPromise: Promise<void> = (async () => {
     if (!storage) return;
     try {
-      const persistedItems = parsePersisted(await withTimeout(storage.getItem(key), READ_TIMEOUT_MS));
-      if (persistedItems.length === 0) return;
-      const events = [...persistedItems.map((p) => p.event), ...pending.map((p) => p.event)];
-      pending = [];
-      nextId = 0;
-      const seen = new Set<string>();
-      for (const event of events) {
-        const sig = safeSig(event);
-        if (seen.has(sig)) continue; // collapse duplicates carried across the merge
-        seen.add(sig);
-        pending.push({ id: nextId++, event, sig });
+      const read = Promise.resolve(storage.getItem(key));
+      // A rejecting read must not surface as an unhandled rejection when the race is won by the
+      // timeout; the recovery path below re-attaches its own handlers.
+      read.catch(() => {});
+      const raced = await withTimeout(read, READ_TIMEOUT_MS);
+      if (raced === READ_TIMED_OUT) {
+        backlogUnread = true;
+        warnInDev(
+          `[wireai] the persisted analytics backlog at "${key}" took longer than ${READ_TIMEOUT_MS}ms ` +
+            "to read, so the queue started without it. The stored events are NOT discarded: writes " +
+            "are held back until the read lands, and the backlog is merged in then. If you see this " +
+            "on every cold start, your storage adapter is too slow to be on the launch path.",
+        );
+        void read
+          .then((late) => {
+            backlogUnread = false;
+            mergePersisted(parsePersisted(late));
+            // Send whatever was just recovered; without this it would wait for the next enqueue.
+            flush();
+          })
+          .catch(() => {
+            // The slow read ultimately failed → nothing to preserve, resume normal persistence.
+            backlogUnread = false;
+            persist();
+          });
+        return;
       }
-      enforceSizeCap();
-      persist();
+      mergePersisted(parsePersisted(raced));
     } catch {
       // Unreadable backlog → start empty; nothing enqueued in-memory is lost.
     }

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

@@ -39,6 +39,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 +59,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;