@wireai/activation 0.14.2 → 0.15.0

package/dist/{transport-B_0SgCBe.d.ts → transport-xqqSFqxs.d.ts}

@@ -1,4 +1,4 @@
-import { k as ReviewTarget, S as SubmitResult, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-h2BZvl1t.js';
+import { k as ReviewTarget, S as SubmitResult, g as ReviewDecisionResponse, j as ReviewSubmission } from './types-tdATL5z0.js';
 
 /**
  * What became of a review POST — the SHARED three-outcome verdict, re-exported under the name the
@@ -25,23 +25,28 @@ type ReviewSubmitResult = SubmitResult;
  *
  * It was, 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 one caller that reads
- * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. But the server mints
- * its own row id (`create_review` / `_new_id()`) and `CreateReviewRequest` carries no 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, double-counting `count` and corrupting `avg` — the precise corruption the
- * one-row latch exists to prevent. A response of any status proves the server was reached, and
- * that is a different question from whether it liked the row. So the two are different values.
+ * this (`ReviewGate.postOnce`) treats `false` as "still owed" and re-posts. At the time there was
+ * no idempotency key on the wire at all, so a 502 returned AFTER the insert commits meant the
+ * re-post wrote a SECOND row, double-counting `count` and corrupting `avg` — the precise corruption
+ * the one-row latch exists to prevent. A response of any status proves the server was reached, and
+ * that is a different question from whether it liked the row. So the two are different values, and
+ * they stay different: the split is what lets the caller decide, and the retry-on-`rejected`
+ * question is a recovery-budget decision the key does not answer on its own.
  *
  * ── THE RESIDUAL, STATED HONESTLY ────────────────────────────────────────────────────────────
  *
  * `unsent` is not proof the server never got the row. A connection dropped after the request was
  * written — or after the row committed — surfaces as a thrown/rejected `fetch` here, exactly like
- * an offline device. Retrying only on `unsent` is therefore SAFER, not SAFE: it removes the
- * double-post the server itself told us about, and leaves the narrow window where the answer never
- * made it back onto the wire. Closing that window needs a CLIENT-MINTED IDEMPOTENCY KEY the server
- * upserts on, which is a server change (`CreateReviewRequest` + `create_review`) and is 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.
+ * an offline device. That used to make the `unsent` re-post SAFER rather than SAFE, and it is what
+ * the client-minted idempotency key now covers: `ReviewSubmission.idempotency_key` reaches
+ * `CreateReviewRequest`, and the server upserts the derived row rather than inserting a second one.
+ *
+ * IT IS A CAPABILITY, NOT A GUARANTEE, and the condition is not ours to enforce from in here. The
+ * server honours the key only when the post also carries a unit it can scope it to —
+ * `meta.device_key`, else `session_id` — and ignores it outright otherwise. `ReviewGate` fills the
+ * device key in for exactly this reason, but this function posts whatever body it is handed, so a
+ * caller that assembles its own body without a unit is back in the old world where a lost detractor
+ * is a gap in the data and a duplicated one is a lie in the data.
  */
 declare const submitReview: (target: ReviewTarget | undefined, review: ReviewSubmission) => Promise<ReviewSubmitResult>;
 /**

package/dist/{types-Cju-1_jT.d.mts → types-Byx306Kv.d.mts}

@@ -1,5 +1,5 @@
 import { O as OnboardingTheme } from './types-BKfpdZzX.mjs';
-import { C as CoachmarkStorage } from './types-BcmagF6K.mjs';
+import { C as CoachmarkStorage } from './types-D_0B0yay.mjs';
 import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.mjs';
 
 /**
@@ -25,20 +25,28 @@ import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.mjs
  *
  * `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.
  */
 type SubmitResult = "accepted" | "rejected" | "unsent";
 
@@ -119,6 +127,13 @@ interface ReviewSubmission {
     contact?: string;
     session_id?: string;
     source?: string;
+    /**
+     * OPTIONAL client-minted key for the two-phase submit: two posts carrying the same key upsert ONE
+     * row instead of creating two. The server honours it ONLY when the post also carries a resolvable
+     * user — `meta.device_key`, else `session_id` — and silently ignores it otherwise, so it always
+     * travels with one of those. One key per gate impression, stable across that impression's posts.
+     */
+    idempotency_key?: string;
     meta?: Record<string, unknown>;
 }
 /**

package/dist/{types-BcmagF6K.d.mts → types-D_0B0yay.d.mts}

@@ -18,8 +18,13 @@ interface TargetRect {
 }
 /**
  * The host-injected gate storage. SYNCHRONOUS on purpose — a coachmark's
- * "seen?" gate must resolve during render with no async flash (otherwise a ring
- * momentarily paints before the read resolves and says "already seen"). MMKV's
+ * "seen?" gate must resolve during render. This is ENFORCED, fail closed: a
+ * probe on first read catches an adapter whose `getItem` returns a thenable
+ * (AsyncStorage handed straight in) and substitutes a closed adapter — every
+ * gate reads "seen", nothing shows, nothing fires, one dev warning names the
+ * fix (see `validateGateStorage` in ./runtime). A raw async adapter would
+ * otherwise report every gate unseen forever: tours replay each open, and a
+ * review gate with `minSessions` 0/1 re-fires each open. MMKV's
  * `getString`/`set` fit as-is; an in-memory `Map` wrapper works for tests. This
  * is deliberately separate from the async `WireOnboardingStorage` used for
  * session persistence.

package/dist/{types-BcmagF6K.d.ts → types-D_0B0yay.d.ts}

@@ -18,8 +18,13 @@ interface TargetRect {
 }
 /**
  * The host-injected gate storage. SYNCHRONOUS on purpose — a coachmark's
- * "seen?" gate must resolve during render with no async flash (otherwise a ring
- * momentarily paints before the read resolves and says "already seen"). MMKV's
+ * "seen?" gate must resolve during render. This is ENFORCED, fail closed: a
+ * probe on first read catches an adapter whose `getItem` returns a thenable
+ * (AsyncStorage handed straight in) and substitutes a closed adapter — every
+ * gate reads "seen", nothing shows, nothing fires, one dev warning names the
+ * fix (see `validateGateStorage` in ./runtime). A raw async adapter would
+ * otherwise report every gate unseen forever: tours replay each open, and a
+ * review gate with `minSessions` 0/1 re-fires each open. MMKV's
  * `getString`/`set` fit as-is; an in-memory `Map` wrapper works for tests. This
  * is deliberately separate from the async `WireOnboardingStorage` used for
  * session persistence.

package/dist/{types-h2BZvl1t.d.ts → types-tdATL5z0.d.ts}

@@ -1,5 +1,5 @@
 import { O as OnboardingTheme } from './types-BKfpdZzX.js';
-import { C as CoachmarkStorage } from './types-BcmagF6K.js';
+import { C as CoachmarkStorage } from './types-D_0B0yay.js';
 import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.js';
 
 /**
@@ -25,20 +25,28 @@ import { a as WireFeatures, b as WireFeaturesConfig } from './types-BpwiRpA8.js'
  *
  * `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.
  */
 type SubmitResult = "accepted" | "rejected" | "unsent";
 
@@ -119,6 +127,13 @@ interface ReviewSubmission {
     contact?: string;
     session_id?: string;
     source?: string;
+    /**
+     * OPTIONAL client-minted key for the two-phase submit: two posts carrying the same key upsert ONE
+     * row instead of creating two. The server honours it ONLY when the post also carries a resolvable
+     * user — `meta.device_key`, else `session_id` — and silently ignores it otherwise, so it always
+     * travels with one of those. One key per gate impression, stable across that impression's posts.
+     */
+    idempotency_key?: string;
     meta?: Record<string, unknown>;
 }
 /**

package/metro/index.js

@@ -71,11 +71,16 @@ const SINGLE_INSTANCE_DEPS = ['react', 'react-native', 'wireai-rn', 'zod'];
  * only thing holding it up.
  *
  * ONLY modules read through a guarded require/import belong here. A module the kit imports
- * STATICALLY at module scope (react-native-reanimated,
- * @blazejkustra/react-native-onboarding) must NOT be stubbed: an empty module would turn a loud
- * build-time "Unable to resolve module" into a silent `undefined` component that crashes at
- * render, which is strictly worse. `test/canary/metroResolution.test.tsx` keeps this list in sync
- * with the source by asking Metro which deps it marks optional.
+ * STATICALLY at module scope must NOT be stubbed: an empty module would turn a loud build-time
+ * "Unable to resolve module" into a silent `undefined` component that crashes at render, which is
+ * strictly worse. That exclusion used to name `react-native-reanimated` and
+ * `@blazejkustra/react-native-onboarding` — as of 0.14.3 both are guarded (`coachmarks/reanimated.ts`,
+ * `showcase/blazejOnboarding.ts`) and so they belong on the list, not in the exclusion. The kit now
+ * has NO statically-imported optional peer: every module it can live without is reached through a
+ * guard, and everything it imports statically (react, react-native, react-native-safe-area-context,
+ * wireai-rn, zod) is a REQUIRED peer whose absence must stay a hard build error.
+ * `test/canary/metroResolution.test.tsx` keeps this list in sync with the source by asking Metro
+ * which deps it marks optional.
  */
 const OPTIONAL_MODULES = [
   // src/icons/expoIcons.ts — icon families; absent → WireIcon renders null.
@@ -91,6 +96,12 @@ const OPTIONAL_MODULES = [
   'expo-haptics',
   // src/coachmarks/expoBlur.ts — the coachmark spotlight frost; absent → plain dimmed scrim.
   'expo-blur',
+  // src/coachmarks/reanimated.ts — the coachmark/showcase animation engine; absent → the overlay
+  // and the gesture glyph render statically, at their resting frame.
+  'react-native-reanimated',
+  // src/showcase/blazejOnboarding.ts — the FeatureShowcase slide pager; absent → the showcase
+  // renders null and calls onDone, so the host's flow still advances.
+  '@blazejkustra/react-native-onboarding',
 ];
 
 function withWireOnboarding(config, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "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>",

package/src/WireOnboarding.tsx

@@ -135,7 +135,10 @@ export const WireOnboarding: React.FC<WireOnboardingProps> = ({
   // per-install `device_key` the analytics surfaces auto-mint and persist — so the default wiring
   // produces a joined funnel instead of a silent zero. Three conditions, all necessary:
   //
-  //   • `missingJoinKey` — a host-supplied key ALWAYS wins, verbatim, and is never touched.
+  //   • `missingJoinKey` — a host-supplied key ALWAYS wins, verbatim, and is never touched. What
+  //     COUNTS as supplied is `resolveIdentity`'s predicate above: a string with at least one
+  //     non-whitespace character. A non-string or an all-whitespace `device_key` yields no record,
+  //     so it reads as absent here and the auto key is merged over it.
   //   • `autoJoinKey !== false` — the documented opt-out for a host that genuinely wants an
   //     unlinked onboarding session; opting out restores the pre-0.12.2 behavior exactly.
   //   • `storage` that actually WORKS — without persistence the auto id is process-scoped, so every

package/src/coachmarks/GestureHint.tsx

@@ -1,6 +1,8 @@
 import React, { useEffect, useMemo, type ReactNode } from "react";
 import { StyleSheet, View } from "react-native";
-import Animated, {
+
+import {
+  Animated,
   useAnimatedStyle,
   useReducedMotion,
   useSharedValue,
@@ -8,15 +10,22 @@ import Animated, {
   withRepeat,
   withSequence,
   withTiming,
-} from "react-native-reanimated";
-
+} from "./reanimated";
 import type { GestureKind } from "./types";
 
 /**
- * Abstract gesture pictogram shown beside a coachmark tooltip. Pure reanimated —
- * every animation runs on the UI thread (shared values + worklets), never
- * setState, so it costs nothing on the JS thread. Honors Reduce Motion by
- * dropping the motion loop and rendering the glyph static.
+ * Abstract gesture pictogram shown beside a coachmark tooltip. With the OPTIONAL
+ * `react-native-reanimated` peer installed every animation runs on the UI thread
+ * (shared values + worklets), never setState, so it costs nothing on the JS
+ * thread. Honors Reduce Motion by dropping the motion loop and rendering the
+ * glyph static.
+ *
+ * The peer is reached through the guarded lazy require in `reanimated.ts`, never
+ * a static import, so `@wireai/activation/coachmarks` (and `/showcase`, which
+ * reaches this component through FeatureShowcase) builds on a host that never
+ * installed it. Absent, the glyph renders STATICALLY at its resting frame — the
+ * same capsules, ring, dot and motion track, at full opacity and no travel, with
+ * one render instead of a UI-thread loop. The pictogram never disappears.
  *
  * NO drawn-hand anatomy. Swipes render the standard two-finger swipe glyph: two
  * rounded vertical capsules (an abstract index + middle finger, slightly

package/src/coachmarks/SpotlightOverlay.tsx

@@ -6,7 +6,12 @@ import {
   useWindowDimensions,
   View,
 } from "react-native";
-import Animated, {
+
+import { useOnboardingTheme } from "../theme/ThemeContext";
+import { resolveBlurView } from "./expoBlur";
+import { GestureHint } from "./GestureHint";
+import {
+  Animated,
   FadeIn,
   FadeOut,
   useAnimatedProps,
@@ -16,11 +21,7 @@ import Animated, {
   withRepeat,
   withSequence,
   withTiming,
-} from "react-native-reanimated";
-
-import { useOnboardingTheme } from "../theme/ThemeContext";
-import { resolveBlurView } from "./expoBlur";
-import { GestureHint } from "./GestureHint";
+} from "./reanimated";
 import type { GestureKind, Placement, TargetRect } from "./types";
 
 const BLUR_INTENSITY = 26;
@@ -55,14 +56,19 @@ export interface SpotlightOverlayProps {
  * root (above the tab bar) via CoachmarkOverlayHost.
  *
  * Performance: one BlurView (mounted only while a step is visible), the ring
- * glow is a single reanimated view, and all animation runs on the UI thread.
- * Reduce Motion drops the pulse.
+ * glow is a single animated view, and with `react-native-reanimated` installed
+ * every animation runs on the UI thread. Reduce Motion drops the pulse.
  *
- * `expo-blur` is OPTIONAL. It is resolved through a guarded lazy require (see
- * `expoBlur.ts`) and the animated component is built once on first use, so the
- * subpath never carries a static top-level import of the peer. When it is not
- * installed the frost drops to an equivalent dimmed scrim — a decorative frost
- * missing must never blank a tour, so the ring, copy and gestures are unchanged.
+ * BOTH native peers are OPTIONAL, and each is resolved through a guarded lazy
+ * require, so the subpath never carries a static top-level import of either:
+ *   • `expo-blur` (`expoBlur.ts`) — absent, the frost drops to an equivalent
+ *     dimmed scrim. The animated component is built once, on first use.
+ *   • `react-native-reanimated` (`reanimated.ts`) — absent, the overlay renders
+ *     STATICALLY at its resting frame: the ring sits at scale 1 (no pulse), the
+ *     blur at full BLUR_INTENSITY (no fade-in), and the whole overlay appears
+ *     and leaves without the fade. Nothing moves; everything renders.
+ * A missing decoration must never blank a tour, so the ring, tooltip, copy and
+ * gestures are identical in all four combinations.
  */
 const SpotlightOverlayComponent: React.FC<SpotlightOverlayProps> = ({
   message,

package/src/coachmarks/index.ts

@@ -2,8 +2,13 @@
  * @wireai/activation/coachmarks — the performance-first guided-tour engine.
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
- * free: importing this pulls in the optional peers `react-native-reanimated` and
- * `expo-blur`. The app declares WHERE things anchor (useCoachmarkAnchor) and
+ * free. Importing this pulls in NO native peer: `react-native-reanimated` and
+ * `expo-blur` are both OPTIONAL and both reached through guarded lazy requires
+ * (`reanimated.ts`, `expoBlur.ts`). Installed, you get UI-thread animation and a
+ * frosted spotlight; absent, the tour still renders — statically, and with a
+ * plain dimmed scrim instead of the frost. (This doc used to say the subpath
+ * "pulls in" both peers, which was true until 0.14.2 / 0.14.3 removed the static
+ * imports.) The app declares WHERE things anchor (useCoachmarkAnchor) and
  * WHICH tour plays (useCoachmarkTour); the kit owns the animation, measuring,
  * blur, ring, gesture hand, and one-overlay-at-a-time queue.
  *