@asstio-dev/storefront 0.7.0 → 0.9.2

package/README.md

@@ -193,6 +193,120 @@ case-insensitively, or key prefix — returning at most 50. A facet with more di
 over its top 1000; no regular expression ever reaches the search index. `key` has to be a `list` or `swatch` facet:
 an unknown key is `FACET_NOT_FOUND` (404), and a range or toggle facet is `FACET_NOT_SEARCHABLE` (400).
 
+### Checkout
+
+Two small modules, because the suspend → update → resume rule spans two runtimes. The server helpers need the
+client and the cart token (an `httpOnly` cookie, so they run in Server Actions and route handlers);
+`mountCheckout` needs neither key nor fetch — it mounts the provider's widget and drives it from the answers
+your server hands it.
+
+```ts
+import { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, mountCheckout, startCheckout, syncCheckout } from "@asstio-dev/storefront";
+```
+
+**Server.** `startCheckout(client, cartToken, { option?, returnOrigin? })` creates the cart's checkout attempt
+or converges on the live one; call it from a Server Action or route handler **on the shopper's navigation to the
+checkout page, never during a Server Component's render** (a re-render would create a provider order per
+mutation). `syncCheckout` is the same `POST /v1/checkout`, retrying `CHECKOUT_IN_PROGRESS` per `Retry-After`
+twice by default — **call it after every cart mutation on the checkout page**, through the browser handle's
+`update`; there, and for the handle's `sync`, pass `{ retries: 0 }` so each call is one POST and the handle's own
+burst does the retrying. `getCheckoutStatus(client, attemptId, cartToken)` is the non-mutating
+`GET /v1/checkout/{attemptId}` behind the handle's `status` callback.
+`completeCheckout(client, attemptId, cartToken?)` is the confirmation page's call; with the cart token
+the answer carries `order.accessToken`, on every call, so a lost first answer or a reload still ends with the token.
+`awaitCompletion(() => completeCheckout(…))` polls with backoff until the order exists. `getOrder(client, orderId,
+token)` sends the token as `X-Order-Token` — a header, never a query string; send `Referrer-Policy: no-referrer`
+on the order page and keep its URL out of your logs.
+
+```ts
+// A Server Action or route handler, on the shopper's navigation to the checkout page.
+const result = await startCheckout(storefront, cartToken, { returnOrigin: "https://shop.example" });
+if (!result.ok) return { problem: result.problem, retryAfter: result.retryAfter };
+return { checkout: result.data };   // "open" with a widget, or "completed"/"pending" with an order
+
+// The Server Action behind mountCheckout's `sync`, and the POST inside every cart update: one HTTP POST per call.
+export async function syncForBrowser() {
+  return syncCheckout(storefront, cartToken, undefined, { retries: 0 });
+}
+
+// The confirmation page: complete with the cart token, keep the order's access token, then poll for the number.
+const first = await completeCheckout(storefront, attemptId, cartToken);
+const done = await awaitCompletion(() => completeCheckout(storefront, attemptId, cartToken));
+
+// The order page: the token is a header.
+const order = await getOrder(storefront, orderId, token);   // 404 ORDER_NOT_FOUND for an unknown id and a wrong token alike
+```
+
+**Browser.** `mountCheckout(container, checkout, { sync, status, onProblem, onOrder })` takes the `open` answer
+your page was rendered with and returns a handle `{ attemptId, suspended, suspend, resume, remount, destroy,
+sync(update) }`. The container is a client component **keyed by `attemptId`**. `handle.sync(update)` is the whole
+rule: it suspends the widget, runs your `update` **once** (mutate the cart, `POST /checkout`, return its answer),
+then dispatches **status first, identity on `open`**: `completed`/`pending` → `onOrder(order, attemptId)` (you
+navigate); `locked` → stays suspended and retries `sync()` per `Retry-After` within the API's budget (30 s, ten
+calls — a 429 counts the same; a `Retry-After` past the 30 s is not waited out), then polls `status(attemptId)`;
+`processing` → polls `status()`; `declined`/`expired` → one `sync()`; `open` → resumes when the answer's
+`attemptId` is the mounted one, else remounts from the answer's widget (`changed` only says *this* call created a
+new attempt — never resume on it). A `status()` answer is never dispatched as payable: its `open` leads to one
+non-mutating `sync()`. An `update` that throws leaves the widget suspended. The widget is suspended the moment
+`handle.sync` is called, and stays suspended while another update is queued behind it; a newly queued update ends
+the running sync's waits (a retry or a status poll), so it runs at once. `CHECKOUT_IN_PROGRESS` is retried like
+`locked`, within the same burst. If the provider's script loads late, the handle keeps trying to bind its decline
+signal every half second for as long as the widget is mounted. A 503 `CHECKOUT_UNAVAILABLE` or
+`CHECKOUT_PROVIDER_UNAVAILABLE` is retried per its `Retry-After` by non-mutating syncs within the same budget, then
+reported; any other 503 (`SITE_KEYS_SYNCING`, `SITE_REGISTRY_WARMING`) and every other non-2xx of the SDK's own calls
+reaches `onProblem(problem, { status })` at once, `status` being the HTTP status — a `409 CHECKOUT_CART_CHANGED`
+carries the corrected cart in `problem.cart`: show it and its warnings, then `handle.sync(() => POST /checkout)`.
+`handle.sync` never rejects. `onProblem` also receives the SDK's own codes: `SDK_SYNC_FAILED` or `SDK_STATUS_FAILED`
+when one of its calls throws (a network failure), `SDK_UPDATE_FAILED` when your `update` throws, and
+`SDK_DISPATCH_FAILED` for any other throw while dispatching (an `onOrder` that throws, an unknown widget controller) —
+each with `{ status: 0 }` and the widget left suspended; `SDK_CHECKOUT_CLOSED` when the one `sync()` after a
+`declined`/`expired` answers closed again, and `SDK_UNKNOWN_STATUS` for an answer status the SDK does not know (both
+`{ status: 200 }`); and `SDK_EMPTY_ANSWER`, which the server helpers return when an answer carried no body (with that
+answer's HTTP status). The SDK also syncs **by itself**: once on the provider's
+payment-declined signal where its JavaScript offers one, when the page becomes visible again while suspended, and
+**three minutes before expiry, timed from the DTO's `expiresInSeconds`** (server-relative, so a browser clock ahead
+of the server's still lands inside the server's five-minute window). An autonomous sync is skipped while another
+sync is running or queued.
+
+```ts
+// A client component, keyed by attemptId so a re-render never resets it.
+const handle = mountCheckout(container, checkout, {
+  sync: callSync,       // a Server Action calling syncForBrowser()
+  status: callStatus,   // a Server Action calling getCheckoutStatus(storefront, attemptId, cartToken)
+  onProblem: (problem) => { /* problem.cart when code === "CHECKOUT_CART_CHANGED"; otherwise the message for problem.code */ },
+  onOrder: (order, attemptId) => { location.assign(`/kassa/tack?attempt=${attemptId}&order=${order.id}`); },
+});
+// Every cart mutation on the page goes through the handle: suspend → your update once → status first, identity on open.
+await handle.sync(() => callAddLine(sku));   // callAddLine mutates the cart, then syncs, and returns that answer
+```
+
+**After completion.** Every cart endpoint answers `410 CART_EXPIRED` for the converted cart, while the cart token
+is still what re-delivers the order's access token — so **a `410` from a cart mutation on the checkout or
+confirmation path does not end the cart cookie**: call `GET /v1/checkout/{attemptId}` (or `POST /checkout`, which
+answers the converted cart's completed attempt) with the same token, navigate to the confirmation from its
+`order`, and clear the cookie only once the confirmation page holds the access token.
+
+**Copy and CSP.** The `pending` state ("awaiting payment approval") is your copy. Each provider's widget needs its
+domains in your CSP: Qliro One `*.qliro.com` (`pago.qit.nu` in the sandbox), Klarna/Kustom `*.klarna.com`
+(`*.kustom.co`), Walley `*.walleypay.com`, plus their `frame-src`/`script-src`/`connect-src` — the provider's
+integration guide lists the exact hosts.
+
+Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `cart`), `CHECKOUT_PREVIEW_KEY`,
+`CHECKOUT_MARKET_MISMATCH` (switch the cart's market first, then sync), `OPTION_NOT_AVAILABLE`,
+`ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE` and `CHECKOUT_PROVIDER_UNAVAILABLE` (503, `Retry-After`),
+`CHECKOUT_IN_PROGRESS` (409, `Retry-After`), `CHECKOUT_PROVIDER_REJECTED` (502), `CHECKOUT_NOT_FOUND`,
+`ORDER_NOT_FOUND`, `SITE_KEYS_SYNCING` (503 for a secret key on a freshly created site, `Retry-After`).
+
+#### Qliro (`qliro-q1`)
+
+- The widget is Qliro's HTML snippet; `mountCheckout` re-creates its scripts so they run.
+- After every cart change, `handle.sync(update)` locks the widget (`q1.lock()`), and resumes it through
+  `q1.onOrderUpdated`, which makes the iframe re-read the order. The widget unlocks only when Qliro's order shows the
+  confirmed total. If it does not within 10 seconds, or the change came before Qliro's script had loaded, the widget is
+  re-rendered from the confirmed checkout instead; it is never unlocked before Qliro shows the confirmed total.
+- When our validation declines a purchase (the cart moved on, the attempt expired, a line is out of stock), Qliro shows
+  its out-of-stock message and fires `q1.onPaymentDeclined`; the SDK then syncs by itself and remounts or resumes.
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.
@@ -234,9 +348,14 @@ Codes you will meet: `SITE_KEY_MISSING`, `SITE_KEY_INVALID`, `SITE_INACTIVE`, `S
 `SITE_REGISTRY_WARMING`, `MARKET_UNKNOWN`, `RATE_LIMITED` (with `retryAfterSeconds`, plus a `Retry-After`
 header), `PRODUCT_NOT_FOUND`, `COLLECTION_NOT_FOUND`, `INVALID_PAGE`, `INVALID_SINCE`, `INVALID_TYPE`,
 `INDEX_UNAVAILABLE` (retry — a preview index is being rebuilt), `NOT_FOUND`, `INVALID_QUERY`,
-`FACET_NOT_FOUND`, `FACET_NOT_SEARCHABLE`.
-
-`SITE_REGISTRY_WARMING` and `INDEX_UNAVAILABLE` are retries, not bugs in your call.
+`FACET_NOT_FOUND`, `FACET_NOT_SEARCHABLE`,
+and, from the checkout ([above](#checkout)): `CART_EMPTY`, `CHECKOUT_CART_CHANGED`, `CHECKOUT_PREVIEW_KEY`,
+`CHECKOUT_MARKET_MISMATCH`, `OPTION_NOT_AVAILABLE`, `ORIGIN_NOT_ALLOWED`, `CHECKOUT_UNAVAILABLE`,
+`CHECKOUT_PROVIDER_UNAVAILABLE`, `CHECKOUT_IN_PROGRESS`, `CHECKOUT_PROVIDER_REJECTED`, `CHECKOUT_NOT_FOUND`,
+`ORDER_NOT_FOUND`, `SITE_KEYS_SYNCING`, `CART_EXPIRED`.
+
+`SITE_REGISTRY_WARMING` and `INDEX_UNAVAILABLE` are retries, not bugs in your call, as are the checkout's
+`CHECKOUT_IN_PROGRESS`, `CHECKOUT_UNAVAILABLE`, `CHECKOUT_PROVIDER_UNAVAILABLE` and `SITE_KEYS_SYNCING` (each with `Retry-After`).
 
 ## Warnings
 

package/dist/checkout/browser.d.ts

@@ -0,0 +1,76 @@
+import { type ProviderWindow } from "./controllers.js";
+import { type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type StatusResult, type StorefrontProblem } from "./types.js";
+export interface MinimalScript {
+    src: string;
+    textContent: string | null;
+    async: boolean;
+    defer: boolean;
+    type: string;
+    getAttributeNames(): string[];
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+    parentNode?: {
+        replaceChild(newNode: unknown, oldNode: unknown): void;
+    } | null;
+}
+export interface MinimalElement {
+    innerHTML: string;
+    querySelectorAll(selector: "script"): ArrayLike<MinimalScript>;
+    appendChild(node: unknown): unknown;
+    ownerDocument?: MinimalDocument | null;
+}
+export interface MinimalDocument {
+    createElement(tag: "script"): MinimalScript;
+    visibilityState: string;
+    addEventListener(type: "visibilitychange", fn: () => void): void;
+    removeEventListener(type: "visibilitychange", fn: () => void): void;
+}
+export interface MinimalWindow {
+    document?: MinimalDocument;
+}
+export interface MountOptions {
+    /** A plain, non-mutating `POST /checkout` (server-side, with the cart token). Recommended: one HTTP POST per call,
+     * `syncCheckout(client, cartToken, opts, { retries: 0 })` — the handle retries `CHECKOUT_IN_PROGRESS` itself inside
+     * its 30 s burst *(plan review 3 #5, final review S1)*. */
+    sync: () => Promise<CheckoutResult>;
+    /** A `GET /checkout/{attemptId}` on the attempt named. */
+    status: (attemptId: string) => Promise<StatusResult>;
+    /** Every non-2xx the SDK's own calls meet, a call of its own that threw, an `update` that threw, and any other
+     * throw while dispatching (`SDK_DISPATCH_FAILED`: an `onOrder` that threw, an unknown controller). A 409
+     * CHECKOUT_CART_CHANGED carries the corrected cart in `problem.cart`. */
+    onProblem: (problem: StorefrontProblem, context: {
+        status: number;
+    }) => void;
+    /** An order exists: navigate to the confirmation from it. The SDK never navigates itself. */
+    onOrder: (order: CheckoutOrderRefDto, attemptId: string) => void;
+    document?: MinimalDocument;
+    window?: ProviderWindow & MinimalWindow;
+    now?: () => number;
+    setTimeout?: (fn: () => void, ms: number) => unknown;
+    clearTimeout?: (handle: unknown) => void;
+    /** The `locked` burst, sized to the API's checkout:{cartToken} policy (20/min): 30 s and at most ten calls (spec
+     * §10.3). The spec's burst is the whole client-side budget: the rolling-minute POST ledger rounds 2–3 added is cut —
+     * the server enforces the policy and a 429 is handled like `locked` *(final review S1)*. */
+    lockedBudgetMs?: number;
+    lockedMaxCalls?: number;
+    pollFirstMs?: number;
+    pollMaxMs?: number;
+    /** How many consecutive `locked` status answers lead to one sync() rather than more polling *(plan review 1 #12)*. */
+    lockedPollsBeforeSync?: number;
+    /** Binding the provider's decline signal until its script has run: every `bindRetryMs` (500 ms) for as long as the
+     * widget is mounted — one interval, no fast and slow phases *(plan review 2 #13, plan review 3 #4, final review S8)*. */
+    bindRetryMs?: number;
+    /** How long before `expiresInSeconds` the SDK syncs by itself (inside the server's five-minute window). */
+    preExpiryMs?: number;
+}
+export interface CheckoutHandle {
+    readonly attemptId: string;
+    readonly suspended: boolean;
+    suspend(): void;
+    resume(): void;
+    remount(checkout: CheckoutDto): void;
+    destroy(): void;
+    /** The whole rule: suspend → `await update()` once → status first, identity on `open`. Never rejects. */
+    sync(update: () => Promise<CheckoutResult>): Promise<void>;
+}
+export declare function mountCheckout(container: MinimalElement, checkout: CheckoutDto, options: MountOptions): CheckoutHandle;

package/dist/checkout/browser.js

@@ -0,0 +1,444 @@
+import { controllerFor } from "./controllers.js";
+import { localProblem } from "./types.js";
+const FINAL_ORDER = new Set(["completed", "pending"]);
+export function mountCheckout(container, checkout, options) {
+    if (checkout.status !== "open" || !checkout.widget)
+        throw new Error("mountCheckout needs an `open` answer with a widget");
+    const doc = options.document ?? globalThis.document;
+    const win = options.window ?? globalThis;
+    if (!doc)
+        throw new Error("mountCheckout needs a document");
+    const setT = options.setTimeout ?? ((fn, ms) => setTimeout(fn, ms));
+    const clearT = options.clearTimeout ?? ((h) => clearTimeout(h));
+    const timers = new Set();
+    // A controller's own timer (qliro-q1's sync deadline) is the handle's: a remount or destroy cancels it.
+    const controllerTimer = (fn, ms) => { const h = setT(() => { timers.delete(h); fn(); }, ms); timers.add(h); };
+    const now = options.now ?? Date.now;
+    const lockedBudgetMs = options.lockedBudgetMs ?? 30_000;
+    const lockedMaxCalls = options.lockedMaxCalls ?? 10;
+    const pollFirstMs = options.pollFirstMs ?? 1000;
+    const pollMaxMs = options.pollMaxMs ?? 10_000;
+    const lockedPollsBeforeSync = options.lockedPollsBeforeSync ?? 3; // *(plan review 1 #12)*
+    const bindRetryMs = options.bindRetryMs ?? 500; // one interval while mounted *(final review S8)*
+    const preExpiryMs = options.preExpiryMs ?? 180_000;
+    let attemptId = checkout.attemptId;
+    let controller = controllerFor(checkout.widget.controller, win, controllerTimer);
+    let suspended = false;
+    // The controller that was last told to suspend: a remount replaces the controller, and a sync still queued behind
+    // it must suspend the new one when it starts *(plan review 2 #11)*.
+    let suspendedOn;
+    let destroyed = false;
+    let generation = 0; // Review Focus 2: a remount or destroy invalidates every running loop and timer
+    // Syncs accepted and not yet finished — the running one and every one queued behind it. Payment stays suspended
+    // while it is above one, an autonomous sync is skipped while it is above zero, and a running sync's waits end as soon
+    // as another is queued behind it *(plan review 2 #11, final review S7, #8)*.
+    let active = 0;
+    let queue = Promise.resolve(); // *(plan review 1 #43)*
+    let unsubscribeDeclined;
+    let expiryTimer;
+    let firedPreExpiryFor; // *(plan review 1 #42, plan review 2 #12)*
+    // Every pending sleep's resolver, so a remount or destroy can settle it instead of clearing its timer and leaving
+    // the promise forever pending: an unsettled dispatch never reaches its `finally`, the queue never drains, and every
+    // later autonomous sync waits for good — and an app awaiting `handle.sync` after `destroy()` waits forever
+    // *(plan review 1 #37)*.
+    // Each sleep's timer is kept with it, so a queued update can end the running sync's waits alone *(final review #8)*.
+    const sleepers = new Map();
+    /** A wait of the running sync — a burst retry or a poll. It answers `false` (stop) when the generation is gone, and
+     * also at once when another sync is queued behind the running one: the shopper's cart update must not wait out a
+     * poll that can last minutes *(final review #8)*. */
+    const sleep = (ms, gen) => new Promise((resolve) => {
+        if (active > 1) {
+            resolve(false);
+            return;
+        }
+        const settle = (alive) => { const h = sleepers.get(settle); sleepers.delete(settle); if (h !== undefined) {
+            clearT(h);
+            timers.delete(h);
+        } resolve(alive); };
+        const h = setT(() => { timers.delete(h); sleepers.delete(settle); resolve(!destroyed && gen === generation); }, ms);
+        sleepers.set(settle, h);
+        timers.add(h);
+    });
+    /** End every pending wait of the running sync with `false`; the binding and expiry timers are left alone. */
+    function endWaits() {
+        for (const settle of Array.from(sleepers.keys()))
+            settle(false);
+    }
+    /** Clear every timer and settle every sleep with `false` (the caller's generation is gone). */
+    function cancelTimers() {
+        endWaits();
+        for (const h of timers)
+            clearT(h);
+        timers.clear();
+    }
+    const alive = (gen) => !destroyed && gen === generation;
+    const message = (e) => (e instanceof Error ? e.message : String(e));
+    /** A failure that never reached the API, reported only to the generation it belongs to *(plan review 2 #16, #17)*. */
+    function reportLocal(gen, code, e) {
+        if (alive(gen))
+            options.onProblem(localProblem(code, message(e)), { status: 0 });
+    }
+    function render(dto) {
+        const w = dto.widget;
+        container.innerHTML = "";
+        if (w.kind === "html") {
+            container.innerHTML = w.html ?? "";
+            // innerHTML never runs a script: each one is re-created with its attributes and text, in order (Review Focus 4).
+            for (const inert of Array.from(container.querySelectorAll("script"))) {
+                const live = doc.createElement("script");
+                for (const name of inert.getAttributeNames())
+                    live.setAttribute(name, inert.getAttribute(name) ?? "");
+                live.async = inert.async; // a script created this way is async by default: keep the snippet's own order *(plan review 1 #44)*
+                live.textContent = inert.textContent;
+                inert.parentNode?.replaceChild(live, inert);
+                container.appendChild(live);
+            }
+        }
+        else {
+            const live = doc.createElement("script");
+            live.async = false; // createElement scripts are async by default; a snippet's externals must run in document order *(plan review 1 #44)*
+            live.setAttribute("src", w.scriptUrl ?? "");
+            if (w.token)
+                live.setAttribute("data-token", w.token);
+            for (const [k, v] of Object.entries(w.attributes ?? {}))
+                live.setAttribute(k, v);
+            container.appendChild(live);
+        }
+    }
+    function suspend() {
+        suspended = true;
+        if (suspendedOn !== controller) {
+            suspendedOn = controller;
+            controller.suspend();
+        }
+    }
+    function resume(target) { if (suspended) {
+        suspended = false;
+        suspendedOn = undefined;
+        controller.resume(target);
+    } }
+    // ---- The locked burst (spec §10.3) ---------------------------------------------------------------------------
+    /** One SDK-owned `POST /checkout`; a transport rejection is reported and swallowed — the caller stops, the widget
+     * stays suspended and the queue is released *(plan review 2 #17)*. Posted directly: the rolling-minute ledger, its
+     * waits and the POST not-before are cut *(final review S1)*. */
+    async function post(gen) {
+        try {
+            return await options.sync();
+        }
+        catch (e) {
+            reportLocal(gen, "SDK_SYNC_FAILED", e);
+            return undefined;
+        }
+    }
+    const withinBurst = (b, waitMs) => b.calls < lockedMaxCalls && now() + waitMs - b.start < lockedBudgetMs;
+    /** One retry of the `locked`/429/503/`CHECKOUT_IN_PROGRESS` burst. The wait must land inside the burst's deadline —
+     * checked before the wait and again after it, so a `Retry-After` longer than what is left of the 30 s never turns
+     * into a call outside it *(plan review 2 #14)*. */
+    async function retry(budget, retryAfterMs, gen) {
+        if (!withinBurst(budget, retryAfterMs))
+            return "exhausted";
+        if (!(await sleep(retryAfterMs, gen)))
+            return "gone";
+        if (!withinBurst(budget, 0))
+            return "exhausted";
+        budget.calls++;
+        return (await post(gen)) ?? "gone";
+    }
+    // One rolling burst window per handle, not one per dispatch *(plan review 1 #40)*.
+    let budgetWindow = { start: now(), calls: 0 };
+    function currentBudget() {
+        if (now() - budgetWindow.start >= lockedBudgetMs)
+            budgetWindow = { start: now(), calls: 0 };
+        return budgetWindow;
+    }
+    // ---- The autonomous syncs --------------------------------------------------------------------------------------
+    function armExpiry(dto) {
+        if (expiryTimer !== undefined) {
+            clearT(expiryTimer);
+            timers.delete(expiryTimer);
+            expiryTimer = undefined;
+        }
+        // Review Focus 5: server-relative, three minutes before, never negative.
+        // The repository's OpenAPI emits every int32 as ["integer","string"], so the generated type is
+        // `number | string` and the multiplication is TS2362. The same rule for any int arithmetic in the SDK
+        // *(plan review 1 #38)*.
+        const delay = Math.max(0, Number(dto.expiresInSeconds) * 1000 - preExpiryMs);
+        // An attempt already inside the window answers `open` again, which would re-arm at delay 0 and sync in a
+        // zero-delay loop. Only that repeat is suppressed: an already-due deadline for an attempt whose pre-expiry sync
+        // has run. A future deadline from a new answer — the server extended the attempt — is armed as usual; round 1's
+        // guard blocked every later timer for the attempt *(plan review 1 #42, plan review 2 #12)*.
+        if (delay === 0 && firedPreExpiryFor === dto.attemptId)
+            return;
+        const gen = generation;
+        expiryTimer = setT(() => {
+            timers.delete(expiryTimer);
+            expiryTimer = undefined;
+            autonomousSync("expiry", gen);
+        }, delay);
+        timers.add(expiryTimer);
+    }
+    function bindProvider(dto, bound = controllerFor(dto.widget.controller, win, controllerTimer)) {
+        // Cleared, not only called: round 1 left the old unsubscriber in place, so a remount's `attach` returned at once
+        // and the new widget's decline signal was never bound *(plan review 2 #13)*.
+        unsubscribeDeclined?.();
+        unsubscribeDeclined = undefined;
+        controller = bound;
+        // A provider without the signal: nothing to bind and nothing to retry *(plan review 2 #13)*.
+        if (!bound.onDeclined)
+            return;
+        const gen = generation;
+        // `render` appends the provider's script; it has not executed when this runs, so the global the controller reads
+        // does not exist yet. Retry every `bindRetryMs` until the subscription is registered (`onDeclined` returns its
+        // unsubscriber) or the generation is gone — one interval for as long as the widget is mounted, so a script that
+        // loads late is still bound. The timers are the handle's, so a remount or destroy cancels them
+        // *(plan review 1 #43, plan review 2 #13, plan review 3 #4, final review S8)*.
+        const attach = () => {
+            if (!alive(gen))
+                return;
+            const unsubscribe = bound.onDeclined(() => autonomousSync("declined", gen));
+            if (unsubscribe) {
+                unsubscribeDeclined = unsubscribe;
+                return;
+            }
+            const h = setT(() => { timers.delete(h); attach(); }, bindRetryMs);
+            timers.add(h);
+        };
+        attach();
+    }
+    function remount(dto) {
+        if (dto.status !== "open" || !dto.widget)
+            throw new Error("remount needs an `open` answer with a widget");
+        // Resolved before any state changes: an unknown controller throws while the generation is still alive, so the
+        // dispatch's catch reports it instead of dropping it for a generation that moved on *(final review B3 T2)*.
+        const next = controllerFor(dto.widget.controller, win, controllerTimer);
+        generation++;
+        cancelTimers(); // *(plan review 1 #37)*
+        expiryTimer = undefined;
+        firedPreExpiryFor = undefined;
+        attemptId = dto.attemptId;
+        // The ruling of round 1 #39: no controller call after a remount (the new widget's script has not loaded), and the
+        // flag is cleared. Unless a sync is queued behind the one running: then payment stays suspended, and that sync
+        // suspends the new controller when it starts (`suspendedOn` is cleared) *(plan review 2 #11)*.
+        suspended = active > 1;
+        suspendedOn = undefined;
+        render(dto);
+        bindProvider(dto, next);
+        armExpiry(dto);
+    }
+    const onVisible = () => { if (!destroyed && suspended && doc.visibilityState === "visible")
+        autonomousSync("visible", generation); };
+    doc.addEventListener("visibilitychange", onVisible);
+    /** A sync the SDK starts by itself. Skipped while another sync runs: that sync is a `POST /checkout` too, and its
+     * `open` answer re-arms the pre-expiry timer (an attempt already inside the window arms at once). The pre-expiry
+     * attempt is marked only when its sync really starts, so a skip never consumes it. The deferral queue rounds 2–3
+     * added is cut *(plan review 2 #12, final review S7)*. */
+    function autonomousSync(reason, gen) {
+        if (!alive(gen) || active > 0)
+            return;
+        if (reason === "visible" && !suspended)
+            return;
+        if (reason === "expiry")
+            firedPreExpiryFor = attemptId;
+        void enqueue(async (g) => {
+            const result = await post(g);
+            if (result)
+                await dispatch(result, g, currentBudget());
+        });
+    }
+    // ---- The rule ------------------------------------------------------------------------------------------------
+    /** Serialized: two quick quantity clicks must not run two dispatches in one generation, or the first `open` resumes
+     * the widget while the second mutation is still in flight *(plan review 1 #43)*. The widget is suspended when the
+     * request is **accepted**, before it waits its turn: round 1 suspended after `await previous`, so `handle.sync`
+     * returned with payment still enabled even on an idle queue *(plan review 2 #11)*. A sync accepted while another
+     * runs ends the running one's waits (a burst retry, a poll that can last minutes): the running sync stops, and the
+     * newer update — which supersedes what it was waiting for — runs at once *(final review #8)*. Never rejects: any
+     * other throw — an app callback, an unknown controller on remount, a provider `lock()` — is reported as
+     * `SDK_DISPATCH_FAILED` to the generation it belongs to, and the first `suspend()` is inside the `try` (still before
+     * the first `await`, so still at acceptance), so a throw cannot leave `active` stuck *(final review B3 T2)*. */
+    function enqueue(work) {
+        if (destroyed)
+            return Promise.resolve();
+        active++;
+        const previous = queue;
+        let release;
+        queue = new Promise((r) => { release = r; });
+        let gen = generation;
+        return (async () => {
+            try {
+                suspend();
+                if (active > 1)
+                    endWaits(); // *(final review #8)*
+                await previous;
+                if (destroyed)
+                    return;
+                gen = generation; // before the suspend: a new controller's throwing lock() is reported under the live generation
+                suspend(); // a remount while this waited replaced the controller: suspend the new one
+                await work(gen);
+            }
+            catch (e) {
+                // The report itself may throw (`onProblem` is an app callback, and one of the causes): swallowed, so
+                // `handle.sync` and the autonomous path still never reject.
+                try {
+                    reportLocal(gen, "SDK_DISPATCH_FAILED", e);
+                }
+                catch { /* never rejects */ }
+            }
+            finally {
+                active--;
+                release();
+            }
+        })();
+    }
+    /** Status first; identity on `open` only. */
+    async function dispatch(result, gen, budget) {
+        if (!alive(gen))
+            return;
+        if (!result.ok) {
+            const retryable503 = result.status === 503 && (result.problem.code === "CHECKOUT_UNAVAILABLE" || result.problem.code === "CHECKOUT_PROVIDER_UNAVAILABLE");
+            // `sync` and `update` are single POSTs (`{ retries: 0 }`), so the handle retries CHECKOUT_IN_PROGRESS itself, in
+            // the same burst as `locked` *(plan review 3 #5, final review S1)*.
+            const inProgress = result.status === 409 && result.problem.code === "CHECKOUT_IN_PROGRESS";
+            if (retryable503 || inProgress || result.status === 429) {
+                const next = await retry(budget, (result.retryAfter ?? 1) * 1000, gen);
+                if (next === "gone")
+                    return;
+                if (next !== "exhausted")
+                    return dispatch(next, gen, budget);
+            }
+            // The last retry's problem, not the first: the app should see the latest state of the checkout. The 503 test
+            // asserts the last code for that reason *(plan review 1 #41)*.
+            options.onProblem(result.problem, { status: result.status });
+            return;
+        }
+        const dto = result.data;
+        switch (dto.status) {
+            case "completed":
+            case "pending":
+                if (dto.order)
+                    options.onOrder(dto.order, dto.attemptId);
+                return;
+            case "locked": {
+                const next = await retry(budget, (result.retryAfter ?? 1) * 1000, gen);
+                if (next === "gone")
+                    return;
+                if (next !== "exhausted")
+                    return dispatch(next, gen, budget);
+                return poll(dto.attemptId, gen);
+            }
+            case "processing":
+                return poll(dto.attemptId, gen);
+            case "declined":
+            case "expired": {
+                const next = await post(gen);
+                if (next)
+                    return dispatchOnce(next, gen);
+                return;
+            }
+            case "open":
+                if (dto.attemptId === attemptId) {
+                    armExpiry(dto);
+                    // Another update is queued behind this one: its mutation is still to come, so payment stays suspended
+                    // until its own answer *(plan review 2 #11)*. The provider unlocks once its view shows `dto.cart`; if it
+                    // never does, the widget is re-rendered from this answer *(plan review 1 #3)*.
+                    if (active <= 1)
+                        resume({ cart: dto.cart, onUnsynced: () => { if (alive(gen))
+                                remount(dto); } });
+                }
+                else {
+                    remount(dto);
+                }
+                return;
+            default:
+                options.onProblem(localProblem("SDK_UNKNOWN_STATUS", String(dto.status)), { status: 200 });
+        }
+    }
+    /** After a `declined`/`expired` or a `GET open`: one sync, dispatched without a second closing → sync loop. */
+    async function dispatchOnce(result, gen) {
+        if (!alive(gen))
+            return;
+        if (result.ok && (result.data.status === "declined" || result.data.status === "expired")) {
+            options.onProblem(localProblem("SDK_CHECKOUT_CLOSED", result.data.status), { status: 200 });
+            return;
+        }
+        return dispatch(result, gen, currentBudget()); // *(plan review 1 #40)*
+    }
+    /** `status(attemptId)` polling with backoff; a GET answer is never payable: `open` (like `declined`/`expired`) leads to one non-mutating `sync()`. */
+    async function poll(id, gen) {
+        let delay = pollFirstMs;
+        let lockedPolls = 0;
+        for (;;) {
+            if (!(await sleep(delay, gen)))
+                return;
+            let s;
+            try {
+                s = await options.status(id);
+            }
+            catch (e) {
+                reportLocal(gen, "SDK_STATUS_FAILED", e); // *(plan review 2 #17)*
+                return;
+            }
+            if (!alive(gen))
+                return;
+            // §10.3 treats a 429 like `locked`: back off and keep polling *(plan review 1 #43)*. The client's backoff is
+            // capped at `pollMaxMs`; the server's `Retry-After` is a lower bound the cap never shortens *(plan review 2 #15)*.
+            if (!s.ok) {
+                if (s.status !== 429) {
+                    options.onProblem(s.problem, { status: s.status });
+                    return;
+                }
+                delay = Math.max(Math.min(delay * 2, pollMaxMs), (s.retryAfter ?? 1) * 1000);
+                continue;
+            }
+            if (FINAL_ORDER.has(s.data.status)) {
+                if (s.data.order)
+                    options.onOrder(s.data.order, s.data.attemptId);
+                return;
+            }
+            // `locked` means an update or an owned read is in flight (§10.2), and only a POST resolves it. An attempt whose
+            // latest snapshot was never confirmed and whose claim is gone answers `locked` to every GET with nothing in
+            // flight, so a status poller would poll for ever: escalate to one sync() *(plan review 1 #12)*. Posted directly
+            // *(final review S1)*.
+            const escalate = s.data.status === "open" || s.data.status === "declined" || s.data.status === "expired"
+                || (s.data.status === "locked" && ++lockedPolls >= lockedPollsBeforeSync);
+            if (escalate) {
+                const next = await post(gen);
+                if (next)
+                    return dispatchOnce(next, gen);
+                return;
+            }
+            delay = Math.min(delay * 2, pollMaxMs);
+        }
+    }
+    const handle = {
+        get attemptId() { return attemptId; },
+        get suspended() { return suspended; },
+        suspend, resume, remount,
+        destroy() {
+            destroyed = true;
+            generation++;
+            cancelTimers(); // *(plan review 1 #37)*
+            unsubscribeDeclined?.();
+            unsubscribeDeclined = undefined;
+            doc.removeEventListener("visibilitychange", onVisible);
+        },
+        sync(update) {
+            return enqueue(async (gen) => {
+                let result;
+                try {
+                    result = await update(); // once — never repeated (LensNow's add action has no idempotency key)
+                }
+                catch (e) {
+                    // Only for the generation it was started in: a rejection after destroy() or a remount is dropped, as a
+                    // fulfilled answer is in `dispatch` *(plan review 2 #16)*. The widget stays suspended until a sync succeeds.
+                    reportLocal(gen, "SDK_UPDATE_FAILED", e);
+                    return;
+                }
+                await dispatch(result, gen, currentBudget()); // *(plan review 1 #40)*
+            });
+        },
+    };
+    render(checkout);
+    bindProvider(checkout);
+    armExpiry(checkout);
+    return handle;
+}