@wireai/activation 0.15.0 → 0.16.0

package/dist/coachmarks/index.d.mts

@@ -29,6 +29,11 @@ interface CoachmarkProviderProps {
      * pre-resolved `features`, OR a `featuresConfig` (serverUrl + apiKey) to lazily fetch once, OR
      * mount a `WireFeaturesProvider` above (context is read automatically). Omit all three and
      * coachmarks stay on (fail-open) — zero behavior change for hosts that never adopt flags.
+     *
+     * While a fetch is still in flight, a NEW tour does not arm (so a tenant who switched the module
+     * off gets no first impression), and a tour already in flight is never torn down. Nothing is
+     * spent by that wait: no once-gate is consumed, so an ON answer plays the tour in full. A failed
+     * fetch is an answer — fail-open is unchanged.
      */
     features?: WireFeatures;
     /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
@@ -130,6 +135,15 @@ interface UseCoachmarkTourOptions {
  * `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.
  *
+ * ARM vs TERMINAL — the third gate, and why it is not the second one. Until the tenant's flags
+ * land, that kill switch reads ON because nobody has asked yet, so a tenant who turned coachmarks
+ * OFF still got the first tour of every cold start. The wait CANNOT be expressed by writing the
+ * kill switch false, precisely because that flag is terminal: it would end the tour of every
+ * ENABLED tenant on every cold start, a worse defect than the one being fixed. So an UNANSWERED
+ * verdict (`areCoachmarksResolved`, written by CoachmarkProvider from the features' `settled`)
+ * blocks only the ARM below — a tour already in flight is never touched by it — and costs nothing
+ * while it waits: no timer, no overlay, no once-gate spent.
+ *
  * 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

package/dist/coachmarks/index.d.ts

@@ -29,6 +29,11 @@ interface CoachmarkProviderProps {
      * pre-resolved `features`, OR a `featuresConfig` (serverUrl + apiKey) to lazily fetch once, OR
      * mount a `WireFeaturesProvider` above (context is read automatically). Omit all three and
      * coachmarks stay on (fail-open) — zero behavior change for hosts that never adopt flags.
+     *
+     * While a fetch is still in flight, a NEW tour does not arm (so a tenant who switched the module
+     * off gets no first impression), and a tour already in flight is never torn down. Nothing is
+     * spent by that wait: no once-gate is consumed, so an ON answer plays the tour in full. A failed
+     * fetch is an answer — fail-open is unchanged.
      */
     features?: WireFeatures;
     /** Lazy-fetch config for the flags, used when `features` is absent and no provider is above. */
@@ -130,6 +135,15 @@ interface UseCoachmarkTourOptions {
  * `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.
  *
+ * ARM vs TERMINAL — the third gate, and why it is not the second one. Until the tenant's flags
+ * land, that kill switch reads ON because nobody has asked yet, so a tenant who turned coachmarks
+ * OFF still got the first tour of every cold start. The wait CANNOT be expressed by writing the
+ * kill switch false, precisely because that flag is terminal: it would end the tour of every
+ * ENABLED tenant on every cold start, a worse defect than the one being fixed. So an UNANSWERED
+ * verdict (`areCoachmarksResolved`, written by CoachmarkProvider from the features' `settled`)
+ * blocks only the ARM below — a tour already in flight is never touched by it — and costs nothing
+ * while it waits: no timer, no overlay, no once-gate spent.
+ *
  * 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

package/dist/coachmarks/index.js

@@ -95,17 +95,31 @@ var failOpen = async (storage, key) => {
   const cached3 = await readCachedFeatures(storage, key);
   return (_a = cached3 == null ? void 0 : cached3.features) != null ? _a : defaultWireFeatures;
 };
-var fetchWithTimeout = async (url, apiKey, timeoutMs) => {
+var NO_ANSWER = /* @__PURE__ */ Symbol("wire-features-no-answer");
+var fetchFeaturesJson = async (url, apiKey, timeoutMs) => {
   const controller = typeof AbortController !== "undefined" ? new AbortController() : void 0;
-  const timer = setTimeout(() => controller == null ? void 0 : controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, {
+  let timer;
+  const expired = new Promise((resolve) => {
+    timer = setTimeout(() => {
+      controller == null ? void 0 : controller.abort();
+      resolve(NO_ANSWER);
+    }, timeoutMs);
+  });
+  const exchange = (async () => {
+    const res = await fetch(url, {
       method: "GET",
       headers: { Accept: "application/json", Authorization: `Bearer ${apiKey}` },
       signal: controller == null ? void 0 : controller.signal
     });
+    if (!res || !res.ok) return NO_ANSWER;
+    return await res.json();
+  })();
+  try {
+    return await Promise.race([exchange, expired]);
   } finally {
     clearTimeout(timer);
+    void exchange.catch(() => {
+    });
   }
 };
 var fetchWireFeatures = async (config) => {
@@ -115,9 +129,8 @@ var fetchWireFeatures = async (config) => {
   const url = `${config.serverUrl.replace(/\/$/, "")}/v1/features`;
   const timeoutMs = config.timeoutMs && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS;
   try {
-    const res = await fetchWithTimeout(url, config.apiKey, timeoutMs);
-    if (!res || !res.ok) return failOpen(storage, key);
-    const json = await res.json();
+    const json = await fetchFeaturesJson(url, config.apiKey, timeoutMs);
+    if (json === NO_ANSWER) return failOpen(storage, key);
     const features = parseWireFeatures(json);
     if (storage) writeCachedFeatures(storage, key, features);
     return features;
@@ -133,39 +146,51 @@ var useStableValue = (value, isEqual) => {
   return ref.current;
 };
 var sameFetchKey = (a, b) => (a == null ? void 0 : a.serverUrl) === (b == null ? void 0 : b.serverUrl) && (a == null ? void 0 : a.apiKey) === (b == null ? void 0 : b.apiKey) && (a == null ? void 0 : a.appId) === (b == null ? void 0 : b.appId);
-var useWireFeatures = (config) => {
+var useWireFeaturesState = (config) => {
   const stableConfig = useStableValue(config, sameFetchKey);
   const [flags, setFlags] = React3.useState(defaultWireFeatures);
   const canFetch = !!(stableConfig == null ? void 0 : stableConfig.serverUrl) && !!(stableConfig == null ? void 0 : stableConfig.apiKey);
+  const [settled, setSettled] = React3.useState(!canFetch);
   React3.useEffect(() => {
     if (!canFetch) {
       setFlags((prev) => featuresEqual(prev, defaultWireFeatures) ? prev : defaultWireFeatures);
+      setSettled(true);
       return;
     }
     let alive = true;
     void fetchWireFeatures(stableConfig).then((next) => {
       if (!alive) return;
       setFlags((prev) => featuresEqual(prev, next) ? prev : next);
+      setSettled(true);
     });
     return () => {
       alive = false;
     };
   }, [canFetch, stableConfig]);
-  return flags;
+  return React3.useMemo(() => ({ flags, settled }), [flags, settled]);
 };
 var CONTEXT_SYMBOL = /* @__PURE__ */ Symbol.for("wireai.features.context");
-var globalObj = globalThis;
-if (!globalObj[CONTEXT_SYMBOL]) {
-  globalObj[CONTEXT_SYMBOL] = React3.createContext(null);
+var featuresContextGlobal = globalThis;
+if (!featuresContextGlobal[CONTEXT_SYMBOL]) {
+  featuresContextGlobal[CONTEXT_SYMBOL] = React3.createContext(null);
 }
-var WireFeaturesContext = globalObj[CONTEXT_SYMBOL];
+var WireFeaturesContext = featuresContextGlobal[CONTEXT_SYMBOL];
+var SETTLED_SYMBOL = /* @__PURE__ */ Symbol.for("wireai.features.settled.context");
+var settledContextGlobal = globalThis;
+if (!settledContextGlobal[SETTLED_SYMBOL]) {
+  settledContextGlobal[SETTLED_SYMBOL] = React3.createContext(true);
+}
+var WireFeaturesSettledContext = settledContextGlobal[SETTLED_SYMBOL];
 var useWireFeaturesContext = () => React3.useContext(WireFeaturesContext);
-var useResolvedFeatures = (options) => {
+var useResolvedFeaturesState = (options) => {
   var _a, _b, _c;
   const ctx = useWireFeaturesContext();
+  const ctxSettled = React3.useContext(WireFeaturesSettledContext);
   const shouldFetch = !(options == null ? void 0 : options.flags) && ctx == null;
-  const fetched = useWireFeatures(shouldFetch ? options == null ? void 0 : options.config : void 0);
-  return (_c = (_b = (_a = options == null ? void 0 : options.flags) != null ? _a : ctx) != null ? _b : fetched) != null ? _c : defaultWireFeatures;
+  const fetched = useWireFeaturesState(shouldFetch ? options == null ? void 0 : options.config : void 0);
+  const flags = (_c = (_b = (_a = options == null ? void 0 : options.flags) != null ? _a : ctx) != null ? _b : fetched.flags) != null ? _c : defaultWireFeatures;
+  const settled = (options == null ? void 0 : options.flags) ? true : ctx != null ? ctxSettled : fetched.settled;
+  return React3.useMemo(() => ({ flags, settled }), [flags, settled]);
 };
 
 // src/coachmarks/runtime.ts
@@ -201,6 +226,17 @@ var setCoachmarksEnabled = (value) => {
   notifyCoachmarksEnabled();
 };
 var areCoachmarksEnabled = () => coachmarkRuntime().coachmarksEnabled;
+var setCoachmarksResolved = (value) => {
+  var _a;
+  const runtime = coachmarkRuntime();
+  if (((_a = runtime.coachmarksResolved) != null ? _a : true) === value) return;
+  runtime.coachmarksResolved = value;
+  notifyCoachmarksEnabled();
+};
+var areCoachmarksResolved = () => {
+  var _a;
+  return (_a = coachmarkRuntime().coachmarksResolved) != null ? _a : true;
+};
 var subscribeCoachmarksEnabled = (listener) => {
   const listeners2 = enabledListeners();
   listeners2.add(listener);
@@ -1013,22 +1049,28 @@ var CoachmarkProvider = ({
   featuresConfig,
   children
 }) => {
-  const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
-  const coachmarksOn = flags.coachmarks.enabled;
+  const { flags, settled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig
+  });
+  const coachmarksOn = settled ? flags.coachmarks.enabled : true;
   setCoachmarkStorage(storage);
   setCoachmarkTesting(isTestingCoachmark);
+  setCoachmarksResolved(settled);
   setCoachmarksEnabled(coachmarksOn);
   React3.useEffect(() => {
     setCoachmarkStorage(storage);
     setCoachmarkTesting(isTestingCoachmark);
+    setCoachmarksResolved(settled);
     setCoachmarksEnabled(coachmarksOn);
     return () => {
       if (getCoachmarkStorage() === storage) {
         setCoachmarkStorage(null);
       }
       setCoachmarksEnabled(true);
+      setCoachmarksResolved(true);
     };
-  }, [storage, isTestingCoachmark, coachmarksOn]);
+  }, [storage, isTestingCoachmark, coachmarksOn, settled]);
   return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
     children,
     /* @__PURE__ */ jsxRuntime.jsx(
@@ -1131,6 +1173,11 @@ var useCoachmarkTour = (steps, {
     areCoachmarksEnabled,
     areCoachmarksEnabled
   );
+  const coachmarksResolved = React3.useSyncExternalStore(
+    subscribeCoachmarksEnabled,
+    areCoachmarksResolved,
+    areCoachmarksResolved
+  );
   const exit = React3.useCallback(
     (writeGate) => {
       if (finishedRef.current) return;
@@ -1145,14 +1192,16 @@ var useCoachmarkTour = (steps, {
   const finish = React3.useCallback(() => exit(true), [exit]);
   React3.useEffect(() => {
     if (!enabled || startedRef.current) return void 0;
+    if (steps.length === 0) return void 0;
     if (!coachmarksOn) return void 0;
+    if (!coachmarksResolved) return void 0;
     if (showOnce && hasSeenGate(coachmarkGateKey(tourId))) return void 0;
     const timer = setTimeout(() => {
       startedRef.current = true;
       setActiveIndex(0);
     }, startDelayMs);
     return () => clearTimeout(timer);
-  }, [enabled, coachmarksOn, startDelayMs, showOnce, tourId]);
+  }, [enabled, coachmarksOn, coachmarksResolved, startDelayMs, showOnce, tourId, steps.length]);
   React3.useEffect(() => {
     if (activeIndex === null) return void 0;
     if (!coachmarksOn) {
@@ -1163,6 +1212,10 @@ var useCoachmarkTour = (steps, {
       if (startedRef.current && !finishedRef.current) coachmarkOverlay.hide();
       return void 0;
     }
+    if (steps.length === 0) {
+      exit(false);
+      return void 0;
+    }
     if (activeIndex >= steps.length) {
       finish();
       return void 0;