framepayments-react-native 3.0.0 → 4.0.0

package/lib/native.js

@@ -1,8 +1,18 @@
-/**
- * Native module bridge. Uses NativeModules for classic React Native bridge.
- */
 import { NativeModules, Platform } from 'react-native';
-import { ErrorCodes } from './errors';
+import { useEffect, useState } from 'react';
+import { presentScreen } from './presenter';
+import { CartScreen } from './ui/screens/cart/CartScreen';
+import { CheckoutScreen } from './ui/screens/checkout/CheckoutScreen';
+import { OnboardingRoot } from './ui/screens/onboarding/OnboardingRoot';
+import { canMakeApplePay } from './applePay';
+import { isGooglePayReady } from './googlePay';
+import { ErrorCodes, frameError } from './errors';
+import { setConfig, isInitialized as configIsInitialized, resetConfig, __internal, getDebugMode, } from './config';
+import { resetClients, warmClients, client } from './client';
+import { configureEvervault, resetEvervault } from './evervault';
+import { fetchIpAddress } from './ipAddress';
+import { presentApplePayFlow } from './applePay';
+import { presentGooglePayFlow } from './googlePay';
 const LINKING_ERROR = `The package 'framepayments-react-native' doesn't seem to be linked. Make sure you have run 'pod install' (iOS) or rebuilt the app (Android).`;
 const FrameSDK = NativeModules.FrameSDK
     ? NativeModules.FrameSDK
@@ -11,19 +21,9 @@ const FrameSDK = NativeModules.FrameSDK
             throw new Error(LINKING_ERROR);
         },
     });
-/**
- * Throw a coded error from synchronous JS validation. Mirrors the `code`/`message`
- * shape that native rejections produce so consumers can catch `e.code === 'INVALID_*'`
- * uniformly.
- */
 function throwCoded(code, message) {
-    const err = new Error(message);
-    err.code = code;
-    throw err;
+    throw frameError(code, message);
 }
-// theme is iOS-only today: frame-android does not yet have a matching theme API,
-// so the field is accepted on both platforms but ignored on Android until it does.
-let isInitialized = false;
 export function initialize(options) {
     if (!options?.secretKey) {
         throwCoded(ErrorCodes.INIT_FAILED, 'Frame.initialize requires secretKey');
@@ -34,107 +34,172 @@ export function initialize(options) {
     if (options.theme !== undefined && (typeof options.theme !== 'object' || Array.isArray(options.theme))) {
         throwCoded(ErrorCodes.INIT_FAILED, 'Frame.initialize: theme must be an object');
     }
-    return wrapPromise(FrameSDK.initialize(options.secretKey, options.publishableKey, options.debugMode ?? false, options.theme ?? null)).then(() => {
-        isInitialized = true;
+    return runInitialize(options);
+}
+// Defer JS-side config + framepayments client warming until the native bridge
+// resolves. A successful resolve means the native side is ready; only then is
+// it safe for parallel guardInitialized() calls to see initialized=true.
+async function runInitialize(options) {
+    try {
+        await wrapPromise(FrameSDK.initialize(options.secretKey, options.publishableKey, options.debugMode ?? false, options.applePayMerchantId ?? null, options.googlePayMerchantId ?? null, options.theme ?? null));
+    }
+    catch (err) {
+        resetConfig();
+        resetClients();
+        throw err;
+    }
+    resetClients();
+    resetEvervault();
+    setConfig({
+        secretKey: options.secretKey,
+        publishableKey: options.publishableKey,
+        debugMode: options.debugMode ?? false,
+        applePayMerchantId: options.applePayMerchantId,
+        googlePayMerchantId: options.googlePayMerchantId,
+        theme: options.theme,
     });
+    warmClients();
+    // Prefetch Evervault + Sift configs in the background. Card encryption can't
+    // proceed until Evervault is configured, but we don't block initialize on it
+    // — submit-time encryption will re-await this promise via configureEvervault's
+    // memoization. Sift's bridge wiring lands in a later phase; we cache the
+    // config now so it's ready when the bridge attaches.
+    void prefetchServiceConfigs();
+    // Resolve the device IP asynchronously and reset the cached SDK client so
+    // subsequent requests pick up the ip_address header. iOS resolves
+    // immediately (getifaddrs); Android does a one-time api.ipify.org lookup
+    // that may take a few hundred ms — requests before it lands go out
+    // without the header (matches the native Frame Android behavior).
+    void prefetchIpAddress();
+}
+async function prefetchIpAddress() {
+    const ip = await fetchIpAddress();
+    if (!ip)
+        return;
+    __internal.setIpAddress(ip);
+    resetClients();
+    warmClients();
+}
+async function prefetchServiceConfigs() {
+    // Fire both fetches in parallel — they're independent and the round-trips
+    // saved matter for time-to-first-encrypt on slow connections.
+    const [evResult, siftResult] = await Promise.allSettled([
+        client.sdk.configuration.getEvervaultConfiguration(),
+        client.sdk.configuration.getSiftConfiguration(),
+    ]);
+    if (evResult.status === 'fulfilled') {
+        const ev = evResult.value;
+        if (ev.team_id && ev.app_id) {
+            __internal.setEvervaultConfiguration({ teamId: ev.team_id, appId: ev.app_id });
+            try {
+                await configureEvervault(ev.team_id, ev.app_id);
+            }
+            catch (err) {
+                debugWarn('Evervault configure failed', err);
+            }
+        }
+        else if (getDebugMode()) {
+            console.warn('[Frame] Backend returned no Evervault config (team_id/app_id missing).');
+        }
+    }
+    else {
+        debugWarn('Evervault config prefetch failed', evResult.reason);
+    }
+    if (siftResult.status === 'fulfilled') {
+        const sift = siftResult.value;
+        if (sift.account_id && sift.beacon_key) {
+            __internal.setSiftConfiguration({ accountId: sift.account_id, beaconKey: sift.beacon_key });
+        }
+        else if (getDebugMode()) {
+            console.warn('[Frame] Backend returned no Sift config (account_id/beacon_key missing).');
+        }
+    }
+    else {
+        debugWarn('Sift config prefetch failed', siftResult.reason);
+    }
+}
+function debugWarn(stage, err) {
+    if (!getDebugMode())
+        return;
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`[Frame] ${stage}: ${message}`);
 }
 function guardInitialized() {
-    if (!isInitialized) {
-        const message = 'Frame SDK must be initialized before calling presentCheckout, presentCart, or presentOnboarding. Call Frame.initialize({ apiKey }) first.';
-        const err = new Error(message);
-        err.code = ErrorCodes.NOT_INITIALIZED;
-        throw err;
+    if (!configIsInitialized()) {
+        throw frameError(ErrorCodes.NOT_INITIALIZED, 'Frame SDK must be initialized before calling presentCheckout, presentCart, or presentOnboarding. Call Frame.initialize({ secretKey, publishableKey }) first.');
     }
 }
 function wrapPromise(p) {
     return p.catch((err) => {
-        let code = 'UNKNOWN_ERROR';
-        let message = String(err?.message ?? err);
-        if (err?.code)
-            code = err.code;
-        if (typeof err === 'object' && err !== null && 'message' in err) {
-            message = String(err.message);
+        // RN bridge rejections already carry { code, message, nativeError }.
+        // Pass them through; rebuild only when the shape is wrong.
+        if (err && typeof err === 'object' && 'code' in err && 'message' in err) {
+            throw err;
         }
-        throw Object.assign(new Error(message), { code, message });
+        const message = err instanceof Error ? err.message : String(err);
+        throw frameError('UNKNOWN_ERROR', message);
     });
 }
-/**
- * Presents the Frame checkout sheet for the given account. Resolves with the
- * created Transfer's id string on success, or rejects with `USER_CANCELED` if
- * the user dismisses the sheet.
- *
- * `accountId` is required: the bundled checkout creates a `Transfer`, which is
- * account-scoped. Callers needing a customer/ChargeIntent flow should use
- * `presentApplePay` / `presentGooglePay` directly with a customer owner.
- */
-export function presentCheckout(options) {
+export async function presentCheckout(options) {
     guardInitialized();
     if (!options?.accountId) {
         throwCoded(ErrorCodes.INVALID_ACCOUNT, 'Frame.presentCheckout requires accountId');
     }
-    return wrapPromise(FrameSDK.presentCheckout(options.accountId, options.amount));
+    const [applePayReady, googlePayReady] = await Promise.all([
+        Platform.OS === 'ios' ? canMakeApplePay() : Promise.resolve(false),
+        Platform.OS === 'android' ? isGooglePayReady() : Promise.resolve(false),
+    ]);
+    return presentScreen((api) => (<CheckoutScreen accountId={options.accountId} amount={options.amount} currency={options.currency} addressMode={options.addressMode} title={options.title} showApplePay={applePayReady} showGooglePay={googlePayReady} onSuccess={(id) => api.complete(id)} onClose={() => api.cancel()} onFail={(err) => api.fail(err)}/>));
 }
-/**
- * Presents the Frame cart UI; tapping checkout routes through the same flow
- * as `presentCheckout` and resolves with the created Transfer's id string.
- *
- * `accountId` is required for the same reason as `presentCheckout`.
- */
-export function presentCart(options) {
+export async function presentCart(options) {
     guardInitialized();
     if (!options?.accountId) {
         throwCoded(ErrorCodes.INVALID_ACCOUNT, 'Frame.presentCart requires accountId');
     }
-    return wrapPromise(FrameSDK.presentCart(options.accountId, options.items, options.shippingAmountInCents));
+    // Cart screen sums items + shipping, then transitions to Checkout for the
+    // actual payment collection. The presenter only ever renders ONE screen at a
+    // time, so the Cart's "Checkout" button swaps the rendered element via a
+    // local React state held by a small bridge component.
+    return presentScreen((api) => (<CartCheckoutBridge cartOptions={options} onComplete={(id) => api.complete(id)} onCancel={() => api.cancel()} onFail={(err) => api.fail(err)}/>));
 }
-export function presentOnboarding(options) {
+export async function presentOnboarding(options) {
     guardInitialized();
-    if (Platform.OS === 'ios') {
-        return wrapPromise(FrameSDK.presentOnboarding(options.accountId ?? null, options.capabilities ?? [], options.applePayMerchantId ?? null));
+    const accountId = options.accountId ?? null;
+    const capabilities = options.capabilities ?? [];
+    return presentScreen((api) => (<OnboardingRoot accountId={accountId} capabilities={capabilities} onComplete={(result) => api.complete(result)} onCancel={() => api.cancel()} onFail={(err) => api.fail(err)}/>));
+}
+function CartCheckoutBridge({ cartOptions, onComplete, onCancel, onFail, }) {
+    const [stage, setStage] = useState('cart');
+    const [applePayReady, setApplePayReady] = useState(false);
+    const [googlePayReady, setGooglePayReady] = useState(false);
+    useEffect(() => {
+        let cancelled = false;
+        (async () => {
+            const [ap, gp] = await Promise.all([
+                Platform.OS === 'ios' ? canMakeApplePay() : Promise.resolve(false),
+                Platform.OS === 'android' ? isGooglePayReady() : Promise.resolve(false),
+            ]);
+            if (cancelled)
+                return;
+            setApplePayReady(ap);
+            setGooglePayReady(gp);
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+    const totalCents = cartOptions.items.reduce((sum, i) => sum + i.amountInCents, 0) +
+        cartOptions.shippingAmountInCents;
+    if (stage === 'cart') {
+        return (<CartScreen items={cartOptions.items} shippingAmountInCents={cartOptions.shippingAmountInCents} currency={cartOptions.currency} title={cartOptions.title} onCheckout={() => setStage('checkout')} onClose={onCancel}/>);
     }
-    return wrapPromise(FrameSDK.presentOnboarding(options.accountId ?? null, options.capabilities ?? [], options.googlePayMerchantId ?? null));
+    return (<CheckoutScreen accountId={cartOptions.accountId} amount={totalCents} currency={cartOptions.currency} addressMode={cartOptions.addressMode} title="Checkout" showApplePay={applePayReady} showGooglePay={googlePayReady} onSuccess={onComplete} onClose={() => setStage('cart')} onFail={onFail}/>);
 }
-/**
- * Presents the Apple Pay sheet and creates a charge from the resulting wallet
- * payment method. Resolves with the created resource's id string on success,
- * or rejects with `USER_CANCELED` if the sheet is dismissed.
- *
- *  - `owner.type === 'customer'` → creates a `ChargeIntent`; resolves with its id.
- *  - `owner.type === 'account'`  → creates a `Transfer`;     resolves with its id.
- */
 export function presentApplePay(options) {
     guardInitialized();
-    if (Platform.OS !== 'ios') {
-        throwCoded('PLATFORM_UNSUPPORTED', 'Frame.presentApplePay is iOS-only; use presentGooglePay on Android.');
-    }
-    if (!options?.owner || (options.owner.type !== 'customer' && options.owner.type !== 'account')) {
-        throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentApplePay requires owner: { type: "customer" | "account", id: string }');
-    }
-    if (!options.owner.id) {
-        throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentApplePay requires owner.id');
-    }
-    if (!options.merchantId) {
-        throwCoded(ErrorCodes.INVALID_MERCHANT_ID, 'Frame.presentApplePay requires merchantId');
-    }
-    return wrapPromise(FrameSDK.presentApplePay(options.owner.type, options.owner.id, options.amount, options.currency ?? 'usd', options.merchantId));
+    return presentApplePayFlow(options);
 }
-/**
- * Presents Google Pay and creates a charge from the resulting wallet payment method.
- * Resolves with the created resource's id string on success.
- *
- *  - `owner.type === 'customer'` → creates a `ChargeIntent`; resolves with its id.
- *  - `owner.type === 'account'`  → creates a `Transfer`;     resolves with its id.
- */
 export function presentGooglePay(options) {
     guardInitialized();
-    if (Platform.OS !== 'android') {
-        throwCoded('PLATFORM_UNSUPPORTED', 'Frame.presentGooglePay is Android-only; use presentApplePay on iOS.');
-    }
-    if (!options?.owner || (options.owner.type !== 'customer' && options.owner.type !== 'account')) {
-        throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentGooglePay requires owner: { type: "customer" | "account", id: string }');
-    }
-    if (!options.owner.id) {
-        throwCoded(ErrorCodes.INVALID_OWNER, 'Frame.presentGooglePay requires owner.id');
-    }
-    return wrapPromise(FrameSDK.presentGooglePay(options.amountCents, options.owner.type, options.owner.id, options.currencyCode ?? 'USD', options.googlePayMerchantId ?? null));
+    return presentGooglePayFlow(options);
 }

package/lib/plaid.d.ts

@@ -0,0 +1,25 @@
+export declare function isPlaidAvailable(): boolean;
+export interface PlaidConnectResult {
+    publicToken: string;
+    selectedAccountId: string;
+    institutionName?: string;
+    subtype?: string;
+}
+/**
+ * Opens Plaid Link for the given Frame account. Fetches a link token via
+ * frame-node's publishable-key route, calls Plaid's create() + open(), and
+ * resolves with the public token + selected account on success. Rejects with
+ * USER_CANCELED on dismiss, PAYMENT_FAILED on any other Plaid error, or
+ * PLAID_UNAVAILABLE if the SDK isn't installed.
+ *
+ * The promise lifecycle owns the create/open round-trip: callers don't have
+ * to think about Plaid's React component model or destroy() cleanup.
+ */
+export declare function openPlaidLink(opts: {
+    accountId: string;
+}): Promise<PlaidConnectResult>;
+/** Force-dismiss any in-flight Plaid Link session. Safe to call when nothing
+ *  is open. Used by the parent's cancel path on screen teardown. */
+export declare function dismissPlaidLink(): void;
+export declare function __resetPlaidSdkCache(): void;
+//# sourceMappingURL=plaid.d.ts.map

package/lib/plaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plaid.d.ts","sourceRoot":"","sources":["../src/plaid.ts"],"names":[],"mappings":"AA+DA,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAoE5F;AAED;oEACoE;AACpE,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAID,wBAAgB,oBAAoB,IAAI,IAAI,CAE3C"}

package/lib/plaid.js

@@ -0,0 +1,101 @@
+import { client } from './client';
+import { ErrorCodes, frameError } from './errors';
+let cachedSdk;
+function loadSdk() {
+    if (cachedSdk !== undefined)
+        return cachedSdk;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require('react-native-plaid-link-sdk');
+        cachedSdk = mod;
+    }
+    catch {
+        cachedSdk = null;
+    }
+    return cachedSdk;
+}
+export function isPlaidAvailable() {
+    return loadSdk() !== null;
+}
+/**
+ * Opens Plaid Link for the given Frame account. Fetches a link token via
+ * frame-node's publishable-key route, calls Plaid's create() + open(), and
+ * resolves with the public token + selected account on success. Rejects with
+ * USER_CANCELED on dismiss, PAYMENT_FAILED on any other Plaid error, or
+ * PLAID_UNAVAILABLE if the SDK isn't installed.
+ *
+ * The promise lifecycle owns the create/open round-trip: callers don't have
+ * to think about Plaid's React component model or destroy() cleanup.
+ */
+export async function openPlaidLink(opts) {
+    const sdk = loadSdk();
+    if (!sdk) {
+        throw frameError(ErrorCodes.PLAID_UNAVAILABLE, 'Plaid is not installed in this app. Add react-native-plaid-link-sdk to your peer deps and rebuild.');
+    }
+    const tokenResponse = await client.sdk.accounts.getPlaidLinkToken(opts.accountId);
+    const linkToken = tokenResponse.link_token;
+    if (!linkToken) {
+        throw frameError(ErrorCodes.PAYMENT_FAILED, 'Frame returned no Plaid link token.');
+    }
+    // Plaid's create() returns void and synchronously caches the configuration;
+    // open() picks the cached config up and triggers the modal. The two-call
+    // ordering is the SDK's documented pattern even though the race-safety
+    // isn't stated explicitly. Don't reorder without re-reading Plaid docs.
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        function settleResolve(value) {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        }
+        function settleReject(err) {
+            if (settled)
+                return;
+            settled = true;
+            reject(err);
+        }
+        sdk.create({ token: linkToken });
+        sdk.open({
+            onSuccess: (success) => {
+                const account = success.metadata.accounts[0];
+                if (!account) {
+                    settleReject(frameError(ErrorCodes.PAYMENT_FAILED, 'Plaid returned no selected account.'));
+                    return;
+                }
+                // Plaid normally returns exactly one selected account, but some
+                // institutions surface multiple. The Frame backend takes a single
+                // account_id so we pick the first; flag in dev to catch future flows
+                // that need a per-account picker.
+                if (success.metadata.accounts.length > 1 && typeof __DEV__ !== 'undefined' && __DEV__) {
+                    // eslint-disable-next-line no-console
+                    console.warn(`[Frame] Plaid returned ${success.metadata.accounts.length} accounts; using the first.`);
+                }
+                settleResolve({
+                    publicToken: success.publicToken,
+                    selectedAccountId: account.id,
+                    institutionName: success.metadata.institution?.name,
+                    subtype: account.subtype,
+                });
+            },
+            onExit: (exit) => {
+                if (exit.error) {
+                    settleReject(frameError(ErrorCodes.PAYMENT_FAILED, exit.error.errorMessage ?? 'Plaid Link failed.'));
+                    return;
+                }
+                settleReject(frameError(ErrorCodes.USER_CANCELED, 'User dismissed Plaid Link.'));
+            },
+        });
+    });
+}
+/** Force-dismiss any in-flight Plaid Link session. Safe to call when nothing
+ *  is open. Used by the parent's cancel path on screen teardown. */
+export function dismissPlaidLink() {
+    const sdk = loadSdk();
+    sdk?.dismissLink();
+}
+// Test-only — clears the SDK cache so tests can swap implementations between
+// `react-native-plaid-link-sdk is missing` and `present` scenarios.
+export function __resetPlaidSdkCache() {
+    cachedSdk = undefined;
+}

package/lib/presenter/FramePresentationHost.d.ts

@@ -0,0 +1,2 @@
+export declare function FramePresentationHost(): import("react").JSX.Element;
+//# sourceMappingURL=FramePresentationHost.d.ts.map

package/lib/presenter/FramePresentationHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FramePresentationHost.d.ts","sourceRoot":"","sources":["../../src/presenter/FramePresentationHost.tsx"],"names":[],"mappings":"AAaA,wBAAgB,qBAAqB,gCAgCpC"}

package/lib/presenter/FramePresentationHost.js

@@ -0,0 +1,30 @@
+import { useEffect, useState } from 'react';
+import { Modal, Platform } from 'react-native';
+import { subscribe, setHostMounted, requestActiveCancel, } from './presenter';
+import { ToastHost } from '../ui/primitives/Toast';
+// Subscribes to the presenter singleton and renders whichever screen is
+// currently active inside an RN <Modal>. Mounted exactly once by FrameProvider.
+export function FramePresentationHost() {
+    const [active, setActive] = useState(null);
+    useEffect(() => {
+        setHostMounted(true);
+        const unsubscribe = subscribe(setActive);
+        return () => {
+            unsubscribe();
+            setHostMounted(false);
+        };
+    }, []);
+    return (<Modal visible={active !== null} animationType="slide" transparent={false} presentationStyle={Platform.OS === 'ios' ? 'pageSheet' : 'fullScreen'} 
+    // Fires on Android hardware back. On iOS pageSheet, swipe-down also
+    // surfaces here in RN 0.81+. Either path: settle the in-flight promise
+    // with USER_CANCELED so JS state stays in sync with what the user sees.
+    onRequestClose={() => {
+            requestActiveCancel();
+        }}>
+      {active?.element ?? null}
+      {/* Toasts must render INSIDE the modal — on iOS pageSheet the modal is a
+            separate native window, so a ToastHost mounted outside it would be
+            invisible while onboarding/checkout is up. */}
+      <ToastHost />
+    </Modal>);
+}

package/lib/presenter/index.d.ts

@@ -0,0 +1,3 @@
+export { presentScreen, isHostMounted, subscribe, setHostMounted, requestActiveCancel, __resetPresenter, type FramePresentationApi, type FramePresentResult, type ActivePresentation, } from './presenter';
+export { FramePresentationHost } from './FramePresentationHost';
+//# sourceMappingURL=index.d.ts.map

package/lib/presenter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/presenter/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC"}

package/lib/presenter/index.js

@@ -0,0 +1,2 @@
+export { presentScreen, isHostMounted, subscribe, setHostMounted, requestActiveCancel, __resetPresenter, } from './presenter';
+export { FramePresentationHost } from './FramePresentationHost';

package/lib/presenter/presenter.d.ts

@@ -0,0 +1,44 @@
+import type { ReactElement } from 'react';
+export type FramePresentResult<T> = {
+    kind: 'success';
+    value: T;
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'failure';
+    error: unknown;
+};
+export interface FramePresentationApi<T> {
+    /** Resolve the pending presentScreen promise with the success value. */
+    complete: (value: T) => void;
+    /** Reject the pending presentScreen promise with USER_CANCELED. */
+    cancel: () => void;
+    /** Reject the pending presentScreen promise with the given error. */
+    fail: (error: unknown) => void;
+}
+export interface ActivePresentation {
+    id: number;
+    element: ReactElement;
+}
+type Listener = (active: ActivePresentation | null) => void;
+export declare function subscribe(listener: Listener): () => void;
+export declare function setHostMounted(mounted: boolean): void;
+export declare function isHostMounted(): boolean;
+/**
+ * Imperatively present a screen and await its result. The `render` callback
+ * receives the presentation API (complete/cancel/fail) and must return the
+ * React element to mount. Returns the value the screen passed to complete().
+ *
+ * Rejects with NO_PROVIDER if `FrameProvider` is not mounted at the time of
+ * the call. Rejects with PRESENTER_BUSY if another screen is already active.
+ */
+export declare function presentScreen<T>(render: (api: FramePresentationApi<T>) => ReactElement): Promise<T>;
+/**
+ * Triggered by the host when the user dismisses via OS gesture (Android back,
+ * iOS swipe-down). Equivalent to the screen calling `api.cancel()` itself.
+ * No-op if nothing is active.
+ */
+export declare function requestActiveCancel(): void;
+export declare function __resetPresenter(): void;
+export {};
+//# sourceMappingURL=presenter.d.ts.map

package/lib/presenter/presenter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presenter.d.ts","sourceRoot":"","sources":["../../src/presenter/presenter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAS1C,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAC5B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAExC,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,wEAAwE;IACxE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,mEAAmE;IACnE,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,qEAAqE;IACrE,IAAI,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,YAAY,CAAC;CACvB;AAED,KAAK,QAAQ,GAAG,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,KAAK,IAAI,CAAC;AAkB5D,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAMxD;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAqBrD;AAED,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,MAAM,EAAE,CAAC,GAAG,EAAE,oBAAoB,CAAC,CAAC,CAAC,KAAK,YAAY,GACrD,OAAO,CAAC,CAAC,CAAC,CA+CZ;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAGD,wBAAgB,gBAAgB,IAAI,IAAI,CAOvC"}

package/lib/presenter/presenter.js

@@ -0,0 +1,112 @@
+import { frameError, ErrorCodes } from '../errors';
+let nextId = 1;
+let active = null;
+// Captured from the in-flight presentScreen so setHostMounted(false) can reject
+// the awaiting caller. Settle paths use the closure-bound reject directly.
+let pendingReject = null;
+// Triggered by the host when the user dismisses via the OS gesture (Android
+// hardware back, iOS pageSheet swipe-down). Resolves to USER_CANCELED on the
+// JS side just like the screen calling `api.cancel()` itself.
+let cancelActive = null;
+let hostMounted = false;
+const listeners = new Set();
+function emit() {
+    for (const listener of listeners)
+        listener(active);
+}
+export function subscribe(listener) {
+    listeners.add(listener);
+    listener(active);
+    return () => {
+        listeners.delete(listener);
+    };
+}
+export function setHostMounted(mounted) {
+    const wasMounted = hostMounted;
+    hostMounted = mounted;
+    if (!mounted && pendingReject) {
+        // The provider unmounted while a presentation was in flight. Reject the
+        // caller, then notify host subscribers so the new state is consistent.
+        const reject = pendingReject;
+        pendingReject = null;
+        cancelActive = null;
+        active = null;
+        reject(frameError('PRESENTER_TEARDOWN', 'FrameProvider unmounted while a screen was presented.'));
+        emit();
+    }
+    // Remount after a previous unmount: clear any stale active state from a
+    // screen the host stopped rendering before it could settle. Listeners stay
+    // attached so the freshly mounted host picks up the now-empty state.
+    if (mounted && !wasMounted) {
+        active = null;
+        pendingReject = null;
+        cancelActive = null;
+    }
+}
+export function isHostMounted() {
+    return hostMounted;
+}
+/**
+ * Imperatively present a screen and await its result. The `render` callback
+ * receives the presentation API (complete/cancel/fail) and must return the
+ * React element to mount. Returns the value the screen passed to complete().
+ *
+ * Rejects with NO_PROVIDER if `FrameProvider` is not mounted at the time of
+ * the call. Rejects with PRESENTER_BUSY if another screen is already active.
+ */
+export function presentScreen(render) {
+    if (!hostMounted) {
+        return Promise.reject(frameError('NO_PROVIDER', 'FrameProvider must be mounted at the app root before calling Frame.presentCheckout / presentCart / presentOnboarding.'));
+    }
+    if (active) {
+        return Promise.reject(frameError('PRESENTER_BUSY', 'Another Frame screen is already presented.'));
+    }
+    return new Promise((resolve, reject) => {
+        const id = nextId++;
+        const api = {
+            complete: (value) => settle({ kind: 'success', value }),
+            cancel: () => settle({ kind: 'cancel' }),
+            fail: (error) => settle({ kind: 'failure', error }),
+        };
+        function settle(result) {
+            if (!active || active.id !== id)
+                return;
+            active = null;
+            pendingReject = null;
+            cancelActive = null;
+            emit();
+            switch (result.kind) {
+                case 'success':
+                    resolve(result.value);
+                    return;
+                case 'cancel':
+                    reject(frameError(ErrorCodes.USER_CANCELED, 'User dismissed the Frame screen without completing.'));
+                    return;
+                case 'failure':
+                    reject(result.error);
+                    return;
+            }
+        }
+        pendingReject = reject;
+        cancelActive = () => api.cancel();
+        active = { id, element: render(api) };
+        emit();
+    });
+}
+/**
+ * Triggered by the host when the user dismisses via OS gesture (Android back,
+ * iOS swipe-down). Equivalent to the screen calling `api.cancel()` itself.
+ * No-op if nothing is active.
+ */
+export function requestActiveCancel() {
+    cancelActive?.();
+}
+// Test-only resets. Not exported from src/index.
+export function __resetPresenter() {
+    active = null;
+    pendingReject = null;
+    cancelActive = null;
+    hostMounted = false;
+    listeners.clear();
+    nextId = 1;
+}