@agent-cards/checkout 0.5.0 → 0.7.0

package/dist/cdp.js

@@ -2,6 +2,7 @@ import { BUILTIN_REGISTRY, cardUrlPatterns } from './registry.js';
 import { ApprovalDeclinedError, ApprovalTimeoutError, CardEncryptedError, CheckoutApiError, PaymentOutcomeUnknownError, ProcessorRefusedError, UnsupportedModeError, redactUrl, } from './client.js';
 import { PreparationGate } from './preparation.js';
 import { classifyBraintreeRequest } from './braintree.js';
+import { CheckoutAttachmentError, attachmentDeadline, attachmentFailure, withinAttachmentDeadline } from './attachment.js';
 import { substituteEncryptedFields } from './substitute.js';
 import { hostedFormSubmittedPage } from './hosted-form.js';
 import { CheckoutLifecycle, paymentEndpointGuards } from './lifecycle.js';
@@ -273,6 +274,59 @@ export function withCorsHeaders(headers, cors) {
 function headerEntries(headers) {
     return Object.entries(headers).map(([name, value]) => ({ name, value: String(value) }));
 }
+/**
+ * The origin of the top-level document the payment form is on, read when a
+ * card request pauses: the fact that names the merchant for the company's
+ * presets (the API's checkout_origin). An https origin, or http://localhost
+ * for local checkout; anything else, or a page that cannot be read, yields
+ * undefined and the authorization goes out without one (a merchant, category
+ * or place rule then refuses it as unknown, never the request itself).
+ */
+async function pageOriginOf(readDocumentUrl) {
+    try {
+        const url = new URL(await readDocumentUrl());
+        if (url.username || url.password)
+            return undefined;
+        if (url.protocol === 'https:' || (url.protocol === 'http:' && url.hostname === 'localhost'))
+            return url.origin;
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The page total, the lowest amount authority, through the integrator's own
+ * reader (AttachOptions.pageAmount): an integer in the smallest unit with its
+ * currency, or nothing. A read is a courtesy, never a wait: it gets one
+ * second, and anything unreadable yields undefined so the authorization goes
+ * out without a page total.
+ */
+const PAGE_AMOUNT_READ_MS = 1_000;
+async function pageAmountOf(opts) {
+    if (!opts.pageAmount)
+        return undefined;
+    let timer;
+    try {
+        const raw = await Promise.race([
+            Promise.resolve().then(() => opts.pageAmount()).catch(() => undefined),
+            new Promise((resolve) => { timer = setTimeout(() => resolve(undefined), PAGE_AMOUNT_READ_MS); }),
+        ]);
+        if (!raw || typeof raw !== 'object')
+            return undefined;
+        const { amount, currency } = raw;
+        if (!Number.isSafeInteger(amount) || amount < 0 || typeof currency !== 'string' || !/^[A-Za-z]{3}$/.test(currency))
+            return undefined;
+        return { amount: amount, currency: currency.toLowerCase() };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Last-resort patterns: the built-in recognizers' hosts, derived the same way
  * as everything else. Used only when the vault hands back nothing at all (a
@@ -328,17 +382,23 @@ function merchantAttempt(lifecycle) {
  */
 export async function attachToCdp(cdp, pageSessionId, opts) {
     opts = safeOptions(opts);
+    const setupTimeoutMs = attachmentDeadline(opts.attachmentTimeoutMs);
+    const setupStop = new AbortController();
+    let attachmentReady = false;
+    let setupFailureReported = false;
     const lifecycle = new CheckoutLifecycle(opts);
     let preparationFrameId;
-    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+    const readDocumentUrl = async () => {
         const tree = await cdp.send('Page.getFrameTree', {}, pageSessionId);
         if (typeof tree?.frameTree?.frame?.url !== 'string')
             throw new Error('merchant_document_unavailable');
         preparationFrameId = tree.frameTree.frame.id;
         return tree.frameTree.frame.url;
-    });
+    };
+    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     const armed = new Set();
+    const arming = new Map();
     // Set once a failure proves that retrying cannot help; see isTerminal.
     let terminal = null;
     // Silence window after a person declined or ignored one; see APPROVAL_COOLDOWN_MS.
@@ -352,23 +412,48 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
     let lastSubmitted = null;
     const derived = typeof opts.vault?.cardUrlPatterns === 'function' ? opts.vault.cardUrlPatterns() : [];
     const urlPatterns = [...new Set([...(derived.length > 0 ? derived : FALLBACK_CARD_PATTERNS), ...guards.patterns])];
-    opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
-    const arm = async (sessionId) => {
+    const arm = async (sessionId, resume = false) => {
         const key = sessionId ?? '__root__';
         if (armed.has(key))
             return;
+        if (arming.has(key))
+            return arming.get(key);
         // Fetch's interception ID differs from Network's ID. Enable failure events
         // before intercepting and bind each attempt to both its ID and CDP session.
-        await cdp.send('Network.enable', {}, sessionId);
-        await cdp.send('Page.enable', {}, sessionId).catch(() => { });
-        await cdp.send('Fetch.enable', {
-            patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
-        }, sessionId);
-        // Descend into this target's own children (iframes inside iframes).
-        await cdp.send('Target.setAutoAttach', {
-            autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
-        }, sessionId);
-        armed.add(key);
+        const pending = withinAttachmentDeadline(async (assertActive) => {
+            await cdp.send('Network.enable', {}, sessionId);
+            assertActive();
+            await cdp.send('Page.enable', {}, sessionId).catch(() => { });
+            assertActive();
+            await cdp.send('Fetch.enable', {
+                patterns: urlPatterns.map((urlPattern) => ({ urlPattern, requestStage: 'Request' })),
+            }, sessionId);
+            assertActive();
+            // Descend into this target's own children (iframes inside iframes).
+            await cdp.send('Target.setAutoAttach', {
+                autoAttach: true, waitForDebuggerOnStart: true, flatten: true,
+            }, sessionId);
+            assertActive();
+            // A child remains part of setup until Chrome acknowledges its resume.
+            // Deduplicate this command with arming, and bound the acknowledgement too.
+            if (resume) {
+                await cdp.send('Runtime.runIfWaitingForDebugger', {}, sessionId);
+                assertActive();
+            }
+        }, setupTimeoutMs, setupStop.signal);
+        arming.set(key, pending);
+        try {
+            await pending;
+            armed.add(key);
+        }
+        catch (error) {
+            const failure = attachmentFailure(error);
+            setupStop.abort(failure);
+            throw failure;
+        }
+        finally {
+            arming.delete(key);
+        }
     };
     cdp.on(async (method, params, sessionId) => {
         if (((method === 'Page.frameNavigated' && !params.frame?.parentId) || (method === 'Page.navigatedWithinDocument' && preparationFrameId && params.frameId === preparationFrameId)) && sessionId === pageSessionId) {
@@ -379,6 +464,7 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
         }
         if ((method === 'Inspector.detached' && sessionId === pageSessionId)
             || (method === 'Target.detachedFromTarget' && params.sessionId === pageSessionId)) {
+            setupStop.abort(new CheckoutAttachmentError('closed'));
             preparationGate.invalidate('merchant_document_closed');
             // The root page owns every attached OOPIF; its loss ends child requests too.
             activeRequest?.attempt.stop();
@@ -396,19 +482,25 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             return;
         }
         if (method === 'Target.attachedToTarget') {
+            if (setupStop.signal.aborted)
+                return;
             const child = params.sessionId;
             try {
-                await arm(child);
+                await arm(child, true);
             }
-            catch {
+            catch (error) {
+                // Shared child setup and sibling cancellation can reject several
+                // handlers together. Publish the terminal setup failure only once.
+                if (setupFailureReported)
+                    return;
+                setupFailureReported = true;
+                setupStop.abort(attachmentFailure(error));
                 terminal = new Error('browser_interception_unavailable');
                 lifecycle.failed(new PaymentOutcomeUnknownError(lifecycle.getState().authorizationId, 'browser_interception_unavailable'));
                 opts.onEvent?.({ type: 'failed', detail: 'browser_interception_unavailable' });
                 // Leave this target paused: resuming an unarmed card frame would silently bypass the vault.
                 return;
             }
-            // Child targets start paused when waitForDebuggerOnStart is set.
-            await cdp.send('Runtime.runIfWaitingForDebugger', {}, child).catch(() => { });
             return;
         }
         if (method !== 'Fetch.requestPaused')
@@ -438,9 +530,14 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             await cdp.send('Fetch.continueRequest', { requestId }, sessionId).catch(() => { });
             return;
         }
+        if (!attachmentReady || arming.has(sessionId ?? '__root__') || setupStop.signal.aborted) {
+            opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
+            await cdp.send('Fetch.failRequest', { requestId, errorReason: 'Aborted' }, sessionId).catch(() => { });
+            return;
+        }
         let preparation;
         try {
-            preparation = preparationGate.claim(request.url, braintree === 'tokenization' ? pausedBody(request) : undefined);
+            preparation = preparationGate.claim(request.url, pausedBody(request));
         }
         catch (error) {
             opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
@@ -490,14 +587,17 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
             activeRequest = { attempt, networkId, sessionId, frameId };
             if (preparation)
                 await preparationGate.assertDocument();
+            const pageOrigin = await pageOriginOf(readDocumentUrl);
+            const pageAmount = await pageAmountOf(opts);
             attempt.assertLive();
             const replay = await opts.vault.authorize({
                 user: opts.user,
                 merchant: opts.merchant,
                 amount: opts.amount,
-                amountCents: opts.amountCents,
                 currency: opts.currency,
                 cardId: preparation?.cardId ?? opts.cardId,
+                pageOrigin,
+                pageAmount,
                 preparation,
                 timeoutMs: opts.timeoutMs,
                 signal: lifecycle.abort.signal,
@@ -590,7 +690,24 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
                 preparationGate.retireUnboundClaim();
         }
     });
-    await arm(pageSessionId);
+    try {
+        await arm(pageSessionId);
+        if (setupStop.signal.aborted)
+            throw attachmentFailure(setupStop.signal.reason);
+        attachmentReady = true;
+        opts.onEvent?.({ type: 'fetch_armed', detail: { patterns: urlPatterns } });
+    }
+    catch (error) {
+        const failure = attachmentFailure(error);
+        setupStop.abort(failure);
+        terminal = failure;
+        if (!setupFailureReported) {
+            setupFailureReported = true;
+            lifecycle.cancel();
+            opts.onEvent?.({ type: 'failed', detail: `checkout_attachment_${failure.reason}` });
+        }
+        throw failure;
+    }
     return lifecycle;
 }
 /**
@@ -606,17 +723,21 @@ export async function attachToCdp(cdp, pageSessionId, opts) {
  */
 export async function attachToPlaywright(page, opts) {
     opts = safeOptions(opts);
+    const setupTimeoutMs = attachmentDeadline(opts.attachmentTimeoutMs);
+    const setupStop = new AbortController();
+    let attachmentReady = false;
     // Routing cannot see requests owned by a service worker. Existing controlled
     // contexts must be recreated with serviceWorkers: 'block' before checkout.
     if (page.context?.().serviceWorkers?.().length) {
         throw new Error('Service workers are active; use a checkout context created with serviceWorkers: "block".');
     }
     const lifecycle = new CheckoutLifecycle(opts);
-    const preparationGate = new PreparationGate(opts, lifecycle, async () => {
+    const readDocumentUrl = async () => {
         if (page.isClosed?.() || typeof page.url !== 'function')
             throw new Error('merchant_document_unavailable');
         return page.url();
-    });
+    };
+    const preparationGate = new PreparationGate(opts, lifecycle, readDocumentUrl);
     const guards = paymentEndpointGuards(opts.paymentEndpoints);
     // Playwright's own routing, NOT a hand-rolled CDP session.
     //
@@ -642,8 +763,10 @@ export async function attachToPlaywright(page, opts) {
         if (activeRequest && activeRequest.request === request)
             activeRequest.attempt.stop();
     });
-    page.on?.('close', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
-    page.on?.('crash', () => { preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('close', () => { if (!attachmentReady)
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
+    page.on?.('crash', () => { if (!attachmentReady)
+        setupStop.abort(new CheckoutAttachmentError('closed')); preparationGate.invalidate('merchant_document_closed'); activeRequest?.attempt.stop(); });
     page.on?.('framenavigated', (frame) => {
         if (frame === page.mainFrame?.()) {
             preparationGate.invalidate('merchant_document_changed');
@@ -658,147 +781,178 @@ export async function attachToPlaywright(page, opts) {
     // The hosted form the cardholder already submitted; see HOSTED_FORM_REPEAT_QUIET_MS.
     const repeatQuietMs = opts.hostedFormRepeatQuietMs ?? HOSTED_FORM_REPEAT_QUIET_MS;
     let lastSubmitted = null;
-    await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
-        const request = route.request();
-        const braintree = request.method().toUpperCase() === 'POST'
-            ? classifyBraintreeRequest(request.url(), request.method(), request.postData() ?? '') : undefined;
-        if (braintree === 'configuration')
-            return route.fallback();
-        if (braintree === 'invalid') {
-            opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
-            return route.abort('aborted');
+    const install = async (assertActive) => {
+        if (page.isClosed?.()) {
+            const failure = new CheckoutAttachmentError('closed');
+            setupStop.abort(failure);
+            throw failure;
         }
-        // The matcher only sees the URL; a preflight or a GET must pass through
-        // untouched or the browser's CORS check fails on our synthetic answer.
-        if (!opts.vault.isCardRequest(request.url(), request.method())) {
-            if (guards.matches(request.url(), request.method())) {
-                preparationGate.invalidate('unsupported_checkout');
-                lifecycle.unsupported();
-                opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+        await page.route((url) => opts.vault.isCardRequest(url.toString()) || guards.matches(url.toString()), async (route) => {
+            const request = route.request();
+            const braintree = request.method().toUpperCase() === 'POST'
+                ? classifyBraintreeRequest(request.url(), request.method(), request.postData() ?? '') : undefined;
+            if (braintree === 'configuration')
+                return route.fallback();
+            if (braintree === 'invalid') {
+                opts.onEvent?.({ type: 'blocked', detail: 'unsupported_braintree_graphql_operation' });
                 return route.abort('aborted');
             }
-            return route.fallback();
-        }
-        let preparation;
-        try {
-            preparation = preparationGate.claim(request.url(), braintree === 'tokenization' ? request.postData() ?? '' : undefined);
-        }
-        catch (error) {
-            opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
-            return route.abort('aborted');
-        }
-        // Fail closed and stay quiet: no card may reach the PSP, but neither may
-        // the page's retry loop turn into a stream of doomed API calls. Every
-        // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
-        // CDP adapter's Fetch.failRequest uses, so a refused navigation
-        // resolves identically whichever adapter is attached.
-        if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
-            const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
-            opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
-            if (preparation)
-                preparationGate.retireUnboundClaim();
-            return route.abort('aborted');
-        }
-        // Reserved before anything that could yield, matching attachToCdp.
-        awaitingApproval = true;
-        const attempt = merchantAttempt(lifecycle);
-        const frames = [];
-        try {
-            for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
-                frames.push(frame);
-        }
-        catch { /* requestfailed/page close still cover unavailable frame metadata */ }
-        const assertRequestLive = () => {
-            if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
-                attempt.stop();
-            attempt.assertLive();
-        };
-        let handoffStarted = false;
-        try {
-            const body = request.postData() ?? '';
-            if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
-                opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
-                return await route.abort('aborted');
+            // The matcher only sees the URL; a preflight or a GET must pass through
+            // untouched or the browser's CORS check fails on our synthetic answer.
+            if (!opts.vault.isCardRequest(request.url(), request.method())) {
+                if (guards.matches(request.url(), request.method())) {
+                    preparationGate.invalidate('unsupported_checkout');
+                    lifecycle.unsupported();
+                    opts.onEvent?.({ type: 'unsupported_checkout', detail: { url: redactUrl(request.url()), method: request.method() } });
+                    return route.abort('aborted');
+                }
+                return route.fallback();
             }
-            opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
-            lifecycle.begin();
-            activeRequest = { request, frames, attempt };
-            if (preparation)
-                await preparationGate.assertDocument();
-            assertRequestLive();
-            const replay = await opts.vault.authorize({
-                user: opts.user,
-                merchant: opts.merchant,
-                amount: opts.amount,
-                amountCents: opts.amountCents,
-                currency: opts.currency,
-                cardId: preparation?.cardId ?? opts.cardId,
-                preparation,
-                timeoutMs: opts.timeoutMs,
-                signal: lifecycle.abort.signal,
-                merchantSignal: attempt.signal,
-                onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
-                onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
-                    lifecycle.approvalUrl(url);
-                    return opts.onApprovalUrl?.(url);
-                } },
-                request: { url: request.url(), method: request.method(), headers: request.headers(), body },
-            });
-            assertRequestLive();
-            if (lifecycle.isCancelled())
-                throw new Error('checkout cancelled locally after approval');
-            lifecycle.prepareHandoff(replay, request.url());
-            handoffStarted = replay.mode !== 'cse';
-            if (replay.mode === 'hosted_form') {
-                // Same as the CDP path: the paused navigation resolves to the
-                // synthetic page, and a re-post of this form is refused.
-                const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
-                // Inert on a navigation (never CORS-checked); one path for every fulfill.
-                await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
-                assertRequestLive();
-                lastSubmitted = { url: request.url(), body, at: Date.now() };
-                opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+            if (!attachmentReady || setupStop.signal.aborted) {
+                opts.onEvent?.({ type: 'blocked', detail: 'checkout_interception_not_ready' });
+                return route.abort('aborted');
             }
-            else if (replay.mode === 'cse') {
-                // Same as the CDP path: the request continues from this browser
-                // with the ciphertext swapped in and no header override; Playwright
-                // recomputes the length itself.
-                const postData = cseBody(body, replay);
-                handoffStarted = true;
-                await route.continue({ postData });
-                assertRequestLive();
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+            let preparation;
+            try {
+                preparation = preparationGate.claim(request.url(), request.postData() ?? '');
             }
-            else {
-                // Playwright adds these itself when a cross-origin fulfill carries
-                // none; written here anyway (replacing a stale value) so a
-                // cross-origin answer is the same whichever adapter ran.
-                const cors = corsDecision(request.url(), request.headers());
-                await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+            catch (error) {
+                opts.onEvent?.({ type: 'blocked', detail: failureSummary(error) });
+                return route.abort('aborted');
+            }
+            // Fail closed and stay quiet: no card may reach the PSP, but neither may
+            // the page's retry loop turn into a stream of doomed API calls. Every
+            // abort in this adapter is 'aborted' (ERR_ABORTED), the same code the
+            // CDP adapter's Fetch.failRequest uses, so a refused navigation
+            // resolves identically whichever adapter is attached.
+            if (terminal || lifecycle.isBlocked() || awaitingApproval || Date.now() < quietUntil) {
+                const why = terminal ?? (lifecycle.isBlocked() ? lifecycle.getState().status : awaitingApproval ? 'an approval is already outstanding' : 'awaiting approval cooldown');
+                opts.onEvent?.({ type: 'blocked', detail: why instanceof Error ? failureSummary(why) : String(why) });
+                if (preparation)
+                    preparationGate.retireUnboundClaim();
+                return route.abort('aborted');
+            }
+            // Reserved before anything that could yield, matching attachToCdp.
+            awaitingApproval = true;
+            const attempt = merchantAttempt(lifecycle);
+            const frames = [];
+            try {
+                for (let frame = request.frame?.(); frame; frame = frame.parentFrame?.())
+                    frames.push(frame);
+            }
+            catch { /* requestfailed/page close still cover unavailable frame metadata */ }
+            const assertRequestLive = () => {
+                if (request.failure?.() || page.isClosed?.() || frames.some(frame => frame.isDetached?.()))
+                    attempt.stop();
+                attempt.assertLive();
+            };
+            let handoffStarted = false;
+            try {
+                const body = request.postData() ?? '';
+                if (isRepeatOfSubmitted(lastSubmitted, request.url(), body, repeatQuietMs)) {
+                    opts.onEvent?.({ type: 'blocked', detail: HOSTED_FORM_REPEAT_REASON });
+                    return await route.abort('aborted');
+                }
+                opts.onEvent?.({ type: 'card_request_paused', detail: { url: redactUrl(request.url()) } });
+                lifecycle.begin();
+                activeRequest = { request, frames, attempt };
+                if (preparation)
+                    await preparationGate.assertDocument();
+                const pageOrigin = await pageOriginOf(readDocumentUrl);
+                const pageAmount = await pageAmountOf(opts);
                 assertRequestLive();
-                opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
+                const replay = await opts.vault.authorize({
+                    user: opts.user,
+                    merchant: opts.merchant,
+                    amount: opts.amount,
+                    currency: opts.currency,
+                    cardId: preparation?.cardId ?? opts.cardId,
+                    pageOrigin,
+                    pageAmount,
+                    preparation,
+                    timeoutMs: opts.timeoutMs,
+                    signal: lifecycle.abort.signal,
+                    merchantSignal: attempt.signal,
+                    onAuthorizationCreated: (id) => lifecycle.approvalCreated(id),
+                    onApprovalUrl: (url) => { if (!preparation && !attempt.signal.aborted) {
+                        lifecycle.approvalUrl(url);
+                        return opts.onApprovalUrl?.(url);
+                    } },
+                    request: { url: request.url(), method: request.method(), headers: request.headers(), body },
+                });
+                assertRequestLive();
+                if (lifecycle.isCancelled())
+                    throw new Error('checkout cancelled locally after approval');
+                lifecycle.prepareHandoff(replay, request.url());
+                handoffStarted = replay.mode !== 'cse';
+                if (replay.mode === 'hosted_form') {
+                    // Same as the CDP path: the paused navigation resolves to the
+                    // synthetic page, and a re-post of this form is refused.
+                    const synthetic = hostedFormSubmittedPage({ authorizationId: replay.authorizationId, merchant: opts.merchant, submittedAt: replay.submittedAt });
+                    // Inert on a navigation (never CORS-checked); one path for every fulfill.
+                    await route.fulfill({ status: synthetic.status, headers: withCorsHeaders(synthetic.headers, corsHeadersFor(request.url(), request.headers())), body: synthetic.body });
+                    assertRequestLive();
+                    lastSubmitted = { url: request.url(), body, at: Date.now() };
+                    opts.onEvent?.({ type: 'submitted_on_device', detail: { authorizationId: replay.authorizationId, submittedAt: replay.submittedAt, outcome: replay.outcome } });
+                }
+                else if (replay.mode === 'cse') {
+                    // Same as the CDP path: the request continues from this browser
+                    // with the ciphertext swapped in and no header override; Playwright
+                    // recomputes the length itself.
+                    const postData = cseBody(body, replay);
+                    handoffStarted = true;
+                    await route.continue({ postData });
+                    assertRequestLive();
+                    opts.onEvent?.({ type: 'authorized', detail: { mode: 'cse', authorizationId: replay.authorizationId, fields: Object.keys(replay.substitutions.fields) } });
+                }
+                else {
+                    // Playwright adds these itself when a cross-origin fulfill carries
+                    // none; written here anyway (replacing a stale value) so a
+                    // cross-origin answer is the same whichever adapter ran.
+                    const cors = corsDecision(request.url(), request.headers());
+                    await route.fulfill({ status: replay.status, headers: withCorsHeaders(replay.headers, cors.headers), body: replay.body });
+                    assertRequestLive();
+                    opts.onEvent?.({ type: 'authorized', detail: { mode: 'token', authorizationId: replay.authorizationId, amountVerified: replay.amountVerified ?? null, cors: cors.outcome } });
+                }
+                lifecycle.handedOff(replay);
             }
-            lifecycle.handedOff(replay);
-        }
-        catch (err) {
-            if (activeRequest?.attempt === attempt)
-                activeRequest = null;
-            lifecycle.failed(err, handoffStarted);
-            if (isTerminal(err))
-                terminal = err;
-            else if (isApprovalOutcome(err))
-                quietUntil = Date.now() + cooldownMs;
-            opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
-            await route.abort('aborted').catch(() => { });
-        }
-        finally {
-            if (activeRequest?.attempt === attempt)
-                activeRequest = null;
-            awaitingApproval = false;
-            lifecycle.end();
-            if (preparation)
-                preparationGate.retireUnboundClaim();
-        }
-    });
+            catch (err) {
+                if (activeRequest?.attempt === attempt)
+                    activeRequest = null;
+                lifecycle.failed(err, handoffStarted);
+                if (isTerminal(err))
+                    terminal = err;
+                else if (isApprovalOutcome(err))
+                    quietUntil = Date.now() + cooldownMs;
+                opts.onEvent?.({ type: 'failed', detail: failureSummary(err) });
+                await route.abort('aborted').catch(() => { });
+            }
+            finally {
+                if (activeRequest?.attempt === attempt)
+                    activeRequest = null;
+                awaitingApproval = false;
+                lifecycle.end();
+                if (preparation)
+                    preparationGate.retireUnboundClaim();
+            }
+        });
+        assertActive();
+    };
+    try {
+        await withinAttachmentDeadline(install, setupTimeoutMs, setupStop.signal);
+        if (setupStop.signal.aborted)
+            throw attachmentFailure(setupStop.signal.reason);
+        attachmentReady = true;
+    }
+    catch (error) {
+        const failure = attachmentFailure(error);
+        setupStop.abort(failure);
+        terminal = failure;
+        lifecycle.cancel();
+        opts.onEvent?.({ type: 'failed', detail: `checkout_attachment_${failure.reason}` });
+        // A route registration may finish after this rejection. Keep its handler
+        // inert for card traffic; removing it would reopen the failed checkout.
+        throw failure;
+    }
     return lifecycle;
 }