@wireai/activation 0.1.0

package/src/OnboardingFlow.tsx

@@ -0,0 +1,504 @@
+/**
+ * OnboardingFlow — the inner engine. Mirrors the proven production-app usage of the SDK
+ * (useWireAIThread + useWireAIAction + ComponentRenderer) and layers on the kit's
+ * shell, progress, and per-step validators.
+ *
+ * Lifecycle per turn:
+ *   1. Auto-send `startMessage` once → backend returns the first card.
+ *   2. Show LoadingBlock until the first card arrives AND between every turn
+ *      (while `isLoading`); on error/timeout, auto-retry up to `maxRetries`, then
+ *      degrade to the host's static `fallbackFlow` (preferred), else `onError`, else
+ *      an inline ErrorBlock — so a generation failure never breaks onboarding.
+ *   3. Render the latest card inside OnboardingScaffold. The progress bar follows
+ *      an asymptotic curve of the step index — it never reveals a total.
+ *   4. Before any answer is sent, if the current screen's question key has a
+ *      validator, run it; on failure show the error inline and DON'T advance.
+ *   5. On the terminal StatusCard, show CompletionView (the recap of what the app
+ *      will do for the user) and fire onComplete only when they tap its CTA.
+ *
+ * Lifecycle events (started / per-turn / error) are surfaced via `onEvent` so a
+ * host can keep its analytics even though the kit owns the thread loop.
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  ComponentRenderer,
+  useWireAIAction,
+  useWireAIThread,
+  type Message,
+} from "wireai-rn";
+import { OnboardingScaffold } from "./components/OnboardingScaffold";
+import { LoadingBlock } from "./components/LoadingBlock";
+import { LoadingScreen } from "./components/LoadingScreen";
+import { ErrorBlock } from "./components/ErrorBlock";
+import { CompletionView } from "./components/CompletionView";
+import { CardHandoff } from "./components/CardHandoff";
+import { deriveAnswers } from "./utils/deriveAnswers";
+import { readProgress } from "./utils/readProgress";
+import { reportClientEvent, type ClientEventTarget } from "./analytics/reportClientEvent";
+import { sendPreview } from "./analytics/sendPreview";
+import type { DeviceContext } from "./device/deviceContext";
+import type { OnboardingCopy, OnboardingEvent, OnboardingResult, StepValidator } from "./types";
+
+type OnboardingFlowProps = {
+  validators?: Record<string, StepValidator>;
+  onComplete: (result: OnboardingResult) => void;
+  onSkip?: () => void;
+  onError?: (err: unknown) => void;
+  onEvent?: (event: OnboardingEvent) => void;
+  copy?: Partial<OnboardingCopy>;
+  approxScreens?: number;
+  startMessage: string;
+  startTimeoutMs: number;
+  /** Static onboarding rendered when the AI flow fails and retries are exhausted. */
+  fallbackFlow?: React.ReactNode;
+  /** Consecutive failures to auto-retry before degrading. */
+  maxRetries: number;
+  /** Where to POST device-only client events (`dropped`). Omit to disable reporting. */
+  reportTarget?: ClientEventTarget;
+  /** Session id shared with the backend (A2A contextId), so `dropped` correlates. */
+  sessionId: string;
+  /**
+   * Device snapshot + host-injected user context, attached to every client event so the
+   * backend can segment the funnel by device. Old servers ignore the extra fields.
+   */
+  clientContext?: {
+    device?: DeviceContext;
+    userContext?: Record<string, string | number | boolean>;
+    /** The host's opaque user id (see WireOnboarding `userId`), rides `dropped`/`client_fallback`. */
+    userId?: string;
+  };
+  /**
+   * True when `sessionId` was restored from persisted storage (app killed mid-flow).
+   * The kickoff then sends the skip sentinel instead of `startMessage` — the server
+   * would record the literal start text as the ANSWER to the pending question, while
+   * the sentinel advances one card recording nothing — and fires `resumed` instead of
+   * `started` so host funnels don't double-count the session.
+   */
+  resumed?: boolean;
+};
+
+// The kit's per-question Skip sends this sentinel; the backend skips ONE question
+// (advances one card, no answer recorded). Must match the backend's SKIP_ONE_SENTINEL.
+const SKIP_ONE_SENTINEL = "__wireai_skip__";
+
+// Callbacks that carry the user's ANSWER (and so must pass validation first).
+const ANSWER_CALLBACKS = ["onSubmit", "onSelect", "onConfirm", "onPress"] as const;
+
+export const DEFAULT_COPY: OnboardingCopy = {
+  startingTitle: "Getting started…",
+  startingHint: "Setting up your onboarding",
+  restoringTitle: "Picking up where you left off…",
+  restoringHint: "Restoring your session",
+  thinkingTitle: "Personalizing…",
+  thinkingHint: "Tailoring your next question",
+  checkingTitle: "Checking…",
+  checkingHint: "One moment",
+  completeTitle: "You're all set",
+  completeCta: "Let's go",
+};
+
+export const OnboardingFlow: React.FC<OnboardingFlowProps> = ({
+  validators,
+  onComplete,
+  onError,
+  onEvent,
+  copy,
+  approxScreens,
+  startMessage,
+  startTimeoutMs,
+  fallbackFlow,
+  maxRetries,
+  reportTarget,
+  sessionId,
+  resumed = false,
+  clientContext,
+}) => {
+  const { messages, error, isLoading, sendMessage, reset } = useWireAIThread();
+  const makeActions = useWireAIAction(sendMessage);
+
+  const c = useMemo<OnboardingCopy>(() => ({ ...DEFAULT_COPY, ...copy }), [copy]);
+
+  // Hold the latest event/error callbacks in refs so the lifecycle effects below
+  // stay stable (and fire exactly once) regardless of the host re-passing closures.
+  const onEventRef = useRef(onEvent);
+  onEventRef.current = onEvent;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  // Client-event reporting refs, captured so the unmount cleanup (which runs once, with a
+  // stale closure) reads current values.
+  const reportTargetRef = useRef(reportTarget);
+  reportTargetRef.current = reportTarget;
+  const sessionIdRef = useRef(sessionId);
+  sessionIdRef.current = sessionId;
+  // Device + user context, held in a ref so the mount-once unmount cleanup (the `dropped`
+  // reporter, which runs with a stale closure) reads the current snapshot.
+  const clientContextRef = useRef(clientContext);
+  clientContextRef.current = clientContext;
+  // 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);
+  // Trailing-edge debounce timer for prefetch-on-select (see previewOnSelect below).
+  const previewTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const started = useRef(false);
+  const finished = useRef(false);
+  const errored = useRef(false);
+  const attempts = useRef(0);
+  // Mirror of the `degraded` state for the unmount cleanup: a degrade to the static
+  // fallback is NOT a drop, so `dropped` must not fire after it.
+  const degradedRef = useRef(false);
+  const [degraded, setDegraded] = useState(false);
+  const [timedOut, setTimedOut] = useState(false);
+  const [validationError, setValidationError] = useState<string | undefined>();
+  const [validating, setValidating] = useState(false);
+
+  const lastCard = useMemo<Message | undefined>(
+    () => [...messages].reverse().find((m) => m.role === "assistant" && m.response?.action === "render"),
+    [messages],
+  );
+
+  // Local fallback counter — how many distinct rendered cards we've seen.
+  const renderedCount = useMemo(
+    () => messages.filter((m) => m.role === "assistant" && m.response?.action === "render").length,
+    [messages],
+  );
+
+  const progress = useMemo(() => readProgress(lastCard?.response), [lastCard]);
+
+  // 1. Auto-start: the backend treats the first inbound message as "begin".
+  //    On a RESUMED session (persisted id restored after an app kill) the kickoff is
+  //    the skip sentinel instead: the server has this session mid-flow with a pending
+  //    question, and would record `startMessage`'s literal text as its ANSWER — the
+  //    sentinel advances one card recording nothing (a `screen_skipped`). On a session
+  //    the server no longer knows (restart/expiry), the sentinel degrades cleanly to a
+  //    normal kickoff under the same id. Retries re-send the same kickoff.
+  useEffect(() => {
+    if (started.current) return;
+    started.current = true;
+    sendMessage(resumed ? SKIP_ONE_SENTINEL : startMessage);
+    // Surface the session id (the A2A contextId) on the start event so a host can capture it
+    // and bind a user AFTER the flow via `identifyOnboarding({ contextId })` — completion clears
+    // the persisted session, so the in-flight event is the reliable post-flow handle. sessionId
+    // is stable for the whole session (minted before this subtree mounts), so this stays mount-once.
+    onEventRef.current?.(
+      resumed
+        ? { type: "resumed", contextId: sessionId }
+        : { type: "started", contextId: sessionId },
+    );
+  }, [sendMessage, startMessage, resumed, sessionId]);
+
+  // 2. Startup watchdog.
+  useEffect(() => {
+    if (lastCard) return;
+    const timer = setTimeout(() => setTimedOut(true), startTimeoutMs);
+    return () => clearTimeout(timer);
+  }, [lastCard, startTimeoutMs]);
+
+  // A new card arrived → clear any prior inline validation error + emit a turn event.
+  useEffect(() => {
+    setValidationError(undefined);
+    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?.({
+      type: "turn",
+      step,
+      component: lastCard.response?.component,
+    });
+    // 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,
+    // or the backend's message-keyed preview cache misses. The card's onSubmit("continue") is
+    // wrapped by the SDK as `My answer is: ${JSON.stringify(value)}`, so mirror that here.
+    // Fire-and-forget; a failed/missed preview just means the real turn generates normally.
+    if (lastCard.response?.component === "InterstitialCard") {
+      sendPreview(reportTargetRef.current, {
+        sessionId: sessionIdRef.current,
+        userMessage: `My answer is: ${JSON.stringify("continue")}`,
+      });
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [lastCard?.id]);
+
+  // `dropped`: the user abandoned onboarding. No backend request fires on unmount, so the
+  // server can't see this — the client must report it. Fire ONLY on a true unmount that
+  // did NOT complete (`onComplete` never ran) and did NOT degrade to the static fallback
+  // (a degrade is a reliability fallback, not a user drop). Refs keep this effect mount-once.
+  useEffect(() => {
+    return () => {
+      if (finished.current || degradedRef.current) return;
+      reportClientEvent(reportTargetRef.current, {
+        event_type: "dropped",
+        session_id: sessionIdRef.current,
+        screen_index: lastScreenIndexRef.current >= 0 ? lastScreenIndexRef.current : undefined,
+        device: clientContextRef.current?.device,
+        user_context: clientContextRef.current?.userContext,
+        user_id: clientContextRef.current?.userId,
+      });
+    };
+  }, []);
+
+  // Silently restart the thread from turn one (shared by auto-retry + manual retry).
+  // Does NOT clear the attempt counter or the degraded flag — the caller decides that.
+  const restartThread = useCallback(() => {
+    setTimedOut(false);
+    started.current = false;
+    errored.current = false;
+    reset();
+  }, [reset]);
+
+  // 3. Error/timeout → auto-retry a transient blip, then degrade to the static flow.
+  //    Each failure: log `error`; if we have retries left, restart the thread silently
+  //    (`retry`); once exhausted, mark `degraded` so the render falls through to the
+  //    host's `fallbackFlow`/`onError` (`fallback`). Counter is a ref → survives the
+  //    reset()-driven re-renders. This is the "AI fails → static onboarding, never a
+  //    broken screen" guarantee.
+  useEffect(() => {
+    if (errored.current) return;
+    if (!error && !timedOut) return;
+    errored.current = true;
+    const reason: "backend" | "timeout" = error ? "backend" : "timeout";
+    onEventRef.current?.({ type: "error", reason });
+    attempts.current += 1;
+    if (attempts.current <= maxRetries) {
+      onEventRef.current?.({ type: "retry", reason, attempt: attempts.current });
+      restartThread();
+    } else {
+      onEventRef.current?.({ type: "fallback", reason });
+      // Report the degrade to the backend so the dashboard's fallback-rate reflects it.
+      // Server-side `llm_fallback` fires per single degraded turn; this `client_fallback`
+      // captures the whole-flow case (AI gave up, the user got static onboarding). The server
+      // ingests it idempotently and back-fills a `session_started` if it never saw the session,
+      // so even a device that dropped straight to its static manifest shows as a counted
+      // fallback session. This is the ONE fallback signal — hosts must NOT also report it.
+      reportClientEvent(reportTargetRef.current, {
+        event_type: "client_fallback",
+        session_id: sessionIdRef.current,
+        screen_index: lastScreenIndexRef.current >= 0 ? lastScreenIndexRef.current : undefined,
+        meta: JSON.stringify({ reason }),
+        device: clientContextRef.current?.device,
+        user_context: clientContextRef.current?.userContext,
+        user_id: clientContextRef.current?.userId,
+      });
+      degradedRef.current = true;
+      setDegraded(true);
+      onErrorRef.current?.(error ?? new Error("Onboarding timed out"));
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [error, timedOut, maxRetries]);
+
+  // 5. Completion: the terminal StatusCard is rendered as CompletionView; we fire
+  //    onComplete only when the user taps its CTA (guarded so it fires once).
+  const handleFinish = useCallback(() => {
+    if (finished.current) return;
+    finished.current = true;
+    onComplete({ answers: deriveAnswers(messages), raw: messages });
+  }, [messages, onComplete]);
+
+  // Manual retry (the no-fallback ErrorBlock button): clear the degrade + counter so
+  // the user gets a fresh set of attempts.
+  const handleRetry = useCallback(() => {
+    attempts.current = 0;
+    degradedRef.current = false;
+    setDegraded(false);
+    restartThread();
+  }, [restartThread]);
+
+  // Per-question Skip: tell the backend to skip THIS question only and advance to the
+  // next card (no answer recorded) — distinct from finishing the flow. Rendered only
+  // when the current card is `skippable` (see the scaffold below).
+  //
+  // NOTE: we deliberately do NOT report a client `screen_skipped` here. The backend already
+  // emits `screen_skipped` (correctly correlated by its own contextId, with screen_index +
+  // question_key) when it processes this SKIP_ONE_SENTINEL — see the server engine. A client
+  // emission would double-count. The reporter supports `screen_skipped` for clients whose skip
+  // never reaches the server, which is not the case for this kit.
+  const skipQuestion = useCallback(() => {
+    if (isLoading) return;
+    sendMessage(SKIP_ONE_SENTINEL);
+  }, [isLoading, sendMessage]);
+
+  // Prefetch on SELECT — the fix for "the first AI question is always the slowest". Q1 is a
+  // deterministic base card (instant); Q2 is the first LLM turn, and neither cache protects it
+  // (flow-cache misses a novel answer combo, the provider prompt-cache is cold on the first
+  // call). Choice cards hold their selection LOCALLY and only commit on Continue, so there's a
+  // real gap we can use: as the user picks, fire a debounced `message/preview` keyed on the
+  // EXACT text the Continue tap will send (`I selected: ${JSON.stringify(value)}`), so the
+  // backend generates Q2 during the pick→Continue window. By the time they tap Continue it's
+  // already cached → the slow question returns instantly. Fire-and-forget: if they change the
+  // selection after the last preview, the real turn just generates normally (never worse than
+  // today). Trailing-edge debounced so rapid multi-select toggles warm at most once.
+  const previewOnSelect = useCallback((value: string | string[]) => {
+    const target = reportTargetRef.current;
+    if (!target?.serverUrl) return;
+    if (Array.isArray(value) ? value.length === 0 : !value) return;
+    if (previewTimer.current) clearTimeout(previewTimer.current);
+    previewTimer.current = setTimeout(() => {
+      sendPreview(target, {
+        sessionId: sessionIdRef.current,
+        userMessage: `I selected: ${JSON.stringify(value)}`,
+      });
+    }, 300);
+  }, []);
+
+  // Cancel any pending preview on unmount so a fired-but-unsent warm can't outlive the flow.
+  useEffect(() => () => {
+    if (previewTimer.current) clearTimeout(previewTimer.current);
+  }, []);
+
+  // 4. Wrap the SDK's action callbacks so an answer is validated before it's sent.
+  const wrappedActions = useCallback(
+    (messageId: string) => {
+      const base = makeActions(messageId);
+      const key = progress.key;
+      const validator = key ? validators?.[key] : undefined;
+      if (!validator) return base;
+
+      const out: Record<string, (...args: unknown[]) => void> = { ...base };
+      for (const name of ANSWER_CALLBACKS) {
+        const original = base[name];
+        if (!original) continue;
+        out[name] = (...args: unknown[]) => {
+          const value = args[0];
+          // Only string answers are validatable (e.g. username). Pass others through.
+          if (typeof value !== "string") return original(...args);
+          setValidating(true);
+          validator(value)
+            .then((res) => {
+              if (res.ok) {
+                setValidationError(undefined);
+                original(...args);
+              } else {
+                setValidationError(res.error ?? "That value isn't available.");
+              }
+            })
+            .catch(() => {
+              // A validator failure must never block the user — let them proceed.
+              original(...args);
+            })
+            .finally(() => setValidating(false));
+        };
+      }
+      return out;
+    },
+    [makeActions, progress.key, validators],
+  );
+
+  // ── Render ────────────────────────────────────────────────────────────────
+  // Degraded (retries exhausted): render the host's static onboarding in place —
+  // the "AI failed → your static flow, never a broken screen" guarantee. If no
+  // static flow was supplied, hand off to onError (host navigates away), else the
+  // inline retry screen as a last resort.
+  if (degraded) {
+    if (fallbackFlow !== undefined) return <>{fallbackFlow}</>;
+    if (onError) {
+      return <LoadingScreen title={c.startingTitle} hint={c.startingHint} />;
+    }
+    return (
+      <ErrorBlock
+        onRetry={handleRetry}
+        message={
+          timedOut
+            ? "This is taking longer than expected. Try again?"
+            : "We couldn't reach the onboarding service. Try again?"
+        }
+      />
+    );
+  }
+
+  // Errored but not yet degraded → an auto-retry is in flight. Show a neutral loader
+  // so a transient blip never flashes an error screen.
+  if (error || timedOut) {
+    return <LoadingScreen title={c.startingTitle} hint={c.startingHint} />;
+  }
+
+  const response = lastCard?.response;
+
+  // No card yet → the first "thinking" screen.
+  if (!lastCard || !response) {
+    return <LoadingScreen title={c.startingTitle} hint={c.startingHint} />;
+  }
+
+  // Step index drives the progress bar. A total (never shown) only paces the fill:
+  // prefer a backend-supplied total, else the host's approximate prop, else asymptotic.
+  const step = progress.step ?? renderedCount;
+  const total = progress.total ?? approxScreens;
+  const isTerminal = response.action === "render" && response.component === "StatusCard";
+
+  // Terminal recap: show what the app will now do for the user (backend-authored),
+  // and finish only when they tap the CTA.
+  if (isTerminal) {
+    const props = (response.props ?? {}) as {
+      title?: string;
+      message?: string;
+      ctaLabel?: string;
+    };
+    return (
+      <OnboardingScaffold step={step} complete approxScreens={total}>
+        <CompletionView
+          title={props.title ?? c.completeTitle}
+          message={props.message}
+          ctaLabel={props.ctaLabel ?? c.completeCta}
+          onContinue={handleFinish}
+        />
+      </OnboardingScaffold>
+    );
+  }
+
+  const overrides: Record<string, unknown> = {
+    ...wrappedActions(lastCard.id),
+    // Inject the inline error onto whichever card supports it (TextInputCard).
+    validationError,
+    // Choice cards (Selection/ChipSelect) call this as the live selection changes, so the flow
+    // can prefetch the next turn before Continue. Non-committing; ignored by cards that don't use it.
+    onSelectionChange: previewOnSelect,
+  };
+
+  return (
+    <OnboardingScaffold
+      step={step}
+      onSkip={progress.skippable ? skipQuestion : undefined}
+      approxScreens={total}
+    >
+      {/* CardHandoff pairs the exit with the enter (the design's "cards hand off,
+          they don't cut"): the answered card leaves left while the next arrives
+          from the right; loader states enter/exit as a short fade. transitionKey
+          identifies WHAT is on screen — loader states get a stable key per state,
+          cards key on the message id. */}
+      <CardHandoff
+        transitionKey={validating ? "loader:checking" : isLoading ? "loader:thinking" : lastCard.id}
+        variant={
+          validating || isLoading
+            ? "fade"
+            : lastCard.response?.component === "InterstitialCard"
+              ? "spring"
+              : "slide"
+        }
+      >
+        {validating ? (
+          <LoadingBlock title={c.checkingTitle} hint={c.checkingHint} />
+        ) : isLoading ? (
+          // Between turns: the answer was sent and we're waiting on the next card.
+          // Show the "thinking" loader instead of leaving the old card on screen.
+          <LoadingBlock title={c.thinkingTitle} hint={c.thinkingHint} />
+        ) : (
+          // key={lastCard.id} is load-bearing: cards (SelectionCard/ChipSelectCard)
+          // hold internal `selected`/`submitted` state, and React reuses a component
+          // instance across turns when the rendered type is identical (e.g. two
+          // SelectionCards in a row). Without a per-turn key the second card inherits
+          // the first's `submitted=true` and silently rejects all taps. Keying on the
+          // message id forces a fresh mount every turn. (CardHandoff's transitionKey
+          // shares the id, but this renderer key stays the state-isolation guarantee.)
+          <ComponentRenderer
+            key={lastCard.id}
+            messageId={lastCard.id}
+            response={response}
+            callbackOverrides={overrides as never}
+          />
+        )}
+      </CardHandoff>
+    </OnboardingScaffold>
+  );
+};