@wireai/activation 0.13.6-next.0 → 0.13.6

package/llms.txt

@@ -14,7 +14,7 @@
 - **Render:** drop `<WireOnboarding config={wireConfigFromEnv({ appId })} theme={...} onComplete={persist} fallbackFlow={<YourStaticOnboarding/>} />` into the signup flow.
 - **The join key.** Pass `userContext={activationJoinContext(deviceKey)}` on `<WireOnboarding>` (or `activationJoinContext(resolveAutoDeviceKey({ appId, storage }))` when the app owns no device id). `user_context.device_key` is the ONLY thing that joins an onboarding session to the app's later events; omit it and the `activated` funnel reads zero with no error.
 - **Lifecycle (mount it once):** `useLifecycleEvents(config, { deviceKey?, sessionCount?, userId? })` at the app root, before anything else touches analytics. It is the only path that emits `app.first_open`, it registers the per-open session id `createAnalytics` / `wire.track` / the gates all correlate to, and with `config.storage` it stamps the persisted auto `device_key` on `app.session_started`, which is what the server counts `min_sessions` from. `useSessionStart` / `reportSessionStart` are the alternatives for a host that already owns an open counter; neither emits `first_open`.
-- **Capture is deterministic.** `onComplete` returns `{ answers, raw }`; no second LLM call. Persist all answers through the app's normal profile-update path.
+- **Capture is deterministic.** `onComplete` returns an `OnboardingResult`: `answers` and `raw` always, plus (since 0.13.6) `plan` when the backend sent an onboarding plan and `variant` when the tenant runs an experiment and the backend assigned an arm. No second LLM call. Persist all answers through the app's normal profile-update path. Those two extra keys are set ONLY when the backend actually sent them, so a run without them returns exactly the object earlier versions returned, and the kit interprets neither: validate `plan` before applying it.
 - **It can never break onboarding.** Pass `fallbackFlow` (your existing static onboarding) so a backend error/timeout degrades instead of dead-ending.
 
 ## Helpers (the reusable substrate)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wireai/activation",
-  "version": "0.13.6-next.0",
+  "version": "0.13.6",
   "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/OnboardingFlow.tsx

@@ -177,6 +177,12 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // Last 0-based screen index we showed the user (matches the server's `screen_shown`
   // index). Used as the `dropped` event's screen_index. -1 = nothing shown yet.
   const lastScreenIndexRef = useRef(-1);
+  // The backend's experiment arm for this session, LATCHED at first sight and never cleared.
+  // The server's assignment is sticky per session but it only rides the render envelope, so a
+  // later card that omits `progress.variant` must not un-assign what an earlier card declared.
+  // `undefined` = no arm seen, which is every turn of every tenant running no experiment.
+  // The kit stores the string and nothing else: it is not parsed, branded, defaulted or logged.
+  const variantRef = useRef<string | undefined>(undefined);
   // Trailing-edge debounce timer for prefetch-on-select (see previewOnSelect below).
   const previewTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
 
@@ -269,15 +275,22 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   // A new card arrived → clear any prior inline validation error + emit a turn event.
   useEffect(() => {
     setValidationError(undefined);
+    // Latch the arm BEFORE the turn event fires, so the card that first declares one already
+    // carries it. An empty string is not an assignment, so it is ignored like an absent key.
+    if (variantRef.current === undefined && progress.variant) variantRef.current = progress.variant;
     if (!lastCard?.id) return;
     const step = progress.step ?? renderedCount;
     // Remember the latest screen we showed (0-based) for a possible `dropped` event.
     lastScreenIndexRef.current = Math.max(0, step - 1);
-    onEventRef.current?.({
+    const turn: Extract<OnboardingEvent, { type: "turn" }> = {
       type: "turn",
       step,
       component: lastCard.response?.component,
-    });
+    };
+    // Set the key ONLY when an arm was seen, for the same reason `handleFinish` does it on the
+    // result: a host reading `Object.keys(event)` sees no change when no experiment is running.
+    if (variantRef.current !== undefined) turn.variant = variantRef.current;
+    onEventRef.current?.(turn);
     // Prefetch: an InterstitialCard's answer is always "continue", so we can warm the next
     // turn's cache during the momentum window — by the time the user taps Continue the following
     // card is already generated. The preview MUST use the exact text the real Continue tap sends,
@@ -373,6 +386,10 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
     // object — a host that inspects `Object.keys(result)` or `"plan" in result` sees no change.
     const plan = readPlan(messages);
     if (plan !== undefined) result.plan = plan;
+    // The experiment arm, latched off the render envelopes during the flow. Set under exactly the
+    // same rule as the plan: no arm seen → no key, so the result stays byte-identical for the
+    // tenants (most of them) that run no experiment.
+    if (variantRef.current !== undefined) result.variant = variantRef.current;
     onCompleteRef.current(result);
   }, [messages]);
 

package/src/types.ts

@@ -66,6 +66,16 @@ export type OnboardingResult = {
    * the host's decision, not the kit's.
    */
   plan?: unknown;
+  /**
+   * The experiment ARM the backend assigned this session, when it is running one. Absent when
+   * the tenant runs no experiment, which is the common case, and absent is NOT an error.
+   * The kit does NOT interpret it, does not log it, does not brand it and never attaches it
+   * to an analytics event. What an arm key MEANS is the host's decision.
+   *
+   * Like {@link plan}, the KEY is set only when an arm was actually seen, so a run with no
+   * experiment leaves the result byte-identical to what every host already reads.
+   */
+  variant?: string;
 };
 
 /**
@@ -78,7 +88,11 @@ export type OnboardingResult = {
  *  - `resumed`: a persisted session was restored after an app kill (fires INSTEAD of
  *               `started`, so host funnels don't double-count the same session). Also carries
  *               `contextId`. Requires the `storage` prop.
- *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen).
+ *  - `turn`: a new assistant card arrived (`step` = 1-based index of cards seen). Carries
+ *               `variant`, the backend's experiment arm for this session, from the first card that
+ *               declared one onwards — this is how the arm is available DURING the flow rather than
+ *               only at completion. The key is absent whenever no arm has been seen, which is every
+ *               turn of every tenant running no experiment.
  *  - `error`: the backend errored or the first-card watchdog timed out.
  *  - `retry`: a transient failure is being auto-retried (`attempt` = 1-based).
  *  - `fallback`: retries are exhausted; the kit degraded to the static `fallbackFlow`
@@ -92,7 +106,7 @@ export type OnboardingResult = {
 export type OnboardingEvent =
   | { type: "started"; contextId: string }
   | { type: "resumed"; contextId: string }
-  | { type: "turn"; step: number; component?: string }
+  | { type: "turn"; step: number; component?: string; variant?: string }
   | { type: "error"; reason: "backend" | "timeout" }
   | { type: "retry"; reason: "backend" | "timeout"; attempt: number }
   | { type: "fallback"; reason: "backend" | "timeout" }
@@ -363,4 +377,15 @@ export type OnboardingProgress = {
   slot_id?: string;
   /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
   skippable?: boolean;
+  /**
+   * The EXPERIMENT ARM the backend assigned this session, when the tenant is running one. Rides the
+   * render envelope as a sibling of {@link step}/{@link total}/{@link key}/{@link slot_id}, and is
+   * OMITTED entirely for a tenant running no experiment — which is the common case, and is not an
+   * error. The assignment is sticky for the session, so a later card that omits it does not
+   * un-assign it.
+   *
+   * The kit does NOT interpret this. It is whitelisted, latched and handed to the host exactly as
+   * received; what an arm key MEANS is the host's decision. See {@link OnboardingResult.variant}.
+   */
+  variant?: string;
 };

package/src/utils/readPlan.ts

@@ -24,9 +24,16 @@
 import type { Message } from "wireai-rn";
 
 /**
- * The read-back member the SDK surfaces for every A2A DataPart past the first, in wire order and
- * uninterpreted. Declared HERE, structurally, because the installed `wireai-rn` peer (0.2.4) does
- * not declare it on `Message` yet.
+ * The read-back member the SDK surfaces for every A2A DataPart past the first, uninterpreted.
+ *
+ * NOT in wire order, and nothing here may assume it is. The SDK FLATTENS a task's parts across
+ * agent messages LATEST-FIRST (and then artifacts latest-first) before dropping the first one, so
+ * this array is a cross-message collection, not one turn's parts in the order they arrived. On a
+ * task carrying history, a previous turn's component envelope lands here beside this turn's plan.
+ * `readPlan` is safe from that because it matches the `kind` MARKER below, never a position.
+ *
+ * Declared HERE, structurally, because the installed `wireai-rn` peer (0.2.4) does not declare it
+ * on `Message` yet.
  *
  * TODO(re-pin): delete this local type and read the member straight off `Message` once a
  * `wireai-rn` that declares it is published and the peer range is re-pinned. Until then the two
@@ -58,8 +65,14 @@ const planFromPart = (part: unknown): unknown => {
  *
  * ORDERING, stated so it is not undefined behavior: the thread is scanned NEWEST TURN FIRST, so a
  * thread carrying two plans resolves to the LAST one — the same turn `handleFinish` completes on.
- * Within a single turn, wire order decides: the first well-formed plan part wins. A malformed part
- * is skipped rather than treated as a terminator, so a broken payload can never shadow a good one.
+ *
+ * Inside one message's `dataParts` the first WELL-FORMED plan part wins, and that is a scan order,
+ * NOT a wire-order guarantee. Wire order does not hold even within a single turn: `dataParts` is
+ * the SDK's flattened, cross-agent-message collection (latest-first, see `WithDataParts` above), so
+ * on a task carrying history a previous turn's parts sit in the same array. This is exactly why the
+ * match is on the `onboarding_plan` MARKER and never on a position. A part that is not a
+ * well-formed plan is skipped rather than treated as a terminator, so neither a stale envelope nor
+ * a broken payload can shadow a good plan.
  */
 export const readPlan = (messages: readonly Message[]): unknown => {
   for (let i = messages.length - 1; i >= 0; i--) {

package/src/utils/readProgress.ts

@@ -18,6 +18,8 @@ type PartialProgress = {
   /** The stable per-slot identity, when the backend sends one. See `OnboardingProgress.slot_id`. */
   slot_id?: string;
   skippable?: boolean;
+  /** The experiment arm assigned to this session, when the tenant runs one. See `OnboardingProgress.variant`. */
+  variant?: string;
 };
 
 export const readProgress = (response?: WireAIResponse): PartialProgress => {
@@ -33,5 +35,8 @@ export const readProgress = (response?: WireAIResponse): PartialProgress => {
     // Whitelisted the same way as every other field: an old backend simply omits it.
     slot_id: typeof p.slot_id === "string" ? p.slot_id : undefined,
     skippable: typeof p.skippable === "boolean" ? p.skippable : undefined,
+    // Whitelisted like the rest: a non-string (or absent) arm key reads as "no experiment", never
+    // as an error. The kit does not interpret the value — see `OnboardingProgress.variant`.
+    variant: typeof p.variant === "string" ? p.variant : undefined,
   };
 };