@wireai/activation 0.14.3 → 0.16.0

package/src/showcase/FeatureShowcase.tsx

@@ -9,7 +9,8 @@ import { type ImageSourcePropType, StyleSheet, View } from "react-native";
 
 import { GestureHint } from "../coachmarks/GestureHint";
 import { hasSeenGate, markSeenGate, showcaseGateKey } from "../coachmarks/runtime";
-import { useResolvedFeatures } from "../features/WireFeaturesProvider";
+import { useResolvedFeaturesState } from "../features/WireFeaturesProvider";
+import { READ_TIMEOUT_MS } from "../session/persistedSession";
 import { useOnboardingTheme } from "../theme/ThemeContext";
 import type { OnboardingTheme } from "../theme/types";
 import { resolveShowcaseOnboarding } from "./blazejOnboarding";
@@ -49,6 +50,11 @@ const mergeThemeOver = (
  * When the gate says "seen", it renders nothing and calls `onDone` from an
  * effect (never during render).
  *
+ * When the tenant's feature answer has not landed yet AND the flags could still change the
+ * outcome (an unseen gate + a resolvable pager), it renders nothing and calls nothing for up to
+ * `READ_TIMEOUT_MS`, then falls through to the optimistic path. That window is bounded, and only
+ * ever reached on the launch the showcase would actually play; see the hold note below.
+ *
  * The underlying package is an OPTIONAL peer, resolved through the guarded lazy
  * require in `blazejOnboarding.ts` rather than a static import, so the showcase
  * subpath builds on a host that never installed it. Absent, this takes the SAME
@@ -76,7 +82,11 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
 
   // Feature kill switch: disabled → treat like "already seen" (render nothing, call onDone so the
   // host flow continues) but WITHOUT writing the seen gate, so re-enabling replays the showcase.
-  const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
+  // `settled` separates the tenant's ANSWER from the optimistic all-on default; see the hold below.
+  const { flags, settled } = useResolvedFeaturesState({
+    flags: features,
+    config: featuresConfig,
+  });
   const disabled = !flags.showcase.enabled;
 
   // The optional pager peer. Resolved once, on first render, instead of at module scope — so
@@ -94,6 +104,37 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   // the feature is re-enabled or the peer is installed.
   const skip = seen || disabled || !Onboarding;
 
+  /**
+   * THE FIRST-FRAME HOLD, and why it is scoped this tightly.
+   *
+   * The flags start all-on and swap when `GET /v1/features` resolves, so on a cold start `disabled`
+   * reads false because nobody has asked yet. A tenant who switched the showcase OFF therefore got
+   * the whole full-screen intro anyway — and if the user tapped through it inside that window,
+   * `finish` wrote the seen gate, so the showcase never replayed even after the tenant re-enabled
+   * it. Silent, permanent, once per install.
+   *
+   * The seam the review + questionnaire gates use — hold the first render outright until the
+   * flags settle — does not port unchanged: this component's disabled path calls `onDone`, so a
+   * naive hold on `!settled` would leave a blank full screen, and on every launch, including the
+   * ones where the flags cannot change the outcome at all.
+   * Two things bound it:
+   *   • `flagsCouldMatter` — an already-seen gate or an absent pager skips whatever the tenant
+   *     answers, so those launches (which is every launch after the first) never wait at all;
+   *   • `READ_TIMEOUT_MS` — the repo's one exported read ceiling, reused rather than a third
+   *     number invented here. The features fetch's own ceiling is 4000ms, which is too long to
+   *     stare at nothing, so an answer that has not arrived by then falls through to the previous
+   *     optimistic behaviour. Fail-open in the time dimension: the worst case is what shipped
+   *     before, reached later.
+   */
+  const flagsCouldMatter = !seen && !!Onboarding;
+  const [holdExpired, setHoldExpired] = useState(false);
+  useEffect(() => {
+    if (settled || holdExpired || !flagsCouldMatter) return undefined;
+    const timer = setTimeout(() => setHoldExpired(true), READ_TIMEOUT_MS);
+    return () => clearTimeout(timer);
+  }, [settled, holdExpired, flagsCouldMatter]);
+  const holding = flagsCouldMatter && !settled && !holdExpired;
+
   const doneRef = useRef(false);
   const finish = useCallback(() => {
     if (doneRef.current) return;
@@ -105,11 +146,14 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   // Already seen OR disabled → skip without rendering; call onDone from an effect so the host's
   // navigation continues (never write the gate here — `finish` owns the seen write).
   useEffect(() => {
+    // Never advance the host while holding: `onDone` is the host's navigation, and a skip decided
+    // on the optimistic default is the same guess the render path refuses below.
+    if (holding) return;
     if (skip && !doneRef.current) {
       doneRef.current = true;
       onDone();
     }
-  }, [skip, onDone]);
+  }, [holding, skip, onDone]);
 
   const [activeIndex, setActiveIndex] = useState(0);
 
@@ -191,6 +235,9 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
     [t],
   );
 
+  // Holding for the tenant's answer: render nothing AND advance nothing (the effect above is
+  // gated too), so a disabled tenant never gets the first frame and never burns the seen gate.
+  if (holding) return null;
   // `!Onboarding` is already folded into `skip`; it is repeated here so the narrowing is explicit
   // to the reader and to the compiler at the JSX below.
   if (skip || !Onboarding) return null;

package/src/types.ts

@@ -240,10 +240,11 @@ export type WireOnboardingProps = {
    * Build the value with the helper so the wire spelling is decided in one place:
    *
    * ```tsx
-   * <WireOnboarding userContext={activationJoinContext(deviceKey)} ... />
-   * // no device id of your own? pass `storage` and leave this prop alone — the kit injects its
-   * // own key, and only after it has confirmed the key actually persists (see `autoJoinKey`).
-   * <WireOnboarding config={{ ...config, storage }} ... />
+   * <WireOnboarding config={config} userContext={activationJoinContext(deviceKey)} ... />
+   * // no device id of your own? pass the `storage` PROP (it is a prop of this component, never a
+   * // field of `WireOnboardingConfig`) and leave this prop alone — the kit injects its own key,
+   * // and only after it has confirmed the key actually persists (see `autoJoinKey`).
+   * <WireOnboarding config={config} storage={storage} ... />
    * ```
    *
    * ⛔ Do NOT hand-build the auto key with `activationJoinContext(resolveAutoDeviceKey({...}))`.
@@ -256,8 +257,11 @@ export type WireOnboardingProps = {
    *
    * SINCE 0.12.2, leaving it out no longer silently empties the funnel: when you pass `storage` and
    * this prop carries no `device_key`, the kit injects its OWN per-install key — the same one the
-   * analytics surfaces mint and persist — so the default wiring joins. Anything you DO pass wins
-   * verbatim and is never touched. See `autoJoinKey` for the opt-out and the two cases where the kit
+   * analytics surfaces mint and persist — so the default wiring joins. A `device_key` you DO pass
+   * wins verbatim and is never touched, provided it is a string with at least one non-whitespace
+   * character (`resolveIdentity`) — this map also accepts numbers and booleans, and a non-string or
+   * all-whitespace value is not a usable join key, so it is read as absent and the auto key is
+   * merged over it. See `autoJoinKey` for the opt-out and the two cases where the kit
    * still cannot fill the gap (no `storage`, or you opted out), which keep warning in dev.
    *
    * Never hand-write `userContext={{ deviceKey }}`: the server's device lookup reads `device_key`,
@@ -284,8 +288,11 @@ export type WireOnboardingProps = {
    * `autoJoinKey={false}` if you genuinely want an UNLINKED onboarding session; that restores the
    * pre-0.12.2 behavior exactly (nothing injected) and the dev warning fires again.
    *
-   * Two things this flag does NOT do. It never overrides a `device_key` you passed — a host-supplied
-   * key always wins, whatever this is set to. And it cannot conjure a key without `storage`: with no
+   * Two things this flag does NOT do. It never overrides a `device_key` you actually supplied — a
+   * host-supplied key always wins, whatever this is set to, where "supplied" means a string with at
+   * least one non-whitespace character (`resolveIdentity`); a non-string or an all-whitespace value
+   * is read as absent and the auto key is merged over it. And it cannot conjure a key without
+   * `storage`: with no
    * persistence the kit's id is minted fresh every launch, and a per-launch key corrupts
    * `min_sessions` instead of merely leaving the join empty, so the kit declines to inject and warns
    * in dev instead.

package/src/utils/submitResult.ts

@@ -21,19 +21,27 @@
  *
  * `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.
+ * treats `false` as "still owed" and re-posts. At the time neither body carried a client id, so
+ * there was NO idempotency key on the wire on either surface: a 502 returned AFTER the insert
+ * commits meant the re-post wrote 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 — which is why the
+ * three values stay, on both surfaces, whatever the wire gains.
  *
  * ── 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.
+ * device. Closing that window needs a client-minted idempotency key the server upserts on, and AS
+ * OF 2026-08-19 THE TWO SURFACES DIFFER — do not read this paragraph as one fact about both:
+ *
+ *   • REVIEWS — closed. `CreateReviewRequest` takes an optional `idempotency_key` and the server
+ *     upserts a derived row on it, so a `ReviewGate` re-post merges instead of duplicating. It is a
+ *     capability, not a guarantee: the server honours the key only when the post also carries a
+ *     unit to scope it to (`meta.device_key`, else `session_id`), so a caller that strips both is
+ *     back to the old behaviour.
+ *   • QUESTIONNAIRES — still open, and still exactly as this paragraph used to read for both. The
+ *     response body carries no client id and the server has no idempotency path for it at all, so
+ *     retrying only on `unsent` there is SAFER, not SAFE. 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.
  */
 export type SubmitResult = "accepted" | "rejected" | "unsent";

package/src/utils/withDeadline.ts

@@ -0,0 +1,70 @@
+/**
+ * withDeadline — put a CEILING on an awaited network exchange, body read included.
+ *
+ * ── THE DEFECT CLASS THIS CLOSES ───────────────────────────────────────────────────────────────
+ * The kit's awaited `fetch` calls used to split into two groups. `eventQueue.postBatch` and
+ * `wireDoctor` each carried their own `AbortController` + 15s / 10s timer; the review and
+ * questionnaire transports and `reportClientEventsOutcome` carried nothing at all. A hung request on
+ * one of those has no ceiling but the PLATFORM's, which on iOS is ~60s — and for that whole window
+ * `ReviewGate` / `QuestionnaireGate`'s `postOnce` latch stays closed (so the unmount recovery net
+ * cannot re-post) and a host's `await wire.track()` stays pending. It is bounded, so it is not the
+ * hang; it is the thing that WIDENS the in-flight window every other fix in this area narrows.
+ *
+ * ── WHY TWO MECHANISMS, NOT JUST AN ABORT ──────────────────────────────────────────────────────
+ * Lifted verbatim in shape from `features/fetchWireFeatures.ts`, which learned it the expensive way:
+ * a timer cleared around the `fetch` alone dies the moment the HEADERS land, so `await res.json()`
+ * then runs with no ceiling at all and a proxy that flushes headers and hangs pends forever. So the
+ * exchange callback owns the body read too, and there are two independent guards:
+ *
+ *   • the ABORT tears the socket down, so a stalled stream is cancelled and not merely un-awaited;
+ *   • the RACE guarantees this promise SETTLES even on a runtime that ignores `signal` once the body
+ *     has started (RN's `fetch` is the XHR polyfill; abort support is not something to bet a latch on).
+ *
+ * A ceiling that depends on the host honouring abort is not a ceiling.
+ *
+ * INTERNAL SEAM — deliberately not on the public barrels, like `utils/warnInDev` and
+ * `analytics/currentSession`'s `isMintedSessionId`. It is dependency-free and imports nothing, so it
+ * is safe for the tree-shaken `./analytics` graph (`analytics/treeShake.test.ts`).
+ */
+
+/**
+ * "The deadline passed before the exchange produced anything." A `unique symbol`, so it can never
+ * collide with a value the exchange itself resolved — `null`, `undefined` and `false` are all
+ * legitimate answers at these call sites, which is exactly why the sentinel cannot be one of them.
+ */
+export const DEADLINE_EXPIRED: unique symbol = Symbol("wire-deadline-expired");
+
+/**
+ * The one ceiling for the kit's awaited transports. 15s, matching `eventQueue.postBatch`'s existing
+ * ceiling on an awaited POST — the precedent in this repo for "long enough that a slow but real
+ * network still lands, short enough that nothing waits on the ~60s platform default".
+ */
+export const DEFAULT_DEADLINE_MS = 15_000;
+
+/**
+ * Run `exchange` under `timeoutMs`, handing it the abort signal to pass to `fetch`. Resolves what
+ * the exchange resolved, or {@link DEADLINE_EXPIRED} if the deadline won. REJECTS with whatever the
+ * exchange threw (an abort included), so every existing `try/catch` at a call site keeps its meaning.
+ */
+export const withDeadline = async <T>(
+  exchange: (signal: AbortSignal | undefined) => Promise<T>,
+  timeoutMs: number = DEFAULT_DEADLINE_MS,
+): Promise<T | typeof DEADLINE_EXPIRED> => {
+  const controller = typeof AbortController !== "undefined" ? new AbortController() : undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<typeof DEADLINE_EXPIRED>((resolve) => {
+    timer = setTimeout(() => {
+      controller?.abort();
+      resolve(DEADLINE_EXPIRED);
+    }, timeoutMs);
+  });
+  const running = exchange(controller?.signal);
+  try {
+    return await Promise.race([running, expired]);
+  } finally {
+    clearTimeout(timer);
+    // The loser can still settle after the race is decided with nothing awaiting it, and an
+    // unobserved rejection is a hard crash on some hosts. Attach a handler either way.
+    void running.catch(() => {});
+  }
+};