@wireai/activation 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1390 @@
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+import * as wireai_rn from 'wireai-rn';
+import { Message, WireAIComponent, WireAIResponse } from 'wireai-rn';
+import { O as OnboardingTheme } from './types-BKfpdZzX.js';
+export { a as OnboardingButtonStyle, b as OnboardingColors, c as OnboardingFonts, d as OnboardingRadius, e as OnboardingSpacing } from './types-BKfpdZzX.js';
+import { b as WireOnboardingStorage, a as WireFeaturesConfig, W as WireFeatures } from './types-CMuOexw0.js';
+export { D as DEFAULT_SESSION_TTL_MS, L as LoadedSession, O as OnboardingMode, c as clearPersistedSession, l as loadPersistedSession, p as peekPersistedSession, s as savePersistedSession, d as sessionStorageKey } from './types-CMuOexw0.js';
+export { C as CenteredModal, a as CenteredModalHandle, b as CenteredModalProps } from './CenteredModal-Cdgns6--.js';
+import { Platform } from 'react-native';
+
+/** Transport + tenant config for the managed Wire AI onboarding backend (A2A). */
+type WireOnboardingConfig = {
+    /** Tenant API key (resolves the app server-side). */
+    apiKey: string;
+    /** Base server URL; the kit appends `/a2a`. */
+    serverUrl: string;
+    /** App id — passed as the A2A `model` (informational; the key resolves the app). */
+    appId: string;
+    /**
+     * Extra metadata merged into every A2A request (e.g. install attribution).
+     * NOTE: the kit reserves `sessionId` (correlation seed) and `supportedComponents`
+     * (the renderable card names this device advertises to the backend) — it sets both
+     * automatically, so don't override them here.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Host app version string (e.g. "1.4.2"). HOST-INJECTED — the kit adds no dependency to
+     * read it; hosts typically pass it from `expo-constants`
+     * (`Constants.expoConfig?.version`). Forwarded to the backend on the session metadata and
+     * on client events (merged into the `device` snapshot as `device.appVersion`) so analytics
+     * can segment the funnel by app version. Optional; omit if unknown.
+     */
+    appVersion?: string;
+};
+/**
+ * A per-step validator, keyed by a base-question `key` (e.g. `username`). Runs
+ * before the answer is sent to the backend. Return `{ ok: false, error }` to
+ * block advancing and show the error inline on the card.
+ */
+type StepValidator = (value: string) => Promise<{
+    ok: boolean;
+    error?: string;
+}>;
+/** Result handed to `onComplete` when the flow reaches its terminal StatusCard. */
+type OnboardingResult = {
+    /** Question-key → captured value, derived from the thread. */
+    answers: Record<string, unknown>;
+    /** The raw message thread, for custom downstream parsing. */
+    raw: Message[];
+};
+/**
+ * Lifecycle events emitted as the flow runs, for host-side analytics. The kit owns
+ * the thread loop, so this is how a host recovers per-turn telemetry it used to get
+ * by driving the loop itself.
+ *  - `started`: the very first message was sent to the backend. Carries `contextId` (the
+ *               A2A session id). Capture it if you may need to bind a user AFTER the flow
+ *               finishes (see `identifyOnboarding` and the `userId` prop).
+ *  - `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).
+ *  - `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`
+ *               (or handed off to `onError`). This is the client-side mirror of the
+ *               backend's `llm_fallback` reliability event.
+ */
+type OnboardingEvent = {
+    type: "started";
+    contextId: string;
+} | {
+    type: "resumed";
+    contextId: string;
+} | {
+    type: "turn";
+    step: number;
+    component?: string;
+} | {
+    type: "error";
+    reason: "backend" | "timeout";
+} | {
+    type: "retry";
+    reason: "backend" | "timeout";
+    attempt: number;
+} | {
+    type: "fallback";
+    reason: "backend" | "timeout";
+};
+/**
+ * Copy overrides for the kit's built-in (English) strings, so a host can localize
+ * the loaders / completion fallback via its own i18n. Any field left unset keeps
+ * the kit default.
+ */
+type OnboardingCopy = {
+    /** First "thinking" screen, before any card arrives. */
+    startingTitle: string;
+    startingHint: string;
+    /** While the persisted session id is being restored from `storage` (pre-mount gate). */
+    restoringTitle: string;
+    restoringHint: string;
+    /** Between-turns loader, while the next card is generated. */
+    thinkingTitle: string;
+    thinkingHint: string;
+    /** While a per-step validator is running. */
+    checkingTitle: string;
+    checkingHint: string;
+    /** Completion fallback when the backend omits a title/CTA. */
+    completeTitle: string;
+    completeCta: string;
+};
+type WireOnboardingProps = {
+    config: WireOnboardingConfig;
+    /** Partial theme merged over the neutral default. */
+    theme?: Partial<OnboardingTheme>;
+    /** Override the registered cards (defaults to the kit's `onboardingComponents`). */
+    components?: wireai_rn.WireAIComponent[];
+    /**
+     * App-supplied artwork for InterstitialCard, keyed by name. The backend names one
+     * via `illustration`; the kit slots the matching node (keeping itself dependency-free).
+     */
+    illustrations?: Record<string, React.ReactNode>;
+    /** Per-step validators keyed by base-question key, e.g. `{ username: checkUsername }`. */
+    validators?: Record<string, StepValidator>;
+    /** Fired once the flow reaches its terminal StatusCard. */
+    onComplete: (result: OnboardingResult) => void;
+    /**
+     * Retained for back-compat. NOTE: per-question Skip is now INTERNAL — the kit shows
+     * a Skip control only on screens the backend marks `skippable`, and it advances ONE
+     * question (it does not exit the flow). This callback is no longer wired to that control.
+     */
+    onSkip?: () => void;
+    /**
+     * Fired on a backend error or first-card timeout, AFTER retries are exhausted.
+     * When `fallbackFlow` is NOT supplied and this is provided, the host owns recovery
+     * (e.g. navigate to its own static onboarding) instead of the kit's inline retry.
+     */
+    onError?: (err: unknown) => void;
+    /**
+     * Your predefined STATIC onboarding, rendered in place when the AI flow fails and
+     * retries are exhausted — so a generation/backend/timeout error degrades to your
+     * static flow instead of breaking the app. Takes precedence over `onError`. This
+     * is the "it can never break your onboarding" guarantee: supply the same flow you
+     * shipped before adding Wire AI and the user always keeps moving.
+     */
+    fallbackFlow?: React.ReactNode;
+    /**
+     * Consecutive failures to auto-retry before degrading to `fallbackFlow`/`onError`.
+     * Default 1 (one silent retry, then degrade). 0 = degrade on the first failure.
+     */
+    maxRetries?: number;
+    /** Lifecycle hook for host-side analytics (started / per-turn / error). */
+    onEvent?: (event: OnboardingEvent) => void;
+    /**
+     * Host-injected, non-PII context the app already knows about the user — signup method,
+     * referral source, plan tier, a HASHED user id, etc. Same host-injection philosophy as
+     * `storage`: the kit collects nothing here; the host passes what it wants. Forwarded to the
+     * backend on the session metadata AND on client events so analytics can segment the funnel.
+     *
+     * MUST NOT contain PII such as raw emails, names, or phone numbers — pass a hash if you need
+     * a user key. Values are limited to primitives (`string | number | boolean`); the server caps
+     * key count / size and drops deep nesting. Old servers ignore it (backward compatible).
+     */
+    userContext?: Record<string, string | number | boolean>;
+    /**
+     * The host's own user id, so onboarding sessions can be reconciled to real users later
+     * (console sessions ↔ your user table / GA4 users). First-class alongside `userContext`.
+     *
+     * An OPAQUE PSEUDONYMOUS string YOU own — your internal user id, NOT an email/name/phone.
+     * Trimmed and capped at 128 chars (longer is truncated). **No PII.**
+     *
+     * LATE BINDING: users often register DURING or AFTER onboarding, so this is fully optional
+     * and can arrive late:
+     *  - present at MOUNT → rides the A2A session-start metadata (server binds it at session start);
+     *  - CHANGES mid-session (e.g. the user just registered) → the kit emits an `identify` event
+     *    that attaches the id to the LIVE session;
+     *  - available only AFTER completion → capture the `contextId` from the `started`/`resumed`
+     *    `onEvent` while the flow runs, then call `identifyOnboarding({ contextId, userId })` once
+     *    the user registers. Completion clears the persisted session, so the captured `contextId`
+     *    is the reliable post-flow handle.
+     *
+     * Backward compatible: omit it and nothing changes; old servers ignore the extra field.
+     */
+    userId?: string;
+    /** Localized overrides for the kit's built-in English strings. */
+    copy?: Partial<OnboardingCopy>;
+    /**
+     * Approximate total number of screens, if known (e.g. the backend screen budget).
+     * Paces the progress bar as `step / approxScreens` (capped, never shown as a
+     * number) instead of the asymptotic default. A backend-supplied `progress.total`
+     * takes precedence when present.
+     */
+    approxScreens?: number;
+    /** First message that kicks off the backend flow. Default `"start"`. */
+    startMessage?: string;
+    /** Ms to wait for the first card before showing the error/retry state. Default 15000. */
+    startTimeoutMs?: number;
+    /**
+     * Host-injected storage for session-id persistence (AsyncStorage-compatible subset:
+     * pass `@react-native-async-storage/async-storage` as-is, or a small MMKV wrapper).
+     * When set, the kit caches its session id so an app KILL mid-onboarding resumes the
+     * SAME backend session instead of minting a new one — keeping the analytics funnel's
+     * `started` count honest (no phantom drops). Omit for the previous per-mount behavior.
+     * This persists the kit's own correlation seed only — never answers.
+     */
+    storage?: WireOnboardingStorage;
+    /**
+     * How long a persisted session id stays resumable, in ms. Default 3 600 000 (1h),
+     * matching the backend's session TTL. Only meaningful with `storage`.
+     */
+    sessionTtlMs?: number;
+    /**
+     * Override the storage key (default `wireai:session:<config.appId>`). Scope it
+     * per-user (e.g. append a user id) if one device can run onboarding for multiple
+     * accounts mid-flow. Only meaningful with `storage`.
+     */
+    persistKey?: string;
+};
+/** Backend-supplied progress, read off `response.props.progress` when present. */
+type OnboardingProgress = {
+    step: number;
+    total: number;
+    /** Base-question key for the CURRENT screen, when known (used to pick a validator). */
+    key?: string;
+    /** Whether the CURRENT screen may be skipped (backend-marked; default false → no Skip shown). */
+    skippable?: boolean;
+};
+
+/**
+ * WireOnboarding — the public host component. Drop it into a screen and it runs
+ * the whole AI onboarding: builds the A2A transport from `config`, wires the SDK
+ * provider with the themed cards, applies the theme, and renders the flow.
+ *
+ *   <WireOnboarding
+ *     config={{ apiKey, serverUrl, appId }}
+ *     theme={myBrandTheme}
+ *     validators={{ username: checkUsernameAvailable }}
+ *     onComplete={persist}
+ *     onSkip={skip}
+ *   />
+ */
+
+declare const WireOnboarding: React__default.FC<WireOnboardingProps>;
+
+type DemoOnboardingProps = {
+    /** The Wire AI config, or `null` when the app hasn't integrated Wire AI yet. */
+    config: WireOnboardingConfig | null;
+    theme?: WireOnboardingProps["theme"];
+    illustrations?: WireOnboardingProps["illustrations"];
+    validators?: WireOnboardingProps["validators"];
+    copy?: WireOnboardingProps["copy"];
+    /** Trigger button label. Default "Demo onboarding". */
+    label?: string;
+    /** Observe the demo result. By default the demo just closes (no persistence). */
+    onComplete?: (result: OnboardingResult) => void;
+    /** Render your own trigger instead of the default button: `(open) => <YourButton onPress={open} />`. */
+    renderTrigger?: (open: () => void) => ReactNode;
+};
+declare function DemoOnboarding({ config, theme, illustrations, validators, copy, label, onComplete, renderTrigger, }: DemoOnboardingProps): React.JSX.Element;
+
+/**
+ * ThemeContext — provides the resolved OnboardingTheme to every shell element and
+ * themed card via `useOnboardingTheme()`. WHY a context rather than prop-drilling:
+ * the cards are mounted by the SDK's ComponentRenderer (not by us), so we can't
+ * pass them props directly — they must read the theme from context.
+ */
+
+type OnboardingThemeProviderProps = {
+    /** Partial overrides merged over the neutral default theme. */
+    theme?: Partial<OnboardingTheme>;
+    children: React__default.ReactNode;
+};
+declare const OnboardingThemeProvider: React__default.FC<OnboardingThemeProviderProps>;
+/**
+ * Read the active theme. Falls back to the default theme when used outside a
+ * provider so a stray card never crashes — it just renders neutral.
+ */
+declare const useOnboardingTheme: () => OnboardingTheme;
+
+/**
+ * defaultOnboardingTheme — a neutral, light, brand-agnostic baseline. Consumers
+ * pass a `Partial<OnboardingTheme>` that is deep-merged over this (see
+ * `mergeTheme`), so they only override what differs from neutral.
+ */
+
+declare const defaultOnboardingTheme: OnboardingTheme;
+/**
+ * Deep-merge a partial theme over the default. Two levels deep is enough — the
+ * theme is intentionally shallow (colors/fonts/radius/spacing), so we merge each
+ * known sub-object and leave scalars to overwrite.
+ */
+declare const mergeTheme: (override?: Partial<OnboardingTheme>) => OnboardingTheme;
+
+type ThemeFromBrandInput = {
+    /** Brand / accent color — drives selected states, primary buttons, progress fill. */
+    primary: string;
+    /** App background behind the whole flow. Default: the neutral light background. */
+    background?: string;
+    /** Card / elevated surface background. Default: the neutral surface. */
+    surface?: string;
+    /** Primary body text color. Default: the neutral near-black. */
+    text?: string;
+    /** Text/icon color on top of `primary`. Default: white. */
+    onPrimary?: string;
+    /**
+     * A single font family applied to regular/medium/bold (the kit derives weight
+     * from size when a family isn't weight-split). Pass `fonts` in `extra` for
+     * per-weight families.
+     */
+    font?: string;
+    /** Any further theme overrides, deep-merged last (radius/spacing/button/fonts/colors). */
+    extra?: Partial<OnboardingTheme>;
+};
+declare const themeFromBrand: (input: ThemeFromBrandInput) => Partial<OnboardingTheme>;
+
+/**
+ * OnboardingScaffold — the themed shell that wraps every step:
+ *   [ safe area ]
+ *     header   -> StepProgress (a numberless fill — never "Step X of N") + optional Skip
+ *     body     -> the rendered card (children), full-screen (flex: 1)
+ *     footer   -> optional Back link
+ *
+ * WHY a single scaffold: the body content changes every turn (it's an
+ * SDK-rendered card), but the chrome — progress, skip, back, padding, safe area —
+ * stays constant. Keeping it here means cards never re-implement the frame.
+ *
+ * The body no longer centers/scrolls the card: each card fills the body via the
+ * shared CardLayout, which owns its own scroll + bottom-pinned CTA (Cal-AI style).
+ * The safe area uses `react-native-safe-area-context` (top + bottom edges) — the
+ * RN core SafeAreaView is deprecated and iOS-only, so the kit takes the standard
+ * Expo/RN peer instead of shipping cropped layouts on Android + notched devices.
+ */
+
+type OnboardingScaffoldProps = {
+    /** 1-based index of the current step; drives the (countless) progress bar. */
+    step: number;
+    /** When true, the progress bar fills to 100% (flow finished). */
+    complete?: boolean;
+    /** Approximate total screens, if known — paces the bar (never shown). */
+    approxScreens?: number;
+    /** Optional Back action — hidden when omitted (e.g. on the first step). */
+    onBack?: () => void;
+    /** Optional Skip action — hidden when omitted. */
+    onSkip?: () => void;
+    skipLabel?: string;
+    backLabel?: string;
+    children: React__default.ReactNode;
+};
+declare const OnboardingScaffold: React__default.NamedExoticComponent<OnboardingScaffoldProps>;
+
+/**
+ * StepProgress — a single themed progress bar that conveys forward motion. It never
+ * shows a "Step X of N" number (the count would read as a promise the model may not
+ * keep), but it can be *paced* two ways:
+ *
+ *  - Default (no `approxScreens`): an asymptotic curve of the step index — always
+ *    advances, never reaches the end until the flow actually completes.
+ *  - With `approxScreens`: when the host knows roughly how many screens the flow
+ *    runs (e.g. the backend's screen budget), the fill tracks `step / approxScreens`
+ *    (capped below 100% until `complete`). More truthful pacing, still no number.
+ */
+
+type StepProgressProps = {
+    /** 1-based index of the current step. Drives the fill. */
+    step: number;
+    /** When true, fill to 100% (flow finished). */
+    complete?: boolean;
+    /**
+     * Approximate total number of screens, if known (e.g. the backend screen budget).
+     * Paces the bar as `step / approxScreens` instead of the asymptotic curve. Never
+     * shown as a number — it only shapes the fill. Omit for the asymptotic default.
+     */
+    approxScreens?: number;
+};
+declare const StepProgress: React__default.NamedExoticComponent<StepProgressProps>;
+
+/**
+ * LoadingBlock — the "AI is thinking" indicator, shown before the first card and
+ * between every turn (each round-trip to the backend). The Wire Activation
+ * loading treatment: no generic spinner — the brand mark breathes inside a
+ * dashed ring while an accent dot orbits it, and skeleton lines appear (softly
+ * pulsing) only when the fetch runs past 300ms so a fast turn never flashes
+ * placeholder chrome (design-refs/EXTRACTED-SPEC.md rows 17-19).
+ *
+ * Reduce motion: static mark + copy, no orbit, no pulse.
+ */
+
+type LoadingBlockProps = {
+    /** Primary line, e.g. "Thinking…". */
+    title?: string;
+    /** Supporting line under the title. */
+    hint?: string;
+};
+declare const LoadingBlock: React__default.NamedExoticComponent<LoadingBlockProps>;
+
+/**
+ * LoadingScreen — the STANDALONE loader surface: a full-area safe frame that centers a
+ * LoadingBlock dead in the middle of the screen. Used for the loader slots that render on
+ * their own (no OnboardingScaffold around them): the cold-start "getting started" wait, the
+ * resumed-session "restoring" wait, and the transient error/timeout retry beat.
+ *
+ * WHY a dedicated frame: those slots used to return a bare <LoadingBlock/>, whose flex:1 only
+ * fills whatever the host happened to give it — with no safe area and, if the host didn't
+ * bound it, no height at all (top-anchored). This wraps them in the same SafeAreaView the flow
+ * uses, so the standalone loaders center exactly like the between-turns loader (which centers
+ * in the full flow area via the scaffold's loaderChrome offset). One consistent centered look.
+ */
+
+declare const LoadingScreen: React__default.NamedExoticComponent<LoadingBlockProps>;
+
+/**
+ * AnimatedSparkle — the themed "AI is thinking" glyph (✦), animated with RN's
+ * built-in `Animated` (native driver) so the kit needs neither reanimated nor a
+ * vector-icon dependency.
+ *
+ * Variants:
+ *   - "spin" (default, unchanged): continuous rotation — the original loader.
+ *   - "pulse": the Wire Activation loading treatment — the mark breathes
+ *     (opacity 0.35 ↔ 1, 1600ms loop) instead of rotating.
+ *
+ * Reduce motion: no loop at all — the glyph renders static at full opacity
+ * (final frame), per design-refs/EXTRACTED-SPEC.md row 17.
+ */
+
+type AnimatedSparkleProps = {
+    /** Glyph size in px. */
+    size?: number;
+    /** Override color; defaults to the theme primary. */
+    color?: string;
+    /** "spin" rotates (default, the original), "pulse" breathes (the loader treatment). */
+    variant?: "spin" | "pulse";
+};
+declare const AnimatedSparkle: React__default.NamedExoticComponent<AnimatedSparkleProps>;
+
+/**
+ * ErrorBlock — shown on backend error/timeout. Carries a retry action so the flow
+ * never dead-ends. The host decides what retry does (re-send start, or fall back).
+ */
+
+type ErrorBlockProps = {
+    title?: string;
+    message?: string;
+    retryLabel?: string;
+    onRetry?: () => void;
+};
+declare const ErrorBlock: React__default.NamedExoticComponent<ErrorBlockProps>;
+
+/**
+ * DoneBlock — a brief themed "all set" state shown when the flow completes, while
+ * the host persists results and navigates away. Purely cosmetic; the real
+ * terminal signal is the SDK's StatusCard (handled in OnboardingFlow).
+ */
+
+type DoneBlockProps = {
+    title?: string;
+    message?: string;
+};
+declare const DoneBlock: React__default.NamedExoticComponent<DoneBlockProps>;
+
+/**
+ * CompletionView — the terminal "you're all set" screen, shown when the flow
+ * reaches its final StatusCard. It surfaces the backend's recap (what the app
+ * will do for the user, derived from their answers) and a single clear CTA.
+ *
+ * WHY a dedicated screen (not an instant hand-off): the backend spends the last
+ * turn summarizing the user's tastes and what their experience will now look
+ * like. The user should actually SEE that payoff and tap to continue — so
+ * `onContinue` fires only on the button press, never automatically.
+ *
+ * Motion (design-refs/EXTRACTED-SPEC.md rows 14-16, the peak-end beat): the
+ * badge pops in with a spring (scale 0.4→1, slight overshoot), ONE soft accent
+ * burst radiates once behind it (scale 0.4→1.5, opacity 0.5→0, 500ms) —
+ * celebratory without confetti — and the copy fades up 80ms apart. Everything
+ * settles well under a second. Reduce motion: final frame, no burst.
+ */
+
+type CompletionViewProps = {
+    title: string;
+    message?: string;
+    ctaLabel?: string;
+    onContinue: () => void;
+};
+declare const CompletionView: React__default.NamedExoticComponent<CompletionViewProps>;
+
+/**
+ * Illustration registry — lets the host app supply brand artwork (SVG / Lottie /
+ * Image nodes) keyed by name, which the backend references from an InterstitialCard
+ * by `illustration`. Keeping the registry in React context (rather than as a card
+ * prop) is what keeps the kit dependency-free: the kit never imports react-native-svg
+ * or Lottie — the app brings its own nodes and the kit just slots the matching one.
+ *
+ *   <WireOnboarding illustrations={{ "before-after": <BeforeAfter/> }} ... />
+ *
+ * When the backend names an illustration the registry doesn't have, the
+ * InterstitialCard falls back to its `imageUrl` (a plain RN <Image>).
+ */
+
+type IllustrationRegistry = Record<string, React__default.ReactNode>;
+type IllustrationProviderProps = {
+    registry?: IllustrationRegistry;
+    children: React__default.ReactNode;
+};
+declare const IllustrationProvider: React__default.FC<IllustrationProviderProps>;
+/** Look up an app-supplied illustration node by name. Returns undefined if absent. */
+declare const useIllustration: (name?: string) => React__default.ReactNode | undefined;
+
+/**
+ * defaultIllustrations — a tiny, dependency-free fallback registry so an app can
+ * render `InterstitialCard` with ZERO illustration code. These are plain
+ * <View>/<Text> glyphs (NO react-native-svg, NO Lottie, NO image assets) themed
+ * from the active OnboardingTheme, covering the common backend-emitted names.
+ *
+ * Spread it under your own artwork — your named nodes win:
+ *
+ *   illustrations={{ ...defaultIllustrations, ...myIllustrations }}
+ *
+ * Names match what the onboarding backend commonly emits via an InterstitialCard's
+ * `illustration`: `momentum` (forward-motion arc) and `before-after` (two states).
+ * Add more by spreading your own — these are only sensible defaults.
+ */
+
+/**
+ * The default registry. `WireOnboarding`'s `illustrations` prop is
+ * `Record<string, ReactNode>`, so these are concrete element nodes.
+ */
+declare const defaultIllustrations: Record<string, React__default.ReactNode>;
+
+/**
+ * Button — the kit's themed primary/outline button, replacing the SDK's hardcoded
+ * `Btn`. Every color/radius/font comes from the active theme.
+ *
+ * Motion (design-refs/EXTRACTED-SPEC.md row 20): "a footer button that answers
+ * the tap" — scale 1→0.975 spring on press-in, back on release, native driver.
+ * Reduce motion: an opacity dip to 0.85 while pressed, no scale. Disabled keeps
+ * the `disabled` token fill with no press handler (unchanged).
+ */
+
+type Variant = "primary" | "outline";
+type ButtonProps = {
+    title: string;
+    onPress?: () => void;
+    variant?: Variant;
+    disabled?: boolean;
+    /** Stretch to the container width — for form-style CTAs (e.g. the review form's
+     *  "Send feedback"). Default false keeps the content-width pill used by cards. */
+    fullWidth?: boolean;
+};
+declare const Button: React__default.NamedExoticComponent<ButtonProps>;
+
+/**
+ * CardHandoff — the card-to-card transition from the Wire Activation design:
+ * "cards hand off, they don't cut". When `transitionKey` changes, the outgoing
+ * child leaves left (translateX 0→-26, fade, 180ms) in an absolute layer while
+ * the incoming child arrives from the right (translateX +26→0, fade, 220ms)
+ * delayed by the 80ms exit lead — one moving surface, ~300ms total.
+ *
+ * Variants (per child):
+ *   - "slide": questions — the directional stepper motion above.
+ *   - "spring": the InterstitialCard value beat — scale 0.96→1 spring pop
+ *     (the shell's springier variant, kept from AnimatedCard).
+ *   - "fade": loaders — enter/exit as a plain 120ms fade so the "thinking"
+ *     state hands off to the first card without a hard cut.
+ *
+ * Reduce motion: every handoff becomes a 120ms crossfade, no translate/scale.
+ * All values run on the native driver (transform/opacity only); in-flight
+ * animations are stopped when superseded and on unmount.
+ *
+ * This SUPERSEDES the enter-only AnimatedCard: same keyed-remount contract from
+ * OnboardingFlow (the child renderer stays keyed on the message id), plus the
+ * paired exit layer the design calls for.
+ */
+
+type CardHandoffVariant = "slide" | "spring" | "fade";
+type CardHandoffProps = {
+    /** Identity of the current child (e.g. the message id). A change runs the handoff. */
+    transitionKey: string;
+    /** How the CURRENT child enters (and, snapshotted, how it will later exit). */
+    variant?: CardHandoffVariant;
+    children: React__default.ReactNode;
+};
+declare const CardHandoff: React__default.NamedExoticComponent<CardHandoffProps>;
+
+declare const useReducedMotion: () => boolean;
+
+/**
+ * motionSpec — the single source of truth for every animation value in the kit,
+ * extracted 1:1 from the Wire Activation card-interactions design canvas
+ * (see design-refs/EXTRACTED-SPEC.md for the row-by-row mapping).
+ *
+ * Pure constants + pure helpers only — NO react-native import — so the spec is
+ * unit-testable under node:test and components can't drift from the design
+ * without a red test.
+ */
+/** The design system's "ease-wire" curve: cubic-bezier(0.16, 1, 0.3, 1). */
+declare const WIRE_BEZIER: readonly [0.16, 1, 0.3, 1];
+/** Design-system duration tokens (colors_and_type.css --duration-*). */
+declare const DURATION_FAST_MS = 150;
+declare const DURATION_BASE_MS = 300;
+declare const DURATION_SLOW_MS = 500;
+/** Reduce-motion fallback: a short fade to the final frame, never a frozen mid-state. */
+declare const REDUCED_FADE_MS = 120;
+declare const ROW_PRESS_SCALE = 0.975;
+declare const CHIP_PRESS_SCALE = 0.94;
+declare const BUTTON_PRESS_SCALE = 0.975;
+/** Reduce-motion press feedback: opacity dip instead of scale. */
+declare const REDUCED_PRESS_OPACITY = 0.85;
+declare const PRESS_SPRING: {
+    readonly friction: 8;
+    readonly tension: 220;
+};
+declare const BUTTON_PRESS_SPRING: {
+    readonly friction: 8;
+    readonly tension: 240;
+};
+declare const SELECT_FILL_MS = 180;
+declare const CHIP_FILL_MS = 160;
+declare const CHECK_SPRING: {
+    readonly friction: 6;
+    readonly tension: 180;
+};
+declare const CHECK_SCALE_FROM = 0.6;
+declare const CARD_ENTER_MS = 220;
+declare const CARD_EXIT_MS = 180;
+/** The exit starts this long BEFORE the enter (enter is delayed by this). */
+declare const CARD_EXIT_LEAD_MS = 80;
+declare const CARD_SLIDE_PX = 26;
+declare const CARD_ENTER_SCALE_FROM = 0.96;
+/** The interstitial keeps the shell's springier value-beat (AnimatedCard idiom). */
+declare const CARD_SPRING: {
+    readonly damping: 14;
+    readonly stiffness: 180;
+    readonly mass: 1;
+};
+/** Loader-to-card handoff: the loader just fades out. */
+declare const LOADER_HANDOFF_FADE_MS = 120;
+declare const INTERSTITIAL_HEAD_MS = 500;
+declare const INTERSTITIAL_HEAD_STAGGER_MS = 100;
+declare const INTERSTITIAL_ITEM_MS = 300;
+declare const INTERSTITIAL_ITEM_STAGGER_MS = 90;
+declare const INTERSTITIAL_ITEM_BASE_DELAY_MS = 200;
+declare const INTERSTITIAL_CHECK_DELAY_MS = 200;
+declare const INTERSTITIAL_CHECK_SCALE_FROM = 0.4;
+/** Delay before work item `index` begins its reveal (row lands after the head). */
+declare const interstitialItemDelay: (index: number) => number;
+/** Delay before work item `index`'s check pops (200ms after its row starts). */
+declare const interstitialCheckDelay: (index: number) => number;
+declare const STATUS_POP_SPRING: {
+    readonly friction: 6;
+    readonly tension: 200;
+};
+declare const STATUS_POP_SCALE_FROM = 0.4;
+declare const STATUS_BURST_MS = 500;
+declare const STATUS_BURST_SCALE_FROM = 0.4;
+declare const STATUS_BURST_SCALE_TO = 1.5;
+declare const STATUS_BURST_OPACITY_FROM = 0.5;
+declare const STATUS_COPY_MS = 300;
+declare const STATUS_COPY_STAGGER_MS = 80;
+/** Copy starts settling once the badge pop is visibly underway. */
+declare const STATUS_COPY_BASE_DELAY_MS = 200;
+/** Delay before payoff copy line `index` fades up. */
+declare const statusCopyDelay: (index: number) => number;
+declare const LOADER_PULSE_MS = 1600;
+declare const LOADER_PULSE_MIN_OPACITY = 0.35;
+declare const LOADER_ORBIT_MS = 2400;
+/** Skeleton lines appear only when the fetch runs past this. */
+declare const SKELETON_DELAY_MS = 300;
+declare const SKELETON_PULSE_MS = 1500;
+declare const SKELETON_MIN_OPACITY = 0.45;
+declare const PROGRESS_MS = 400;
+/** Set the global duration multiplier (clamped to 0.1-10; invalid resets to 1). */
+declare const setMotionDurationScale: (scale: number) => void;
+declare const getMotionDurationScale: () => number;
+/** Apply the current duration scale to a spec duration/delay (rounded ms). */
+declare const scaledMs: (ms: number) => number;
+type EntranceSpec = {
+    /** Duration to animate with (falls back to the short fade under reduce motion). */
+    duration: number;
+    /** Whether transforms (translate/scale) may move; false = opacity-only fade. */
+    useTransform: boolean;
+};
+/** Entrances: full motion normally; a 120ms opacity-only fade under reduce motion. */
+declare const entranceSpec: (reduced: boolean, durationMs: number) => EntranceSpec;
+/** State changes (select fills etc.): snap instantly under reduce motion. */
+declare const stateChangeDuration: (reduced: boolean, durationMs: number) => number;
+/** Looping/ambient animations run only when motion is allowed. */
+declare const loopEnabled: (reduced: boolean) => boolean;
+
+declare const motionSpec_BUTTON_PRESS_SCALE: typeof BUTTON_PRESS_SCALE;
+declare const motionSpec_BUTTON_PRESS_SPRING: typeof BUTTON_PRESS_SPRING;
+declare const motionSpec_CARD_ENTER_MS: typeof CARD_ENTER_MS;
+declare const motionSpec_CARD_ENTER_SCALE_FROM: typeof CARD_ENTER_SCALE_FROM;
+declare const motionSpec_CARD_EXIT_LEAD_MS: typeof CARD_EXIT_LEAD_MS;
+declare const motionSpec_CARD_EXIT_MS: typeof CARD_EXIT_MS;
+declare const motionSpec_CARD_SLIDE_PX: typeof CARD_SLIDE_PX;
+declare const motionSpec_CARD_SPRING: typeof CARD_SPRING;
+declare const motionSpec_CHECK_SCALE_FROM: typeof CHECK_SCALE_FROM;
+declare const motionSpec_CHECK_SPRING: typeof CHECK_SPRING;
+declare const motionSpec_CHIP_FILL_MS: typeof CHIP_FILL_MS;
+declare const motionSpec_CHIP_PRESS_SCALE: typeof CHIP_PRESS_SCALE;
+declare const motionSpec_DURATION_BASE_MS: typeof DURATION_BASE_MS;
+declare const motionSpec_DURATION_FAST_MS: typeof DURATION_FAST_MS;
+declare const motionSpec_DURATION_SLOW_MS: typeof DURATION_SLOW_MS;
+type motionSpec_EntranceSpec = EntranceSpec;
+declare const motionSpec_INTERSTITIAL_CHECK_DELAY_MS: typeof INTERSTITIAL_CHECK_DELAY_MS;
+declare const motionSpec_INTERSTITIAL_CHECK_SCALE_FROM: typeof INTERSTITIAL_CHECK_SCALE_FROM;
+declare const motionSpec_INTERSTITIAL_HEAD_MS: typeof INTERSTITIAL_HEAD_MS;
+declare const motionSpec_INTERSTITIAL_HEAD_STAGGER_MS: typeof INTERSTITIAL_HEAD_STAGGER_MS;
+declare const motionSpec_INTERSTITIAL_ITEM_BASE_DELAY_MS: typeof INTERSTITIAL_ITEM_BASE_DELAY_MS;
+declare const motionSpec_INTERSTITIAL_ITEM_MS: typeof INTERSTITIAL_ITEM_MS;
+declare const motionSpec_INTERSTITIAL_ITEM_STAGGER_MS: typeof INTERSTITIAL_ITEM_STAGGER_MS;
+declare const motionSpec_LOADER_HANDOFF_FADE_MS: typeof LOADER_HANDOFF_FADE_MS;
+declare const motionSpec_LOADER_ORBIT_MS: typeof LOADER_ORBIT_MS;
+declare const motionSpec_LOADER_PULSE_MIN_OPACITY: typeof LOADER_PULSE_MIN_OPACITY;
+declare const motionSpec_LOADER_PULSE_MS: typeof LOADER_PULSE_MS;
+declare const motionSpec_PRESS_SPRING: typeof PRESS_SPRING;
+declare const motionSpec_PROGRESS_MS: typeof PROGRESS_MS;
+declare const motionSpec_REDUCED_FADE_MS: typeof REDUCED_FADE_MS;
+declare const motionSpec_REDUCED_PRESS_OPACITY: typeof REDUCED_PRESS_OPACITY;
+declare const motionSpec_ROW_PRESS_SCALE: typeof ROW_PRESS_SCALE;
+declare const motionSpec_SELECT_FILL_MS: typeof SELECT_FILL_MS;
+declare const motionSpec_SKELETON_DELAY_MS: typeof SKELETON_DELAY_MS;
+declare const motionSpec_SKELETON_MIN_OPACITY: typeof SKELETON_MIN_OPACITY;
+declare const motionSpec_SKELETON_PULSE_MS: typeof SKELETON_PULSE_MS;
+declare const motionSpec_STATUS_BURST_MS: typeof STATUS_BURST_MS;
+declare const motionSpec_STATUS_BURST_OPACITY_FROM: typeof STATUS_BURST_OPACITY_FROM;
+declare const motionSpec_STATUS_BURST_SCALE_FROM: typeof STATUS_BURST_SCALE_FROM;
+declare const motionSpec_STATUS_BURST_SCALE_TO: typeof STATUS_BURST_SCALE_TO;
+declare const motionSpec_STATUS_COPY_BASE_DELAY_MS: typeof STATUS_COPY_BASE_DELAY_MS;
+declare const motionSpec_STATUS_COPY_MS: typeof STATUS_COPY_MS;
+declare const motionSpec_STATUS_COPY_STAGGER_MS: typeof STATUS_COPY_STAGGER_MS;
+declare const motionSpec_STATUS_POP_SCALE_FROM: typeof STATUS_POP_SCALE_FROM;
+declare const motionSpec_STATUS_POP_SPRING: typeof STATUS_POP_SPRING;
+declare const motionSpec_WIRE_BEZIER: typeof WIRE_BEZIER;
+declare const motionSpec_entranceSpec: typeof entranceSpec;
+declare const motionSpec_getMotionDurationScale: typeof getMotionDurationScale;
+declare const motionSpec_interstitialCheckDelay: typeof interstitialCheckDelay;
+declare const motionSpec_interstitialItemDelay: typeof interstitialItemDelay;
+declare const motionSpec_loopEnabled: typeof loopEnabled;
+declare const motionSpec_scaledMs: typeof scaledMs;
+declare const motionSpec_setMotionDurationScale: typeof setMotionDurationScale;
+declare const motionSpec_stateChangeDuration: typeof stateChangeDuration;
+declare const motionSpec_statusCopyDelay: typeof statusCopyDelay;
+declare namespace motionSpec {
+  export { motionSpec_BUTTON_PRESS_SCALE as BUTTON_PRESS_SCALE, motionSpec_BUTTON_PRESS_SPRING as BUTTON_PRESS_SPRING, motionSpec_CARD_ENTER_MS as CARD_ENTER_MS, motionSpec_CARD_ENTER_SCALE_FROM as CARD_ENTER_SCALE_FROM, motionSpec_CARD_EXIT_LEAD_MS as CARD_EXIT_LEAD_MS, motionSpec_CARD_EXIT_MS as CARD_EXIT_MS, motionSpec_CARD_SLIDE_PX as CARD_SLIDE_PX, motionSpec_CARD_SPRING as CARD_SPRING, motionSpec_CHECK_SCALE_FROM as CHECK_SCALE_FROM, motionSpec_CHECK_SPRING as CHECK_SPRING, motionSpec_CHIP_FILL_MS as CHIP_FILL_MS, motionSpec_CHIP_PRESS_SCALE as CHIP_PRESS_SCALE, motionSpec_DURATION_BASE_MS as DURATION_BASE_MS, motionSpec_DURATION_FAST_MS as DURATION_FAST_MS, motionSpec_DURATION_SLOW_MS as DURATION_SLOW_MS, type motionSpec_EntranceSpec as EntranceSpec, motionSpec_INTERSTITIAL_CHECK_DELAY_MS as INTERSTITIAL_CHECK_DELAY_MS, motionSpec_INTERSTITIAL_CHECK_SCALE_FROM as INTERSTITIAL_CHECK_SCALE_FROM, motionSpec_INTERSTITIAL_HEAD_MS as INTERSTITIAL_HEAD_MS, motionSpec_INTERSTITIAL_HEAD_STAGGER_MS as INTERSTITIAL_HEAD_STAGGER_MS, motionSpec_INTERSTITIAL_ITEM_BASE_DELAY_MS as INTERSTITIAL_ITEM_BASE_DELAY_MS, motionSpec_INTERSTITIAL_ITEM_MS as INTERSTITIAL_ITEM_MS, motionSpec_INTERSTITIAL_ITEM_STAGGER_MS as INTERSTITIAL_ITEM_STAGGER_MS, motionSpec_LOADER_HANDOFF_FADE_MS as LOADER_HANDOFF_FADE_MS, motionSpec_LOADER_ORBIT_MS as LOADER_ORBIT_MS, motionSpec_LOADER_PULSE_MIN_OPACITY as LOADER_PULSE_MIN_OPACITY, motionSpec_LOADER_PULSE_MS as LOADER_PULSE_MS, motionSpec_PRESS_SPRING as PRESS_SPRING, motionSpec_PROGRESS_MS as PROGRESS_MS, motionSpec_REDUCED_FADE_MS as REDUCED_FADE_MS, motionSpec_REDUCED_PRESS_OPACITY as REDUCED_PRESS_OPACITY, motionSpec_ROW_PRESS_SCALE as ROW_PRESS_SCALE, motionSpec_SELECT_FILL_MS as SELECT_FILL_MS, motionSpec_SKELETON_DELAY_MS as SKELETON_DELAY_MS, motionSpec_SKELETON_MIN_OPACITY as SKELETON_MIN_OPACITY, motionSpec_SKELETON_PULSE_MS as SKELETON_PULSE_MS, motionSpec_STATUS_BURST_MS as STATUS_BURST_MS, motionSpec_STATUS_BURST_OPACITY_FROM as STATUS_BURST_OPACITY_FROM, motionSpec_STATUS_BURST_SCALE_FROM as STATUS_BURST_SCALE_FROM, motionSpec_STATUS_BURST_SCALE_TO as STATUS_BURST_SCALE_TO, motionSpec_STATUS_COPY_BASE_DELAY_MS as STATUS_COPY_BASE_DELAY_MS, motionSpec_STATUS_COPY_MS as STATUS_COPY_MS, motionSpec_STATUS_COPY_STAGGER_MS as STATUS_COPY_STAGGER_MS, motionSpec_STATUS_POP_SCALE_FROM as STATUS_POP_SCALE_FROM, motionSpec_STATUS_POP_SPRING as STATUS_POP_SPRING, motionSpec_WIRE_BEZIER as WIRE_BEZIER, motionSpec_entranceSpec as entranceSpec, motionSpec_getMotionDurationScale as getMotionDurationScale, motionSpec_interstitialCheckDelay as interstitialCheckDelay, motionSpec_interstitialItemDelay as interstitialItemDelay, motionSpec_loopEnabled as loopEnabled, motionSpec_scaledMs as scaledMs, motionSpec_setMotionDurationScale as setMotionDurationScale, motionSpec_stateChangeDuration as stateChangeDuration, motionSpec_statusCopyDelay as statusCopyDelay };
+}
+
+declare const ChipSelectCard: WireAIComponent;
+
+declare const TextInputCard: WireAIComponent;
+
+declare const SelectionCard: WireAIComponent;
+
+declare const StatusCard: WireAIComponent;
+
+declare const NumberStepperCard: WireAIComponent;
+
+declare const InterstitialCard: WireAIComponent;
+
+/**
+ * onboardingComponents — the constrained set of themed cards the kit registers
+ * with the SDK. The backend's `allowed_components` must be a subset of these
+ * names so every card the agent asks for has a themed renderer.
+ */
+
+declare const onboardingComponents: WireAIComponent[];
+
+/**
+ * deviceContext — collect a small, privacy-label-neutral snapshot of the device so
+ * onboarding analytics can segment the funnel (platform / form factor / locale) WITHOUT
+ * adding a single dependency to the kit or changing a host app's App Privacy / Data Safety
+ * declarations.
+ *
+ * HARD RULE (why this file has no imports beyond React Native built-ins):
+ *   The kit stays dependency-free. Everything here comes from `Platform`, `Dimensions`,
+ *   `I18nManager`, and the standard `Intl` global. There are NO advertising IDs, NO
+ *   `getUniqueId`/IDFA/GAID/fingerprinting APIs, and nothing that would require a new
+ *   privacy-label entry. A host can adopt this without touching its store declarations.
+ *
+ * DEFENSIVE BY DESIGN: `collectDeviceContext()` never throws. Every read is guarded and
+ * a missing/unavailable field is simply omitted (Hermes may ship without full `Intl`,
+ * `Platform.constants` differs per OS and RN version, etc.). Analytics must never be able
+ * to break onboarding.
+ */
+
+/** Coarse device class. iOS uses the reported interface idiom; else a screen-size heuristic. */
+type DeviceFormFactor = "phone" | "tablet";
+/**
+ * A privacy-label-neutral device snapshot. ALL fields except `platform` are optional and are
+ * omitted when unavailable. Nothing here identifies a user or device uniquely.
+ */
+type DeviceContext = {
+    /** `Platform.OS` — "ios" | "android" | "windows" | "macos" | "web". Always present. */
+    platform: typeof Platform.OS;
+    /** OS version string (iOS `osVersion`/`Platform.Version`, Android `Release`). */
+    osVersion?: string;
+    /** Android device brand (e.g. "samsung"). Android only. */
+    brand?: string;
+    /** Android device model (e.g. "SM-G991B"). Android only. */
+    model?: string;
+    /** iOS interface idiom ("phone" | "pad" | …), when reported. iOS only. */
+    interfaceIdiom?: string;
+    /** Derived device class. */
+    formFactor?: DeviceFormFactor;
+    /** `Dimensions.get('screen')` width in dp. */
+    screenWidth?: number;
+    /** `Dimensions.get('screen')` height in dp. */
+    screenHeight?: number;
+    /** Screen pixel density (`scale`). */
+    screenScale?: number;
+    /** Right-to-left layout (`I18nManager.isRTL`). */
+    isRTL?: boolean;
+    /** Resolved locale (e.g. "en-US"), from `Intl` when available. */
+    locale?: string;
+    /** IANA time zone (e.g. "Europe/Berlin"), from `Intl` when available. */
+    timeZone?: string;
+    /**
+     * Host app version (e.g. "1.4.2). HOST-INJECTED — NOT collected here. `WireOnboarding`
+     * merges `config.appVersion` into the snapshot; `collectDeviceContext()` never sets it.
+     * Hosts typically pass it from `expo-constants` (the kit itself adds no dependency).
+     */
+    appVersion?: string;
+};
+/**
+ * Collect the device snapshot. Pure, synchronous, and never throws — call it once per
+ * onboarding session. Missing fields are omitted rather than sent as null/undefined so the
+ * payload (and the server's stored dict) stays compact.
+ */
+declare const collectDeviceContext: () => DeviceContext;
+
+/**
+ * reportClientEvent — forward DEVICE-ONLY onboarding events to the Wire AI analytics
+ * backend (`POST {serverUrl}/v1/events`), completing the funnel for events the server
+ * can't observe on its own.
+ *
+ * The backend already records the server-observable funnel during the A2A flow
+ * (`session_started`, `screen_shown`, `answer_submitted`, `completed`, `llm_fallback`,
+ * and even `screen_skipped` — it derives that from the kit's skip sentinel). The one
+ * event no server request can capture is `dropped`: the user closing the app / unmounting
+ * the flow without finishing. That's what this reporter is for.
+ *
+ * Contract (server: routers/onboarding.py → analytics/events.py):
+ *   POST {serverUrl}/v1/events
+ *   Authorization: Bearer {apiKey}
+ *   { "events": [ { event_type, session_id, screen_index?, component?, question_key?,
+ *                   latency_ms?, meta?, device?, user_context? } ] }
+ * The server fills `app_id` + `environment` from the resolving key (never send app_id),
+ * and silently skips malformed events — one bad payload never fails the batch.
+ *
+ * ⚠️ Correlation: `session_id` MUST equal the A2A `contextId` the server uses to key the
+ * server-side events, or the funnel report (which groups by `session_id`) treats this as a
+ * phantom session. See `makeSessionId` + WireOnboarding for how the kit seeds it.
+ *
+ * Fire-and-forget: this never throws into the UI and never awaits — analytics must never
+ * be able to break onboarding.
+ */
+
+/** Event types a CLIENT may report. The rest of the funnel is server-side; sending those
+ *  here would double-count. `screen_skipped` is included for completeness, but the kit does
+ *  NOT emit it — the backend already derives it from the skip sentinel (see OnboardingFlow).
+ *  `client_fallback` is emitted by the kit when the AI flow degrades to the static fallback,
+ *  so the dashboard's fallback-rate counts the whole-flow case (distinct from the server's
+ *  per-turn `llm_fallback`). The server back-fills a `session_started` for it if unseen.
+ *  This is the SINGLE fallback signal — hosts must NOT also report their own.
+ *  `identify` binds the host's opaque `user_id` to this `session_id` (late binding — the user
+ *  registered during/after onboarding). It carries no funnel weight; the server maps the
+ *  session to the user and back-fills a `session_started` if it never saw the session. */
+type ClientEventType = "screen_skipped" | "dropped" | "client_fallback" | "identify";
+/** One client-reported event. Mirrors the server's `OnboardingEvent` (client-settable fields). */
+type ClientEvent = {
+    event_type: ClientEventType;
+    /** Must match the server-side A2A contextId for this onboarding (see makeSessionId). */
+    session_id: string;
+    /** 0-based index of the screen the event refers to (matches server `screen_shown`). */
+    screen_index?: number;
+    component?: string;
+    question_key?: string;
+    latency_ms?: number;
+    /** JSON-stringified extras; the server stores it verbatim. */
+    meta?: string;
+    /**
+     * Privacy-label-neutral device snapshot (platform / form factor / locale / host appVersion).
+     * Sent as an object; the server sanitizes + persists it and derives a coarse country. Old
+     * servers ignore this unknown field — fully backward compatible. See device/deviceContext.ts.
+     */
+    device?: DeviceContext;
+    /**
+     * Host-injected, non-PII context (signup method, referral, plan, hashed user id). Old servers
+     * ignore it. MUST NOT contain PII like raw emails — see the README `userContext` section.
+     */
+    user_context?: Record<string, string | number | boolean>;
+    /**
+     * The host's OPAQUE PSEUDONYMOUS user id (their internal id, NOT an email/name). Required on
+     * `identify`, optional (rides along) on other events. Trimmed + capped at 128 chars host-side.
+     * Lets the backend reconcile onboarding sessions to real users. Old servers ignore it.
+     */
+    user_id?: string;
+};
+/** Where to POST. Derived from `WireOnboardingConfig` (`serverUrl` + `apiKey`). */
+type ClientEventTarget = {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+    serverUrl: string;
+    /** Tenant API key; sent as `Authorization: Bearer`. */
+    apiKey: string;
+};
+/**
+ * A unique-per-onboarding session id. Used both as the client event `session_id` AND as the
+ * seed the kit forwards to the backend so the SERVER adopts it as the A2A `contextId` — making
+ * client and server agree (see WireOnboarding + the SDK-correlation note in the kit docs).
+ * No crypto dependency: timestamp + random is collision-safe for a single device's onboarding.
+ */
+declare const makeSessionId: () => string;
+/**
+ * POST one or more client events, fire-and-forget. A missing/invalid target, a build error,
+ * a missing `fetch`, or a network failure is swallowed — the call returns immediately and the
+ * request (if any) runs in the background.
+ */
+declare const reportClientEvents: (target: ClientEventTarget | undefined, events: ClientEvent[]) => void;
+/** Convenience single-event wrapper around {@link reportClientEvents}. */
+declare const reportClientEvent: (target: ClientEventTarget | undefined, event: ClientEvent) => void;
+
+/**
+ * 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.
+ */
+
+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__default.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;
+};
+declare const OnboardingFlow: React__default.FC<OnboardingFlowProps>;
+
+/**
+ * deriveAnswers — read the user's structured choices off the thread.
+ *
+ * The cards send answers back as natural-language strings (the SDK's
+ * useWireAIAction wraps them, e.g. `I selected: ["Food","Travel"]`,
+ * `My answer is: "Casablanca"`). We pair each rendered question with the reply
+ * that followed it and key the answer by the backend's progress `key` when
+ * present (so `username`/`interests`/`city` come back under their real keys),
+ * else by the question text. No second LLM call — the values ARE the data.
+ */
+
+declare const deriveAnswers: (messages: Message[]) => Record<string, unknown>;
+
+/**
+ * readProgress — pull the backend's progress metadata off a render response.
+ *
+ * The managed backend rides `{ step, total, key }` inside the Wire envelope's
+ * `props.progress`. That's the only field that survives the SDK's strict client
+ * validation (extra top-level keys get folded into props; the card's own schema
+ * silently strips `progress` from its render props, but it stays readable on
+ * `response.props`). All fields are optional so an older backend just falls back
+ * to the local counter.
+ */
+
+type PartialProgress = {
+    step?: number;
+    total?: number;
+    key?: string;
+    skippable?: boolean;
+};
+declare const readProgress: (response?: WireAIResponse) => PartialProgress;
+
+/**
+ * Resolve the tenant's feature flags. Attempts the network once; on ANY failure returns the
+ * cached value (any age), else the all-on defaults. On success, persists the fresh value to the
+ * cache (fire-and-forget) and returns it. Never throws.
+ *
+ *   const flags = await fetchWireFeatures({ serverUrl, apiKey, appId, storage });
+ *   if (!flags.coachmarks.enabled) { /* skip the tour * / }
+ */
+declare const fetchWireFeatures: (config?: WireFeaturesConfig) => Promise<WireFeatures>;
+
+declare const useWireFeatures: (config?: WireFeaturesConfig) => WireFeatures;
+
+/**
+ * WireFeaturesProvider + useResolvedFeatures — the OPTIONAL one-fetch-serves-all-modules layer.
+ *
+ * Mount `WireFeaturesProvider` once near your app root with the tenant `config` and it fetches the
+ * flags ONCE; every gated surface below it (coachmarks / showcase / reviews) reads the same
+ * resolved value from context instead of each fetching its own. It is entirely optional: with no
+ * provider, every surface falls back to its own lazy fetch (when given a config) or to the all-on
+ * defaults, so modules work with zero setup and a host that never adopts flags is unchanged.
+ *
+ * NOTE on the built npm subpaths: React context is shared across the kit's subpath entries in the
+ * SOURCE-consumption path (the monorepo apps) and in this test suite — one module instance, one
+ * context. If you consume the built `wireai-onboarding/*` subpaths as separate bundles, pass the
+ * resolved flags (or a `featuresConfig`) to each surface explicitly instead of relying on context.
+ */
+
+interface WireFeaturesProviderProps {
+    /** Tenant creds (+ optional storage) to fetch the flags once for the whole tree. */
+    config?: WireFeaturesConfig;
+    /**
+     * Pre-resolved flags to provide directly instead of fetching (e.g. you already have them, or
+     * you drive them from your own remote-config). Takes precedence over `config`.
+     */
+    flags?: WireFeatures;
+    children: React__default.ReactNode;
+}
+/**
+ * Fetch (or accept) the flags once and broadcast them to descendants. The provider VALUE is
+ * memoized (performance rule #6) so a fresh object each render doesn't re-render every consumer.
+ */
+declare const WireFeaturesProvider: React__default.FC<WireFeaturesProviderProps>;
+/** Raw context read — `null` when no `WireFeaturesProvider` is mounted above. */
+declare const useWireFeaturesContext: () => WireFeatures | null;
+/** Options for `useResolvedFeatures`: an explicit override and/or a lazy-fetch config. */
+interface ResolveFeaturesOptions {
+    /** Explicit flags — win over everything (a surface's own `features` prop). */
+    flags?: WireFeatures;
+    /** Lazy-fetch config, used ONLY when there is no explicit `flags` and no provider above. */
+    config?: WireFeaturesConfig;
+}
+/**
+ * The resolution every gated surface uses. Precedence:
+ *   1. explicit `options.flags` (a surface's own prop)  →
+ *   2. the nearest `WireFeaturesProvider` (context)     →
+ *   3. a lazy fetch from `options.config` (serverUrl + apiKey)  →
+ *   4. the all-on defaults.
+ * Always fail-open, always a stable reference for a given value (so it's safe in effect deps).
+ */
+declare const useResolvedFeatures: (options?: ResolveFeaturesOptions) => WireFeatures;
+
+/**
+ * The fail-open defaults + a tolerant parser for the server's flags payload.
+ *
+ * THE CONTRACT: fail-open, never fail-dark. An absent server object, a missing module key, a
+ * malformed value, or an unreachable endpoint must resolve to the MOST PERMISSIVE state — every
+ * module ON, onboarding `ai` — so a control-plane outage can only ever be more permissive than
+ * the dashboard intends. It can never dark a tenant's activation. Matches the server's own
+ * documented fail-open default (FEATURES.md: "local defaults — every module on, onboarding ai").
+ */
+
+/**
+ * ALL ON, onboarding `ai`. Frozen + module-level so its reference is stable across every call
+ * (consumers that list resolved flags in an effect dep array never loop on a fresh identity).
+ */
+declare const defaultWireFeatures: WireFeatures;
+/**
+ * Narrow the server's (untrusted) JSON to a complete `WireFeatures`. Every field is filled with
+ * its fail-open default when the server omits it or sends the wrong type, so a partial or
+ * malformed payload degrades PERMISSIVELY rather than throwing. A non-object input (null, array,
+ * string) → the full defaults. Never throws.
+ */
+declare const parseWireFeatures: (raw: unknown) => WireFeatures;
+/** Value-equality of two resolved flags — lets the hook hold a stable reference across churn. */
+declare const featuresEqual: (a: WireFeatures, b: WireFeatures) => boolean;
+
+/**
+ * TTL for a cached flags entry, aligned to the server's `Cache-Control: private, max-age=300`.
+ * A cache younger than this is "fresh"; older is "stale" (still served on a fetch error).
+ */
+declare const DEFAULT_FEATURES_TTL_MS = 300000;
+/** Storage key for a tenant's cached flags, e.g. `wireai:features:myelino`. */
+declare const featuresCacheKey: (appId?: string) => string;
+/** A cached flags entry: the resolved flags + the epoch-ms they were fetched. */
+interface CachedFeatures {
+    features: WireFeatures;
+    /** Age of the entry in ms at read time. */
+    ageMs: number;
+}
+/** Whether a cache entry is still within the TTL (server max-age aligned). */
+declare const isFeaturesFresh: (ageMs: number, ttlMs?: number) => boolean;
+/**
+ * Read the cached flags for `key`, or `undefined` when absent/corrupt/timed-out. Returns the
+ * value AND its age so a caller can apply a TTL (fresh) or ignore it (stale-while-error). Never
+ * throws; never hangs past the read timeout. The stored value is re-parsed through
+ * `parseWireFeatures`, so a partially-corrupt entry still degrades fail-open.
+ */
+declare const readCachedFeatures: (storage: WireOnboardingStorage, key: string) => Promise<CachedFeatures | undefined>;
+/** Persist `{ features, ts }` under `key` — fire-and-forget, all errors swallowed. */
+declare const writeCachedFeatures: (storage: WireOnboardingStorage, key: string, features: WireFeatures) => void;
+
+/**
+ * wireConfigFromEnv — stop re-authoring env gating in every app. Reads the Wire AI
+ * tenant key + server URL from the standard Expo public env vars and returns a
+ * ready `WireOnboardingConfig`, or `null` when the key/URL are missing (so a host
+ * can fall through to a static onboarding without writing the `if (!key)` itself).
+ *
+ *   EXPO_PUBLIC_WIREAI_API_KEY=...      (required)
+ *   EXPO_PUBLIC_WIREAI_SERVER_URL=...   (required)
+ *
+ *   const config = wireConfigFromEnv({ appId: "morrow" });
+ *   if (!config) return <StaticOnboarding />;
+ *   return <WireOnboarding config={config} ... />;
+ *
+ * `appId` defaults to `EXPO_PUBLIC_WIREAI_APP_ID` (or "default"); pass overrides to
+ * set `appId`/`metadata` or to substitute the key/URL programmatically.
+ */
+
+type WireConfigOverrides = Partial<WireOnboardingConfig>;
+declare const wireConfigFromEnv: (overrides?: WireConfigOverrides) => WireOnboardingConfig | null;
+
+type OnboardingFlagOptions = {
+    /**
+     * Optional remote kill-switch the app already read (Firebase/LD/etc.). When `false`, it
+     * disables onboarding even though transport is present. Omit (or `true`) to leave it on.
+     */
+    remote?: boolean;
+    /**
+     * Config overrides forwarded to `wireConfigFromEnv` for the transport-present check
+     * (e.g. a programmatic `apiKey`/`serverUrl`). Usually omitted.
+     */
+    config?: WireConfigOverrides;
+};
+declare const isOnboardingEnabled: (opts?: OnboardingFlagOptions) => boolean;
+
+/**
+ * Canonical analytics names for the onboarding funnel. The kit already emits a typed
+ * `OnboardingEvent` (`started | turn | error | retry | fallback`) — but one app logged them as
+ * `onboarding_*` and another as `AI_ONBOARDING_*`, so the same funnel reads differently per app.
+ * This maps the kit event to ONE canonical `wire_onboarding_*` name + params, and the app logs
+ * it through whatever transport it already has (Firebase, Amplitude, console). The app still
+ * owns the logger; only the NAMES are standardized.
+ *
+ *   <WireOnboarding
+ *     onEvent={(e) => { const a = toAnalyticsEvent(e); logEvent(a.name, a.params); }}
+ *     onComplete={(r) => { logEvent(WIRE_ONBOARDING_EVENTS.completed, { answers: Object.keys(r.answers).length }); persist(r); }}
+ *   />
+ *
+ * `completed` has no kit `OnboardingEvent` (the kit signals completion via `onComplete`, not
+ * `onEvent`) — the app logs it explicitly on `onComplete` using the constant below, so the
+ * funnel name stays canonical.
+ */
+
+declare const WIRE_ONBOARDING_EVENTS: {
+    readonly started: "wire_onboarding_started";
+    /** A persisted session was restored after an app kill (fires instead of `started`). */
+    readonly resumed: "wire_onboarding_resumed";
+    readonly turn: "wire_onboarding_turn";
+    readonly error: "wire_onboarding_error";
+    readonly retry: "wire_onboarding_retry";
+    readonly fallback: "wire_onboarding_fallback";
+    /** Logged by the host on `onComplete` (no matching kit `OnboardingEvent`). */
+    readonly completed: "wire_onboarding_completed";
+};
+type WireOnboardingEventName = (typeof WIRE_ONBOARDING_EVENTS)[keyof typeof WIRE_ONBOARDING_EVENTS];
+type AnalyticsEvent = {
+    name: WireOnboardingEventName;
+    params?: Record<string, unknown>;
+};
+/**
+ * Map a kit `OnboardingEvent` to its canonical `{ name, params }`. Exhaustive over the union
+ * (the `never` default makes a new event type a compile error here — intentional).
+ */
+declare const toAnalyticsEvent: (event: OnboardingEvent) => AnalyticsEvent;
+
+/**
+ * attribution — forward install/ad attribution to the onboarding agent so it can tailor the
+ * first question by acquisition source (e.g. a paid-campaign install vs an organic one). The
+ * channel already exists: `WireOnboardingConfig.metadata` is merged into every A2A request by
+ * `WireOnboarding`. No production app populated it before; this gives every app a standard shape.
+ *
+ * The app reads its raw attribution (AppsFlyer / Branch / deferred deep link — an app concern,
+ * not the kit's) and passes the normalized result as `metadata`:
+ *
+ *   const config = wireConfigFromEnv({
+ *     appId: "morrow-self",
+ *     metadata: attributionMetadata({ source: conv.mediaSource, campaign: conv.campaign, isOrganic: conv.isOrganic }),
+ *   });
+ *
+ * The backend sees `metadata.attribution = { source, campaign, ... }`.
+ */
+/** Normalized acquisition attribution. All fields optional — pass what the SDK gives you. */
+type OnboardingAttribution = {
+    /** Media source / network, e.g. "appsflyer", "branch", "organic". */
+    source?: string;
+    campaign?: string;
+    adset?: string;
+    ad?: string;
+    /** Deferred deep-link slug / path that routed the install. */
+    deepLink?: string;
+    isFirstLaunch?: boolean;
+    isOrganic?: boolean;
+    /** Escape hatch for SDK-specific fields not covered above. */
+    raw?: Record<string, unknown>;
+};
+/**
+ * Wrap attribution into the `{ attribution: {...} }` metadata the agent reads. Drops `undefined`
+ * fields so the request payload stays compact. Returns `{ attribution: {} }` for empty input
+ * (still a valid, harmless metadata object).
+ */
+declare const attributionMetadata: (a: OnboardingAttribution) => {
+    attribution: Record<string, unknown>;
+};
+
+/** Max accepted user-id length. Longer strings are truncated (never rejected). Keep in sync
+ *  with the server's `USER_ID_MAX_LENGTH` (analytics/events.py). */
+declare const USER_ID_MAX_LENGTH = 128;
+/**
+ * Normalize a host-supplied user id: trim, drop empty, and cap at {@link USER_ID_MAX_LENGTH}.
+ * Returns `undefined` for a missing/blank/non-string value so callers can `if (id)`-gate.
+ * PII is a host concern — this only bounds length, it does not (and cannot) detect an email.
+ */
+declare const sanitizeUserId: (raw: unknown) => string | undefined;
+/** Options for {@link identifyOnboarding}. */
+type IdentifyOnboardingOptions = {
+    /** Tenant transport, same shape as `WireOnboardingConfig` (only these two fields are used). */
+    config: {
+        serverUrl: string;
+        apiKey: string;
+    };
+    /** The host's opaque user id to bind. Trimmed + capped; NO PII. */
+    userId: string;
+    /**
+     * The onboarding session id to bind to (the A2A contextId) — the `contextId` field carried on
+     * the `started`/`resumed` `onEvent`. Pass this when you captured it there. Required after the
+     * flow COMPLETED, since completion clears the persisted session. Wins over the storage lookup.
+     */
+    contextId?: string;
+    /**
+     * The SAME host storage you passed to `<WireOnboarding storage={…} />`. When `contextId` is
+     * omitted, the helper reads the persisted contextId from it (works while the session is still
+     * persisted — i.e. dropped or mid-flow, before completion clears it).
+     */
+    storage?: WireOnboardingStorage;
+    /** App id, to derive the default storage key `wireai:session:<appId>` when reading from storage. */
+    appId?: string;
+    /** Storage key override — pass the same `persistKey` you gave `<WireOnboarding>`, if any. */
+    persistKey?: string;
+};
+/**
+ * Attach a host user id to an onboarding session AFTER the fact (post-registration), by sending
+ * an `identify` client event to `/v1/events`. Resolves the contextId from an explicit
+ * `contextId` or, failing that, from the persisted session in the host `storage`.
+ *
+ * Fire-and-forget under the hood (never throws, never blocks onboarding). Resolves to `true`
+ * when an identify event was dispatched, `false` when it couldn't (no user id, no server url,
+ * or no resolvable contextId).
+ */
+declare const identifyOnboarding: (opts: IdentifyOnboardingOptions) => Promise<boolean>;
+
+/**
+ * reportSessionStart — the ONE standard emitter for "the user opened the app again".
+ *
+ * Every app-open posts a single `app.session_started` event to the Wire analytics backend
+ * (`POST {serverUrl}/v1/events`). That event does two jobs at once, with ZERO server changes:
+ *
+ *   1. SESSION MAPPING. It carries the host's opaque `userId` + a stable `deviceKey`, so the
+ *      backend can group a user's (or a pre-auth device's) opens over time — "when did this
+ *      user last use the app, and how many times". The device_key links the pre-auth opens to
+ *      the user once `userId` arrives (here or via `identifyOnboarding`).
+ *   2. QUESTIONNAIRE / RETENTION FIRING. It flows into the SAME event stream the server's
+ *      decision engines read, so a questionnaire trigger `{event:"app.session_started", min_count:N}`
+ *      (matched within a session) or a questionnaire `min_sessions:N` (distinct device sessions)
+ *      fires on the user's Nth open with no new server endpoint.
+ *
+ * WIRE CONTRACT (server: analytics/events.py + routers/onboarding.py `POST /v1/events`):
+ *   The event is stored as `event_type='app_event'`, `question_key='app.session_started'` — the
+ *   generic app.* namespace the reviews wave shipped. The server's `_event_name(ev)` returns the
+ *   `question_key` for an `app_event`, which is what a trigger's `event` string matches. We do NOT
+ *   send `event_type:'app.session_started'` — that name is not in the server's EVENT_TYPES and
+ *   would be rejected. `device_key` rides in the non-PII `user_context` bucket, where the server's
+ *   `_event_device_key(ev)` reads it to group a device's sessions. `app_id` + `environment` are
+ *   filled server-side from the resolving key (never sent here).
+ *
+ * SESSION ID DISTINCTION (important): the `session_id` on this event is a PER-OPEN id (a fresh
+ * `makeSessionId()` each app-open) — it is NOT the onboarding A2A `contextId`. Onboarding runs
+ * ONCE (first launch) and owns its own context id; session-start fires on EVERY open, so it needs
+ * its own per-open id. Grouping over time is done by `device_key`/`user_id`, not by session_id.
+ *
+ * Fire-and-forget: like every analytics path in the kit, this never throws into the UI, never
+ * awaits, and swallows a missing target / bad URL / missing fetch / network error. Analytics must
+ * never be able to break the app.
+ */
+
+/** The canonical event name for an app-open. A trigger keys off this exact string. */
+declare const SESSION_STARTED_EVENT: "app.session_started";
+/** Options for {@link reportSessionStart}. Everything except `target` is optional so a pre-auth
+ *  open (no user yet) is a valid, device-only session. */
+interface ReportSessionStartOptions {
+    /** Where to POST — the tenant transport (`serverUrl` + `apiKey`), same as `WireOnboardingConfig`. */
+    target: ClientEventTarget | undefined;
+    /**
+     * The per-open session id. Defaults to a fresh `makeSessionId()`. Pass your own ONLY to
+     * dedupe re-renders of the same open (the {@link useSessionStart} hook does exactly that).
+     * This is NOT the onboarding contextId — see the file header.
+     */
+    sessionId?: string;
+    /** The host's OPAQUE pseudonymous user id (their internal id, NOT an email/PII). Sanitized +
+     *  capped here; omitted on a pre-auth open (device-only session). */
+    userId?: string;
+    /** A stable, non-PII device id the host owns. Rides in `user_context.device_key` so the server
+     *  groups this device's sessions (the min_sessions signal). Host-supplied, same as reviews. */
+    deviceKey?: string;
+    /** The host's own local open-counter value for this open (1 on the first ever open). Drives the
+     *  `returning` flag and lets analytics read "Nth session" without server-side counting. */
+    sessionCount?: number;
+    /** Host app version (e.g. "1.4.2"), if cheaply available. Segments retention by release. */
+    appVersion?: string;
+    /** Platform string (e.g. "ios"), if cheaply available. */
+    platform?: string;
+    /** An optional richer device snapshot (from `collectDeviceContext()`); the hook fills this. */
+    device?: DeviceContext;
+    /** Small non-PII extras, stored as a JSON string in the event `meta`. */
+    meta?: Record<string, unknown>;
+    /** Set `false` to bypass the once-per-open guard (default on). See {@link resetSessionStartGuard}. */
+    once?: boolean;
+}
+/** Test-only: forget every emitted session id so a unit test starts from a clean guard. */
+declare const resetSessionStartGuard: () => void;
+/**
+ * Emit one `app.session_started` event for this app-open. Fire-and-forget; returns immediately.
+ * Idempotent per `sessionId` (unless `once:false`) so a re-render can never double-fire.
+ */
+declare const reportSessionStart: (opts: ReportSessionStartOptions) => void;
+
+/** A foreground after at least this long in the background counts as a NEW app-open (30 min). */
+declare const BACKGROUND_SESSION_MS: number;
+/** Tenant transport + optional host app version. Same creds as `WireOnboardingConfig`. */
+interface SessionStartConfig {
+    /** Base server URL (same as `WireOnboardingConfig.serverUrl`); `/v1/events` is appended. */
+    serverUrl?: string;
+    /** Tenant API key; sent as `Authorization: Bearer`. */
+    apiKey?: string;
+    /** Host app version (e.g. "1.4.2"), forwarded for release segmentation. Optional. */
+    appVersion?: string;
+}
+/** Per-open identity the host supplies. All optional: a pre-auth open is device-only. */
+interface UseSessionStartOptions {
+    /** The host's opaque pseudonymous user id (NOT PII). Omitted before the user authenticates. */
+    userId?: string;
+    /** The host's local open-counter value for this open. Drives `returning` + "Nth session". */
+    sessionCount?: number;
+    /** A stable, non-PII device id the host owns. Groups this device's sessions server-side. */
+    deviceKey?: string;
+    /** Small non-PII extras forwarded on the event `meta`. */
+    meta?: Record<string, unknown>;
+    /** Set `false` to disable firing (e.g. behind a consent gate). Default enabled. */
+    enabled?: boolean;
+}
+/**
+ * Fire `app.session_started` on mount and on every real foreground-after-background. Returns
+ * nothing — it is a side-effecting hook. Safe to call with inline options (values are read
+ * through a ref, so changing `userId`/`sessionCount` never re-fires a session).
+ */
+declare const useSessionStart: (config: SessionStartConfig | undefined, options?: UseSessionStartOptions) => void;
+
+export { type AnalyticsEvent, AnimatedSparkle, BACKGROUND_SESSION_MS, type CachedFeatures, CardHandoff, type CardHandoffProps, type CardHandoffVariant, ChipSelectCard, type ClientEvent, type ClientEventTarget, type ClientEventType, CompletionView, DEFAULT_FEATURES_TTL_MS, DemoOnboarding, type DemoOnboardingProps, type DeviceContext, type DeviceFormFactor, DoneBlock, ErrorBlock, type IdentifyOnboardingOptions, IllustrationProvider, type IllustrationRegistry, InterstitialCard, LoadingBlock, LoadingScreen, NumberStepperCard, type OnboardingAttribution, Button as OnboardingButton, type OnboardingCopy, type OnboardingEvent, type OnboardingFlagOptions, OnboardingFlow, type OnboardingProgress, type OnboardingResult, OnboardingScaffold, OnboardingTheme, OnboardingThemeProvider, type ReportSessionStartOptions, type ResolveFeaturesOptions, SESSION_STARTED_EVENT, SelectionCard, type SessionStartConfig, StatusCard, StepProgress, type StepValidator, TextInputCard, type ThemeFromBrandInput, USER_ID_MAX_LENGTH, type UseSessionStartOptions, WIRE_ONBOARDING_EVENTS, type WireConfigOverrides, WireFeatures, WireFeaturesConfig, WireFeaturesProvider, type WireFeaturesProviderProps, WireOnboarding, type WireOnboardingConfig, type WireOnboardingEventName, type WireOnboardingProps, WireOnboardingStorage, attributionMetadata, collectDeviceContext, defaultIllustrations, defaultOnboardingTheme, defaultWireFeatures, deriveAnswers, featuresCacheKey, featuresEqual, fetchWireFeatures, identifyOnboarding, isFeaturesFresh, isOnboardingEnabled, makeSessionId, mergeTheme, motionSpec, onboardingComponents, parseWireFeatures, readCachedFeatures, readProgress, reportClientEvent, reportClientEvents, reportSessionStart, resetSessionStartGuard, sanitizeUserId, themeFromBrand, toAnalyticsEvent, useIllustration, useOnboardingTheme, useReducedMotion, useResolvedFeatures, useSessionStart, useWireFeatures, useWireFeaturesContext, wireConfigFromEnv, writeCachedFeatures };