Checkout loader lifecycle

Implementation scope: the route-local Paddle payment-link page and the shared plan button's pending treatment. No provider switch, server changes, deployment, production payment, subscription mutation, credentials or CSP widening.

Authoritative Paddle references

Verified against the Paddle developer documentation during implementation:

• https://developer.paddle.com/paddle-js/events/checkout-loadedcheckout.loaded is emitted when a checkout is created and loaded on the page, once per checkout. This is the overlay-open/loading settlement signal. There is no checkout.opened listener in this implementation; the browser regression deliberately fires that invented name as a negative control. A ready value in data.status describes payment-field completeness, not initial UI readiness.
• https://developer.paddle.com/paddle-js/events/checkout-errorcheckout.error is a fatal checkout startup error. A warning or failed payment attempt is not equivalent: neither should tear down a customer's usable checkout.
• https://developer.paddle.com/paddle-js/events/checkout-completed Completion may mean instant capture or authorization pending capture. The page says "Checkout completed", not "Payment received". Backend webhooks, not this browser event, remain authoritative for account/credit state.
• https://developer.paddle.com/paddle-js/events/checkout-closed Both user dismissal and Paddle.Checkout.close() may emit this event. Mark a startup failure terminal BEFORE closing so it cannot become a canceled redirect.
• https://developer.paddle.com/paddle-js/methods/paddle-initialize Initialize is allowed only once per page. A page ref and module-level guard protect against repeated effects, refetches, concurrent calls and SPA revisits.
• https://developer.paddle.com/build/transactions/default-payment-link Explicit Checkout.open({transactionId}) takes priority over automatic _ptxn handling. Transaction validation and trusted same-origin URL checks are unchanged.

State and recovery decisions

• Loading spans summary, CDN script and the interval between Checkout.open returning and checkout.loaded. Resolving openPaddleCheckout is NOT readiness.
• The checkout summary uses its own ["billing", "checkout", transaction] snapshot rather than sharing the sidebar credits query's in-flight promise. Otherwise the sidebar's request can bypass the checkout timeout and network-error handling. The sidebar still makes its ordinary summary request even for an invalid link.
• Summary fetch, script load and overlay startup each have a 20-second bound. These are local UX limits, not Paddle's SLA or a payment deadline. There is no deadline on a loaded overlay while the customer is entering payment details.
• HTTP, network, SDK-global/script, invalid transaction, disabled/wrong provider, missing/invalid configuration, thrown startup and checkout.error failures render an alert instead of an animation. No arbitrary provider event detail is rendered. The SDK is never requested with an invalid transaction/config/provider.
• Loaded events are idempotent; completed/closed/failure are terminal. Duplicates and late events cannot restart the animation, cancel a completed checkout, or schedule repeated redirects. Completion retains the existing 1.5-second delay; cancellation retains the full navigation to /billing?checkout=canceled.
• Retry is an ordinary same-origin link to the validated payment-link URL. It reloads the document instead of calling Initialize a second time. Back to billing is also a full navigation and is available during loading and errors. Leaving via the SPA navigation during SDK load suppresses late initialization; revisiting without a reload offers the same safe recovery rather than re-init.
• Existing sandbox selection, trusted URL/transaction helpers, missing-email remediation, route-local SDK loading and nginx CSP are preserved.

Accessibility and presentation

A lime-accent ring and lock mark match the existing dark dashboard; animation is purely decorative (aria-hidden). A stable polite role=status, atomic text and screen-reader-only neutral label announce "Loading checkout…" once, not again for each asynchronous stage. Loading errors use an alert and clear that status. The spinner is removed at checkout.loaded/terminal/failure, not simply hidden behind the provider. The card keeps the same bounding box between loading and ready. motion-safe:animate-spin with motion-reduce:animate-none leaves a static mark under reduced motion. Selected plan buttons show a small decorative spinner plus "Processing…", retain their plan-specific accessible name, expose aria-busy and disable all plan actions while pending. No full-page loader is used in buttons. Those buttons render inside the shared Billing Upgrade picker, so the two /billing plan-control regressions open that picker first; the pending treatment itself is unchanged by that composition.

Scoped verification

Run inside the isolated worktree with Node 24 (system Node 12 is insufficient):

export PATH=/home/nyanpasu/.local/share/fnm/node-versions/v24.22.1/installation/bin:$PATH
corepack pnpm install --frozen-lockfile
corepack pnpm --filter @scrapingcow/ui typecheck
corepack pnpm --filter @scrapingcow/ui build
BROWSER_SWEEP_REQUIRED=1 node --test apps/ui/tests/billing.test.mjs apps/ui/tests/paths.test.mjs apps/ui/tests/billing-routes.test.mjs apps/ui/tests/checkout-loader.test.mjs apps/ui/tests/upgrade-sheet.test.mjs

checkout-loader.test.mjs drives the actual built route and SDK adapter in Chrome. Only API and CDN boundaries are mocked; the SDK mock is intentionally inert until tests fire documented events. Unexpected external requests are aborted, service workers are blocked, and no provider is contacted. Set CHECKOUT_EVIDENCE_DIR to save desktop, mobile, reduced-motion, ready, completed and failure screenshots. The "ready" screenshot shows our background state, NOT a real Paddle overlay. Tests also measure bounding boxes, live-region text mutations, reduced-motion computed styles, safe reload recovery, one-time initialization and terminal events.

Full UI suites and independent integrated-commit desktop/mobile/accessibility and local live-stack verification belong to reviewer t_93d09268. A local mocked pass does not prove provider availability, real overlay rendering, production behavior, webhook delivery or deployment. Manual assistive-technology listening and real sandbox provider compatibility remain distinct from DOM/announcement evidence.