@asstio-dev/storefront 0.17.0 → 0.19.0

package/README.md

@@ -251,10 +251,13 @@ Cards and cart lines carry the product facts the product page has: `brand`, `cat
 shape without `shortDescription` (`productFacts(orderLine).shortDescription` is `null`): its facts are the ones the
 charged checkout snapshot captured, never re-resolved — `url`, `facet` and attribute `facetKey`/`valueKeys` are `null`
 there, the blocks are empty on orders placed before they existed, and `null` on fee, shipping and adjustment lines.
-`productFacts()` reads them from any source:
+A checkout cart line (`checkout.cart.lines[]`) has the order-line shape too, but is resolved **live while the attempt is
+`open`**, like a cart line, with `url`, `facet` and attribute keys filled in. In every other status, and for a line the
+catalogue can no longer describe, it carries the snapshot's frozen facts (links `null`). What it shows may therefore
+differ from what the order later freezes. `productFacts()` reads them from any source:
 
 ```ts
-const facts = productFacts(line);           // card, product, { product, variant }, cart line or product order line
+const facts = productFacts(line);           // card, product, { product, variant }, cart line, checkout cart line or product order line
 render(facts.brand?.label);                 // the item's brand: the variant's own, never a fallback to the family's
 render(facts.productBrand?.label);          // the family brand
 ```
@@ -263,7 +266,8 @@ render(facts.productBrand?.label);          // the family brand
 fall back to `productBrand`. **Categories carry no primary meaning**: `categories[0]` may be a gender, a brand or a
 product-type node. Pick the one you want by its root.
 
-`toGa4Item()` and `toGa4Ecommerce()` map the same sources to GA4 ecommerce data. They are pure: they send nothing and
+`toGa4Item()` and `toGa4Ecommerce()` map the same sources to GA4 ecommerce data; `toGa4Ecommerce(checkout.cart)` is the
+`begin_checkout` payload. They are pure: they send nothing and
 know nothing about consent or a data layer.
 
 | Source | `item_id` | `item_brand` | `price` | `quantity` | `item_variant` |
@@ -271,6 +275,7 @@ know nothing about consent or a data layer.
 | card (impression) | the family `sku` | `brand.label` | from-price | 1 | — |
 | `{ product, variant }` | the variant `sku` | the variant's brand | the variant's price | 1 | selected options |
 | cart line | the line `sku` | the variant's brand | the line's unit price | the line's | selected options |
+| checkout cart line | the line `sku` | the variant's brand | the unit price | the line's | options |
 | order line (product) | the line `sku` | the variant's brand | the unit price | the line's | options |
 
 - A card is a family impression; later events carry the purchased sku. Pass `itemId` to report at family level.
@@ -431,6 +436,8 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
   Qliro shows the confirmed total or version.
 - 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.
+- `q1` callbacks replace per event. The SDK owns `onOrderUpdated` and `onPaymentDeclined`, and with `onShipping` also
+  `onShippingMethodChanged` and `onShippingPriceChanged`: a listener of your own on these silently stops the SDK's.
 
 #### Kustom (`klarna-kco`)
 
@@ -452,6 +459,8 @@ Problem codes you will meet here: `CART_EMPTY`, `CHECKOUT_CART_CHANGED` (with `c
 - Never bind `can_not_complete_order` yourself through `window._klarnaCheckout(api => api.on(...))`. Kustom's `api.on`
   replaces the listener per event instead of adding one, so yours and the SDK's would replace each other. Use
   `onProblem`. Listeners for other events are not affected.
+  With `onShipping` set (see "Live shipping view" below) the SDK also owns `shipping_option_change`,
+  `shipping_address_change` and `order_total_change` (one separate `api.on`); use `onShipping` for those.
 - **CSP hosts** (K-C10, `docs/ops/kustom-playground-checks.md`, 2026-10-09: a card with 3-D Secure and the default
   method, no blocked request). The checkout page itself loads only Kustom's script host. Everything else
   (`kco.assets.kustomcdn.co`, Klarna, Stripe, hCaptcha, Google Pay, Amazon Pay) loads inside Kustom's iframe under
@@ -500,6 +509,40 @@ if (estimate?.available) {
   normally held in Asstio with its reason (rarely the export waits for an operator instead); the page has nothing to
   do for it.
 
+#### Live shipping view
+
+Optionally show what the shopper has chosen inside the widget, from `GET /v1/checkout/{attemptId}/shipping`. The view is
+not a promise: the order's `lines` and `totals` stay the truth.
+
+```ts
+// Server route: forwards the view and Retry-After. The cart token stays on the server.
+const r = await liveShippingFor(client, cartToken, attemptId);
+// r.ok ? r.data : r.problem, with r.retryAfter as the Retry-After header
+
+// Page:
+mountCheckout(el, widget, {
+  /* … */
+  liveShipping: (attemptId) => callMyProxy(attemptId), // returns LiveShippingResult
+  onShipping: (view) => {
+    if (view === null) return showEstimate();            // invalidated: a change is in flight
+    if (view.state === "selected") showLine(view.name, view.shippingInc, view.totalInc);
+  },
+});
+```
+
+- `liveShipping` and `onShipping` are required together (one without the other throws at mount). Without them nothing
+  shipping-related is bound, scheduled or called.
+- `view.state`: `selected`, `unselected`, `unmatched`, `unavailable` (with `reason`: `syncing`, `closed`, `provider`,
+  `throttled`, `mismatch`, `erased`, `not_supported`, and `retryAfterSeconds`).
+- Members: `goodsInc`, `shippingInc`, `totalInc`, `otherInc`, `totalSource`, `option`, `name`, `deliveryType`, `point`,
+  `readAt`, `cartVersion`. `totalInc` is the provider-reported total, before payment-method charges the provider does
+  not report before purchase. `name` can differ from Kustom's display copy.
+- Freshness: a method change on both providers, and an address change on Kustom, typically follows the provider's event
+  within a couple of seconds. A Kustom pickup-point change and a Qliro address change fire no client event we know of and
+  are seen only by the safety net (every 45 to 60 s, best-effort, up to about 60 s), which runs only while the tab is
+  visible.
+- The SDK owns the provider's shipping events while `onShipping` is set; do not bind them yourself.
+
 ## Headers
 
 Every call the client makes carries these; you never set them by hand.

package/dist/analytics/facts.d.ts

@@ -1,6 +1,6 @@
-import { type CartLineDto, type OrderLineDto, type ProductCardDto, type ProductDto, type ProductFacts, type SelectedVariant } from "./types.js";
+import { type CartLineDto, type CheckoutCartLineDto, type OrderLineDto, type ProductCardDto, type ProductDto, type ProductFacts, type SelectedVariant } from "./types.js";
 /**
- * The product facts of a card, a product page (with or without a selected variant), a cart line or an order line, so a
+ * The product facts of a card, a product page (with or without a selected variant), a cart line, a checkout cart line or an order line, so a
  * frontend never needs to know where a surface keeps them. Returns the DTO's own arrays and objects — never copies,
  * filters or mutates them. `brand` is the item's brand: a selected or purchased variant's own, with no fallback to the
  * family brand (null can mean an explicit "none"). An order line that is not a product line throws.
@@ -9,4 +9,5 @@ export declare function productFacts(source: ProductCardDto): ProductFacts;
 export declare function productFacts(source: ProductDto): ProductFacts;
 export declare function productFacts(source: SelectedVariant): ProductFacts;
 export declare function productFacts(source: CartLineDto): ProductFacts;
+export declare function productFacts(source: CheckoutCartLineDto): ProductFacts;
 export declare function productFacts(source: OrderLineDto): ProductFacts;

package/dist/analytics/facts.js

@@ -12,11 +12,13 @@ export function productFacts(source) {
         };
     }
     if (isObject(s.product) && isObject(s.variant)) {
-        // A cart line or a selected-variant wrapper: the same fact paths.
+        // A cart line, a checkout cart line or a selected-variant wrapper: the same fact paths. A checkout line's product has no
+        // `shortDescription` (it is the order-line shape), so it reads null there.
         const { product, variant } = source;
+        const short = product.shortDescription;
         return {
             brand: variant.brand, productBrand: product.brand, categories: product.categories,
-            attributes: product.attributes, shortDescription: product.shortDescription ?? null,
+            attributes: product.attributes, shortDescription: short ?? null,
         };
     }
     const flat = source;

package/dist/analytics/ga4.d.ts

@@ -1,4 +1,4 @@
-import { type CartDto, type Ga4Ecommerce, type Ga4Item, type Ga4ItemOptions, type Ga4ItemSource, type Ga4Purchase, type Ga4SharedOptions, type OrderDto } from "./types.js";
+import { type CartDto, type CheckoutCartDto, type Ga4Ecommerce, type Ga4Item, type Ga4ItemOptions, type Ga4ItemSource, type Ga4Purchase, type Ga4SharedOptions, type OrderDto } from "./types.js";
 /** An item and its unit price in cents, so a payload's `value` sums exact cents rather than re-reading floats. */
 export type MappedItem = {
     item: Ga4Item;
@@ -6,7 +6,7 @@ export type MappedItem = {
 };
 /**
  * One GA4 item from a card (an impression: the family sku and from-price), a product with its selected variant, a cart
- * line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
+ * line, a checkout cart line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
  * A source without a price throws — never `price: 0`.
  */
 export declare function toGa4Item(source: Ga4ItemSource, opts?: Ga4ItemOptions): Ga4Item;
@@ -18,4 +18,5 @@ export declare function mapItem(source: Ga4ItemSource, opts?: Ga4ItemOptions): M
  * recorded VAT and its `shipping` comes from its shipping lines, each netted at its own rate and rounded once.
  */
 export declare function toGa4Ecommerce(source: CartDto, opts?: Ga4SharedOptions): Ga4Ecommerce;
+export declare function toGa4Ecommerce(source: CheckoutCartDto, opts?: Ga4SharedOptions): Ga4Ecommerce;
 export declare function toGa4Ecommerce(source: OrderDto, opts?: Ga4SharedOptions): Ga4Purchase;

package/dist/analytics/ga4.js

@@ -3,7 +3,7 @@ import { productFacts } from "./facts.js";
 import { AnalyticsError, } from "./types.js";
 /**
  * One GA4 item from a card (an impression: the family sku and from-price), a product with its selected variant, a cart
- * line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
+ * line, a checkout cart line or a product order line. `item_brand` and the categories come from `productFacts`, so they never disagree with it.
  * A source without a price throws — never `price: 0`.
  */
 export function toGa4Item(source, opts = {}) {
@@ -65,6 +65,11 @@ function lineOf(source) {
             throw new AnalyticsError(`an order line of type "${l.type}" is not an item`);
         return { id: l.sku, name: l.name, gross: parseDecimal(l.unitPriceInc), vatRate: parseDecimal(l.vatRate), quantity: sourceQuantity(l.quantity), options: l.options };
     }
+    if (typeof s.unitPriceInc === "string" && typeof s.productId === "string" && typeof s.type !== "string") {
+        // A checkout cart line: the snapshot's own amounts (`unitPriceInc`, `vatRate`), not a PriceDto, and the options on the line.
+        const l = source;
+        return { id: l.sku, name: l.name, gross: parseDecimal(l.unitPriceInc), vatRate: parseDecimal(l.vatRate), quantity: sourceQuantity(l.quantity), options: l.options };
+    }
     if (typeof s.variant === "object" && s.variant !== null && "selectedOptions" in s.variant) {
         if ("quantity" in s) {
             const l = source;

package/dist/analytics/types.d.ts

@@ -7,6 +7,8 @@ export type CartDto = Schemas["CartDto"];
 export type CartLineDto = Schemas["CartLineDto"];
 export type OrderDto = Schemas["OrderDto"];
 export type OrderLineDto = Schemas["OrderLineDto"];
+export type CheckoutCartDto = Schemas["CheckoutCartDto"];
+export type CheckoutCartLineDto = Schemas["CheckoutCartLineDto"];
 export type BrandDto = Schemas["BrandDto"];
 export type CategoryRefDto = Schemas["CategoryRefDto"];
 export type AttributeDto = Schemas["AttributeDto"];
@@ -26,7 +28,7 @@ export type ProductFacts = {
     categories: CategoryRefDto[];
     /** As the source carries them: a `ProductDto` may include `html` attributes; cards, cart and order lines do not. */
     attributes: AttributeDto[];
-    /** Null on order lines. */
+    /** Null on order lines and checkout cart lines. */
     shortDescription: string | null;
 };
 /** A source the analytics helpers cannot map: a non-product order line, an unpriced variant, an invalid quantity. */
@@ -70,7 +72,7 @@ export type Ga4ItemOptions = Ga4SharedOptions & {
     itemId?: string;
     index?: number;
 };
-export type Ga4ItemSource = ProductCardDto | SelectedVariant | CartLineDto | OrderLineDto;
+export type Ga4ItemSource = ProductCardDto | SelectedVariant | CartLineDto | CheckoutCartLineDto | OrderLineDto;
 /** `view_cart`, `begin_checkout` and the like. */
 export type Ga4Ecommerce = {
     currency: string;

package/dist/checkout/browser.d.ts

@@ -1,5 +1,5 @@
 import { type ProviderWindow } from "./controllers.js";
-import { type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type StatusResult, type StorefrontProblem } from "./types.js";
+import { type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type CheckoutShippingViewDto, type LiveShippingResult, type StatusResult, type StorefrontProblem } from "./types.js";
 export interface MinimalScript {
     src: string;
     textContent: string | null;
@@ -62,6 +62,12 @@ export interface MountOptions {
     bindRetryMs?: number;
     /** How long before `expiresInSeconds` the SDK syncs by itself (inside the server's five-minute window). */
     preExpiryMs?: number;
+    /** A `GET /checkout/{attemptId}/shipping` on the attempt named (server-side, with the cart token, e.g.
+     * `liveShippingFor`). Must be provided together with `onShipping`; one without the other throws at mount. */
+    liveShipping?: (attemptId: string) => Promise<LiveShippingResult>;
+    /** Receives the live shipping view; `null` means invalidated: show the estimate or a placeholder. Must be provided
+     * together with `liveShipping`. Without both, nothing shipping-related is bound, scheduled or called. */
+    onShipping?: (view: CheckoutShippingViewDto | null) => void;
 }
 export interface CheckoutHandle {
     readonly attemptId: string;
@@ -73,4 +79,10 @@ export interface CheckoutHandle {
     /** The whole rule: suspend → `await update()` once → status first, identity on `open`. Never rejects. */
     sync(update: () => Promise<CheckoutResult>): Promise<void>;
 }
+/** Kustom replays its events once, about 1 s after the first `api.on` registration (K-L15). A shipping event within this
+ * window of a mount's first successful shipping subscription, before any later event, is that replay: it carries no
+ * change, so it is not an invalidation. It joins the explicit first read if that read has not started, and is dropped
+ * if a read already started at or after the subscription (that read already covers it). Applied to `klarna-kco` only:
+ * no other provider replays, so their events always invalidate. */
+export declare const REPLAY_WINDOW_MS = 1500;
 export declare function mountCheckout(container: MinimalElement, checkout: CheckoutDto, options: MountOptions): CheckoutHandle;

package/dist/checkout/browser.js

@@ -1,7 +1,16 @@
 import { controllerFor } from "./controllers.js";
+import { createLiveShippingObserver } from "./live-shipping.js";
 import { localProblem } from "./types.js";
 const FINAL_ORDER = new Set(["completed", "pending"]);
+/** Kustom replays its events once, about 1 s after the first `api.on` registration (K-L15). A shipping event within this
+ * window of a mount's first successful shipping subscription, before any later event, is that replay: it carries no
+ * change, so it is not an invalidation. It joins the explicit first read if that read has not started, and is dropped
+ * if a read already started at or after the subscription (that read already covers it). Applied to `klarna-kco` only:
+ * no other provider replays, so their events always invalidate. */
+export const REPLAY_WINDOW_MS = 1500;
 export function mountCheckout(container, checkout, options) {
+    if ((options.liveShipping === undefined) !== (options.onShipping === undefined))
+        throw new Error("liveShipping and onShipping must be provided together");
     if (checkout.status !== "open" || !checkout.widget)
         throw new Error("mountCheckout needs an `open` answer with a widget");
     const doc = options.document ?? globalThis.document;
@@ -36,6 +45,7 @@ export function mountCheckout(container, checkout, options) {
     let queue = Promise.resolve(); // *(plan review 1 #43)*
     let unsubscribeDeclined;
     let unsubscribeCannotComplete;
+    let unsubscribeShipping;
     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
@@ -79,6 +89,87 @@ export function mountCheckout(container, checkout, options) {
         if (alive(gen))
             options.onProblem(localProblem(code, message(e)), { status: 0 });
     }
+    // ---- Live shipping (spec 2026-10-12 §4.6) ---------------------------------------------------------------------
+    // A separate observation flow, never driven through `dispatch` or `poll`. One observer per mount: a remount or destroy
+    // destroys it, so an answer or a provider callback of an older mount is dropped. Without `onShipping` it never exists.
+    let observer;
+    let observerSuspended = false; // the observer was told `suspended()` and not yet `resumed()`
+    let observerResumeReady = false; // the provider reported it is resumed (or this mount is fresh): resume once drained
+    let shippingBoundAt; // this mount's first successful shipping subscription
+    let lastReadAt; // when this mount's observer last started a read
+    let replayOver = false; // a non-replay shipping event was handled on this mount
+    function createObserver(gen) {
+        if (!options.onShipping || !options.liveShipping)
+            return undefined;
+        const onShipping = options.onShipping;
+        const liveShipping = options.liveShipping;
+        let reported = false; // SDK_LIVE_SHIPPING_FAILED once per mount, for liveShipping and onShipping alike
+        const report = (e) => {
+            if (reported || !alive(gen))
+                return;
+            reported = true;
+            try {
+                reportLocal(gen, "SDK_LIVE_SHIPPING_FAILED", e);
+            }
+            catch { /* an app callback: never reaches checkout */ }
+        };
+        shippingBoundAt = undefined;
+        lastReadAt = undefined;
+        replayOver = false;
+        return createLiveShippingObserver({
+            // A synchronous throw and a rejection are both reported, then rethrown: the observer still sees a failed read.
+            // The attempt is read at call time.
+            read: async () => {
+                lastReadAt = now();
+                try {
+                    return await liveShipping(attemptId);
+                }
+                catch (e) {
+                    report(e);
+                    throw e;
+                }
+            },
+            deliver: (view) => {
+                if (!alive(gen))
+                    return;
+                try {
+                    onShipping(view);
+                }
+                catch (e) {
+                    report(e);
+                }
+            },
+            now,
+            // The handle's timers, so a remount or destroy cancels them with every other.
+            setTimeout: (fn, ms) => { const h = setT(() => { timers.delete(h); fn(); }, ms); timers.add(h); return h; },
+            clearTimeout: (h) => { clearT(h); timers.delete(h); },
+            visible: () => doc.visibilityState === "visible",
+            random: Math.random,
+        });
+    }
+    function observerSuspend() {
+        if (!observer)
+            return;
+        observerResumeReady = false;
+        if (observerSuspended)
+            return;
+        observerSuspended = true;
+        observer.suspended();
+    }
+    /** The refresh after a sync waits for both: the provider is actually resumed and the sync queue has drained. */
+    function observerTryResume() {
+        if (!observer || !observerSuspended || !observerResumeReady || active > 0)
+            return;
+        observerSuspended = false;
+        observerResumeReady = false;
+        observer.resumed();
+    }
+    function observerProviderResumed(target) {
+        if (!observer || observer !== target)
+            return;
+        observerResumeReady = true;
+        observerTryResume();
+    }
     function render(dto) {
         const w = dto.widget;
         container.innerHTML = "";
@@ -108,6 +199,7 @@ export function mountCheckout(container, checkout, options) {
     }
     function suspend() {
         suspended = true;
+        observerSuspend();
         if (suspendedOn === controller)
             return;
         // Recorded before the call, as on main: a controller whose suspend throws (a broken provider `lock()`) stays recorded, so a
@@ -124,6 +216,13 @@ export function mountCheckout(container, checkout, options) {
         suspendedOn = undefined;
         controller.resume(target);
     } }
+    /** The app's own `handle.resume()`: no confirmed answer to wait for, so the observer resumes once the queue drains. */
+    function appResume() {
+        const was = suspended;
+        resume();
+        if (was)
+            observerProviderResumed(observer);
+    }
     // ---- 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
@@ -191,6 +290,8 @@ export function mountCheckout(container, checkout, options) {
         unsubscribeDeclined = undefined;
         unsubscribeCannotComplete?.();
         unsubscribeCannotComplete = undefined;
+        unsubscribeShipping?.();
+        unsubscribeShipping = undefined;
         controller = bound;
         const gen = generation;
         // `render` appends the provider's script; it has not executed when this runs, so the global the controller reads
@@ -219,6 +320,25 @@ export function mountCheckout(container, checkout, options) {
         // Spec F §7.1: Kustom's can_not_complete_order is the app's problem to show, not a validation decline (no sync).
         bind(bound.onCannotComplete, () => { if (alive(gen))
             options.onProblem(localProblem("SDK_PROVIDER_CANNOT_COMPLETE", "can_not_complete_order"), { status: 0 }); }, (off) => { unsubscribeCannotComplete = off; });
+        // Live shipping: only with `onShipping`. The provider's shipping signals are a trigger only (spec §4.6).
+        const obs = observer;
+        // Only Kustom replays its shipping events after registration (K-L15); every other provider's event is real, also
+        // inside the window, and always invalidates *(final review B)*.
+        const replays = dto.widget.controller === "klarna-kco";
+        const onShippingEvent = () => {
+            if (!alive(gen))
+                return;
+            if (replays && !replayOver && shippingBoundAt !== undefined && now() - shippingBoundAt <= REPLAY_WINDOW_MS) {
+                // Kustom's replay: no invalidation. Covered by a read started since the subscription, else it joins the first read.
+                if (lastReadAt === undefined || lastReadAt < shippingBoundAt)
+                    obs.trigger("first");
+                return;
+            }
+            replayOver = true;
+            obs.trigger("event");
+        };
+        if (obs)
+            bind(bound.onShippingEvent, onShippingEvent, (off) => { unsubscribeShipping = off; shippingBoundAt ??= now(); });
     }
     function remount(dto) {
         if (dto.status !== "open" || !dto.widget)
@@ -227,11 +347,20 @@ export function mountCheckout(container, checkout, options) {
         // 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);
         controller.dispose?.(); // spec F §7.1: the old mount's deferred callbacks and timers do nothing now
+        observer?.destroy(); // the old observation's sequence is gone with its mount
         generation++;
         cancelTimers(); // *(plan review 1 #37)*
         expiryTimer = undefined;
         firedPreExpiryFor = undefined;
         attemptId = dto.attemptId;
+        // The new mount owns the recovery read: invalidate (`null`) now, read once the sync queue has drained — a remount
+        // inside a dispatch runs while `active > 0`, so the refresh is queued, never skipped (spec §4.6 Resume). The new
+        // widget needs no provider resume signal (no controller call after a remount); a sync still queued suspends it again.
+        observer = createObserver(generation);
+        observerSuspended = false;
+        observerResumeReady = false;
+        observerSuspend();
+        observerResumeReady = !!observer;
         // 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)*.
@@ -240,6 +369,7 @@ export function mountCheckout(container, checkout, options) {
         render(dto);
         bindProvider(dto, next);
         armExpiry(dto);
+        observerTryResume();
     }
     const onVisible = () => { if (!destroyed && suspended && doc.visibilityState === "visible")
         autonomousSync("visible", generation); };
@@ -302,6 +432,7 @@ export function mountCheckout(container, checkout, options) {
             finally {
                 active--;
                 release();
+                observerTryResume(); // the refresh after a sync waits for the queue to drain (spec §4.6 Resume)
             }
         })();
     }
@@ -356,9 +487,13 @@ export function mountCheckout(container, checkout, options) {
                     // 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)
+                    if (active <= 1) {
+                        const obs = observer;
                         resume({ cart: dto.cart, cartVersion: Number(dto.cartVersion), onUnsynced: () => { if (alive(gen))
-                                remount(dto); } });
+                                remount(dto); },
+                            onResumed: () => { if (alive(gen))
+                                observerProviderResumed(obs); } });
+                    }
                 }
                 else {
                     remount(dto);
@@ -428,11 +563,15 @@ export function mountCheckout(container, checkout, options) {
     const handle = {
         get attemptId() { return attemptId; },
         get suspended() { return suspended; },
-        suspend, resume, remount,
+        suspend, resume: appResume, remount,
         destroy() {
             destroyed = true;
             generation++;
+            observer?.destroy();
+            observer = undefined;
             cancelTimers(); // *(plan review 1 #37)*
+            unsubscribeShipping?.();
+            unsubscribeShipping = undefined;
             unsubscribeDeclined?.();
             unsubscribeDeclined = undefined;
             unsubscribeCannotComplete?.();
@@ -456,8 +595,12 @@ export function mountCheckout(container, checkout, options) {
             });
         },
     };
+    observer = createObserver(generation);
     render(checkout);
     bindProvider(checkout);
     armExpiry(checkout);
+    // The explicit first read: Kustom replays its events once after the first registration and Qliro never replays, so the
+    // first view never depends on a provider event; a replay inside the debounce coalesces with it (spec §4.6 Binding).
+    observer?.trigger("first");
     return handle;
 }

package/dist/checkout/controllers.d.ts

@@ -20,6 +20,10 @@ export interface ProviderWindow {
         /** Fires when our validation callback declined the purchase, with the `DeclineReason` it answered
          * (developers.qliro.com → Listeners). */
         onPaymentDeclined?(cb: (declineReason?: string, declineReasonMessage?: string) => void): void;
+        /** Shipping listeners (developers.qliro.com → Listeners). Registration replaces per event and nothing replays; the
+         * payload is never read, a call is only a refresh trigger. */
+        onShippingMethodChanged?(cb: (payload?: unknown) => void): void;
+        onShippingPriceChanged?(cb: (price?: unknown) => void): void;
     };
     _klarnaCheckout?: (cb: (api: KlarnaCheckoutApi) => void) => void;
     walley?: {
@@ -42,6 +46,10 @@ export interface ResumeTarget {
     cartVersion?: number;
     /** The provider never showed `cart` before its deadline: the handle re-renders the widget from the confirmed answer. */
     onUnsynced(): void;
+    /** The provider is actually resumed: Qliro on the matching `onOrderUpdated` (with the unlock), Kustom after `api.resume()`
+     * ran, Walley after its `resume()`; at once when nothing was held (the provider global is missing, or Kustom's throws).
+     * Never called on a Qliro deadline, nor when Qliro's lock was missed (that is `onUnsynced`). */
+    onResumed?(): void;
 }
 export interface CheckoutController {
     /** Returns `false` when the suspension could not be handed to the provider yet (its script has not defined its API): the
@@ -57,6 +65,10 @@ export interface CheckoutController {
     /** The provider says no offered payment method can complete the order (Kustom's `can_not_complete_order`). Same binding
      * contract as `onDeclined`: `undefined` until the provider's script exposes it. */
     onCannotComplete?(handler: () => void): (() => void) | undefined;
+    /** The provider's shipping-change signals (Kustom `shipping_option_change`, `shipping_address_change`,
+     * `order_total_change`; Qliro `onShippingMethodChanged`, `onShippingPriceChanged`). The handler is only a trigger. Same
+     * binding contract as `onDeclined`: `undefined` until the provider's script exposes the signals; returns the unsubscribe. */
+    onShippingEvent?(handler: () => void): (() => void) | undefined;
     /** This mount is over (remount, destroy): every deferred provider callback and timer of this controller does nothing after it. */
     dispose?(): void;
 }
@@ -68,9 +80,13 @@ export type ControllerFactory = (win: ProviderWindow, timer: ControllerTimer) =>
 /** How long `qliro-q1`'s resume waits for `q1.onOrderUpdated` to show the confirmed cart. Past it the widget is
  * re-rendered, never unlocked blindly *(plan review 1 #3)*. */
 export declare const QLIRO_SYNC_DEADLINE_MS = 10000;
+/** How often `qliro-q1`'s shipping dispatcher checks whether `window.q1` is a new object (a re-render replaces it, and a
+ * registration on a stale instance is silent). */
+export declare const QLIRO_REBIND_MS = 500;
 /** Qliro's check before `unlock()` (*Update order*: "Verify that the total amount of the order = total amount in the
- * shopping cart"), in öre, **or** the `MerchantUpdateVersion` our PUT sent (carriers 1b ruling R-S3-K1: on a shipping
- * market Qliro's total includes the fee, so the total alone never matches). The echo is a string in Qliro's schema; its
+ * shopping cart"), in öre, **or** the `MerchantUpdateVersion` our PUT sent (carriers 1b ruling R-S3-K1: Qliro's client
+ * `onOrderUpdated.totalPrice` is goods only while the GET total includes shipping (Q-L2), so on a shipping market the two
+ * totals can differ and the total alone is not a reliable match). The echo is a string in Qliro's schema; its
  * name is read case-insensitively (VQ-8 records the real one). */
 export declare function qliroOrderMatches(order: unknown, target: Pick<ResumeTarget, "cart" | "cartVersion">): boolean;
 export declare const controllers: Record<"qliro-q1" | "klarna-kco" | "walley", ControllerFactory>;