@wireai/activation 0.13.2 → 0.13.3

package/dist/coachmarks/index.d.mts

@@ -121,6 +121,15 @@ interface UseCoachmarkTourOptions {
  * 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
@@ -164,7 +173,11 @@ steps: CoachmarkStep[], { tourId, showOnce, enabled, startDelayMs, onComplete, o
 
 /**
  * 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.
  */
 declare const setCoachmarksEnabled: (value: boolean) => void;
 /** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */

package/dist/coachmarks/index.d.ts

@@ -121,6 +121,15 @@ interface UseCoachmarkTourOptions {
  * 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
@@ -164,7 +173,11 @@ steps: CoachmarkStep[], { tourId, showOnce, enabled, startDelayMs, onComplete, o
 
 /**
  * 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.
  */
 declare const setCoachmarksEnabled: (value: boolean) => void;
 /** Whether the coachmarks module is enabled. False → tours/overlays are silently skipped. */

package/dist/coachmarks/index.js

@@ -152,7 +152,7 @@ var useWireFeatures = (config) => {
   return flags;
 };
 var CONTEXT_SYMBOL = /* @__PURE__ */ Symbol.for("wireai.features.context");
-var globalObj = global;
+var globalObj = globalThis;
 if (!globalObj[CONTEXT_SYMBOL]) {
   globalObj[CONTEXT_SYMBOL] = React3.createContext(null);
 }
@@ -176,10 +176,36 @@ var coachmarkRuntime = () => {
   runtimeGlobal[COACHMARK_RUNTIME_SLOT] = created;
   return created;
 };
+var enabledListeners = () => {
+  const runtime = coachmarkRuntime();
+  if (!runtime.listeners) runtime.listeners = /* @__PURE__ */ new Set();
+  return runtime.listeners;
+};
+var notifyCoachmarksEnabled = () => {
+  if (enabledListeners().size === 0) return;
+  void Promise.resolve().then(() => {
+    for (const listener of [...enabledListeners()]) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  });
+};
 var setCoachmarksEnabled = (value) => {
-  coachmarkRuntime().coachmarksEnabled = value;
+  const runtime = coachmarkRuntime();
+  if (runtime.coachmarksEnabled === value) return;
+  runtime.coachmarksEnabled = value;
+  notifyCoachmarksEnabled();
 };
 var areCoachmarksEnabled = () => coachmarkRuntime().coachmarksEnabled;
+var subscribeCoachmarksEnabled = (listener) => {
+  const listeners2 = enabledListeners();
+  listeners2.add(listener);
+  return () => {
+    listeners2.delete(listener);
+  };
+};
 var setCoachmarkStorage = (storage) => {
   coachmarkRuntime().storage = storage;
 };
@@ -293,7 +319,12 @@ var defaultOnboardingTheme = {
 var mergeTheme = (override) => {
   return defaultOnboardingTheme;
 };
-var OnboardingThemeContext = React3.createContext(null);
+var THEME_CONTEXT_SLOT = /* @__PURE__ */ Symbol.for("@wireai/activation:themeContext");
+var themeGlobal = globalThis;
+if (!themeGlobal[THEME_CONTEXT_SLOT]) {
+  themeGlobal[THEME_CONTEXT_SLOT] = React3.createContext(null);
+}
+var OnboardingThemeContext = themeGlobal[THEME_CONTEXT_SLOT];
 var useOnboardingTheme = () => {
   const ctx = React3.useContext(OnboardingThemeContext);
   return ctx != null ? ctx : mergeTheme();
@@ -838,26 +869,39 @@ var useCoachmarkTour = (steps, {
   const lastShownStepIdRef = React3.useRef(null);
   const callbacksRef = React3.useRef({ onStepShown, onStepEngaged, onStepDismissed });
   callbacksRef.current = { onStepShown, onStepEngaged, onStepDismissed };
-  const finish = React3.useCallback(() => {
-    if (finishedRef.current) return;
-    finishedRef.current = true;
-    if (showOnce) markSeenGate(coachmarkGateKey(tourId));
-    coachmarkOverlay.hide();
-    setActiveIndex(null);
-    onComplete == null ? void 0 : onComplete();
-  }, [onComplete, showOnce, tourId]);
+  const coachmarksOn = React3.useSyncExternalStore(
+    subscribeCoachmarksEnabled,
+    areCoachmarksEnabled,
+    areCoachmarksEnabled
+  );
+  const exit = React3.useCallback(
+    (writeGate) => {
+      if (finishedRef.current) return;
+      finishedRef.current = true;
+      if (writeGate && showOnce) markSeenGate(coachmarkGateKey(tourId));
+      coachmarkOverlay.hide();
+      setActiveIndex(null);
+      onComplete == null ? void 0 : onComplete();
+    },
+    [onComplete, showOnce, tourId]
+  );
+  const finish = React3.useCallback(() => exit(true), [exit]);
   React3.useEffect(() => {
     if (!enabled || startedRef.current) return void 0;
-    if (!areCoachmarksEnabled()) return void 0;
+    if (!coachmarksOn) return void 0;
     if (showOnce && hasSeenGate(coachmarkGateKey(tourId))) return void 0;
     const timer = setTimeout(() => {
       startedRef.current = true;
       setActiveIndex(0);
     }, startDelayMs);
     return () => clearTimeout(timer);
-  }, [enabled, startDelayMs, showOnce, tourId]);
+  }, [enabled, coachmarksOn, startDelayMs, showOnce, tourId]);
   React3.useEffect(() => {
     if (activeIndex === null) return void 0;
+    if (!coachmarksOn) {
+      exit(false);
+      return void 0;
+    }
     if (!enabled) {
       if (startedRef.current && !finishedRef.current) coachmarkOverlay.hide();
       return void 0;
@@ -907,7 +951,7 @@ var useCoachmarkTour = (steps, {
     return () => {
       cancelled = true;
     };
-  }, [activeIndex, steps, finish, enabled]);
+  }, [activeIndex, steps, finish, exit, enabled, coachmarksOn]);
   React3.useEffect(
     () => () => {
       if (!finishedRef.current) coachmarkOverlay.hide();