@wireai/activation 0.14.2 → 0.15.0

package/src/reviews/ReviewGate.tsx

@@ -17,7 +17,11 @@
  *
  * The form NEVER asks for identity (no name / email / contact field): the host already
  * identifies the user via `sessionId` + `meta` (e.g. user_id, device_key), which is all
- * the POST body carries alongside the rating and the free text.
+ * the POST body carries alongside the rating and the free text. Since 2026-08-19 the gate also
+ * fills in `meta.device_key` from the kit's own per-install id when the host passed none — not for
+ * identification, but because it is the unit the server scopes the idempotency key to, and without
+ * it the key is discarded. Any non-blank string the host passes still wins verbatim. See
+ * `idempotency.ts`.
  *
  * Motion (2026-07-16): the three phases used to swap IN PLACE with no transition. They now
  * ride `ModalPaneHost`, the same pane-slide primitive the questionnaire steps use, and the
@@ -45,6 +49,7 @@ import { useOnboardingTheme } from "../theme/ThemeContext";
 import { bodyStyle, captionStyle, headingStyle } from "../theme/typography";
 import { buildReviewSubmission, routeRating } from "./decision";
 import { feedbackInputHeights } from "./feedbackForm";
+import { createImpression, hasDeviceKey, type ReviewImpression } from "./idempotency";
 import { resolvePresentation } from "./presentation";
 import { ReviewModal, type ReviewModalHandle } from "./ReviewModal";
 import { requestStoreReview } from "./storeReview";
@@ -107,18 +112,63 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     onResolved?.();
   }, [onResolved]);
 
+  /**
+   * ONE identity + ONE idempotency key for this whole gate impression, opened lazily at the first
+   * post so a prompt the user never acts on mints nothing.
+   *
+   * Both values live for the IMPRESSION, not the render and not the post: the server derives the
+   * row id from `(app_id, unit, key)`, so a key that moves between two posts writes two rows and a
+   * unit that moves does the same. `idempotency.ts` carries the full reasoning.
+   */
+  const impressionRef = React.useRef<ReviewImpression | null>(null);
+
+  /**
+   * Build a submission for THIS impression: the host's `meta` plus whatever the call site adds,
+   * stamped with the impression's key and — only when the host supplied none — its device key.
+   *
+   * A host-supplied `meta.device_key` ALWAYS wins and is never overwritten — "supplied" meaning a
+   * string with at least one non-whitespace character, the bar {@link hasDeviceKey} sets; a blank
+   * or non-string value is not a usable unit and is replaced. This mirrors the `userContext` /
+   * `autoJoinKey` rule one directory over, which sets the same bar through `resolveIdentity`. The
+   * injection exists because without a resolvable unit the server discards the key outright, and a
+   * home-feed gate has no `session_id` to fall back to.
+   */
+  const buildBody = useCallback(
+    (input: {
+      stars: number;
+      feedbackText?: string;
+      suggestion?: string;
+      extraMeta?: Record<string, unknown>;
+    }): ReviewSubmission => {
+      let impression = impressionRef.current;
+      if (!impression) {
+        impression = createImpression();
+        impressionRef.current = impression;
+      }
+      const merged: Record<string, unknown> = { ...meta, ...input.extraMeta };
+      if (!hasDeviceKey(merged) && impression.deviceKey) merged.device_key = impression.deviceKey;
+      return buildReviewSubmission({
+        stars: input.stars,
+        feedbackText: input.feedbackText,
+        suggestion: input.suggestion,
+        sessionId,
+        meta: merged,
+        idempotencyKey: impression.idempotencyKey,
+      });
+    },
+    [meta, sessionId],
+  );
+
   /**
    * EXACTLY ONE review row per gate, ever — the latch that makes "force feedback" safe.
    *
-   * WHY ONE POST AND NOT TWO: the tempting design is to post the rating at star-tap and then
-   * post again with the text, enriching the first row. That needs the server to accept a
-   * client-supplied id so the second write UPSERTS. It does not, as deployed today:
-   * `create_review` mints its own id unconditionally (`app/reviews.py` `_new_id()`) and
-   * `CreateReviewRequest` (`app/schemas.py`) has no id field — so two posts = two rows, which
-   * double-counts `count` and corrupts `avg`. Reading the ack does not rescue that guess either:
-   * a second post against a server with no upsert comes back 2xx HAVING created the second row, so
-   * the failure is invisible to the caller and permanent. Post once, at the last responsible
-   * moment, and never depend on an unmerged/undeployed server capability.
+   * WHY ONE POST AND NOT TWO: the tempting design is to post the rating at star-tap and then post
+   * again with the text, enriching the first row. The server now supports exactly that — a post
+   * carrying `idempotency_key` upserts on a derived row id instead of inserting — but the latch
+   * stays, because two posts buy nothing the one-at-the-last-responsible-moment post does not
+   * already have, and every additional post is another chance to hand the server a unit it cannot
+   * resolve. What the key genuinely buys is the RECOVERY paths below: the `unsent` re-post and the
+   * abandonment net now merge into the row they may have already written instead of duplicating it.
    *
    * ── THE LATCH IS A CLAIM, NOT A RECEIPT ────────────────────────────────────────────────────
    *
@@ -134,17 +184,23 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
    *
    * "Did it land" and "did the server answer" are DIFFERENT questions, which is why `submitReview`
    * resolves `accepted` / `rejected` / `unsent` instead of a boolean. Only `unsent` un-latches.
-   * A non-2xx means the server was REACHED, and with no idempotency key on the wire (see above:
-   * the id is server-minted) we cannot know whether it stored the row before failing to say so — a
-   * gateway 502 after the insert commits looks identical to a refusal. Re-posting on that verdict
-   * writes the second row this whole latch exists to prevent, and does it on the exact code path
-   * meant to protect the data. So on any answer the latch stays closed and `unackedRef` is
-   * cleared: the row is the server's problem now.
+   * A non-2xx means the server was REACHED, and we still cannot know whether it stored the row
+   * before failing to say so — a gateway 502 after the insert commits looks identical to a refusal.
+   * That verdict is left alone DELIBERATELY (2026-08-19): re-posting on it is now safe wherever the
+   * key is honoured, but it would also turn a genuine 4xx refusal into a retry needing its own
+   * budget, so changing it is its own decision and not this one. On any answer the latch stays
+   * closed and `unackedRef` is cleared: the row is the server's problem now.
    *
-   * HONEST RESIDUAL: `unsent` is not proof the server never got it either. A connection dropped
-   * after the row committed throws here exactly like an offline device, so the one re-post below
-   * can still duplicate. This is SAFER, not safe. The real fix is a client-minted idempotency key
-   * the server upserts on — a server change, out of scope for the kit.
+   * WHAT THE KEY CHANGED, STATED AS A CAPABILITY: `unsent` was never proof the server got nothing —
+   * a connection dropped after the row committed throws here exactly like an offline device, so the
+   * one re-post below could duplicate. It now carries this impression's `idempotency_key` and the
+   * unit the server scopes it to, so the server upserts that row rather than adding a second one.
+   * That holds while the unit is resolvable, and a host CANNOT make it unresolvable by editing
+   * `meta`: `buildBody` tests the MERGED bucket, so stripping `device_key` there only gets the auto
+   * id re-injected. The one post that carries no unit is the one where the kit cannot name an id
+   * honestly — two tenants registered in one process leave `impression.deviceKey` undefined, and
+   * nothing is stamped. On a gate with no `session_id` that post reaches the server with no unit to
+   * scope the key to, so the server ignores the key and it is back in the old, duplicating world.
    *
    * NOTHING HERE IS AWAITED. `postOnce` returns synchronously and every caller advances the phase
    * on the next line, so the user is never waiting on the network to dismiss the prompt.
@@ -169,8 +225,9 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
           postedRef.current = false;
           return;
         }
-        // `accepted` OR `rejected`: the server answered, so it owns this row. Never re-post it —
-        // a non-2xx can follow a committed insert, and the wire has no idempotency key.
+        // `accepted` OR `rejected`: the server answered, so it owns this row. Not re-posted here —
+        // a non-2xx can follow a committed insert, and re-posting a refusal is a retry decision
+        // with its own budget, deliberately left out of the change that added the key.
         unackedRef.current = null;
       });
     },
@@ -202,12 +259,11 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     }
     if (postedRef.current || stars < 1) return;
     postOnce(
-      buildReviewSubmission({
+      buildBody({
         stars,
         feedbackText: feedback,
         suggestion,
-        sessionId,
-        meta: { ...meta, abandoned: true },
+        extraMeta: { abandoned: true },
       }),
     );
   };
@@ -249,10 +305,9 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
         // the user actually left a review — this only ever means we ASKED. Never read it as
         // a review count. We await first so the row carries the route it actually took.
         postOnce(
-          buildReviewSubmission({
+          buildBody({
             stars: value,
-            sessionId,
-            meta: { ...meta, store_route: route },
+            extraMeta: { store_route: route },
           }),
         );
         setPhase("thanks");
@@ -263,7 +318,7 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
         setPhase("feedback");
       }
     },
-    [onEvent, id, store, postOnce, sessionId, meta, resolveWithDelay],
+    [onEvent, id, store, postOnce, buildBody, resolveWithDelay],
   );
 
   /**
@@ -284,19 +339,13 @@ const _ReviewGate: React.FC<ReviewGateProps> = ({
     if (!feedbackReady) return;
     // Identity is NEVER collected here — the host already sends user_id / device /
     // session via `sessionId` + `meta`. We POST only the rating + the free text.
-    const body = buildReviewSubmission({
-      stars,
-      feedbackText: feedback,
-      suggestion,
-      sessionId,
-      meta,
-    });
+    const body = buildBody({ stars, feedbackText: feedback, suggestion });
     postOnce(body);
     onEvent?.({ name: "review_feedback_submitted", id, stars });
     playHaptic("success");
     setPhase("thanks");
     resolveWithDelay();
-  }, [feedbackReady, stars, feedback, suggestion, sessionId, meta, postOnce, onEvent, id, resolveWithDelay]);
+  }, [feedbackReady, stars, feedback, suggestion, buildBody, postOnce, onEvent, id, resolveWithDelay]);
 
   const dismiss = useCallback(() => {
     setPhase("thanks");

package/src/reviews/decision.ts

@@ -103,7 +103,14 @@ export const evaluateGate = (rules: GateRules, s: GateSignals): ReviewDecision =
 export const routeRating = (stars: number): RatingRoute =>
   stars >= 5 ? "store" : "feedback";
 
-/** Build the `POST /v1/reviews` body. Feedback text/contact belong ONLY here, never in events. */
+/**
+ * Build the `POST /v1/reviews` body. Feedback text/contact belong ONLY here, never in events.
+ *
+ * STILL PURE, deliberately: `idempotencyKey` and the `meta.device_key` the server scopes it to are
+ * both passed IN rather than resolved here. Reaching into the device-key registry from this function
+ * would make the gate logic untestable in isolation, and both values are scoped to an impression
+ * this function cannot see — see `reviews/idempotency.ts`.
+ */
 export const buildReviewSubmission = (input: {
   stars: number;
   feedbackText?: string;
@@ -111,6 +118,8 @@ export const buildReviewSubmission = (input: {
   contact?: string;
   sessionId?: string;
   source?: string;
+  /** The impression's idempotency key. Omitted → the server mints a row id and inserts, as before. */
+  idempotencyKey?: string;
   meta?: Record<string, unknown>;
 }): ReviewSubmission => {
   const body: ReviewSubmission = { stars: input.stars };
@@ -122,6 +131,7 @@ export const buildReviewSubmission = (input: {
   if (contact) body.contact = contact;
   if (input.sessionId) body.session_id = input.sessionId;
   if (input.source) body.source = input.source;
+  if (input.idempotencyKey) body.idempotency_key = input.idempotencyKey;
   if (input.meta && Object.keys(input.meta).length > 0) body.meta = input.meta;
   return body;
 };

package/src/reviews/idempotency.ts

@@ -0,0 +1,71 @@
+/**
+ * idempotency.ts — the ONE idempotency key and the ONE identity a single gate impression posts under.
+ *
+ * ── WHAT THE SERVER DOES WITH THESE, AND WHY BOTH ARE REQUIRED ───────────────────────────────
+ *
+ * `POST /v1/reviews` accepts an optional `idempotency_key`: two posts carrying the same key upsert
+ * ONE row instead of creating two, which is what stops a re-post double-counting `count` and
+ * corrupting `avg`. The row id is derived, never the key verbatim —
+ * `rev_ + sha256(app_id : unit : key)[:24]` — where `app_id` comes from the resolved `wai_` Bearer
+ * key (never the body) and `unit` is the USER the key is scoped to.
+ *
+ * THE PART THAT MAKES A KEY-ONLY CHANGE INERT: `unit` is `meta.device_key`, else `session_id`, and
+ * when the post carries NEITHER the server drops the key on the floor and inserts a normal row —
+ * deliberately, because an unbounded key could merge two strangers' reviews. The gate lives on the
+ * home feed, where a user legitimately has no onboarding session, so `session_id` is frequently
+ * absent; and nothing in the kit ever put a `device_key` into a review `meta` — that was documented
+ * as a host responsibility. Sending a key without guaranteeing the identity would therefore have
+ * shipped a field the server discards.
+ *
+ * ── THE SCOPE IS THE WHOLE DESIGN ────────────────────────────────────────────────────────────
+ *
+ * One key per gate IMPRESSION, held across every post of that impression:
+ *   • minted per POST instead → the re-post carries a different key, writes the second row, and
+ *     defeats the feature on the exact path it exists to protect.
+ *   • minted once per INSTALL instead → a later, genuine second review merges into the first and
+ *     destroys a rating.
+ * The identity is pinned for the same reason and in the same object: the auto device key is adopted
+ * from persistence ASYNCHRONOUSLY, so a value re-read between two posts of one impression can move
+ * under us, and two posts under two different units hash to two different rows.
+ */
+import { ambientAutoDeviceKey } from "../context/deviceId";
+
+/** Prefix so a kit-minted review key is visibly ours in a stored `meta` dump. */
+export const REVIEW_IDEMPOTENCY_PREFIX = "rvw_";
+
+/**
+ * Mint a fresh idempotency key. Dependency-free timestamp + randomness, the same scheme
+ * `makeSessionId` and `mintDeviceId` already use — the key only has to be unique among the
+ * impressions of ONE install, because the server hashes it together with `app_id` and the unit
+ * before it ever becomes a row id.
+ */
+export const mintIdempotencyKey = (): string =>
+  `${REVIEW_IDEMPOTENCY_PREFIX}${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+
+/** Whether a `meta` bucket already carries a usable, host-supplied `device_key`. */
+export const hasDeviceKey = (meta: Record<string, unknown> | undefined): boolean => {
+  const value = meta?.device_key;
+  return typeof value === "string" && value.trim().length > 0;
+};
+
+/** The key + identity every post of ONE gate impression carries. Both resolved once, at creation. */
+export interface ReviewImpression {
+  /** The `idempotency_key` on the wire. Stable for the impression, distinct across impressions. */
+  readonly idempotencyKey: string;
+  /**
+   * The auto `device_key` to stamp when the host supplied none, or `undefined` when the kit cannot
+   * name one honestly (two tenants in one process). A host-supplied key that {@link hasDeviceKey}
+   * accepts — a string with at least one non-whitespace character — always wins over this and is
+   * never touched; the caller checks that first.
+   */
+  readonly deviceKey: string | undefined;
+}
+
+/**
+ * Open one impression. Both fields are resolved EAGERLY here rather than read per post, which is the
+ * entire point: a lazily re-read key or identity is a per-post value wearing an impression's name.
+ */
+export const createImpression = (): ReviewImpression => ({
+  idempotencyKey: mintIdempotencyKey(),
+  deviceKey: ambientAutoDeviceKey(),
+});

package/src/reviews/index.ts

@@ -55,8 +55,10 @@ export { requestStoreReview, openStoreListing, storeUrl } from "./storeReview";
 // hand-rolling a decision fetch: a host-rolled one that collapses `{fire:false}` into undefined
 // makes the server able to turn prompts ON but never OFF (the 2026-07-16 first-session incident).
 // `submitReview` resolves with a THREE-state `ReviewSubmitResult` (accepted / rejected / unsent),
-// not a boolean: only `unsent` may be retried, because the wire has no idempotency key and a
-// re-post after a non-2xx that already committed writes a second row.
+// not a boolean: only `unsent` is retried today. A body built by `ReviewGate` now carries an
+// `idempotency_key` plus the unit the server scopes it to, so that re-post upserts one row instead
+// of writing a second; whether a `rejected` verdict should ALSO retry is a separate recovery-budget
+// decision and is deliberately unchanged.
 export { submitReview, fetchReviewDecision, reportAppEvent } from "./transport";
 export type {
   FetchReviewDecisionOptions,

package/src/reviews/runtime.ts

@@ -5,7 +5,7 @@
  * mounted CoachmarkProvider gets review gating for free — no second storage to wire.
  */
 import type { CoachmarkStorage } from "../coachmarks/types";
-import { getCoachmarkStorage } from "../coachmarks/runtime";
+import { getCoachmarkStorage, validateGateStorage } from "../coachmarks/runtime";
 import { getCurrentSessionId } from "../analytics/currentSession";
 import { makeSessionId } from "../analytics/reportClientEvent";
 
@@ -22,10 +22,12 @@ export const reviewSessionsKey = (id: string): string => `wire_review_${id}_sess
 /** Companion key holding the open id the counter was LAST incremented for (see {@link bumpSessionCount}). */
 export const reviewSessionOpenKey = (id: string): string => `wire_review_${id}_open`;
 
-/** Resolve the storage to use: an explicit override, else the provider-injected singleton. */
+/** Resolve the storage to use: an explicit override, else the provider-injected singleton — both
+ *  routed through the thenable probe, so an ASYNC adapter resolves to the fail-closed substitute
+ *  (see `validateGateStorage` in coachmarks/runtime) instead of feeding Promises to `readInt`. */
 export const resolveStorage = (
   override?: CoachmarkStorage | null,
-): CoachmarkStorage | null => override ?? getCoachmarkStorage();
+): CoachmarkStorage | null => validateGateStorage(override ?? getCoachmarkStorage());
 
 /** RN sets this global; absent under node/SSR. Read defensively via {@link warnMissingGateStorage}. */
 declare const __DEV__: boolean | undefined;

package/src/reviews/transport.ts

@@ -45,23 +45,28 @@ export 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.
  */
 export const submitReview = async (
   target: ReviewTarget | undefined,

package/src/reviews/types.ts

@@ -97,6 +97,13 @@ export 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/src/showcase/FeatureShowcase.tsx

@@ -1,8 +1,8 @@
-import Onboarding, {
-  type OnboardingColors,
-  type OnboardingFonts,
-  type OnboardingProps,
-  type OnboardingStep,
+import type {
+  OnboardingColors,
+  OnboardingFonts,
+  OnboardingProps,
+  OnboardingStep,
 } from "@blazejkustra/react-native-onboarding";
 import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { type ImageSourcePropType, StyleSheet, View } from "react-native";
@@ -12,6 +12,7 @@ import { hasSeenGate, markSeenGate, showcaseGateKey } from "../coachmarks/runtim
 import { useResolvedFeatures } from "../features/WireFeaturesProvider";
 import { useOnboardingTheme } from "../theme/ThemeContext";
 import type { OnboardingTheme } from "../theme/types";
+import { resolveShowcaseOnboarding } from "./blazejOnboarding";
 import { showcaseColorsFromTheme, showcasePanelBackground } from "./showcaseColors";
 import type { FeatureShowcaseProps } from "./types";
 
@@ -47,6 +48,13 @@ const mergeThemeOver = (
  *
  * When the gate says "seen", it renders nothing and calls `onDone` from an
  * effect (never during render).
+ *
+ * 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
+ * path as the kill switch — render null, call `onDone`, write no gate — so the
+ * host's flow always advances and the showcase still plays once if the peer is
+ * added later.
  */
 const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   config,
@@ -71,14 +79,20 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
   const flags = useResolvedFeatures({ flags: features, config: featuresConfig });
   const disabled = !flags.showcase.enabled;
 
+  // The optional pager peer. Resolved once, on first render, instead of at module scope — so
+  // merely importing this file (and thus the showcase subpath) never needs it. Absent → treated
+  // exactly like the kill switch below: no render, no gate write, `onDone` from the effect.
+  const Onboarding = useMemo(() => resolveShowcaseOnboarding(), []);
+
   const gateKey = showcaseGateKey(config.id);
   const seen = useMemo(
     () => hasSeenGate(gateKey, storage, isTesting),
     [gateKey, storage, isTesting],
   );
-  // Either already-seen OR feature-disabled short-circuits the showcase. Only the seen path is a
-  // gate write (in `finish`); the disabled path never persists, so it replays when re-enabled.
-  const skip = seen || disabled;
+  // Already-seen, feature-disabled OR the peer missing short-circuits the showcase. Only the seen
+  // path is a gate write (in `finish`); the other two never persist, so the showcase replays once
+  // the feature is re-enabled or the peer is installed.
+  const skip = seen || disabled || !Onboarding;
 
   const doneRef = useRef(false);
   const finish = useCallback(() => {
@@ -177,7 +191,9 @@ const _FeatureShowcase: React.FC<FeatureShowcaseProps> = ({
     [t],
   );
 
-  if (skip) 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;
 
   const activeGesture = config.slides[activeIndex]?.gesture;
   // Same rule as the coachmark path: tap / double-tap slides show no glyph.

package/src/showcase/blazejOnboarding.ts

@@ -0,0 +1,136 @@
+/**
+ * blazejOnboarding — resolve `@blazejkustra/react-native-onboarding`, lazily and optionally.
+ *
+ * ── WHY THIS DOES NOT BREAK THE NO-NATIVE-DEPENDENCY POLICY ──────────────────────────────
+ *
+ * `@blazejkustra/react-native-onboarding` is an OPTIONAL peer of the showcase subpath — it is the
+ * slide pager `FeatureShowcase` wraps. Before this file, `FeatureShowcase.tsx` imported its default
+ * export at module scope, and `showcase/index.ts` re-exports the component with no wildcard escape,
+ * so importing ANYTHING from `@wireai/activation/showcase` (even `selectShowcaseSlides`) dragged
+ * the peer in, and a host that skipped the "optional" peer hit a Metro resolution failure. This
+ * resolver removes that static edge. Same class and same shape as the 0.14.2 `expo-blur` fix
+ * (`coachmarks/expoBlur.ts`), whose header carries the reasoning in full.
+ *
+ * The TYPES stay statically imported on purpose: a type-only import is erased by every toolchain
+ * (babel, esbuild and sucrase all drop it), so it creates no runtime edge and no bundle dependency,
+ * and `showcaseColors.ts` already relies on exactly that.
+ *
+ * ── THE SPECIFIER MUST BE A STRING LITERAL, INSIDE A TRY/CATCH ───────────────────────────
+ *
+ * Metro collects dependencies statically and matches only a call whose callee is literally the
+ * identifier `require` and whose argument is literally a string; the try/catch around it is what
+ * marks the dependency `isOptional`. Both halves are load-bearing — see `icons/expoIcons.ts` for
+ * the full autopsy of the 0.8.0 shape that aliased the callee and was collected nowhere.
+ *
+ * ── THE DEGRADE ─────────────────────────────────────────────────────────────────────────
+ *
+ * Absent → `FeatureShowcase` renders null and calls `onDone` from an effect, which is the SAME path
+ * the feature kill switch already takes. The host's flow always advances (a showcase that cannot
+ * render must never strand the user on a blank screen), and the seen-gate is deliberately NOT
+ * written, so installing the peer later still plays the showcase once.
+ */
+import type { ComponentType } from "react";
+
+import type { OnboardingProps } from "@blazejkustra/react-native-onboarding";
+
+// Metro injects a module-scoped `require`; it is ABSENT in a pure-ESM runtime (the kit's own tests
+// run under `node --test` as ESM). Declared locally so this type-checks without ambient Node types;
+// the `typeof` guard keeps the reference ESM-safe.
+declare const require: ((id: string) => unknown) | undefined;
+
+/** A `require`-like resolver. Injectable in tests; production uses the guarded literal require. */
+export type OptionalRequire = (moduleName: string) => unknown;
+
+/** The pager component `FeatureShowcase` wraps. */
+export type OnboardingComponent = ComponentType<OnboardingProps>;
+
+const MODULE_NAME = "@blazejkustra/react-native-onboarding";
+
+/**
+ * The production resolver. The specifier is a LITERAL so Metro collects it (see the header); the
+ * `moduleName` parameter exists only to keep the `OptionalRequire` seam shape, so anything other
+ * than the one module this file owns resolves to undefined.
+ */
+const runtimeRequire: OptionalRequire = (moduleName) => {
+  if (moduleName !== MODULE_NAME) return undefined;
+  if (typeof require !== "function") return undefined;
+  try {
+    return require("@blazejkustra/react-native-onboarding");
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * TEST-ONLY seam. `FeatureShowcase`'s public props are frozen, so it cannot take a `requireModule`
+ * the way `WireIcon` does — this lets a component render exercise the PRESENT path without the peer
+ * installed. Production never sets it; `runtimeRequire` is the only resolver.
+ */
+let testRequire: OptionalRequire | undefined;
+export const __setShowcaseOnboardingRequireForTests = (fn: OptionalRequire | undefined): void => {
+  testRequire = fn;
+  cached = undefined;
+};
+
+/**
+ * Read the component off the module. The package ships it as a DEFAULT export; a CJS build may put
+ * the component directly on `module.exports` instead, so both shapes are accepted.
+ */
+const interop = (mod: unknown): unknown => {
+  if (typeof mod === "function") return mod;
+  if (!mod || typeof mod !== "object") return undefined;
+  const ns = mod as Record<string, unknown>;
+  if (ns.default) return ns.default;
+  // `module.exports = forwardRef(...)`: the component IS the namespace, and it is an object rather
+  // than a function, so it would slip past the check above.
+  if ("$$typeof" in ns) return ns;
+  return undefined;
+};
+
+/**
+ * Narrow an unknown export to something mountable: a real component (function or class) or a
+ * React.memo / forwardRef wrapper (an object carrying `$$typeof`). Reject anything else rather than
+ * handing the reconciler a non-component.
+ */
+const asComponent = (value: unknown): OnboardingComponent | undefined => {
+  if (typeof value === "function") return value as OnboardingComponent;
+  if (value && typeof value === "object" && "$$typeof" in (value as object)) {
+    return value as OnboardingComponent;
+  }
+  return undefined;
+};
+
+/**
+ * Module-level memo. `null` = "we looked and it is not there" (distinct from "not looked yet"), so
+ * an absent peer costs exactly one failed require per process, not one per showcase mount.
+ */
+let cached: OnboardingComponent | null | undefined;
+
+/** Reset the memo. TEST-ONLY seam — production never calls it. */
+export const resetShowcaseOnboardingCache = (): void => {
+  cached = undefined;
+};
+
+/**
+ * Resolve the pager component, or undefined when the peer is absent/unresolvable. Never throws: an
+ * absent showcase must advance the host's flow, never break it.
+ *
+ * `requireModule` is injectable so tests can exercise BOTH the found and absent paths without
+ * installing the peer (same convention as `resolveBlurView` / `resolveIconFamily`).
+ */
+export const resolveShowcaseOnboarding = (
+  requireModule: OptionalRequire = testRequire ?? runtimeRequire,
+): OnboardingComponent | undefined => {
+  try {
+    if (cached === undefined || requireModule !== runtimeRequire) {
+      const component = asComponent(interop(requireModule(MODULE_NAME)));
+      // Don't poison the module memo from an injected test require.
+      if (requireModule === runtimeRequire) cached = component ?? null;
+      return component;
+    }
+    if (cached === null) return undefined;
+    return cached;
+  } catch {
+    return undefined;
+  }
+};

package/src/showcase/index.ts

@@ -2,10 +2,14 @@
  * @wireai/activation/showcase — the pre-onboarding feature showcase ("app intro").
  *
  * Subpath entry, kept OUT of the main barrel so the core kit stays dependency-
- * free: importing this pulls in the optional peer
- * `@blazejkustra/react-native-onboarding` (and, transitively via GestureHint,
- * `react-native-reanimated`). The app supplies a declarative ShowcaseConfig; the
- * kit bakes in the Wire theme + optional per-slide gesture hand and gates once.
+ * free. Importing this pulls in NO native peer (0.14.3): the pager
+ * `@blazejkustra/react-native-onboarding` is reached through the guarded lazy
+ * require in `blazejOnboarding.ts`, and the transitive edge through GestureHint
+ * to `react-native-reanimated` is guarded the same way in `coachmarks/reanimated.ts`.
+ * Without the pager the showcase renders null and calls `onDone` so the host's
+ * flow advances; without reanimated the gesture glyph renders static. The app
+ * supplies a declarative ShowcaseConfig; the kit bakes in the Wire theme +
+ * optional per-slide gesture hand and gates once.
  *
  *   import { FeatureShowcase, selectShowcaseSlides } from "@wireai/activation/showcase";
  */