@userflow-tech/react-native 0.1.1 → 0.3.0

package/lib/typescript/module/src/hostAppVersion.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Read the host app's native marketing version (store version), not the
+ * SDK package version. React Native does not expose the store version on
+ * `Platform`; Expo hosts may use optional expo modules; bare RN reads
+ * `NativeModules.RNDeviceInfo` constants from the bundled device-info native
+ * module (after autolink + rebuild). The OS name is `Platform.OS`.
+ *
+ * Do not `require('react-native-device-info')` — that package throws at import
+ * when the native module is missing, and Metro/Hermes may surface it as uncaught
+ * even inside try/catch.
+ */
+export type HostAppVersionSource = 'expo-application' | 'expo-constants' | 'react-native-device-info' | 'init-override';
+export interface HostAppVersion {
+    version: string;
+    build?: string;
+    source: HostAppVersionSource;
+}
+export interface RNDeviceInfoConstants {
+    appVersion?: string;
+    buildNumber?: string;
+}
+/** Visible for tests: map an `expo-application` module shape to a version. */
+export declare function readExpoApplication(mod: unknown): HostAppVersion | null;
+/** Visible for tests: map an `expo-constants` module shape to a version. */
+export declare function readExpoConstants(mod: unknown): HostAppVersion | null;
+/** Visible for tests: map linked RNDeviceInfo native constants to a version. */
+export declare function readDeviceInfoFromNativeModule(module: RNDeviceInfoConstants | null | undefined): HostAppVersion | null;
+/** Visible for tests: first non-null reader wins (Expo modules, then RNDeviceInfo). */
+export declare function resolveHostAppVersionFromSources(sources: {
+    expoApplication?: unknown;
+    expoConstants?: unknown;
+    deviceInfoNative?: RNDeviceInfoConstants | null;
+}): HostAppVersion | null;
+export declare function resolveHostAppVersion(): HostAppVersion | null;
+export interface HostAppVersionInitOptions {
+    /** When set, overrides auto-detection for the lifetime of this init. */
+    appVersion?: string;
+    appBuild?: string;
+}
+/** Visible for tests: resolve version for init, honoring an optional client override. */
+export declare function resolveHostAppVersionForInit(options?: HostAppVersionInitOptions): HostAppVersion | null;
+/**
+ * Resolve and cache the host app version during {@link Userflow.init}.
+ * Re-running init replaces the cache.
+ */
+export declare function cacheHostAppVersionAtInit(options?: HostAppVersionInitOptions): HostAppVersion | null;
+/** Returns the version cached at init, or `null` before init or when unavailable. */
+export declare function getCachedHostAppVersion(): HostAppVersion | null;
+/** User attribute keys for the host app's native store version. */
+export declare const HOST_APP_VERSION_USER_ATTRIBUTE = "app_version";
+export declare const HOST_APP_BUILD_USER_ATTRIBUTE = "app_build";
+/** Returns cached host version fields for UpsertUser, or `{}` when unavailable. */
+export declare function hostAppVersionUserAttributes(): Record<string, string>;
+/** Optional user-attribute keys added by {@link mergeHostAppVersionUserAttributes}. */
+export type HostAppVersionUserAttributeMap = Partial<{
+    [HOST_APP_VERSION_USER_ATTRIBUTE]: string;
+    [HOST_APP_BUILD_USER_ATTRIBUTE]: string;
+}>;
+/** Merges cached host version attrs into identify attributes; caller values win on key conflicts. */
+export declare function mergeHostAppVersionUserAttributes<T extends Record<string, unknown>>(attributes?: T): (T & HostAppVersionUserAttributeMap) | undefined;
+/** @internal Resets init cache between tests. */
+export declare function resetCachedHostAppVersionForTests(): void;
+export declare function formatHostAppVersionLog(resolved: HostAppVersion | null, os: string): {
+    level: 'log' | 'warn';
+    message: string;
+};
+/** Log the host app's native version and platform OS to the console. */
+export declare function logHostAppVersion(): void;
+//# sourceMappingURL=hostAppVersion.d.ts.map

package/lib/typescript/module/src/hostAppVersion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostAppVersion.d.ts","sourceRoot":"","sources":["../../../../src/hostAppVersion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,GAClB,gBAAgB,GAChB,0BAA0B,GAC1B,eAAe,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA+CD,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAOvE;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAYrE;AAED,gFAAgF;AAChF,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAC/C,cAAc,GAAG,IAAI,CAUvB;AAED,uFAAuF;AACvF,wBAAgB,gCAAgC,CAAC,OAAO,EAAE;IACxD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,gBAAgB,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACjD,GAAG,cAAc,GAAG,IAAI,CAMxB;AAED,wBAAgB,qBAAqB,IAAI,cAAc,GAAG,IAAI,CAM7D;AAED,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yFAAyF;AACzF,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,yBAA8B,GACtC,cAAc,GAAG,IAAI,CAWvB;AAKD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,yBAA8B,GACtC,cAAc,GAAG,IAAI,CAGvB;AAED,qFAAqF;AACrF,wBAAgB,uBAAuB,IAAI,cAAc,GAAG,IAAI,CAE/D;AAED,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,gBAAgB,CAAC;AAC7D,eAAO,MAAM,6BAA6B,cAAc,CAAC;AAEzD,mFAAmF;AACnF,wBAAgB,4BAA4B,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOrE;AAED,uFAAuF;AACvF,MAAM,MAAM,8BAA8B,GAAG,OAAO,CAAC;IACnD,CAAC,+BAA+B,CAAC,EAAE,MAAM,CAAC;IAC1C,CAAC,6BAA6B,CAAC,EAAE,MAAM,CAAC;CACzC,CAAC,CAAC;AAEH,qGAAqG;AACrG,wBAAgB,iCAAiC,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjF,UAAU,CAAC,EAAE,CAAC,GACb,CAAC,CAAC,GAAG,8BAA8B,CAAC,GAAG,SAAS,CAMlD;AAED,iDAAiD;AACjD,wBAAgB,iCAAiC,IAAI,IAAI,CAExD;AAaD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,cAAc,GAAG,IAAI,EAC/B,EAAE,EAAE,MAAM,GACT;IACD,KAAK,EAAE,KAAK,GAAG,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;CACjB,CAcA;AAED,wEAAwE;AACxE,wBAAgB,iBAAiB,IAAI,IAAI,CAWxC"}

package/lib/typescript/module/src/index.d.ts

@@ -7,11 +7,17 @@
  * (background/foreground + idle) to the connection, hosts the flow session
  * engine + provider overlay for Phase 3 rendering, and tracks screen changes.
  */
-import type { UserflowAttributes, UserflowConfig, UserflowEventAttributes, UserflowGroupOptions, UserflowIdentifyOptions, UserflowInitOptions, UserflowTrackOptions } from '@userflow-tech/core';
+import type { PublicAttributes, UserflowAttributes, UserflowConfig, UserflowEventAttributes, UserflowGroupOptions, UserflowIdentifyOptions, UserflowInitOptions, UserflowTrackOptions, UserflowUpdateGroupOptions } from '@userflow-tech/core';
 import './anchors/autoAnchor';
 import { type CustomScrollIntoView, type ScrollPadding } from './anchors/scrollConfig';
+import { type DeviceContext } from './deviceContext';
+import { type HostAppVersion } from './hostAppVersion';
 import { type FlowNavigateHandler } from './navigation/openFlowNavigateUrl';
 export { SDK_VERSION } from './version';
+export type { DeviceContext, DeviceOs, DeviceType, SdkPlatform } from './deviceContext';
+export type { HostAppVersion, HostAppVersionSource } from './hostAppVersion';
+export { EmbedBannerPlaceholder } from './runtime/EmbedBannerPlaceholder';
+export type { EmbedBannerPlaceholderProps } from './runtime/EmbedBannerPlaceholder';
 export { UserflowProvider, useUserflow } from './runtime/UserflowProvider';
 export type { UserflowProviderProps, UserflowContextValue } from './runtime/UserflowProvider';
 export { useFlowSessionState } from './runtime/useFlowSessionState';
@@ -37,8 +43,15 @@ export type UserflowInitConfig = UserflowInitOptions & {
      * Defaults to `https://e.userflow.com`.
      */
     pairingEndpoint?: string;
+    /**
+     * Override auto-detected native store version. When omitted, the SDK reads
+     * the host app's marketing version at init (Expo modules or native constants).
+     */
+    appVersion?: string;
+    /** Optional build number paired with {@link appVersion}. */
+    appBuild?: string;
 };
-export type { UserflowAttributes, UserflowConfig, UserflowEventAttributes, UserflowGroupOptions, UserflowIdentifyOptions, UserflowInitOptions, UserflowTrackOptions, } from '@userflow-tech/core';
+export type { PublicAttributeChange, PublicAttributes, UserflowAttributes, UserflowConfig, UserflowEventAttributes, UserflowGroupOptions, UserflowIdentifyOptions, UserflowInitOptions, UserflowTrackOptions, UserflowUpdateGroupOptions, } from '@userflow-tech/core';
 /**
  * Public SDK entry point. Delegates to the platform-agnostic engine in
  * `@userflow-tech/core` and manages the app-lifecycle subscription.
@@ -72,14 +85,42 @@ export declare const Userflow: {
     didHandleURL(url: string): Promise<boolean>;
     /** Associate the current user with a group and upsert group/membership attributes. */
     group(groupId: string | number, attributes?: UserflowAttributes, options?: UserflowGroupOptions): Promise<void>;
-    /** Record a custom analytics event for the current user (and group, unless `userOnly`). */
+    /**
+     * Upsert attributes for the current user without re-identifying.
+     * Requires a prior {@link identify}. Flow button "Set user attribute" actions
+     * use this path.
+     */
+    updateUser(attributes?: PublicAttributes): Promise<void>;
+    /**
+     * Upsert attributes for the current group / membership without re-grouping.
+     * Requires a prior {@link group}.
+     */
+    updateGroup(attributes?: PublicAttributes, options?: UserflowUpdateGroupOptions): Promise<void>;
+    /**
+     * Record a custom analytics event for the current user (and group, unless `userOnly`).
+     * Operational failures (network, rate limit, unexpected SDK bugs) are isolated and
+     * logged; the promise still resolves. `UserflowAuthError` for missing
+     * `init` / `identify` or an invalid event name still rejects.
+     */
     track(name: string, attributes?: UserflowEventAttributes, options?: UserflowTrackOptions): Promise<void>;
     /** The currently identified user id, or `null` before identify. */
     getUserId(): string | null;
     /** A copy of the attributes recorded for the current user. */
     getAttributes(): UserflowAttributes;
+    /**
+     * Host app marketing version cached during {@link init}, or `null` before init
+     * or when auto-detection and any init override are unavailable.
+     */
+    getHostAppVersion(): HostAppVersion | null;
+    /**
+     * Platform metadata cached during {@link init} (`sdk`, `deviceOs`, `deviceType`),
+     * or `null` before init.
+     */
+    getDeviceContext(): DeviceContext | null;
     /** The flow session engine (created lazily; attach runs after identify). */
     getFlowSessionEngine(): import("@userflow-tech/core").FlowSessionEngine;
+    /** The banner session engine (created lazily; attach runs after identify). */
+    getBannerSessionEngine(): import("@userflow-tech/core").BannerSessionEngine;
     /** Clears the current user identity and disconnects from Userflow. */
     reset(): Promise<void>;
     /** Remove app-lifecycle, network, and deep-link subscriptions (call on unmount / teardown). */
@@ -108,5 +149,30 @@ export declare const Userflow: {
      * default fiber / registry path (mirrors web `userflow.setCustomScrollIntoView`).
      */
     setCustomScrollIntoView(fn: CustomScrollIntoView | null | undefined): void;
+    /**
+     * When true (default), tooltip cutout bands and step-transition exit block
+     * taps on the host app underneath. Pass `false` to restore legacy pass-through
+     * tooltip backdrop behavior (dim bands only; `tooltipTargetBlocked` hole seal
+     * is unchanged). Modals always block. Takes effect on the next surface re-render.
+     */
+    setSurfaceInteractionBlocking(enabled: boolean | null | undefined): void;
+    /**
+     * Values exposed to Evaluate JavaScript as `window.userflowContext.host`
+     * (language, theme, tab bar height, and anything else the page used to read
+     * from the DOM). Replaces the previous host bag.
+     */
+    setEvalJsContext(values: Record<string, unknown> | null | undefined): void;
+    /**
+     * Log the host app's native marketing version (store version), not
+     * {@link SDK_VERSION}, and the platform OS (`ios` / `android` / …).
+     * Prefers `expo-application` / `expo-constants` when present; otherwise reads
+     * `NativeModules.RNDeviceInfo` from the bundled device-info native module.
+     */
+    logHostAppVersion(): void;
+    /**
+     * Log cached user-attribute values (`sdk`, `device_os`, `device_type`).
+     * Requires {@link init}; before init, logs that init is required.
+     */
+    logDeviceContext(): void;
 };
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/src/lifecycle.d.ts

@@ -41,8 +41,16 @@ export interface LifecycleControllerDeps {
      * Do not call while lifecycle-suspended — use {@link resume} instead.
      */
     ensureAlive: () => void;
-    /** True while any mid-flow session (live or draft/preview) is on screen. */
+    /**
+     * True while a mid-flow session is held, including one Temporarily Hide is
+     * suppressing. Idle suspend waits so a later attribute update can still unhide it.
+     */
     hasActiveSession: () => boolean;
+    /**
+     * Re-fire the current screen view after a real background (away past grace).
+     * Not called for Control Center / biometric blurs inside the grace window.
+     */
+    onScreenResume?: () => void;
     scheduler?: LifecycleScheduler;
     now?: () => number;
     /** Override for tests; defaults to {@link SUSPEND_GRACE_MS}. */
@@ -63,6 +71,7 @@ export declare class LifecycleController {
     private readonly clearLocalSession;
     private readonly ensureAlive;
     private readonly hasActiveSession;
+    private readonly onScreenResume;
     private readonly scheduler;
     private readonly now;
     private readonly suspendGraceMs;

package/lib/typescript/module/src/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAC;AAE5E,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,QAAgB,CAAC;AAEnD,wEAAwE;AACxE,eAAO,MAAM,iCAAiC,QAAgB,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC;IACzD,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,cAAc,CAAC;IAC1C,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAC/E;AAYD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAa;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAuB;IAC1D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4D;IAE9F,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,iFAAiF;IACjF,OAAO,CAAC,SAAS,CAAS;gBAEd,IAAI,EAAE,uBAAuB;IAazC,KAAK,IAAI,IAAI;IAYb,IAAI,IAAI,IAAI;IAWZ;;;OAGG;IACH,cAAc,IAAI,IAAI;IAOtB,yBAAyB;IACzB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAalD,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,cAAc;CAMvB"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAC;AAE5E,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,QAAgB,CAAC;AAEnD,wEAAwE;AACxE,eAAO,MAAM,iCAAiC,QAAgB,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC;IACzD,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,cAAc,CAAC;IAC1C,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAC/E;AAYD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAa;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2B;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAuB;IAC1D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4D;IAE9F,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,iFAAiF;IACjF,OAAO,CAAC,SAAS,CAAS;gBAEd,IAAI,EAAE,uBAAuB;IAczC,KAAK,IAAI,IAAI;IAYb,IAAI,IAAI,IAAI;IAWZ;;;OAGG;IACH,cAAc,IAAI,IAAI;IAOtB,yBAAyB;IACzB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAalD,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,YAAY;IAqCpB,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,cAAc;CAMvB"}

package/lib/typescript/module/src/navigation/WithUserflowReactNavigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WithUserflowReactNavigation.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/WithUserflowReactNavigation.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,aAAa,EACd,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAQ/B,KAAK,6BAA6B,GAAG;IACnC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,sBAAsB,CAAC,aAAa,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;CACnD,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC,6BAA6B,CAAC,CAAC;CAC7D;AAkBD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,EAC1C,QAAQ,GACT,EAAE,gCAAgC,GAAG,KAAK,CAAC,YAAY,CAmCvD"}
+{"version":3,"file":"WithUserflowReactNavigation.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/WithUserflowReactNavigation.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,aAAa,EACd,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAU/B,KAAK,6BAA6B,GAAG;IACnC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,sBAAsB,CAAC,aAAa,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;CACnD,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC,6BAA6B,CAAC,CAAC;CAC7D;AAkBD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,EAC1C,QAAQ,GACT,EAAE,gCAAgC,GAAG,KAAK,CAAC,YAAY,CAoDvD"}

package/lib/typescript/module/src/navigation/isOverlayPresentation.d.ts

@@ -0,0 +1,14 @@
+/** True when the focused route is a modal / sheet overlay, not a screen navigation. */
+export declare function isOverlayPresentation(presentation: unknown): boolean;
+/**
+ * Reads `presentation` from a React Navigation container ref.
+ * Accepts either a `NavigationContainerRef` or a `NavigationContainerRefWithCurrent`
+ * (`ref.current` is checked when the wrapper itself has no `getCurrentOptions`).
+ */
+export declare function readNavigationPresentation(ref: unknown): string | undefined;
+/**
+ * Subscribes to React Navigation container `state` events.
+ * Accepts a `NavigationContainerRef` or `NavigationContainerRefWithCurrent`.
+ */
+export declare function subscribeNavigationState(ref: unknown, listener: () => void): (() => void) | undefined;
+//# sourceMappingURL=isOverlayPresentation.d.ts.map

package/lib/typescript/module/src/navigation/isOverlayPresentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isOverlayPresentation.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/isOverlayPresentation.ts"],"names":[],"mappings":"AAWA,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAEpE;AAiBD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO3E;AAkBD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,IAAI,GACnB,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAO1B"}

package/lib/typescript/module/src/navigation/openFlowNavigateUrl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openFlowNavigateUrl.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/openFlowNavigateUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAKtF,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC;AAE5F,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAMF,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEvF;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,sBAAsB,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,GAC5D,IAAI,CAEN;AAED,gEAAgE;AAChE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEtF;AAED,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMvD;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCpE;AAED,gBAAgB;AAChB,wBAAgB,iCAAiC,IAAI,IAAI,CAIxD"}
+{"version":3,"file":"openFlowNavigateUrl.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/openFlowNavigateUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAMtF,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC;AAE5F,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAMF,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEvF;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,sBAAsB,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,GAC5D,IAAI,CAEN;AAED,gEAAgE;AAChE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEtF;AAED,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMvD;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuCpE;AAED,gBAAgB;AAChB,wBAAgB,iCAAiC,IAAI,IAAI,CAIxD"}

package/lib/typescript/module/src/pairing/PairingController.d.ts

@@ -1,4 +1,4 @@
-import { PairingEngine, type PairingEngineState, type UserflowCore } from '@userflow-tech/core';
+import { PairingEngine, type PairingEngineState, type PairingPurpose, type UserflowCore } from '@userflow-tech/core';
 import { type AppStateStatus } from 'react-native';
 import { type PairingLogger } from './diagnostics';
 import { type PairingTokenStore } from './tokenStorage';
@@ -10,6 +10,13 @@ export interface PairingControllerOptions {
     tokenStore?: PairingTokenStore;
     /** Clear mid-flow session when exiting preview. */
     clearLocalSession?: () => void;
+    /** End the previewed draft on the server when exiting preview. */
+    endDraftSession?: () => Promise<void>;
+    /**
+     * Drop an end that is waiting for a draft identify has not delivered.
+     * A new preview must call this so that draft is not ended when it arrives.
+     */
+    cancelPendingDraftEnd?: () => void;
     LinkingModule?: {
         getInitialURL(): Promise<string | null>;
         addEventListener(type: 'url', handler: (event: {
@@ -25,6 +32,11 @@ export interface PairingControllerOptions {
     };
     /** Sink for pairing diagnostics. Injected in tests. */
     logger?: PairingLogger;
+    /**
+     * Stable pairing device id. Defaults to the persisted install id.
+     * Injected in tests.
+     */
+    deviceIdProvider?: () => Promise<string>;
 }
 /**
  * Inbound deep links → pairing session → preview mode.
@@ -41,15 +53,36 @@ export declare class PairingController {
     private readonly LinkingModule;
     private readonly AppStateModule;
     private readonly clearLocalSession;
+    private readonly endDraftSession;
+    private readonly cancelPendingDraftEnd;
     private readonly core;
     private readonly pairingEndpoint;
     private readonly logger;
+    private readonly deviceIdProvider;
+    private pairingDeviceId;
+    /** A link or resume already claimed this launch, so a stored token must not. */
+    private acceptedPairingToken;
+    /**
+     * Bumped by exitPreview. An in-flight resume or connect checks it after
+     * every await and does not write the token or leave the socket up.
+     */
+    private launchEpoch;
+    /** Latest enterPreview. An older attempt must not clear a newer token. */
+    private enterAttempt;
+    /**
+     * Orders token and purpose writes. Two scans can overlap on the awaits, and
+     * the slower one's purpose must not land on the token the faster one saved.
+     */
+    private previewSaveQueue;
     private initPhase;
     private initFailureReason;
     /** Pairing token captured before init resolved, replayed once it does. */
     private deferredPairingToken;
+    /** Purpose of {@link deferredPairingToken}, so the held banner already honours it. */
+    private deferredPurpose;
     /** Diagnostics already emitted for the current init attempt. */
     private readonly loggedOnce;
+    private relayUnsub;
     constructor(options: PairingControllerOptions);
     getEngine(): PairingEngine | null;
     /** Whether deep-link / AppState listeners have been started. */
@@ -60,6 +93,11 @@ export declare class PairingController {
      * this the host app shows no sign that a pairing link was ever received.
      */
     private blockedState;
+    /**
+     * A link or resumed token is waiting for init. Report connecting so the
+     * banner is visible during credential validation instead of looking idle.
+     */
+    private heldState;
     onStateChange(listener: PairingControllerListener): () => void;
     /**
      * Start deep-link listeners. Safe to call multiple times, and never rejects —
@@ -68,19 +106,31 @@ export declare class PairingController {
      */
     start(): Promise<void>;
     private startListening;
+    /**
+     * Rejoin the Builder session after a relaunch when no new pairing link won.
+     * An expired or undecodable token is cleared so the next launch stays idle.
+     */
+    private resumeStoredToken;
     stop(): void;
     /**
      * Host apps that intercept deep links themselves can forward them here.
      */
     handleUrl(url: string): Promise<boolean>;
+    /**
+     * Connect now, or hold the token until init resolves or fails. Links and
+     * resumed sessions share this gate so both are deferred, replayed, and
+     * shown the same way.
+     */
+    private connectWhenReady;
     /**
      * Called when `Userflow.init()` begins. Clears a previous failure so a retried
      * init does not keep reporting the old error.
      */
     notifyInitStarted(): void;
     /**
-     * Called when `Userflow.init()` resolves. Connects a link that arrived while
-     * init was still in flight.
+     * Called when `Userflow.init()` resolves. Connects a link or resumed session
+     * that arrived while init was still in flight. `Userflow.init` does not await
+     * this — the pairing socket must not block identify.
      */
     notifyInitialized(): Promise<void>;
     /**
@@ -94,11 +144,35 @@ export declare class PairingController {
      */
     private warnOnce;
     /** Explicit entry with a raw pairing JWT (tests / advanced hosts). */
-    enterPreview(pairingToken: string): Promise<void>;
+    enterPreview(pairingToken: string, purpose?: PairingPurpose | null): Promise<void>;
+    /**
+     * Write the token and its purpose as one attempt. Writes are queued so an
+     * older scan cannot finish its purpose after a newer scan has saved its own.
+     * Returns false when this attempt lost the race; storage then still belongs
+     * to whoever connected, or is cleared if this attempt was the last writer.
+     */
+    private savePreviewCredentials;
+    /**
+     * Drop credentials this attempt wrote, when they are still the ones stored.
+     * A newer scan may already have replaced them; those stay.
+     */
+    private revertPreviewCredentials;
+    /**
+     * Remove the token this attempt wrote. A newer pair may already have
+     * replaced it; that token stays.
+     */
+    private discardPreviewToken;
+    private resolveDeviceId;
     exitPreview(): Promise<void>;
+    /**
+     * Replay the last previewed flow from step 1. No-ops when nothing has been
+     * delivered yet (restart control is hidden in that case).
+     */
+    restartPreview(): Promise<boolean>;
     /** Flush queued startFlowWithToken after identify. */
     notifyIdentified(): void;
     private ensureEngine;
+    private unbindRelay;
     private emit;
 }
 //# sourceMappingURL=PairingController.d.ts.map

package/lib/typescript/module/src/pairing/PairingController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PairingController.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/PairingController.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"PairingController.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/PairingController.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/src/pairing/PreviewModeBanner.d.ts

@@ -1,11 +1,24 @@
 import type { PairingEngineState } from '@userflow-tech/core';
 import * as React from 'react';
+/** A short blip stays quiet. Longer than this, the hidden bar comes back until the socket recovers. */
+export declare const RECONNECT_REVEAL_DELAY_MS = 2000;
 export interface PreviewModeBannerProps {
     state: PairingEngineState;
     onExit: () => void;
+    onRestart?: () => void;
+    /** True while a chrome confirm dialog is open, so the provider can trap host a11y. */
+    onConfirmingChange?: (open: boolean) => void;
+    /** Hide the preview bar while the element picker is using the same top slot. */
+    suppressed?: boolean | undefined;
+    /**
+     * Hide default-tone chrome without giving the top slot to the picker.
+     * Error tone still shows. Set for the brief intro after a new pairing and
+     * for the stretch after element selection until the Builder starts a preview.
+     */
+    held?: boolean | undefined;
 }
 /**
  * Overlay chrome for Builder pairing preview mode.
  */
-export declare function PreviewModeBanner({ state, onExit, }: PreviewModeBannerProps): React.ReactElement | null;
+export declare function PreviewModeBanner({ state, onExit, onRestart, onConfirmingChange, suppressed, held, }: PreviewModeBannerProps): React.ReactElement | null;
 //# sourceMappingURL=PreviewModeBanner.d.ts.map

package/lib/typescript/module/src/pairing/PreviewModeBanner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PreviewModeBanner.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/PreviewModeBanner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,MAAM,GACP,EAAE,sBAAsB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAgEpD"}
+{"version":3,"file":"PreviewModeBanner.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/PreviewModeBanner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAiB/B,uGAAuG;AACvG,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,sFAAsF;IACtF,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7C,gFAAgF;IAChF,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACjC;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,MAAM,EACN,SAAS,EACT,kBAAkB,EAClB,UAAkB,EAClB,IAAY,GACb,EAAE,sBAAsB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAmRpD"}

package/lib/typescript/module/src/pairing/deepLink.d.ts

@@ -1,13 +1,17 @@
+import type { PairingPurpose } from '@userflow-tech/core';
 /**
  * Parse Builder pairing deep links:
- *   {scheme_id}://?pairing_token=<jwt>
+ *   {scheme_id}://?pairing_token=<jwt>[&purpose=preview|select_element]
  *
- * `scheme_id` is typically `userflow-<digits>`.
+ * `scheme_id` is `userflow-` followed by an opaque, backend-generated id.
  */
 export interface PairingDeepLink {
     scheme: string;
     pairingToken: string;
+    /** Absent when the link has no `purpose`, or one this SDK does not know. */
+    purpose?: PairingPurpose;
 }
+export declare function parsePairingPurpose(value: string | null | undefined): PairingPurpose | null;
 /**
  * Why a URL was not treated as a pairing link.
  *

package/lib/typescript/module/src/pairing/deepLink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepLink.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/deepLink.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAChC,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,aAAa,GACb,eAAe,GACf,eAAe,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAE9F,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,wBAAwB,GAC/B,MAAM,IAAI,uBAAuB,CAEnC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,qBAAqB,CAqD5F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAG3F;AAED,iEAAiE;AACjE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E"}
+{"version":3,"file":"deepLink.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/deepLink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAID,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,cAAc,GAAG,IAAI,CAE3F;AAaD;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAChC,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,aAAa,GACb,eAAe,GACf,eAAe,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAE9F,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,wBAAwB,GAC/B,MAAM,IAAI,uBAAuB,CAEnC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,qBAAqB,CAsD5F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAG3F;AAED,iEAAiE;AACjE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E"}

package/lib/typescript/module/src/pairing/deviceId.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Stable id for this install on the pairing channel.
+ *
+ * The server allows one device per pairing topic and only the same id may
+ * rejoin while the previous presence lingers. The id identifies the device,
+ * not the user, so `reset()` and `exitPreview()` must not clear it.
+ */
+export declare const PAIRING_DEVICE_ID_STORAGE_KEY = "userflow:pairingDeviceId";
+export declare function getOrCreatePairingDeviceId(): Promise<string>;
+/** @internal Clears the process memo so tests can simulate a new launch. */
+export declare function resetPairingDeviceIdForTests(): void;
+//# sourceMappingURL=deviceId.d.ts.map

package/lib/typescript/module/src/pairing/deviceId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deviceId.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/deviceId.ts"],"names":[],"mappings":"AAIA;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,6BAA6B,CAAC;AAIxE,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,MAAM,CAAC,CAsBlE;AAED,4EAA4E;AAC5E,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}

package/lib/typescript/module/src/pairing/diagnostics.d.ts

@@ -30,6 +30,11 @@ export declare function pairingLinkInitFailedMessage(reason: string): string;
  * already paired, backend unreachable). Never fatal to the host app.
  */
 export declare function pairingConnectFailedMessage(reason: string): string;
+/**
+ * Engine-reported pairing failure (`lastError`). The preview top bar no longer
+ * has a second line for this, so it must reach Metro under the `[Userflow]` prefix.
+ */
+export declare function pairingPreviewErrorMessage(reason: string): string;
 /** A pairing link arrived without the `pairing_token` query parameter. */
 export declare function pairingMissingTokenMessage(url: string): string;
 /**
@@ -45,8 +50,9 @@ export declare function pairingTokenStoreClearFailedMessage(reason: string): str
 export declare function pairingListenerSetupFailedMessage(reason: string): string;
 /**
  * The URL used a `userflow-` scheme that is not a valid `scheme_id`. Pairing
- * requires `userflow-` followed by digits, so an arbitrary `userflow-*` scheme
- * can match preview links but not pairing ones.
+ * requires `userflow-` followed by one or more alphanumeric segments joined by
+ * single hyphens. A malformed `userflow-*` scheme can match preview links but
+ * not pairing ones.
  */
 export declare function pairingSchemeShapeMessage(url: string): string;
 //# sourceMappingURL=diagnostics.d.ts.map

package/lib/typescript/module/src/pairing/diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAY1D,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAGlC,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,0BAA0B,IAAI,MAAM,CAKnD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,0EAA0E;AAC1E,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED,4DAA4D;AAC5D,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,uBAAuB,EAC/B,GAAG,EAAE,MAAM,GACV,MAAM,CASR;AAED,6EAA6E;AAC7E,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED,iFAAiF;AACjF,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKxE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM7D"}
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAY1D,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAGlC,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,0BAA0B,IAAI,MAAM,CAKnD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,0EAA0E;AAC1E,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED,4DAA4D;AAC5D,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,uBAAuB,EAC/B,GAAG,EAAE,MAAM,GACV,MAAM,CASR;AAED,6EAA6E;AAC7E,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED,iFAAiF;AACjF,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKxE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7D"}

package/lib/typescript/module/src/pairing/elementPickerRelay.d.ts

@@ -0,0 +1,11 @@
+import type { PairingRelayEvent } from '@userflow-tech/protocol';
+export interface ElementPickerRelayEngine {
+    onRelay: (handler: (event: PairingRelayEvent, payload: unknown) => void) => () => void;
+    sendRelay: (event: PairingRelayEvent, payload: unknown) => Promise<unknown>;
+}
+/**
+ * Bridge pairing-channel `selectElement*` events onto {@link elementPickerController}.
+ * UI-free: the overlay (and QA harness) own the actual picking.
+ */
+export declare function bindElementPickerRelay(engine: ElementPickerRelayEngine): () => void;
+//# sourceMappingURL=elementPickerRelay.d.ts.map

package/lib/typescript/module/src/pairing/elementPickerRelay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elementPickerRelay.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/elementPickerRelay.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAOjE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IACvF,SAAS,EAAE,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E;AAiCD;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,wBAAwB,GAAG,MAAM,IAAI,CAmDnF"}

package/lib/typescript/module/src/pairing/resolvePreviewChrome.d.ts

@@ -0,0 +1,16 @@
+import type { PairingEngineState } from '@userflow-tech/core';
+import type { ChromeTopBarTone } from '../authoring/chrome/ChromeTopBar';
+export type PreviewChrome = {
+    visible: false;
+} | {
+    visible: true;
+    tone: ChromeTopBarTone;
+    label: string;
+    numberOfLines: number;
+};
+/**
+ * Maps pairing-engine state onto the preview top-bar chrome.
+ * Pure: no React, so the nine-case table can be asserted without a renderer.
+ */
+export declare function resolvePreviewChrome(state: PairingEngineState): PreviewChrome;
+//# sourceMappingURL=resolvePreviewChrome.d.ts.map

package/lib/typescript/module/src/pairing/resolvePreviewChrome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolvePreviewChrome.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/resolvePreviewChrome.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,MAAM,MAAM,aAAa,GACrB;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,GAClB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC;AAuBpF;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAuB7E"}

package/lib/typescript/module/src/pairing/tokenStorage.d.ts

@@ -1,11 +1,23 @@
 /**
- * Persist the pairing JWT for reconnect within the current app session.
- * Cleared on SDK init / exit preview / app restart (pairing exits on restart).
+ * Persist the pairing JWT so a relaunch can resume Builder pairing until the
+ * token expires or preview is exited. Resume requires `expo-secure-store`;
+ * the in-memory fallback does not survive a process restart.
  */
+import type { PairingPurpose } from '@userflow-tech/core';
+export declare const PAIRING_TOKEN_STORAGE_KEY = "userflow.pairingToken";
+export declare const PAIRING_PURPOSE_STORAGE_KEY = "userflow.pairingPurpose";
 export interface PairingTokenStore {
     get(): Promise<string | null>;
     set(token: string): Promise<void>;
+    /** Clears the token and its purpose. */
     clear(): Promise<void>;
+    /**
+     * Purpose of the link that wrote the token, so a resume keeps the same
+     * preview chrome. Optional so custom stores keep working; a store without
+     * it resumes with no purpose.
+     */
+    getPurpose?(): Promise<PairingPurpose | null>;
+    setPurpose?(purpose: PairingPurpose | null): Promise<void>;
 }
 /** In-memory store used when SecureStore is unavailable (and in tests). */
 export declare function createMemoryPairingTokenStore(): PairingTokenStore;
@@ -13,4 +25,6 @@ export declare function createMemoryPairingTokenStore(): PairingTokenStore;
  * Prefer expo-secure-store (Keychain / Keystore); fall back to memory.
  */
 export declare function createPairingTokenStore(): PairingTokenStore;
+/** @internal Resets module cache between tests. */
+export declare function resetPairingTokenStoreCacheForTests(): void;
 //# sourceMappingURL=tokenStorage.d.ts.map