@wireai/activation 0.13.5 → 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.5",
+  "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

@@ -33,6 +33,7 @@ import { ErrorBlock } from "./components/ErrorBlock";
 import { CompletionView } from "./components/CompletionView";
 import { CardHandoff } from "./components/CardHandoff";
 import { deriveAnswers } from "./utils/deriveAnswers";
+import { readPlan } from "./utils/readPlan";
 import { readProgress } from "./utils/readProgress";
 import { reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
 import { sendPreview } from "./analytics/sendPreview";
@@ -176,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);
 
@@ -268,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,
@@ -366,7 +380,17 @@ export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
   const handleFinish = useCallback(() => {
     if (finished.current) return;
     finished.current = true;
-    onCompleteRef.current({ answers: deriveAnswers(messages), raw: messages });
+    const result: OnboardingResult = { answers: deriveAnswers(messages), raw: messages };
+    // The plan rides a second DataPart on the AI path only; the static flow carries none. Setting
+    // the key ONLY when there is one keeps the no-plan result byte-identical to the pre-plan
+    // 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]);
 
   // Manual retry (the no-fallback ErrorBlock button): clear the degrade + counter so

package/src/types.ts

@@ -53,6 +53,29 @@ export type OnboardingResult = {
   answers: Record<string, unknown>;
   /** The raw message thread, for custom downstream parsing. */
   raw: Message[];
+  /**
+   * The backend's onboarding plan, when it sent one. Present ONLY on the AI path: a tenant running
+   * the static flow, or any run the server finished without a plan, leaves this `undefined` AND
+   * leaves the key off the result object entirely — so a host written before plans existed sees
+   * byte-identically what it always saw.
+   *
+   * ⚠️ The kit does NOT interpret this and does NOT validate it. It checks one structural fact (a
+   * plan is an object) and hands the payload straight through, unread, unlogged, and never attached
+   * to an analytics event. THE HOST MUST VALIDATE IT before applying it: the fields are
+   * backend-authored, they may gain new ones without a kit release, and what any of them mean is
+   * 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;
 };
 
 /**
@@ -65,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`
@@ -79,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" }
@@ -350,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

@@ -0,0 +1,87 @@
+/**
+ * readPlan — lift the backend's onboarding plan off the message thread.
+ *
+ * WHY IT EXISTS. On the AI path the server appends a SECOND A2A DataPart to the turn it finishes
+ * on: `{ kind: "onboarding_plan", plan: {...} }`, alongside the component envelope the renderer
+ * already consumes. The kit carries that payload out through `OnboardingResult.plan` and stops
+ * there. It does NOT interpret it, does NOT validate its fields, does NOT log it and does NOT
+ * attach it to any event — the plan is user-derived content, and deciding what it MEANS is the
+ * host's job (the kit/host boundary in `ai_rules/context_map.md`: the kit ends at the completion
+ * CTA).
+ *
+ * THE ONE THING IT IS ALLOWED TO REJECT is a structural fact: a plan is an object. A scalar, an
+ * array, or a missing payload is not a plan, and yields `undefined` so the host falls back to
+ * exactly its pre-plan behavior. Nothing below that line is checked: no field is required and no
+ * unknown field is stripped (the server's lenient path adds its own markers), because a kit-side
+ * schema would make the kit the thing that rejects a plan the host could have used.
+ *
+ * MALFORMED INPUT NEVER THROWS. This runs inside `handleFinish`, the single path to `onComplete`,
+ * so a throw here would cost the user the completion of an onboarding they already finished. Every
+ * step below is a runtime-guarded read.
+ *
+ * The static (non-AI) flow carries no plan at all. That path is unchanged and fully supported.
+ */
+import type { Message } from "wireai-rn";
+
+/**
+ * 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
+ * shapes are equal by CONVENTION, not by the compiler, and `hasDataParts` below is what makes that
+ * safe at runtime. Deliberately NOT an `as` cast: a cast silences the compiler in BOTH directions,
+ * including the day the published type disagrees with this one.
+ */
+type WithDataParts = { dataParts: readonly unknown[] };
+
+/** The marker the server stamps on the plan DataPart. */
+const PLAN_PART_KIND = "onboarding_plan";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** RUNTIME proof that a value carries a `dataParts` ARRAY, before anything indexes into one. */
+const hasDataParts = (value: unknown): value is WithDataParts =>
+  isRecord(value) && Array.isArray(value.dataParts);
+
+/** The plan a single DataPart carries, or `undefined` when that part is not a well-formed plan. */
+const planFromPart = (part: unknown): unknown => {
+  if (!isRecord(part) || part.kind !== PLAN_PART_KIND) return undefined;
+  return isRecord(part.plan) ? part.plan : undefined;
+};
+
+/**
+ * The plan the backend sent, or `undefined` when it sent none (or sent something that is not a
+ * plan). Never throws.
+ *
+ * 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.
+ *
+ * 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--) {
+    const message = messages[i];
+    if (!hasDataParts(message)) continue;
+    for (const part of message.dataParts) {
+      const plan = planFromPart(part);
+      if (plan !== undefined) return plan;
+    }
+  }
+  return undefined;
+};

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,
   };
 };