@reclaimprotocol/client 0.1.29 → 0.1.31

package/lib/launch/flow.js

@@ -0,0 +1,222 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ReclaimFlow_instances, _ReclaimFlow_input, _ReclaimFlow_options, _ReclaimFlow_env, _ReclaimFlow_parsed, _ReclaimFlow_parse, _ReclaimFlow_resolve, _ReclaimFlow_resolveExtensionTarget, _ReclaimFlow_execute, _ReclaimFlow_openNewTab;
+import { appendSessionQuery, resolveDestinationUrl } from "./destination.js";
+import { resolveDevice } from "./device.js";
+import { defaultEnvironment } from "./environment.js";
+import { ReclaimFlowUnavailableError } from "./errors.js";
+import { probeExtension, sendExtensionCancelVerification, sendExtensionStartVerification, } from "./extension.js";
+import { buildAndroidMarketIntentUrl, redirectToAndroid, redirectToAppClip, redirectToIosDeepLink, } from "./mobile.js";
+import { showQrModal } from "./modal.js";
+import { DEFAULT_APP_CLIP_URL, DEFAULT_IOS_APP_DOWNLOAD_URL, DEFAULT_IOS_DEEP_LINK_BASE_URL, resolveAndroidAppDownloadUrl, resolveAndroidDeepLinkPackage, resolveCanUseDeferredDeepLinksFlow, } from "./options.js";
+import { embedPortalIframe, openPortalTab } from "./portal.js";
+import { parseFlowUrl } from "./target.js";
+export { ReclaimFlowUnavailableError, isReclaimFlowUnavailableError, } from "./errors.js";
+function inputVerificationUrl(input) {
+    const verificationUrl = typeof input === 'string'
+        ? input
+        : input.verificationUrl;
+    if (!verificationUrl) {
+        throw new Error('ReclaimFlow.from() input must be a verificationUrl string, or '
+            + 'an object carrying one');
+    }
+    return verificationUrl;
+}
+export class ReclaimFlow {
+    constructor(input, options) {
+        _ReclaimFlow_instances.add(this);
+        _ReclaimFlow_input.set(this, void 0);
+        _ReclaimFlow_options.set(this, void 0);
+        _ReclaimFlow_env.set(this, void 0);
+        _ReclaimFlow_parsed.set(this, void 0);
+        __classPrivateFieldSet(this, _ReclaimFlow_input, input, "f");
+        __classPrivateFieldSet(this, _ReclaimFlow_options, options, "f");
+        __classPrivateFieldSet(this, _ReclaimFlow_env, options.environment ?? defaultEnvironment(), "f");
+    }
+    /** The only constructor — no `fromSession`/`fromVerificationUrl`/
+     *  `fromDescriptor` family. */
+    static from(input, options = {}) {
+        return new ReclaimFlow(input, options);
+    }
+    /** The `session`/object this flow was built from, or `undefined` when
+     *  `from()` was given a bare `verificationUrl` string. */
+    get session() {
+        return typeof __classPrivateFieldGet(this, _ReclaimFlow_input, "f") === 'string' ? undefined : __classPrivateFieldGet(this, _ReclaimFlow_input, "f");
+    }
+    /** Merges `options` for later `getUrl()`/`resolveTarget()`/`launch()`
+     *  calls. Chainable. */
+    setOptions(options) {
+        __classPrivateFieldSet(this, _ReclaimFlow_options, { ...__classPrivateFieldGet(this, _ReclaimFlow_options, "f"), ...options }, "f");
+        if (options.environment) {
+            __classPrivateFieldSet(this, _ReclaimFlow_env, options.environment, "f");
+        }
+        // `verificationClientId` feeds target resolution (./target.ts), so a
+        // change invalidates the cached parse.
+        __classPrivateFieldSet(this, _ReclaimFlow_parsed, undefined, "f");
+        return this;
+    }
+    /** Resolves the target and returns the claimant URL, without navigating. */
+    async getUrl() {
+        const parsed = __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_parse).call(this);
+        return resolveDestinationUrl(parsed.target, parsed, __classPrivateFieldGet(this, _ReclaimFlow_options, "f"));
+    }
+    /** Which client and mechanism this flow will use on this device. A read:
+     *  reports the mechanism and changes nothing (the one exception is a
+     *  short-lived `postMessage` probe for an extension-bound session, which
+     *  navigates nothing and shows no UI). */
+    async resolveTarget() {
+        return __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_resolve).call(this);
+    }
+    /** Opens it. Rejects with `ReclaimFlowUnavailableError` for an
+     *  extension-bound session this device can't run, rather than silently
+     *  falling back to another mechanism. */
+    async launch() {
+        const resolved = await __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_resolve).call(this);
+        if (!resolved.available) {
+            throw new ReclaimFlowUnavailableError(resolved.reason ?? 'extension-not-found');
+        }
+        return __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_execute).call(this, resolved);
+    }
+}
+_ReclaimFlow_input = new WeakMap(), _ReclaimFlow_options = new WeakMap(), _ReclaimFlow_env = new WeakMap(), _ReclaimFlow_parsed = new WeakMap(), _ReclaimFlow_instances = new WeakSet(), _ReclaimFlow_parse = function _ReclaimFlow_parse() {
+    __classPrivateFieldSet(this, _ReclaimFlow_parsed, __classPrivateFieldGet(this, _ReclaimFlow_parsed, "f") ?? parseFlowUrl(inputVerificationUrl(__classPrivateFieldGet(this, _ReclaimFlow_input, "f")), __classPrivateFieldGet(this, _ReclaimFlow_options, "f").verificationClientId), "f");
+    return __classPrivateFieldGet(this, _ReclaimFlow_parsed, "f");
+}, _ReclaimFlow_resolve = async function _ReclaimFlow_resolve() {
+    const parsed = __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_parse).call(this);
+    const { device, confidence } = resolveDevice(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"));
+    const client = parsed.target;
+    if (client === 'reclaim-browser-extension') {
+        return __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_resolveExtensionTarget).call(this, client, device, confidence);
+    }
+    if (client === 'verifier-app') {
+        let mechanism;
+        if (device === 'desktop') {
+            mechanism = 'qr-modal';
+        }
+        else if (device === 'ios') {
+            mechanism = __classPrivateFieldGet(this, _ReclaimFlow_options, "f").useAppClip ? 'ios-app-clip' : 'ios-deep-link';
+        }
+        else {
+            mechanism = 'android-deep-link';
+        }
+        return { client, device, confidence, mechanism, available: true };
+    }
+    // `builder` | `portals` | undefined (unrecognised path — degrades to a
+    // tab). iframe embedding is desktop-only, per the plan's mechanism
+    // table — mobile always gets a new tab even with `options.target` set.
+    const wantsIframe = !!client && device === 'desktop'
+        && !!__classPrivateFieldGet(this, _ReclaimFlow_options, "f").target;
+    const mechanism = wantsIframe ? 'iframe' : 'new-tab';
+    return { client, device, confidence, mechanism, available: true };
+}, _ReclaimFlow_resolveExtensionTarget = async function _ReclaimFlow_resolveExtensionTarget(client, device, confidence) {
+    const unavailable = (reason) => ({
+        client,
+        device,
+        confidence,
+        mechanism: 'unavailable',
+        available: false,
+        reason,
+    });
+    if (device !== 'desktop') {
+        return unavailable('mobile-device');
+    }
+    if (__classPrivateFieldGet(this, _ReclaimFlow_options, "f").useBrowserExtension === false) {
+        return unavailable('extension-disabled');
+    }
+    const found = await probeExtension(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), __classPrivateFieldGet(this, _ReclaimFlow_options, "f"));
+    if (!found) {
+        return unavailable('extension-not-found');
+    }
+    return {
+        client,
+        device,
+        confidence,
+        mechanism: 'extension-handoff',
+        available: true,
+    };
+}, _ReclaimFlow_execute = function _ReclaimFlow_execute(resolved) {
+    const parsed = __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_parse).call(this);
+    switch (resolved.mechanism) {
+        case 'extension-handoff': {
+            const handoff = {
+                sessionId: parsed.sessionId ?? '',
+                diag: parsed.diag,
+                extensionID: __classPrivateFieldGet(this, _ReclaimFlow_options, "f").extensionID,
+            };
+            sendExtensionStartVerification(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), handoff);
+            return {
+                target: resolved,
+                close: () => sendExtensionCancelVerification(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), handoff),
+            };
+        }
+        case 'qr-modal': {
+            const url = resolveDestinationUrl(parsed.target, parsed, __classPrivateFieldGet(this, _ReclaimFlow_options, "f"));
+            const modal = showQrModal(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), url, {
+                ...__classPrivateFieldGet(this, _ReclaimFlow_options, "f").modalOptions,
+                renderQr: __classPrivateFieldGet(this, _ReclaimFlow_options, "f").renderQr,
+            });
+            return { target: resolved, close: () => modal.close() };
+        }
+        case 'ios-app-clip': {
+            const appClipUrl = appendSessionQuery(__classPrivateFieldGet(this, _ReclaimFlow_options, "f").appClipUrl ?? DEFAULT_APP_CLIP_URL, parsed);
+            const handle = redirectToAppClip(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), appClipUrl);
+            return { target: resolved, close: () => handle.close() };
+        }
+        case 'ios-deep-link': {
+            const deepLinkUrl = appendSessionQuery(__classPrivateFieldGet(this, _ReclaimFlow_options, "f").iosDeepLinkBaseUrl ?? DEFAULT_IOS_DEEP_LINK_BASE_URL, parsed);
+            const storeUrl = __classPrivateFieldGet(this, _ReclaimFlow_options, "f").iosAppDownloadUrl
+                ?? DEFAULT_IOS_APP_DOWNLOAD_URL;
+            const handle = redirectToIosDeepLink(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), { deepLinkUrl, storeUrl });
+            return { target: resolved, close: () => handle.close() };
+        }
+        case 'android-deep-link': {
+            const shareUrl = resolveDestinationUrl(parsed.target, parsed, __classPrivateFieldGet(this, _ReclaimFlow_options, "f"));
+            const deepLinkUrl = appendSessionQuery(__classPrivateFieldGet(this, _ReclaimFlow_options, "f").iosDeepLinkBaseUrl ?? DEFAULT_IOS_DEEP_LINK_BASE_URL, parsed);
+            const marketIntentUrl = buildAndroidMarketIntentUrl(shareUrl, resolveAndroidDeepLinkPackage(__classPrivateFieldGet(this, _ReclaimFlow_options, "f")));
+            const handle = redirectToAndroid(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), {
+                deepLinkUrl,
+                marketIntentUrl,
+                shareUrl,
+                canUseDeferredDeepLinksFlow: resolveCanUseDeferredDeepLinksFlow(__classPrivateFieldGet(this, _ReclaimFlow_options, "f"), 'android'),
+            });
+            return { target: resolved, close: () => handle.close() };
+        }
+        case 'iframe': {
+            const url = resolveDestinationUrl(parsed.target, parsed, __classPrivateFieldGet(this, _ReclaimFlow_options, "f"));
+            const container = __classPrivateFieldGet(this, _ReclaimFlow_options, "f").target;
+            if (!container) {
+                // `#resolve()` only picks 'iframe' when `options.target` is set;
+                // kept total rather than asserting, in case options changed
+                // between `resolveTarget()` and `launch()`.
+                return __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_openNewTab).call(this, resolved, url);
+            }
+            const handle = embedPortalIframe(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), url, container);
+            return {
+                target: resolved, iframe: handle.iframe, close: () => handle.close(),
+            };
+        }
+        case 'new-tab': {
+            const url = resolveDestinationUrl(parsed.target, parsed, __classPrivateFieldGet(this, _ReclaimFlow_options, "f"));
+            return __classPrivateFieldGet(this, _ReclaimFlow_instances, "m", _ReclaimFlow_openNewTab).call(this, resolved, url);
+        }
+        case 'unavailable':
+            // `launch()` already rejected before calling `#execute()`.
+            throw new ReclaimFlowUnavailableError(resolved.reason ?? 'extension-not-found');
+    }
+}, _ReclaimFlow_openNewTab = function _ReclaimFlow_openNewTab(resolved, url) {
+    const handle = openPortalTab(__classPrivateFieldGet(this, _ReclaimFlow_env, "f"), url, __classPrivateFieldGet(this, _ReclaimFlow_options, "f").preOpenedTab);
+    return { target: resolved, tab: handle.tab, close: () => handle.close() };
+};
+// Re-exported so a consumer building `androidAppDownloadUrl`/
+// `androidDeepLinkPackage` defaults for display (e.g. an install-link
+// banner) doesn't have to duplicate them.
+export { resolveAndroidAppDownloadUrl, resolveAndroidDeepLinkPackage };

package/lib/launch/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@reclaimprotocol/client/launch` — a browser-only, credential-free
+ * launcher. Given a Builder `verificationUrl`, `ReclaimFlow` works out how
+ * to open it on this device (browser extension handoff, native app deep
+ * link/App Clip, portal/builder tab or iframe, or a QR modal) and hands
+ * back a `FlowHandle` to tear the UI down again.
+ *
+ * See `devtools/plans/client-launch-api.md` for the design this implements.
+ */
+export { ReclaimFlow, ReclaimFlowUnavailableError, isReclaimFlowUnavailableError, } from './flow.ts';
+export type { DetectionConfidence, DeviceKind, FlowHandle, FlowInput, FlowOptions, LaunchMechanism, ReclaimFlowUnavailableReason, ResolvedTarget, VerificationTarget, } from './flow.ts';
+export { showQrModal } from './modal.ts';
+export type { ModalHandle, ModalOptions } from './modal.ts';
+export type { RenderQr } from './qr.ts';
+export { defaultEnvironment } from './environment.ts';
+export type { LaunchClipboard, LaunchContainer, LaunchDocument, LaunchElement, LaunchEnvironment, LaunchMessageEvent, LaunchNavigator, LaunchStyleDeclaration, LaunchUserAgentData, LaunchWindow, LaunchWindowHandle, } from './environment.ts';

package/lib/launch/index.js

@@ -0,0 +1,12 @@
+/**
+ * `@reclaimprotocol/client/launch` — a browser-only, credential-free
+ * launcher. Given a Builder `verificationUrl`, `ReclaimFlow` works out how
+ * to open it on this device (browser extension handoff, native app deep
+ * link/App Clip, portal/builder tab or iframe, or a QR modal) and hands
+ * back a `FlowHandle` to tear the UI down again.
+ *
+ * See `devtools/plans/client-launch-api.md` for the design this implements.
+ */
+export { ReclaimFlow, ReclaimFlowUnavailableError, isReclaimFlowUnavailableError, } from "./flow.js";
+export { showQrModal } from "./modal.js";
+export { defaultEnvironment } from "./environment.js";

package/lib/launch/mobile.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The `verifier-app` target's mobile mechanisms, ported from the reference
+ * JS SDK's `redirectToAppClip`/`redirectToiOSApp`/`redirectToInstantApp`
+ * (`Reclaim.ts` ~1663/~1752/~1773). Per the launch-API plan's mechanism
+ * table (not the reference SDK's own branching, which folds iOS into an
+ * Android-shaped fallback in one corner case the plan doesn't carry over):
+ *
+ *  - iOS is exactly two mechanisms: `useAppClip` picks the App Clip, its
+ *    absence picks the `reclaimverifier://` deep link with a 3s App Store
+ *    fallback. Both redirect the current tab — there's no popup on a phone.
+ *  - Android mirrors it: clipboard write, top-level `reclaimverifier://`
+ *    navigation, Play Store market-intent fallback if the tab never
+ *    backgrounds. Unless `canUseDeferredDeepLinksFlow` is false, in which
+ *    case it's a plain redirect to the share URL.
+ *
+ * All delays go through `env.setTimeout`/`env.clearTimeout` (see
+ * ./environment.ts), so tests exercise the fallback paths with a fake
+ * scheduler instead of waiting on real 1.5s/3s timers.
+ */
+import type { LaunchEnvironment } from './environment.ts';
+export interface MobileRedirectHandle {
+    close(): void;
+}
+/** iOS, `useAppClip: true`. A one-way redirect — nothing to probe or fall
+ *  back from, so `close()` is a no-op. */
+export declare function redirectToAppClip(env: LaunchEnvironment, appClipUrl: string): MobileRedirectHandle;
+/** iOS, `useAppClip: false` (the default): try the custom-scheme deep link,
+ *  fall back to the App Store after 3s if the tab never backgrounded (i.e.
+ *  the OS never handed off to the app). */
+export declare function redirectToIosDeepLink(env: LaunchEnvironment, options: {
+    deepLinkUrl: string;
+    storeUrl: string;
+}): MobileRedirectHandle;
+/** Android. `canUseDeferredDeepLinksFlow` (default `true`) gates the
+ *  clipboard-write + hidden-iframe probe + Play Store market-intent
+ *  fallback; `false` is a plain redirect to the share URL. */
+export declare function redirectToAndroid(env: LaunchEnvironment, options: {
+    deepLinkUrl: string;
+    marketIntentUrl: string;
+    shareUrl: string;
+    canUseDeferredDeepLinksFlow: boolean;
+}): MobileRedirectHandle;
+/** Builds the Play Store market-intent fallback URL, ported from
+ *  `redirectToInstantApp`'s `deepLink` construction.
+ *
+ *  The legacy JS SDK put the verification URL in `url=`. Play never read it —
+ *  Play forwards exactly one parameter to the installed app, `referrer`, via
+ *  the Install Referrer API, so `url=` has always been inert and only the
+ *  clipboard carried a deferred install across the Play Store. This emits
+ *  `referrer=` instead, which `reclaim-verifier-app`'s
+ *  `checkInstallReferrerForLink` (`lib/widgets/link_handler.dart`) now reads
+ *  via `PlayInstallReferrer.installReferrer`. `url=` is dropped rather than
+ *  kept alongside `referrer=`: nothing in this codebase or the verifier app
+ *  reads it (the app has no `queryParameters['url']` handling anywhere), so
+ *  it would be dead weight carried forward for no reason.
+ *
+ *  Exactly one layer of `encodeURIComponent` is applied to `shareUrl` here:
+ *   - `referrer` is itself a query-string value inside this intent URI, so it
+ *     needs at least one layer to survive the `?`/`&`/`=` characters in
+ *     `shareUrl` without corrupting the outer intent.
+ *   - Play decodes exactly one layer of percent-encoding off the referrer
+ *     string before handing it to the app — the app's
+ *     `_parseBuilderReferrerUri` documents this and tries the raw string
+ *     first. One layer here round-trips to the literal share URL on the
+ *     other side. The app also falls back to `Uri.decodeFull` if the raw
+ *     string doesn't parse, tolerating an extra layer either way, but this
+ *     is deliberately exactly one layer rather than leaning on that
+ *     fallback.
+ *
+ *  Play truncates the referrer string at roughly 1KB. A Builder verification
+ *  URL is a UUID and two query parameters, comfortably under that — which is
+ *  what makes this viable where the legacy SDK's base64 `template=` payload
+ *  never could be (see the launch-api plan's "Install Referrer beats the
+ *  clipboard"). Keep the clipboard write in `redirectToAndroid` regardless:
+ *  it is still the only carrier for an install that did not come through
+ *  Play, and the app still reads it. */
+export declare function buildAndroidMarketIntentUrl(shareUrl: string, androidDeepLinkPackage: string): string;

package/lib/launch/mobile.js

@@ -0,0 +1,124 @@
+/** How long to wait for the OS to hand off to the app before deciding it is
+ *  not installed and sending the claimant to the Play Store. The tab
+ *  backgrounding is the only signal a page gets, and it arrives quickly when
+ *  it arrives at all. */
+const ANDROID_STORE_FALLBACK_MS = 1500;
+function writeClipboardBestEffort(env, text) {
+    env.navigator?.clipboard?.writeText(text)?.catch(() => {
+        // Clipboard access can be denied (permissions, insecure context); the
+        // deep link/store redirect below is the fallback either way.
+    });
+}
+/** iOS, `useAppClip: true`. A one-way redirect — nothing to probe or fall
+ *  back from, so `close()` is a no-op. */
+export function redirectToAppClip(env, appClipUrl) {
+    env.navigate(appClipUrl);
+    return { close() { } };
+}
+/** iOS, `useAppClip: false` (the default): try the custom-scheme deep link,
+ *  fall back to the App Store after 3s if the tab never backgrounded (i.e.
+ *  the OS never handed off to the app). */
+export function redirectToIosDeepLink(env, options) {
+    writeClipboardBestEffort(env, options.deepLinkUrl);
+    let appOpened = false;
+    const onVisibilityChange = () => {
+        if (env.document?.hidden) {
+            appOpened = true;
+        }
+    };
+    env.document?.addEventListener('visibilitychange', onVisibilityChange, { once: true });
+    env.navigate(options.deepLinkUrl);
+    const timeoutHandle = env.setTimeout(() => {
+        env.document?.removeEventListener('visibilitychange', onVisibilityChange);
+        if (!appOpened) {
+            env.navigate(options.storeUrl);
+        }
+    }, 3000);
+    return {
+        close() {
+            env.document?.removeEventListener('visibilitychange', onVisibilityChange);
+            env.clearTimeout(timeoutHandle);
+        },
+    };
+}
+/** Android. `canUseDeferredDeepLinksFlow` (default `true`) gates the
+ *  clipboard-write + hidden-iframe probe + Play Store market-intent
+ *  fallback; `false` is a plain redirect to the share URL. */
+export function redirectToAndroid(env, options) {
+    if (!options.canUseDeferredDeepLinksFlow) {
+        env.navigate(options.shareUrl);
+        return { close() { } };
+    }
+    writeClipboardBestEffort(env, options.shareUrl);
+    // Navigate the tab straight at the custom scheme, rather than probing it
+    // from a hidden iframe first. Chrome on Android has blocked custom-scheme
+    // navigation from an iframe for years — it fails silently, so the probe
+    // never opened the app and the Play Store fallback did all the work, even
+    // for someone who already had the app installed. A top-level navigation
+    // is the only thing the OS acts on, and it is what the iOS branch above
+    // has always done.
+    let appOpened = false;
+    const onVisibilityChange = () => {
+        if (env.document?.hidden) {
+            appOpened = true;
+        }
+    };
+    env.document?.addEventListener('visibilitychange', onVisibilityChange, { once: true });
+    env.navigate(options.deepLinkUrl);
+    // Still here, still visible: the scheme resolved to nothing, so the app is
+    // not installed. Send them to the Play Store, carrying the referrer that
+    // survives the install.
+    const timeoutHandle = env.setTimeout(() => {
+        env.document?.removeEventListener('visibilitychange', onVisibilityChange);
+        if (!appOpened) {
+            env.navigate(options.marketIntentUrl);
+        }
+    }, ANDROID_STORE_FALLBACK_MS);
+    return {
+        close() {
+            env.document?.removeEventListener('visibilitychange', onVisibilityChange);
+            env.clearTimeout(timeoutHandle);
+        },
+    };
+}
+/** Builds the Play Store market-intent fallback URL, ported from
+ *  `redirectToInstantApp`'s `deepLink` construction.
+ *
+ *  The legacy JS SDK put the verification URL in `url=`. Play never read it —
+ *  Play forwards exactly one parameter to the installed app, `referrer`, via
+ *  the Install Referrer API, so `url=` has always been inert and only the
+ *  clipboard carried a deferred install across the Play Store. This emits
+ *  `referrer=` instead, which `reclaim-verifier-app`'s
+ *  `checkInstallReferrerForLink` (`lib/widgets/link_handler.dart`) now reads
+ *  via `PlayInstallReferrer.installReferrer`. `url=` is dropped rather than
+ *  kept alongside `referrer=`: nothing in this codebase or the verifier app
+ *  reads it (the app has no `queryParameters['url']` handling anywhere), so
+ *  it would be dead weight carried forward for no reason.
+ *
+ *  Exactly one layer of `encodeURIComponent` is applied to `shareUrl` here:
+ *   - `referrer` is itself a query-string value inside this intent URI, so it
+ *     needs at least one layer to survive the `?`/`&`/`=` characters in
+ *     `shareUrl` without corrupting the outer intent.
+ *   - Play decodes exactly one layer of percent-encoding off the referrer
+ *     string before handing it to the app — the app's
+ *     `_parseBuilderReferrerUri` documents this and tries the raw string
+ *     first. One layer here round-trips to the literal share URL on the
+ *     other side. The app also falls back to `Uri.decodeFull` if the raw
+ *     string doesn't parse, tolerating an extra layer either way, but this
+ *     is deliberately exactly one layer rather than leaning on that
+ *     fallback.
+ *
+ *  Play truncates the referrer string at roughly 1KB. A Builder verification
+ *  URL is a UUID and two query parameters, comfortably under that — which is
+ *  what makes this viable where the legacy SDK's base64 `template=` payload
+ *  never could be (see the launch-api plan's "Install Referrer beats the
+ *  clipboard"). Keep the clipboard write in `redirectToAndroid` regardless:
+ *  it is still the only carrier for an install that did not come through
+ *  Play, and the app still reads it. */
+export function buildAndroidMarketIntentUrl(shareUrl, androidDeepLinkPackage) {
+    const encodedShareUrl = encodeURIComponent(shareUrl);
+    return `intent://details?id=${androidDeepLinkPackage}`
+        + `&referrer=${encodedShareUrl}`
+        + '#Intent;scheme=market;action=android.intent.action.VIEW;'
+        + 'package=com.android.vending;end;';
+}

package/lib/launch/modal.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The desktop `verifier-app` mechanism: a dependency-free QR dialog over the
+ * share URL, with the QR itself bundled (see ./qr.ts).
+ *
+ * The layout follows the reference JS SDK's `utils/modalUtils.ts`
+ * `QRCodeModal` — same card, same close affordance, same countdown and
+ * progress bar along the bottom — so a consumer moving from `reclaim-js-sdk`
+ * sees the dialog they already know. Two things differ on purpose: the QR is
+ * an inline SVG from the vendored encoder rather than a `qrcode` dependency,
+ * and the countdown can be switched off entirely, because a dialog that
+ * closes itself under a claimant who is still reaching for their phone is
+ * worse than one that waits.
+ */
+import type { LaunchEnvironment } from './environment.ts';
+import type { RenderQr } from './qr.ts';
+export interface ModalOptions {
+    title?: string;
+    description?: string;
+    darkTheme?: boolean;
+    /**
+     * Seconds to keep the dialog open before closing it on the claimant's
+     * behalf, shown as a countdown and a draining progress bar.
+     *
+     * Pass `0` (or `Infinity`) to keep it open until something closes it —
+     * `handle.close()`, the close button, the backdrop, or Escape. The
+     * countdown and bar are then omitted rather than frozen, since a timer
+     * that never moves reads as broken.
+     */
+    autoCloseSeconds?: number;
+    /** Shows the "install the extension" tip, linking here. */
+    extensionUrl?: string;
+    /** Called once, whenever and however the dialog closes. */
+    onClose?(): void;
+}
+export interface ModalHandle {
+    close(): void;
+    /** Seconds left before the dialog closes itself, or `null` when it is
+     *  waiting indefinitely. Reads `0` once closed. */
+    readonly remainingSeconds: number | null;
+}
+/**
+ * Opens the dialog and returns the handle that closes it again.
+ *
+ * Exported from the package root as well as used by `launch()`, so a consumer
+ * who only wants a QR over a share link can open one directly without going
+ * through flow resolution.
+ */
+export declare function showQrModal(env: LaunchEnvironment, url: string, options?: ModalOptions & {
+    renderQr?: RenderQr;
+}): ModalHandle;