@code-collective/booking-widget 1.0.12 → 1.0.13

package/src/lib/CheckoutModal.svelte

@@ -89,36 +89,88 @@
   let productsById = $state<Map<string, CheckoutProductDto>>(new Map());
 
   async function loadProducts() {
-    const productIds = [...new Set(cart.items.map((i) => i.productId))];
-    const results = await Promise.all(productIds.map((id) => api.getProduct(id)));
-    const map = new Map<string, CheckoutProductDto>();
-    for (const p of results) {
-      map.set(p.id, p);
+    try {
+      const productIds = [...new Set(cart.items.map((i) => i.productId))];
+      const results = await Promise.all(productIds.map((id) => api.getProduct(id)));
+      const map = new Map<string, CheckoutProductDto>();
+      for (const p of results) {
+        map.set(p.id, p);
+      }
+      productsById = map;
+    } catch {
+      // These supply titles and unit labels; the cart itself renders from the cart's own rows, and productTitle
+      // falls back to the product id, so losing them is a plainer checkout rather than none. Letting isLoading
+      // stand would be neither: the spinner is the first branch in the markup, so one rejected getProduct hung
+      // the whole modal on it for good - over an already settled payment included (PR 8447 review).
+    } finally {
+      isLoading = false;
     }
-    productsById = map;
-    isLoading = false;
   }
 
-  loadProducts();
+  void loadProducts();
 
   // A reload mid-payment: the server still holds this cart in AwaitingPaymentConfirmation for the Peach
   // checkout recorded before the reload, and will refuse every edit and a second payCart until that attempt
-  // is settled or abandoned - so the only useful place to land is back on that same card form. Peach's own
-  // handlers then route exactly as they do without a reload: a completed charge confirms, a cancel/expiry/
-  // error abandons the attempt and reopens the cart. Same resume as onPayNow's own paymentResult short-cut.
-  function resumeInterruptedPayment() {
+  // is settled or abandoned. Where to land depends on how far the shopper got before the reload, and only the
+  // server knows: Peach's form may have completed a moment earlier - a charge, or a decline the server reads
+  // straight back from Peach's status endpoint, since Peach sends no webhook for one - so it is asked once
+  // first, and a recorded outcome is shown exactly as it would have been without the reload. Only "not paid"
+  // puts the shopper back on that same card form, whose Peach handlers then route as they do without a
+  // reload: a completed charge confirms, a cancel/expiry/error abandons the attempt and reopens the cart.
+  // Same resume as onPayNow's own paymentResult short-cut.
+  async function resumeInterruptedPayment() {
     const interruptedAttempt = recallPaymentAttempt(api.cartToken);
     if (!interruptedAttempt) return;
     paymentResult = interruptedAttempt;
-    currentView = 'payment';
+    // Posted before the answer is known, as Pay Now does: CartExpiryGuard must treat the attempt as in flight
+    // whichever screen it ends up on, and a decline's own payment:ended (releaseDeclinedAttempt) then reads the
+    // same as it does without a reload.
     postMessage({ type: 'payment:started' });
+    if (await resumeOntoRecordedOutcome()) return;
+    currentView = 'payment';
     // The guard's watcher fires once per deadline and may already have done so before this modal existed (a
     // reload after the clock ran out, or checkout reopened late). Nothing else would tear the attempt down
     // then; the shopper would land on a card form for a cart that is already gone.
     if (cartDeadline(cart).getTime() <= Date.now()) void onPaymentTimedOut();
   }
 
-  resumeInterruptedPayment();
+  // Whether the server already holds an outcome for the interrupted attempt - shown on the result view if so.
+  // A settled answer (a charge, a supplier-side partial failure, or a decline) is final; a confirmation the
+  // webhook is running right now joins the ordinary confirm loop to read its result; a cart the server no
+  // longer has closes the modal, as a 401 does everywhere else here. A 402 says neither the webhook nor Peach's
+  // status endpoint has anything final for this attempt - a shopper who never submitted the card, or one who
+  // reloaded mid-3-D Secure, and the two cannot be told apart from here (PR 8447 review). The card form is
+  // where both of them were, and it is Peach's own form for this same checkoutId - the state of that checkout,
+  // not a fresh charge - so that is where they go back to. Anything else - the server unreachable, an
+  // unexpected refusal - is treated the same way rather than parking them on a screen that tells them not to
+  // pay again for a card they may never have submitted.
+  async function resumeOntoRecordedOutcome(): Promise<boolean> {
+    isConfirming = true;
+    currentView = 'result';
+    let answer: ConfirmAnswer;
+    try {
+      answer = await interpretConfirm();
+    } catch {
+      // Nothing in interpretConfirm is meant to throw past its own catch, but this resume is fire-and-forget:
+      // anything that did would strand the modal on "Verifying payment..." with no button at all. A decline
+      // already recorded before the throw is shown; anything else falls back to the card form.
+      isConfirming = false;
+      return confirmOutcome !== null;
+    }
+    isConfirming = false;
+    if (answer === 'settled') return true;
+    if (answer === 'cartGone') {
+      close();
+      return true;
+    }
+    if (answer === 'confirming') {
+      await runConfirmLoop();
+      return true;
+    }
+    return false;
+  }
+
+  void resumeInterruptedPayment();
 
   let cartTotal = $derived(() => cart.items.reduce((s, i) => s + i.amount, 0));
   let cartCurrency = $derived(() => cart.items[0]?.currencyCode ?? 'ZAR');
@@ -267,15 +319,36 @@
     if (!contactForm?.isValid() || !privacyAccepted) return;
 
     // paymentResult is only ever still set here when the previous attempt could not be torn down: the abandon
-    // call failed (Peach unreachable), or Peach reported the charge as settled or still in flight. The server
-    // still holds that attempt (a second payCart would be refused with a 409), so the only useful move is to
-    // resume it. Every other way out of PaymentPage - cancel, expiry, error - abandons the attempt and clears
-    // paymentResult, and the next Pay Now creates a NEW Peach checkout. That is deliberate, not waste: Peach's
-    // SDK forbids re-rendering a checkoutId once it has been unmounted, a cancelled checkout is finished on
-    // Peach's side, and the total is frozen at creation so an edited cart needs a new one regardless.
+    // call failed (Peach unreachable), or Peach reported the charge as settled or still in flight. Every other
+    // way out of PaymentPage - cancel, expiry, error - releases the attempt and clears paymentResult, and the
+    // next Pay Now creates a NEW Peach checkout. That is deliberate, not waste: Peach's SDK will not re-render
+    // a checkoutId it has already unmounted, a cancelled checkout is finished on Peach's side, and the total is
+    // frozen at creation so an edited cart needs a new one regardless.
+    //
+    // Which is exactly why this asks the server to release the attempt once more before anything else, rather
+    // than resuming it on the spot as it used to: that put the shopper back on a card form for a checkoutId
+    // Peach was done with, and Peach's own unrecoverable-error card in front of them instead of ours (PR 8447
+    // review). A release that succeeds leaves the cart Open and falls through to a genuinely new checkout. One
+    // that reports it has taken over - the charge turned out to have settled after all, or the cart is gone -
+    // owns what happens next, and paying again is the one thing that must not happen. Only a release that fails
+    // again leaves the server still holding the attempt (a second payCart would be refused with a 409), and
+    // then resuming that same card form really is the only move left.
     if (paymentResult) {
-      currentView = 'payment';
-      return;
+      isPaying = true;
+      try {
+        if (!(await releaseAbandonedAttempt())) return;
+      } catch {
+        // reloadCart rethrows anything that is not the cart being gone, and releaseAbandonedAttempt re-reads
+        // the cart on its way out. The attempt's own outcome is already decided by then, so the two lines
+        // below still route correctly on it; all a failed re-read costs is a countdown read a moment ago.
+      } finally {
+        isPaying = false;
+      }
+
+      if (paymentResult) {
+        currentView = 'payment';
+        return;
+      }
     }
 
     const contact = contactForm.getContact();
@@ -317,8 +390,10 @@
     // Neither cancelled, expired nor error ever reached a real charge - Peach's own SDK is reporting that the
     // checkout itself didn't go through (the shopper backed out, session timeout, a declined card, a 3DS
     // failure, a client-side error), not that a successful charge's confirmation is in question. That
-    // distinction matters: the confirm path at the bottom is only reachable once onCompleted has fired,
-    // meaning the card WAS charged, so "try again" there would risk a second charge. Here nothing was charged,
+    // distinction matters: the confirm path at the bottom is only reachable once onCompleted has fired, which
+    // Peach does for a settled outcome of either kind - a charge, or a decline (the server reads that back from
+    // Peach's status endpoint, since Peach sends no webhook for one, and answers PAYMENT_FAILED). So "try again"
+    // there is only ever offered once the server itself has said nothing was charged. Here nothing was charged,
     // so the attempt is abandoned server-side (a retry then starts a genuinely new Peach checkout instead of
     // reopening this dead one) and re-opening the card form is exactly correct.
     if (result.status === 'cancelled' || result.status === 'expired' || result.status === 'error') {
@@ -387,7 +462,8 @@
   }
 
   // The declined counterpart to releaseAbandonedAttempt, and deliberately without its abandon call: the server
-  // has already resolved this attempt itself - the webhook landed with a decline, which is what moved the cart
+  // has already resolved this attempt itself - a decline reached it (Peach's webhook, or its own read of Peach's
+  // status endpoint on confirm, since Peach sends no webhook for a declined card), which is what moved the cart
   // to Failed and produced the PAYMENT_FAILED this follows - so there is nothing left to report. AbandonPaymentAsync
   // answers a Failed cart with AlreadyOpen, an explicit no-op, and skipping it also keeps this off the branch
   // that routes a 'settled' abandon back into runConfirmLoop, which would recurse from inside that very loop.
@@ -399,33 +475,36 @@
     forgetPaymentAttempt();
     // Failed is live and still payable again - the decline leaves the cart's one clock exactly where it was -
     // so this re-reads whatever time Try Again actually has left rather than the deadline from before the card
-    // form. A cart whose clock ran out meanwhile 401s here and closes the modal, same as anywhere else.
-    if (await reloadCart()) notifyCartUpdated(cart);
+    // form. A cart whose clock ran out meanwhile 401s here and closes the modal, same as anywhere else. Any
+    // other failure of the re-read must not escape: this runs inside interpretConfirm's own catch, from where
+    // a throw would strand the shopper on "Verifying payment..." with no button at all, and the decline itself
+    // is already recorded - Try Again simply counts down from the older deadline (PR 8447 review).
+    try {
+      if (await reloadCart()) notifyCartUpdated(cart);
+    } catch {
+      // see above
+    }
     // Without this CartExpiryGuard keeps treating a payment as in flight for the rest of the page's life, so it
     // never prompts or expires this cart again.
     postMessage({ type: 'payment:ended' });
   }
 
-  // One confirm attempt, interpreted: records the result and reports whether it settled (success or a
-  // supplier-side partial failure - either way, nothing left to retry) versus still needs another attempt
-  // (the two webhook races below). Shared by the automatic loop and the manual on-demand recheck so there is
-  // exactly one place that decides what a given confirmCart() outcome means.
-  async function attemptConfirm(): Promise<'settled' | 'awaitingWebhook'> {
+  type ConfirmAnswer = 'settled' | 'notPaid' | 'confirming' | 'cartGone' | 'unknown';
+
+  // One confirmCart() call, interpreted - the single place that decides what each answer means, shared by the
+  // automatic loop, the manual on-demand recheck and a resume after a reload. 'settled' has recorded the result
+  // (success, a supplier-side partial failure, or a decline - nothing left to retry); the other three record
+  // nothing and leave the caller to decide what "no outcome yet" means where it stands.
+  async function interpretConfirm(): Promise<ConfirmAnswer> {
     try {
-      confirmResult = await api.confirmCart();
-      const allOk = confirmResult.items.every((i) => i.statusCode >= 200 && i.statusCode < 300);
-      confirmOutcome = allOk ? 'success' : 'partial';
-      // Notifies the host (order value/currency for analytics, clearing the stored cart token) without
-      // closing the modal - the shopper still needs to see the success screen below, and only dismisses it
-      // themselves via ResultView's Done button, which is the one thing that posts modal:close.
-      if (allOk) {
-        onOrderConfirmed();
-      }
+      recordConfirmation(await api.confirmCart());
       return 'settled';
     } catch (e) {
-      // The one case that is a real, settled failure rather than a race still resolving: Peach's webhook has
-      // already landed and it was a decline (or another non-success outcome), so there is no charge behind
-      // this attempt and never will be - retrying confirmCart again cannot change that. Checked before the
+      // The one case that is a real, settled failure rather than a race still resolving: the server knows the
+      // attempt was declined (or another non-success outcome) - from Peach's webhook, or from asking Peach's
+      // status endpoint itself when no webhook had landed, which is how every ordinary card decline arrives
+      // since Peach sends no webhook for one - so there is no charge behind this attempt and never will be;
+      // retrying confirmCart again cannot change that. Checked before the
       // generic 402/409 below, which would otherwise read this the same as "webhook not here yet" and retry
       // it right into the same generic "still confirming" pending screen a decline should never land on.
       if (isPaymentFailed(e)) {
@@ -435,22 +514,45 @@
       }
 
       // Two different races with the same webhook, neither a real failure:
-      //   402 - the charge succeeded (that's why PaymentPage's onCompleted fired) but the webhook hasn't
-      //         reached PeachWebhookEndpoints yet to move the cart to Paid.
+      //   402 - Peach has no final answer for this attempt yet (a 3-D Secure check still in flight, or its own
+      //         bookkeeping not caught up with the form that just completed) and the webhook hasn't reached
+      //         PeachWebhookEndpoints yet either, so the cart is not yet Paid.
       //   409 - the webhook got there first and is confirming the cart right now, so there is no outcome to
       //         read yet. Only one caller is allowed to run confirmation, and the loser is told to retry
       //         rather than being handed a second, independently-produced answer.
-      // Both resolve on their own within a second or two, so both are worth retrying. Any other error settles
-      // as 'pending' rather than a failure state - the charge already succeeded by the time this can run at
-      // all, so there is no "payment failed" to report, only "not confirmed yet".
-      if (e instanceof ApiError && (e.status === 402 || e.status === 409)) {
-        return 'awaitingWebhook';
-      }
-      confirmOutcome = 'pending';
-      return 'settled';
+      // Both resolve on their own within a second or two. What "no outcome yet" or an unexpected error means
+      // depends on who is asking - see attemptConfirm and resumeOntoRecordedOutcome.
+      if (e instanceof ApiError && e.status === 402) return 'notPaid';
+      if (e instanceof ApiError && e.status === 409) return 'confirming';
+      if (isInvalidCart(e)) return 'cartGone';
+      return 'unknown';
+    }
+  }
+
+  function recordConfirmation(result: CheckoutCartConfirmResultDto): void {
+    confirmResult = result;
+    const allOk = result.items.every((i) => i.statusCode >= 200 && i.statusCode < 300);
+    confirmOutcome = allOk ? 'success' : 'partial';
+    // Notifies the host (order value/currency for analytics, clearing the stored cart token) without closing
+    // the modal - the shopper still needs to see the success screen, and only dismisses it themselves via
+    // ResultView's Done button, which is the one thing that posts modal:close.
+    if (allOk) {
+      onOrderConfirmed();
     }
   }
 
+  // The loop and the on-demand recheck only run once the attempt is known to have completed on Peach's side -
+  // onCompleted fired, or a resume after a reload found the webhook already confirming it - so "not paid" and
+  // "being confirmed" are both webhook races worth another attempt, and any other error (a cart the server no
+  // longer has included - by now that is a paid cart it cannot show, not one to pay again) settles as 'pending'
+  // rather than a failure state: there is no "payment failed" to report, only "not confirmed yet".
+  async function attemptConfirm(): Promise<'settled' | 'awaitingWebhook'> {
+    const answer = await interpretConfirm();
+    if (answer === 'notPaid' || answer === 'confirming') return 'awaitingWebhook';
+    if (answer === 'unknown' || answer === 'cartGone') confirmOutcome = 'pending';
+    return 'settled';
+  }
+
   async function runConfirmLoop() {
     isConfirming = true;
     confirmOutcome = null;
@@ -483,10 +585,11 @@
     isConfirming = false;
   }
 
-  // The one ResultView prop that isn't a straight readout of confirmOutcome: 'partial' means the payment
-  // succeeded but this gateway could not confirm every item, which is a real problem worth surfacing
-  // distinctly from 'pending' (which resolves on its own) - but from ResultView's own outcome union, that is
-  // still a kind of 'failed', just one retryPayment must gate off since the charge already happened.
+  // A straight readout of confirmOutcome onto ResultView's own outcome union, which now carries one of each.
+  // 'partial' - the payment succeeded but this gateway could not confirm every item - keeps an outcome of its
+  // own the whole way through: it is a real problem worth surfacing distinctly from 'pending' (which resolves
+  // on its own), and it must never reach the shopper as "Payment Failed", because their card was charged.
+  // ResultView owns the wording for it, as it already did for 'successful' and 'pending'.
   let resultStatus = $derived(
     isConfirming
       ? null
@@ -495,12 +598,7 @@
         : confirmOutcome === 'pending'
           ? { outcome: 'pending' as const }
           : confirmOutcome === 'partial'
-            ? {
-                outcome: 'failed' as const,
-                resultDescription:
-                  "Your payment succeeded, but we couldn't confirm every item in your booking. Please contact us with your order details.",
-                retryPayment: false,
-              }
+            ? { outcome: 'partial' as const }
             : confirmOutcome === 'notCharged'
               ? {
                   outcome: 'failed' as const,
@@ -517,13 +615,23 @@
       <div class="spinner"></div>
     </div>
 
-  {:else if currentView === 'payment' && paymentResult}
-    <PaymentPage
-      checkoutId={paymentResult.checkoutId}
-      entityId={paymentResult.entityId}
-      expiresAt={expiryDeadline}
-      {onPaymentComplete}
-    />
+  {:else if currentView === 'payment'}
+    <!-- Still on the payment view but with no attempt left to render: releaseAbandonedAttempt clears
+         paymentResult and then re-reads the cart before its caller routes anywhere, and without this the modal
+         fell straight through to the cart view below for the length of that round trip - so the shopper watched
+         their cart reappear before landing on the failure screen they were being sent to (PR 8447 review). -->
+    {#if paymentResult}
+      <PaymentPage
+        checkoutId={paymentResult.checkoutId}
+        entityId={paymentResult.entityId}
+        expiresAt={expiryDeadline}
+        {onPaymentComplete}
+      />
+    {:else}
+      <div class="loading-center" style="height:100%">
+        <div class="spinner"></div>
+      </div>
+    {/if}
 
   {:else if currentView === 'result'}
     <ResultView

package/src/lib/CheckoutPanel.svelte

@@ -1,121 +1,121 @@
-<script lang="ts">
-  import type { BookingApi } from './api';
-  import type { WizardPages } from './config';
-  import { DEFAULT_WIZARD_PAGES } from './config';
-  import type { CheckoutCartDetailDto } from './client-types';
-  import { isInvalidCart } from './api';
-  import { onWidgetMessage, postMessage } from './messages';
-  import type { CartManager } from './cart-manager';
-  import CheckoutModal from './CheckoutModal.svelte';
-  import CartExpiredView from './CartExpiredView.svelte';
-
-  interface Props {
-    api: BookingApi;
-    cartManager?: CartManager;
-    wizardPages?: WizardPages;
-    editPages?: WizardPages;
-    autoSelectSingleTimeSlot?: boolean;
-  }
-  let { api, cartManager, wizardPages = DEFAULT_WIZARD_PAGES, editPages: editPagesProp,
-    autoSelectSingleTimeSlot = false }: Props = $props();
-  let editPages = $derived(editPagesProp ?? wizardPages);
-
-  let cart = $state<CheckoutCartDetailDto | null>(null);
-  let isLoading = $state(true);
-  let expired = $state(false);
-
-  async function load() {
-    // A token this widget still holds for a cart the server has already let go (its window ran out while the
-    // tab sat there) used to render as a bare "No items in cart", with the dead token left in storage for the
-    // next add to trip over. Only a held token can mean that - with none, an empty cart is just empty.
-    const hadCart = api.cartToken !== '';
-    try {
-      cart = await api.getCart();
-    } catch (e) {
-      cart = null;
-      if (hadCart && isInvalidCart(e)) {
-        onCartExpired();
-        expired = true;
-      }
-    }
-    isLoading = false;
-  }
-
-  load();
-
-  // Drops the stored token so whatever the shopper does next starts a fresh cart, and clears bw-cart's
-  // bar/button and any host-side summary built from bw:cart-updated - the cart they were describing no longer
-  // exists. Mirrors what onOrderConfirmed below does once a cart has served its purpose the other way.
-  function onCartExpired() {
-    cartManager?.reset();
-    postMessage({ type: 'cart:updated', cart: null });
-    postMessage({ type: 'cart:expired' });
-  }
-
-  // In modal mode, modal:close is what actually dismisses this screen - bw-checkout.svelte remounts this
-  // component fresh the next time it opens, so the click is fully handled there. Rendered permanently
-  // in-page instead, nothing is listening for modal:close, so without the reload below the click would do
-  // nothing a shopper can see: expired flips off, but cart is still the stale null from the load() that
-  // found it gone, leaving the same "No items in cart" text up with no sign anything happened.
-  function startAgain() {
-    expired = false;
-    postMessage({ type: 'modal:close' });
-    void load();
-  }
-
-  // In modal mode this is redundant - bw-checkout.svelte only mounts this component fresh each time the
-  // modal opens, so it already gets a current cart. Rendered permanently in-page instead (no is-modal), it
-  // would otherwise only ever see the cart as it was on first mount. The event already carries the fresh
-  // cart (see TicketConfigurator/CheckoutModal's own posting sites), so this applies it directly rather than
-  // triggering a second, redundant getCart() call or flashing the spinner over an already-visible cart.
-  $effect(() => onWidgetMessage((d) => {
-    if (d.type === 'cart:updated' && 'cart' in d) cart = d.cart as CheckoutCartDetailDto | null;
-  }));
-</script>
-
-<div class="bw-widget">
-  {#if isLoading}
-    <div class="loading-center" style="height:100vh">
-      <div class="spinner"></div>
-    </div>
-  {:else if cart && cart.items.length > 0}
-    <CheckoutModal
-      {cart}
-      {api}
-      {wizardPages}
-      {editPages}
-      {autoSelectSingleTimeSlot}
-      onClose={() => postMessage({ type: 'modal:close' })}
-      onOrderConfirmed={() => {
-        const total = cart!.items.reduce((s, i) => s + i.amount, 0);
-        const currency = cart!.items[0]?.currencyCode ?? 'ZAR';
-        postMessage({
-          type: 'order:complete',
-          cartToken: cart!.cartToken ?? '',
-          value: total,
-          currency,
-        });
-        // The cart is paid and confirmed, so its token has done its job. Nothing used to clear it, so it sat
-        // in localStorage on the merchant's origin until absoluteExpiresAt - readable by every third-party
-        // script they load, and picked up by the next person to use a shared or kiosk browser.
-        cartManager?.reset();
-      }}
-    />
-  {:else if expired}
-    <div style="height:100vh">
-      <CartExpiredView onStartAgain={startAgain} />
-    </div>
-  {:else}
-    <div class="loading-center" style="height:100vh;color:var(--bw-color-text-secondary)">
-      No items in cart.
-    </div>
-  {/if}
-</div>
-
-<style>
-  /* display: contents - a plain box here would break CheckoutModal's own .modal{height:100%}, which needs
-     to resolve against this component's real parent, not an unsized wrapper inserted in between. */
-  .bw-widget {
-    display: contents;
-  }
-</style>
+<script lang="ts">
+  import type { BookingApi } from './api';
+  import type { WizardPages } from './config';
+  import { DEFAULT_WIZARD_PAGES } from './config';
+  import type { CheckoutCartDetailDto } from './client-types';
+  import { isInvalidCart } from './api';
+  import { onWidgetMessage, postMessage } from './messages';
+  import type { CartManager } from './cart-manager';
+  import CheckoutModal from './CheckoutModal.svelte';
+  import CartExpiredView from './CartExpiredView.svelte';
+
+  interface Props {
+    api: BookingApi;
+    cartManager?: CartManager;
+    wizardPages?: WizardPages;
+    editPages?: WizardPages;
+    autoSelectSingleTimeSlot?: boolean;
+  }
+  let { api, cartManager, wizardPages = DEFAULT_WIZARD_PAGES, editPages: editPagesProp,
+    autoSelectSingleTimeSlot = false }: Props = $props();
+  let editPages = $derived(editPagesProp ?? wizardPages);
+
+  let cart = $state<CheckoutCartDetailDto | null>(null);
+  let isLoading = $state(true);
+  let expired = $state(false);
+
+  async function load() {
+    // A token this widget still holds for a cart the server has already let go (its window ran out while the
+    // tab sat there) used to render as a bare "No items in cart", with the dead token left in storage for the
+    // next add to trip over. Only a held token can mean that - with none, an empty cart is just empty.
+    const hadCart = api.cartToken !== '';
+    try {
+      cart = await api.getCart();
+    } catch (e) {
+      cart = null;
+      if (hadCart && isInvalidCart(e)) {
+        onCartExpired();
+        expired = true;
+      }
+    }
+    isLoading = false;
+  }
+
+  load();
+
+  // Drops the stored token so whatever the shopper does next starts a fresh cart, and clears bw-cart's
+  // bar/button and any host-side summary built from bw:cart-updated - the cart they were describing no longer
+  // exists. Mirrors what onOrderConfirmed below does once a cart has served its purpose the other way.
+  function onCartExpired() {
+    cartManager?.reset();
+    postMessage({ type: 'cart:updated', cart: null });
+    postMessage({ type: 'cart:expired' });
+  }
+
+  // In modal mode, modal:close is what actually dismisses this screen - bw-checkout.svelte remounts this
+  // component fresh the next time it opens, so the click is fully handled there. Rendered permanently
+  // in-page instead, nothing is listening for modal:close, so without the reload below the click would do
+  // nothing a shopper can see: expired flips off, but cart is still the stale null from the load() that
+  // found it gone, leaving the same "No items in cart" text up with no sign anything happened.
+  function startAgain() {
+    expired = false;
+    postMessage({ type: 'modal:close' });
+    void load();
+  }
+
+  // In modal mode this is redundant - bw-checkout.svelte only mounts this component fresh each time the
+  // modal opens, so it already gets a current cart. Rendered permanently in-page instead (no is-modal), it
+  // would otherwise only ever see the cart as it was on first mount. The event already carries the fresh
+  // cart (see TicketConfigurator/CheckoutModal's own posting sites), so this applies it directly rather than
+  // triggering a second, redundant getCart() call or flashing the spinner over an already-visible cart.
+  $effect(() => onWidgetMessage((d) => {
+    if (d.type === 'cart:updated' && 'cart' in d) cart = d.cart as CheckoutCartDetailDto | null;
+  }));
+</script>
+
+<div class="bw-widget">
+  {#if isLoading}
+    <div class="loading-center" style="height:100vh">
+      <div class="spinner"></div>
+    </div>
+  {:else if cart && cart.items.length > 0}
+    <CheckoutModal
+      {cart}
+      {api}
+      {wizardPages}
+      {editPages}
+      {autoSelectSingleTimeSlot}
+      onClose={() => postMessage({ type: 'modal:close' })}
+      onOrderConfirmed={() => {
+        const total = cart!.items.reduce((s, i) => s + i.amount, 0);
+        const currency = cart!.items[0]?.currencyCode ?? 'ZAR';
+        postMessage({
+          type: 'order:complete',
+          cartToken: cart!.cartToken ?? '',
+          value: total,
+          currency,
+        });
+        // The cart is paid and confirmed, so its token has done its job. Nothing used to clear it, so it sat
+        // in localStorage on the merchant's origin until absoluteExpiresAt - readable by every third-party
+        // script they load, and picked up by the next person to use a shared or kiosk browser.
+        cartManager?.reset();
+      }}
+    />
+  {:else if expired}
+    <div style="height:100vh">
+      <CartExpiredView onStartAgain={startAgain} />
+    </div>
+  {:else}
+    <div class="loading-center" style="height:100vh;color:var(--bw-color-text-secondary)">
+      No items in cart.
+    </div>
+  {/if}
+</div>
+
+<style>
+  /* display: contents - a plain box here would break CheckoutModal's own .modal{height:100%}, which needs
+     to resolve against this component's real parent, not an unsized wrapper inserted in between. */
+  .bw-widget {
+    display: contents;
+  }
+</style>