@wireai/activation 0.13.0 → 0.13.3

package/src/cards/PermissionCard.tsx

@@ -0,0 +1,438 @@
+/**
+ * PermissionCard - the priming screen that stands in front of an OS permission dialog.
+ *
+ * THE PRIMING PATTERN, which is the entire point: the OS dialog opens from the primary press
+ * handler and from nowhere else. There is no mount effect, no auto-fire, no timer, and no code path
+ * from render to `request()`. iOS grants an app exactly ONE native notification prompt for its
+ * whole lifetime, so this cheap in-app screen spends first and only forwards the users who said
+ * yes. The secondary ("Maybe later") advances the flow with the prompt still unspent.
+ *
+ * THREE PRIMARY ACTIONS, picked from the non-prompting `getStatus` probe (never from `request`):
+ *   • ask (the default, and the only branch that can reach `request`)
+ *   • settings (status `blocked`: the OS would show nothing, so the only route left is Settings)
+ *   • continue (already granted, or a host that supplied no `request` at all - the kit declines to
+ *     fabricate a prompt it has no way to open)
+ *
+ * IT IS NOT A QUESTION. It sends nothing to the backend, appends nothing to the thread, and mints
+ * no `key` / `slot_id`, so `deriveAnswers` and every completion semantic are untouched. Every
+ * outcome, including a denial, continues the flow.
+ *
+ * Motion: the same register as the other value beats. The illustration springs in
+ * (STATUS_POP_SPRING, the StatusCard glyph pop) and the copy rises behind it on the interstitial
+ * head stagger. Reduce motion: final frame at once, like every other card.
+ *
+ * Registered as a `WireAIComponent` so a later server-emitted placement (AI-chosen timing) renders
+ * through the same component with no rewrite. It is deliberately NOT in `onboardingComponents`:
+ * that array is what the device ADVERTISES as renderable, and a backend told it may emit this card
+ * could emit one for a host that wired no `request`.
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import { Animated, Easing, StyleSheet, Text, View } from "react-native";
+import { z } from "zod";
+import type { InjectedProps, WireAIComponent } from "wireai-rn";
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { bodyStyle, headingStyle } from "../theme/typography";
+import { useIllustration } from "../components/Illustration";
+import { Button } from "../components/Button";
+import { CardLayout } from "../components/CardLayout";
+import {
+  INTERSTITIAL_HEAD_MS,
+  INTERSTITIAL_HEAD_STAGGER_MS,
+  STATUS_POP_SCALE_FROM,
+  STATUS_POP_SPRING,
+  WIRE_BEZIER,
+  scaledMs,
+} from "../motion/motionSpec";
+import { useReducedMotion } from "../motion/useReducedMotion";
+import { normalizePermissionStatus } from "../permissions/permissionEvents";
+import type {
+  PermissionStage,
+  WirePermissionOutcome,
+  WirePermissionStatus,
+} from "../permissions/types";
+import { playHaptic } from "../haptics/haptics";
+import { warnInDev } from "../utils/warnInDev";
+
+const easeWire = Easing.bezier(...WIRE_BEZIER);
+const RISE_PX = 10;
+
+/** The name the card is registered under, and the `component` stamped on its events. */
+export const PERMISSION_CARD_NAME = "PermissionCard";
+
+/**
+ * How long a host's `request` may stay outstanding before the kit hands the controls back.
+ *
+ * DELIBERATELY GENEROUS. This is not a race against the user: someone reading an OS permission
+ * dialog, switching apps mid-prompt, or hitting a slow native bridge is doing nothing wrong, and a
+ * short ceiling would advance the flow underneath a dialog that is still open. It exists for one
+ * failure only, a `request` that never settles at all (a swallowed native callback, a promise
+ * nobody resolves), which would otherwise leave the user on a screen whose buttons are all
+ * disabled. On expiry the kit records NO outcome, because a pending request is not a denial.
+ */
+export const REQUEST_WATCHDOG_MS = 90_000;
+
+/**
+ * The COPY half of the card, i.e. everything a server could legitimately author. The capability
+ * half (`request` / `getStatus` / `openSettings`) is host-injected and deliberately absent here:
+ * a schema field can only ever carry data, never a function, and the kit imports no native module.
+ */
+const schema = z.object({
+  permission: z
+    .string()
+    .describe("Which OS permission this screen primes, e.g. 'notifications'"),
+  title: z.string().describe("Headline for the ask"),
+  message: z.string().describe("Why the app needs it, in the user's terms"),
+  primaryLabel: z.string().describe("Primary button, the only control that can open the OS dialog"),
+  secondaryLabel: z.string().describe("Secondary button, advances without spending the OS prompt"),
+  blockedTitle: z.string().optional().describe("Headline once the permission is permanently refused"),
+  blockedMessage: z.string().optional().describe("Rationale for the settings route"),
+  settingsLabel: z.string().optional().describe("Primary button label on the blocked route"),
+  continueLabel: z.string().optional().describe("Primary button label when there is nothing to ask"),
+  illustration: z
+    .string()
+    .optional()
+    .describe("Name of an app-provided illustration (defaults to the permission name)"),
+});
+
+export type PermissionCardProps = z.infer<typeof schema> &
+  Partial<InjectedProps> & {
+    /** THE ONLY function that can open an OS dialog. Called from the primary handler alone. */
+    request?: () => Promise<WirePermissionStatus>;
+    /** NON-PROMPTING status read. Decides which primary action is offered, nothing else. */
+    getStatus?: () => Promise<WirePermissionStatus>;
+    /** Open the OS settings page. Only reachable on the `blocked` route. */
+    openSettings?: () => void | Promise<void>;
+    /** Reports each moment for analytics. Never control flow. */
+    onStage?: (stage: PermissionStage, status?: WirePermissionStatus) => void;
+    /** Fires exactly once, with the outcome this screen produced. The flow advances on it. */
+    onSettled?: (outcome: WirePermissionOutcome) => void;
+  };
+
+/** Which action the primary button performs. `ask` is the only one that can reach `request`. */
+type PrimaryAction = "ask" | "settings" | "continue";
+
+const _PermissionCard: React.FC<PermissionCardProps> = ({
+  permission,
+  title,
+  message,
+  primaryLabel,
+  secondaryLabel,
+  blockedTitle,
+  blockedMessage,
+  settingsLabel,
+  continueLabel,
+  illustration,
+  request,
+  getStatus,
+  openSettings,
+  onStage,
+  onSettled,
+}) => {
+  const t = useOnboardingTheme();
+  const reduced = useReducedMotion();
+  const art = useIllustration(illustration ?? permission);
+  // The probed status. `undefined` means "not known", which is the ASK state: the kit never
+  // assumes a grant it has not been told about.
+  const [status, setStatus] = useState<WirePermissionStatus | undefined>(undefined);
+  const [busy, setBusy] = useState(false);
+  // One settle per mount. The card is keyed by screen id, so this is one settle per screen. It is
+  // also what makes a late `request` settlement a no-op, since `finish` reaches `settle`
+  // synchronously (see `handlePrimary`).
+  const settledRef = useRef(false);
+  // `accepted` is a per-screen boolean, so `accepted / shown` stays a readable rate.
+  const acceptedRef = useRef(false);
+  const watchdogRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const clearWatchdog = useCallback(() => {
+    if (watchdogRef.current) {
+      clearTimeout(watchdogRef.current);
+      watchdogRef.current = null;
+    }
+  }, []);
+  // A pending watchdog must never outlive the screen (it would setState on an unmounted card).
+  useEffect(() => clearWatchdog, [clearWatchdog]);
+
+  // Host callbacks held in refs so the mount-once effects below stay mount-once no matter how a
+  // host passes them (the documented usage is an INLINE `permissionScreens={[...]}`, which mints a
+  // fresh closure for every one of them on every render).
+  const onStageRef = useRef(onStage);
+  onStageRef.current = onStage;
+  const onSettledRef = useRef(onSettled);
+  onSettledRef.current = onSettled;
+  const getStatusRef = useRef(getStatus);
+  getStatusRef.current = getStatus;
+
+  // `shown` fires once per mount, ref-guarded so StrictMode's dev double-invoke cannot
+  // double-count the denominator every rate in this funnel is measured against.
+  const shownRef = useRef(false);
+  useEffect(() => {
+    if (shownRef.current) return;
+    shownRef.current = true;
+    onStageRef.current?.("shown");
+  }, []);
+
+  // The status probe, MOUNT-ONCE. `getPermissionsAsync()` and its equivalents READ, they never
+  // prompt - which is exactly why `request` is not called here and why this effect may exist at
+  // all. All it decides is which primary action the screen offers.
+  useEffect(() => {
+    const probe = getStatusRef.current;
+    if (!probe) return;
+    let cancelled = false;
+    try {
+      void Promise.resolve(probe())
+        .then((value) => {
+          if (!cancelled) setStatus(normalizePermissionStatus(value));
+        })
+        .catch(() => {
+          // A host probe that throws just leaves the screen in its ask state.
+        });
+    } catch {
+      // A synchronously-throwing probe, same treatment.
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // A host that configured a screen with no `request` gets a screen that cannot ask. The kit says
+  // so instead of rendering a button that silently does nothing (dev only, never a throw).
+  const requestRef = useRef(request);
+  requestRef.current = request;
+  useEffect(() => {
+    if (requestRef.current) return;
+    warnInDev(
+      `[wireai] <WireOnboarding> got a permission screen for "${permission}" with no \`request\` ` +
+        "function, so it cannot open the OS dialog and renders as a plain continue. Pass " +
+        "request: () => Promise<'granted' | 'denied' | 'blocked'> (5 lines around " +
+        "expo-notifications, see the README).",
+    );
+  }, [permission]);
+
+  const settle = useCallback((outcome: WirePermissionOutcome) => {
+    if (settledRef.current) return;
+    settledRef.current = true;
+    clearWatchdog();
+    onSettledRef.current?.(outcome);
+  }, [clearWatchdog]);
+
+  const primaryAction: PrimaryAction =
+    status === "blocked" ? "settings" : status === "granted" || !request ? "continue" : "ask";
+
+  const handlePrimary = useCallback(() => {
+    if (settledRef.current || busy) return;
+
+    if (primaryAction === "settings") {
+      onStageRef.current?.("settings", "blocked");
+      try {
+        void Promise.resolve(openSettings?.()).catch(() => {});
+      } catch {
+        // A settings redirect that fails is not a reason to trap the user on this screen.
+      }
+      settle("blocked");
+      return;
+    }
+
+    if (primaryAction === "continue") {
+      // Already granted (nothing to ask), or no `request` was supplied. Report the state as it is;
+      // never report a grant this screen did not produce as anything other than what it is.
+      if (status === "granted") {
+        onStageRef.current?.("granted", "granted");
+        settle("granted");
+      } else {
+        onStageRef.current?.("skipped");
+        settle("skipped");
+      }
+      return;
+    }
+
+    // THE ONE PATH TO THE OS DIALOG, reachable from this press handler only.
+    //
+    // `accepted` is a per-screen boolean, not a per-tap counter: the screen is shown once, and
+    // `accepted / shown` is the rate that says whether the rationale copy works. A second tap after
+    // the watchdog re-armed the UI would push that rate past 100%, so it is emitted once.
+    if (!acceptedRef.current) {
+      acceptedRef.current = true;
+      onStageRef.current?.("accepted");
+    }
+    setBusy(true);
+    // FIRST SETTLEMENT WINS, and `settledRef` is the whole mechanism. The watchdog below can hand
+    // the UI back while a `request` is still outstanding, so a second tap can put a SECOND one in
+    // flight, and the original can answer late. What decides between them is that this function
+    // runs STRAIGHT THROUGH to `settle` with no await in between: the first settlement to arrive
+    // has already flipped that ref by the time any later one is invoked, so the later one returns
+    // on the line below. The flow advances once and each stage event is emitted once. The same ref
+    // is why a settlement landing after the user skipped changes nothing.
+    const finish = (value: unknown) => {
+      if (settledRef.current) return;
+      clearWatchdog();
+      const resolved = normalizePermissionStatus(value);
+      setBusy(false);
+      setStatus(resolved);
+      if (resolved === "granted") {
+        // A light success tap on the grant, through the kit's optional-peer haptics: a host
+        // without `expo-haptics` simply feels nothing and nothing throws.
+        playHaptic("success");
+        onStageRef.current?.("granted", "granted");
+      } else {
+        onStageRef.current?.("denied", resolved);
+      }
+      settle(resolved);
+    };
+
+    // THE WATCHDOG, and what it deliberately does NOT do.
+    //
+    // A host `request` that never settles (a native module that swallows its callback, a promise
+    // that is never resolved) would otherwise BRICK the screen: `busy` disables both buttons, the
+    // secondary re-guards on it, and nothing upstream rescues a rendered card. Dead end, and
+    // `onComplete` never fires.
+    //
+    // So the ceiling exists to un-brick a HOST BUG, never to race the user. A person can sit on an
+    // OS permission dialog for a long time, so a short ceiling that recorded `denied` on expiry
+    // would advance the flow underneath a dialog that is still open and log an outcome the user
+    // never gave. On expiry this therefore fabricates NOTHING: no outcome, no event, no settle. It
+    // only hands the controls back so the user can tap again or skip, and says so in dev.
+    clearWatchdog();
+    watchdogRef.current = setTimeout(() => {
+      watchdogRef.current = null;
+      if (settledRef.current) return;
+      setBusy(false);
+      warnInDev(
+        `[wireai] the \`request\` for the "${permission}" permission screen has not settled after ` +
+          `${Math.round(REQUEST_WATCHDOG_MS / 1000)}s, so the kit handed the controls back rather ` +
+          "than leaving the user on a dead-end screen. It recorded NO outcome, because a pending " +
+          "request is not a denial. Make sure your request resolves to 'granted' | 'denied' | " +
+          "'blocked' on every branch, including the one where the user dismisses the OS dialog.",
+      );
+    }, REQUEST_WATCHDOG_MS);
+
+    try {
+      void Promise.resolve(request?.()).then(finish, () => finish("denied"));
+    } catch {
+      // A synchronously-throwing request is a denial, never a stuck screen.
+      finish("denied");
+    }
+  }, [busy, primaryAction, status, request, openSettings, settle, clearWatchdog, permission]);
+
+  const handleSecondary = useCallback(() => {
+    if (settledRef.current || busy) return;
+    onStageRef.current?.("skipped");
+    settle("skipped");
+  }, [busy, settle]);
+
+  // Art springs in, copy rises behind it (final frame at once under reduce motion).
+  const popT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const titleT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  const bodyT = useRef(new Animated.Value(reduced ? 1 : 0)).current;
+  useEffect(() => {
+    if (reduced) {
+      popT.setValue(1);
+      titleT.setValue(1);
+      bodyT.setValue(1);
+      return;
+    }
+    const rise = (value: Animated.Value, delay: number) =>
+      Animated.timing(value, {
+        toValue: 1,
+        duration: scaledMs(INTERSTITIAL_HEAD_MS),
+        delay,
+        easing: easeWire,
+        useNativeDriver: true,
+      });
+    const anims = [
+      Animated.spring(popT, {
+        toValue: 1,
+        friction: STATUS_POP_SPRING.friction,
+        tension: STATUS_POP_SPRING.tension,
+        useNativeDriver: true,
+      }),
+      rise(titleT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS)),
+      rise(bodyT, scaledMs(INTERSTITIAL_HEAD_STAGGER_MS * 2)),
+    ];
+    anims.forEach((a) => a.start());
+    return () => anims.forEach((a) => a.stop());
+  }, [reduced, popT, titleT, bodyT]);
+
+  const popScale = popT.interpolate({
+    inputRange: [0, 1],
+    outputRange: [STATUS_POP_SCALE_FROM, 1],
+  });
+  const riseStyle = (value: Animated.Value) => ({
+    opacity: value,
+    transform: [
+      { translateY: value.interpolate({ inputRange: [0, 1], outputRange: [RISE_PX, 0] }) },
+    ],
+  });
+
+  const blocked = status === "blocked";
+  const shownTitle = blocked ? (blockedTitle ?? title) : title;
+  const shownMessage = blocked ? (blockedMessage ?? message) : message;
+  const primaryTitle =
+    primaryAction === "settings"
+      ? (settingsLabel ?? primaryLabel)
+      : primaryAction === "continue"
+        ? (continueLabel ?? primaryLabel)
+        : primaryLabel;
+  // Nothing left to decline once the permission is already granted.
+  const showSecondary = status !== "granted";
+
+  return (
+    <CardLayout
+      align="center"
+      footer={
+        <View style={[styles.footer, { gap: t.spacing.sm }]}>
+          <Button title={primaryTitle} onPress={handlePrimary} variant="primary" disabled={busy} />
+          {showSecondary ? (
+            <Button
+              title={secondaryLabel}
+              onPress={handleSecondary}
+              variant="outline"
+              disabled={busy}
+            />
+          ) : null}
+        </View>
+      }
+    >
+      <View style={[styles.center, { gap: t.spacing.md }]}>
+        {art ? (
+          <Animated.View
+            style={[styles.art, { opacity: popT, transform: [{ scale: popScale }] }]}
+          >
+            {art}
+          </Animated.View>
+        ) : null}
+
+        <Animated.View style={riseStyle(titleT)}>
+          <Text style={[headingStyle(t.fonts), { color: t.colors.text, textAlign: "center" }]}>
+            {shownTitle}
+          </Text>
+        </Animated.View>
+
+        <Animated.View style={riseStyle(bodyT)}>
+          <Text style={[bodyStyle(t.fonts), { color: t.colors.textMuted, textAlign: "center" }]}>
+            {shownMessage}
+          </Text>
+        </Animated.View>
+      </View>
+    </CardLayout>
+  );
+};
+
+/** The typed component the flow renders directly (host-injected placement). */
+export const PermissionCardView = React.memo(_PermissionCard);
+
+/**
+ * The SDK registration object, so a server-emitted placement can adopt this exact screen later.
+ * Not part of `onboardingComponents` on purpose - see the file header.
+ */
+export const PermissionCard: WireAIComponent = {
+  name: PERMISSION_CARD_NAME,
+  description:
+    "A priming screen shown BEFORE an OS permission dialog: it explains why the app wants the permission and asks only on the primary tap. Never first, never last. The user is never blocked by it: the secondary advances the flow with the OS prompt unspent.",
+  component: PermissionCardView as WireAIComponent["component"],
+  propsSchema: schema,
+};
+
+const styles = StyleSheet.create({
+  center: { width: "100%", alignItems: "center", justifyContent: "center" },
+  art: { alignItems: "center", justifyContent: "center" },
+  footer: { width: "100%", alignItems: "center" },
+});

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/cards/index.ts

@@ -21,9 +21,16 @@ export {
   NumberStepperCard,
   InterstitialCard,
 };
+export { PermissionCard, PermissionCardView, PERMISSION_CARD_NAME } from "./PermissionCard";
+export type { PermissionCardProps } from "./PermissionCard";
 export { normalizeOptions, optionsField, optionObjectSchema } from "./optionSchema";
 export type { CardOption } from "./optionSchema";
 
+// ⚠️ `PermissionCard` is deliberately NOT in this array. The list is what the device ADVERTISES to
+// the backend as renderable (`metadata.supportedComponents`), and a backend told it may emit a
+// permission screen could emit one into a host that injected no `request` function, which the kit
+// has no way to honour. Permission screens are host-declared for now (`permissionScreens`); the
+// card is registered and ready for the day a server-emitted placement lands.
 export const onboardingComponents: WireAIComponent[] = [
   ChipSelectCard,
   TextInputCard,

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;

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(