@code-collective/booking-widget 1.0.8 → 1.0.10

package/src/lib/CartExpiryGuard.test.ts

@@ -0,0 +1,331 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/svelte';
+import CartExpiryGuard from './CartExpiryGuard.svelte';
+import { postMessage, postedTypes, posted, resetMessages } from './test/messages-mock';
+import { apiError, buildCart, CART_TOKEN, fakeApi, fakeCartManager, settle } from './test/fixtures';
+import { EXPIRY_WARNING_MS, EXTENSION_ENABLED } from './cart-expiry';
+import { recallPaymentAttempt, rememberPaymentAttempt } from './payment-attempt';
+
+vi.mock('./messages', async () => await import('./test/messages-mock'));
+
+// The guard owns the whole "one clock" experience on the client: the still-there prompt, the extend, and the
+// server-confirmed expiry. Time is faked so a 20-minute cart can be walked to its deadline in a test, and the
+// server is a fake BookingApi whose answers each scenario sets.
+
+const MINUTE = 60_000;
+
+// The prompt is switched off in production for now (EXTENSION_ENABLED in cart-expiry.ts); these tests turn it
+// on explicitly so the extension path stays covered for the day it is turned back on. The "deadline passing"
+// tests below run with it on too - the expiry behaviour must be identical either way - and one test checks
+// the default.
+function mount(cart = buildCart(EXPIRY_WARNING_MS + MINUTE), extensionEnabled = true) {
+  const api = fakeApi(cart);
+  const cartManager = fakeCartManager();
+  render(CartExpiryGuard, { props: { api, cartManager, extensionEnabled } });
+  return { api, cartManager, cart };
+}
+
+async function advance(ms: number) {
+  await vi.advanceTimersByTimeAsync(ms);
+  await settle();
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
+  vi.setSystemTime(new Date('2026-09-12T10:00:00Z'));
+  resetMessages();
+  sessionStorage.clear();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+describe('with the extension switched off (the current default)', () => {
+  it('never shows the prompt - the shopper just sees the cart expire at 0:00', async () => {
+    // Mounted with the production default (EXTENSION_ENABLED, currently false), not this file's opt-in.
+    expect(EXTENSION_ENABLED).toBe(false);
+    const { api } = mount(buildCart(EXPIRY_WARNING_MS - 1000), EXTENSION_ENABLED);
+    await settle();
+    await advance(1000);
+    expect(screen.queryByText('Are you still there?')).toBeNull();
+
+    api.getCart = vi.fn().mockRejectedValue(apiError(401));
+    await advance(EXPIRY_WARNING_MS);
+
+    expect(screen.queryByText('Are you still there?')).toBeNull();
+    expect(screen.getByText('Your cart has expired')).toBeTruthy();
+    expect(api.extendCart).not.toHaveBeenCalled();
+  });
+});
+
+describe('the still-there prompt', () => {
+  it('appears once the deadline is within the warning window', async () => {
+    mount();
+    await settle();
+    expect(screen.queryByText('Are you still there?')).toBeNull();
+
+    await advance(MINUTE + 1000);
+
+    expect(screen.getByText('Are you still there?')).toBeTruthy();
+    expect(screen.getByRole('button', { name: "Yes, I'm still here" })).toBeTruthy();
+  });
+
+  it('is still shown while a Peach checkout is open - the clock keeps running on the card form', async () => {
+    mount();
+    await settle();
+    postMessage({ type: 'payment:started' });
+
+    await advance(MINUTE + 1000);
+
+    expect(screen.getByText('Are you still there?')).toBeTruthy();
+    expect(screen.getByRole('button', { name: "Yes, I'm still here" })).toBeTruthy();
+  });
+
+  it('Yes extends the cart and tells every other reader about the new deadline', async () => {
+    const { api } = mount();
+    await settle();
+    await advance(MINUTE + 1000);
+    const extended = buildCart(15 * MINUTE);
+    api.extendCart = vi.fn().mockResolvedValue(extended);
+
+    screen.getByRole('button', { name: "Yes, I'm still here" }).click();
+    await settle();
+
+    expect(api.extendCart).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText('Are you still there?')).toBeNull();
+    expect(posted.at(-1)).toEqual({ type: 'cart:updated', cart: extended });
+  });
+
+  it('a refused hold extension (deadline comes back unmoved) just closes the prompt and leaves the clock', async () => {
+    const { api, cart } = mount();
+    await settle();
+    await advance(MINUTE + 1000);
+    api.extendCart = vi.fn().mockResolvedValue({ ...cart });
+
+    screen.getByRole('button', { name: "Yes, I'm still here" }).click();
+    await settle();
+
+    expect(screen.queryByText('Are you still there?')).toBeNull();
+    expect(screen.queryByText(/can't be held any longer/)).toBeNull();
+    // Not re-shown for the same deadline on the next tick.
+    await advance(5000);
+    expect(screen.queryByText('Are you still there?')).toBeNull();
+    // The clock is untouched: at the original deadline the guard asks the server, and expires on its 401.
+    api.getCart = vi.fn().mockRejectedValue(apiError(401));
+    await advance(EXPIRY_WARNING_MS);
+    expect(screen.getByText('Your cart has expired')).toBeTruthy();
+  });
+
+  it('only warns, without a Yes, once the cart is at its absolute ceiling', async () => {
+    mount(buildCart(2 * MINUTE, { ceilingMsFromNow: 2 * MINUTE }));
+    await settle();
+    await advance(1000);
+
+    expect(screen.getByText(/can't be held any longer/)).toBeTruthy();
+    expect(screen.queryByRole('button', { name: "Yes, I'm still here" })).toBeNull();
+  });
+});
+
+describe('the deadline passing', () => {
+  it('asks the server and shows the cart as expired on its 401, clearing the cart everywhere', async () => {
+    const { api, cartManager } = mount(buildCart(2000));
+    await settle();
+    api.getCart = vi.fn().mockRejectedValue(apiError(401));
+
+    await advance(3000);
+
+    expect(screen.getByText('Your cart has expired')).toBeTruthy();
+    expect(cartManager.reset).toHaveBeenCalledTimes(1);
+    // cart:expired is the more specific signal, posted right before the general cart:updated/null every
+    // other reader already listens for.
+    expect(postedTypes().slice(-2)).toEqual(['cart:expired', 'cart:updated']);
+    expect(posted.at(-1)).toEqual({ type: 'cart:updated', cart: null });
+  });
+
+  it('keeps a cart the server still reports live - the browser clock only decides when to ask', async () => {
+    const { api, cartManager } = mount(buildCart(2000));
+    await settle();
+    const stillLive = buildCart(2000);
+    api.getCart = vi.fn().mockResolvedValue(stillLive);
+
+    await advance(3000);
+
+    expect(screen.queryByText('Your cart has expired')).toBeNull();
+    expect(cartManager.reset).not.toHaveBeenCalled();
+    expect(posted.at(-1)).toEqual({ type: 'cart:updated', cart: stillLive });
+    // Exactly one read, then a 30s recheck - not a tight loop. Re-reading the cart hands the watcher a fresh
+    // Date for the same past deadline, and a watcher that fired once per effect run rather than once per
+    // deadline re-fired straight away, asking again, and again (CartExpiryWatcher's firedFor).
+    expect(api.getCart).toHaveBeenCalledTimes(1);
+    // The recheck was scheduled at T-0, one second into the advance above.
+    await advance(28_000);
+    expect(api.getCart).toHaveBeenCalledTimes(1);
+    await advance(2000);
+    expect(api.getCart).toHaveBeenCalledTimes(2);
+  });
+
+  it('with a payment in flight, asks the server first and hands a deadline it still reports as past to CheckoutModal', async () => {
+    const { api } = mount(buildCart(2000));
+    await settle();
+    postMessage({ type: 'payment:started' });
+    api.getCart = vi.fn().mockResolvedValue(buildCart(-1000));
+
+    await advance(3000);
+
+    // One ask, one hand-over - even though the cart read back carries a (still past) deadline the watcher had
+    // not fired for yet.
+    expect(api.getCart).toHaveBeenCalledTimes(1);
+    expect(postedTypes().filter((type) => type === 'payment:timed-out')).toHaveLength(1);
+    expect(postedTypes()).toContain('payment:timed-out');
+    expect(screen.queryByText('Your cart has expired')).toBeNull();
+  });
+
+  it('with a payment in flight, keeps a cart the server reports on a later deadline rather than tearing the attempt down', async () => {
+    // Another tab answered the prompt, or the server pushed the clock out to the payment floor when the
+    // attempt began and this guard never heard - either way the browser's deadline was stale, and acting on
+    // it would have destroyed a card form the shopper may be mid-way through.
+    const { api } = mount(buildCart(2000));
+    await settle();
+    postMessage({ type: 'payment:started' });
+    const movedOut = buildCart(5 * MINUTE);
+    api.getCart = vi.fn().mockResolvedValue(movedOut);
+
+    await advance(3000);
+
+    expect(postedTypes()).not.toContain('payment:timed-out');
+    expect(api.abandonPayment).not.toHaveBeenCalled();
+    expect(posted.at(-1)).toEqual({ type: 'cart:updated', cart: movedOut });
+    // The watcher re-armed on the later deadline and asks again there; this time the server agrees.
+    await advance(5 * MINUTE);
+    expect(api.getCart).toHaveBeenCalledTimes(2);
+    expect(postedTypes()).toContain('payment:timed-out');
+  });
+
+  it('with a payment in flight, a read that fails is no grounds to tear the attempt down - it asks again', async () => {
+    const { api } = mount(buildCart(2000));
+    await settle();
+    postMessage({ type: 'payment:started' });
+    api.getCart = vi.fn().mockRejectedValueOnce(apiError(500)).mockResolvedValue(buildCart(-1000));
+
+    await advance(3000);
+    expect(postedTypes()).not.toContain('payment:timed-out');
+
+    await advance(30_000);
+    expect(api.getCart).toHaveBeenCalledTimes(2);
+    expect(postedTypes()).toContain('payment:timed-out');
+  });
+
+  it('after the attempt is torn down, payment:ended brings it back to confirm the expiry', async () => {
+    const { api } = mount(buildCart(2000));
+    await settle();
+    postMessage({ type: 'payment:started' });
+    await advance(3000);
+    api.getCart = vi.fn().mockRejectedValue(apiError(401));
+
+    postMessage({ type: 'payment:ended' });
+    await settle();
+
+    expect(screen.getByText('Your cart has expired')).toBeTruthy();
+  });
+
+  it('with no checkout modal open to answer payment:timed-out, the guard abandons the attempt itself', async () => {
+    // After a reload the guard knows of the attempt from sessionStorage alone; nothing else would ever tear
+    // it down, so the cart would sit in limbo with no expiry shown.
+    rememberPaymentAttempt(CART_TOKEN, { checkoutId: 'peach-1', entityId: 'entity-1' });
+    const { api } = mount(buildCart(2000));
+    await settle();
+    // The server still holds the cart for the attempt (a cart awaiting payment is exempt from the 401), so the
+    // ask at T-0 gets it back unmoved; only once the attempt is abandoned does the reopened, past-deadline cart
+    // stop validating.
+    api.getCart = vi.fn().mockResolvedValueOnce(buildCart(-1000)).mockRejectedValue(apiError(401));
+
+    await advance(3000);
+    expect(postedTypes()).toContain('payment:timed-out');
+    expect(api.abandonPayment).not.toHaveBeenCalled();
+
+    await advance(5000);
+
+    expect(api.abandonPayment).toHaveBeenCalledWith('peach-1');
+    expect(recallPaymentAttempt(CART_TOKEN)).toBeNull();
+    expect(screen.getByText('Your cart has expired')).toBeTruthy();
+  });
+
+  it('a payment that ends while the guard is still asking the server falls through to the ordinary expiry check', async () => {
+    // CheckoutModal tears a resumed attempt down itself when it finds the deadline already past, and its
+    // payment:ended can land while this guard's own read is in flight. Nothing may be handed over after that,
+    // and the expiry still has to be confirmed and shown.
+    rememberPaymentAttempt(CART_TOKEN, { checkoutId: 'peach-1', entityId: 'entity-1' });
+    const { api } = mount(buildCart(2000));
+    await settle();
+    let answerTheRead: (cart: ReturnType<typeof buildCart>) => void = () => {};
+    const pendingRead = new Promise<ReturnType<typeof buildCart>>((resolve) => { answerTheRead = resolve; });
+    api.getCart = vi.fn().mockReturnValueOnce(pendingRead).mockRejectedValue(apiError(401));
+
+    await advance(3000);
+    expect(api.getCart).toHaveBeenCalledTimes(1);
+    postMessage({ type: 'payment:ended' });
+    await settle();
+    answerTheRead(buildCart(-1000));
+    await settle();
+
+    expect(postedTypes()).not.toContain('payment:timed-out');
+    expect(api.getCart).toHaveBeenCalledTimes(2);
+    expect(screen.getByText('Your cart has expired')).toBeTruthy();
+  });
+
+  it('drops the unanswered-timeout fallback when the guard is unmounted before it fires', async () => {
+    // A pending fallback outliving the guard would abandon a payment attempt on behalf of a page that no
+    // longer exists.
+    rememberPaymentAttempt(CART_TOKEN, { checkoutId: 'peach-1', entityId: 'entity-1' });
+    const { api } = mount(buildCart(2000));
+    await settle();
+
+    await advance(3000);
+    expect(postedTypes()).toContain('payment:timed-out');
+    cleanup();
+
+    await advance(5000);
+
+    expect(api.abandonPayment).not.toHaveBeenCalled();
+  });
+
+  it.each(['PAYMENT_PENDING', 'PAYMENT_SETTLED'])(
+    'opens checkout instead of tearing down an attempt Peach reports as live (%s), even with no modal to answer',
+    async (code) => {
+      // Money in motion is never torn down, but nothing else on the page would confirm it either: reopening
+      // checkout resumes the attempt into the modal's confirm loop.
+      rememberPaymentAttempt(CART_TOKEN, { checkoutId: 'peach-1', entityId: 'entity-1' });
+      const { api } = mount(buildCart(2000));
+      await settle();
+      api.abandonPayment = vi.fn().mockRejectedValue(apiError(409, code));
+      api.getCart = vi.fn().mockResolvedValue(buildCart(-1000));
+
+      await advance(3000 + 5000);
+
+      expect(api.abandonPayment).toHaveBeenCalledWith('peach-1');
+      expect(postedTypes()).toContain('modal:open');
+      // One read: the ask at T-0. Nothing asked about expiry after the refusal - the attempt is left as it is.
+      expect(api.getCart).toHaveBeenCalledTimes(1);
+      expect(recallPaymentAttempt(CART_TOKEN)).not.toBeNull();
+      expect(screen.queryByText('Your cart has expired')).toBeNull();
+    },
+  );
+
+  it("a late Yes the server refuses with CART_EXPIRED takes the same tear-down route", async () => {
+    const { api } = mount();
+    await settle();
+    postMessage({ type: 'payment:started' });
+    await advance(MINUTE + 1000);
+    api.extendCart = vi.fn().mockRejectedValue(apiError(409, 'CART_EXPIRED'));
+
+    screen.getByRole('button', { name: "Yes, I'm still here" }).click();
+    await settle();
+
+    expect(postedTypes()).toContain('payment:timed-out');
+    // CART_EXPIRED is the server's own word - nothing to ask before handing over.
+    expect(api.getCart).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText('Your cart has expired')).toBeNull();
+  });
+});

package/src/lib/CartExpiryWatcher.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { EXPIRY_WARNING_MS, formatRemaining } from './cart-expiry';
+
+  // Headless: keeps the clock and reports it, renders nothing. The owner decides what a warning looks like -
+  // a blocking "are you still there?" while shopping, a non-blocking banner over a card form the shopper may
+  // be mid-way through typing into.
+  interface Props {
+    expiresAt: Date;
+    // Fires once per deadline, the moment it passes. A new expiresAt (an extension, an add) re-arms it.
+    onExpired: () => void;
+    remaining?: string;
+    warning?: boolean;
+  }
+  let { expiresAt, onExpired, remaining = $bindable(''), warning = $bindable(false) }: Props = $props();
+
+  // The deadline (ms) onExpired last fired for. Kept outside the effect and keyed to the *value*, not to the
+  // effect run: the owner re-derives expiresAt as a fresh Date whenever its cart object changes, which
+  // includes the owner re-reading the same cart from the server at T-0 - and that read is exactly what
+  // onExpired triggers. A per-run flag re-armed on every such change fired onExpired again for the same past
+  // deadline, which asked the server again, which re-armed it again: a tight loop of reads against a cart the
+  // server considers live, ending only when the deadline actually moved. Plain let, not $state - nothing
+  // rendered depends on it.
+  let firedFor: number | null = null;
+
+  $effect(() => {
+    const deadline = expiresAt.getTime();
+
+    function tick() {
+      const diff = deadline - Date.now();
+      remaining = formatRemaining(diff);
+      warning = diff > 0 && diff <= EXPIRY_WARNING_MS;
+      if (diff <= 0 && firedFor !== deadline) {
+        firedFor = deadline;
+        // untrack the prop *read* itself, not just the call - the owner passes an inline callback, so a
+        // tracked read of onExpired here (not just of expiresAt above) would re-run this effect on every
+        // parent render, resetting `fired` and firing the same expiry again.
+        untrack(() => onExpired)();
+      }
+    }
+
+    tick();
+    const interval = setInterval(tick, 1000);
+    return () => clearInterval(interval);
+  });
+</script>

package/src/lib/CartOverviewButton.svelte

@@ -3,6 +3,7 @@
   import type { BookingApi } from './api';
   import { CartManager } from './cart-manager';
   import { onWidgetMessage, postMessage } from './messages';
+  import { formatRemaining, cartDeadline } from './cart-expiry';
   import { onDestroy } from 'svelte';
 
   interface Props {
@@ -34,11 +35,7 @@
   }));
 
   function updateTimer() {
-    if (!cart) { remaining = '0:00'; return; }
-    const diff = Math.max(0, new Date(cart.absoluteExpiresAt).getTime() - Date.now());
-    const mins = Math.floor(diff / 60000);
-    const secs = Math.floor((diff % 60000) / 1000);
-    remaining = `${mins}:${String(secs).padStart(2, '0')}`;
+    remaining = cart ? formatRemaining(cartDeadline(cart).getTime() - Date.now()) : formatRemaining(0);
   }
 
   updateTimer();

package/src/lib/Checkout.svelte

@@ -3,9 +3,11 @@
   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;
@@ -20,25 +22,61 @@
 
   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 {
+    } 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();
+    // See CartExpiryGuard.svelte's own expire() for why this is posted alongside, and before, cart:updated.
+    postMessage({ type: 'cart:expired' });
+    postMessage({ type: 'cart:updated', cart: null });
+  }
+
+  // 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.
+  //
+  // cart:expired is CartExpiryGuard's own signal that the clock (not a manual clear) is why the cart just
+  // went null - it fires page-wide, including while this modal is already open showing a live cart, and
+  // without it this falls through to the plain "No items in cart" branch below instead of CartExpiredView,
+  // exactly as if the shopper had simply never had anything in their cart at all.
   $effect(() => onWidgetMessage((d) => {
     if (d.type === 'cart:updated' && 'cart' in d) cart = d.cart as CheckoutCartDetailDto | null;
+    if (d.type === 'cart:expired') expired = true;
   }));
 </script>
 
@@ -70,6 +108,10 @@
         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.

package/src/lib/CheckoutModal.confirm-outcome.test.ts

@@ -0,0 +1,91 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/svelte';
+import CheckoutModal from './CheckoutModal.svelte';
+import { resetMessages } from './test/messages-mock';
+import { apiError, buildCart, CART_TOKEN, fakeApi, installFakePeachSdk, settle } from './test/fixtures';
+import { rememberPaymentAttempt } from './payment-attempt';
+
+vi.mock('./messages', async () => await import('./test/messages-mock'));
+
+// confirmCart answers with a bare 402/409 both while Peach's webhook genuinely hasn't landed yet (worth
+// retrying) and once it has landed with a decline (nothing left to wait for) - PAYMENT_FAILED is the one
+// coded exception to that. Regression coverage for the bug this used to have: every one of these outcomes
+// used to retry into the same generic "still confirming" pending screen, so a declined card never told the
+// shopper their card was declined.
+
+const ATTEMPT = { checkoutId: 'peach-checkout-1', entityId: 'entity-1' };
+
+// Mirrors CheckoutModal.payment-timeout.test.ts's own approach: a remembered attempt makes CheckoutModal
+// resume straight onto the card form on mount (resumeInterruptedPayment), the same place a real payCart()
+// success lands, without having to drive the contact form through the UI first.
+function mount(cart = buildCart(10 * 60_000)) {
+  rememberPaymentAttempt(CART_TOKEN, ATTEMPT);
+  const api = fakeApi(cart);
+  const onClose = vi.fn();
+  const onOrderConfirmed = vi.fn();
+  const peach = installFakePeachSdk();
+  render(CheckoutModal, { props: { cart, api, onClose, onOrderConfirmed } });
+  return { api, onClose, onOrderConfirmed, peach };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout', 'setInterval', 'clearInterval', 'Date'] });
+  vi.setSystemTime(new Date('2026-09-12T10:00:00Z'));
+  resetMessages();
+  sessionStorage.clear();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  delete (window as unknown as { Checkout?: unknown }).Checkout;
+});
+
+describe('a card Peach declined', () => {
+  it('shows Payment Failed with a Try Again button, on the first confirm attempt, not another "still confirming"', async () => {
+    const { api, peach } = mount();
+    api.confirmCart = vi.fn().mockRejectedValue(apiError(409, 'PAYMENT_FAILED'));
+    await settle();
+
+    peach.handlers().onCompleted();
+    await settle();
+
+    expect(api.confirmCart).toHaveBeenCalledTimes(1);
+    expect(screen.getByText('Payment Failed')).toBeTruthy();
+    expect(screen.getByRole('button', { name: /try again/i })).toBeTruthy();
+    expect(screen.queryByText('Payment Received')).toBeNull();
+  });
+
+  it('does not retry the way a webhook-not-landed-yet 402 does', async () => {
+    const { api, peach } = mount();
+    api.confirmCart = vi.fn().mockRejectedValue(apiError(409, 'PAYMENT_FAILED'));
+    await settle();
+
+    peach.handlers().onCompleted();
+    await settle();
+
+    // Even if the modal were still retrying (the bug this guards against), the retry delay would need real
+    // time to elapse - advancing well past it and confirming the call count never grows proves it settled
+    // immediately instead.
+    await vi.advanceTimersByTimeAsync(30_000);
+    await settle();
+
+    expect(api.confirmCart).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('a genuinely still-pending webhook, for contrast', () => {
+  it('keeps retrying a plain 402 rather than treating it as a decline', async () => {
+    const { api, peach } = mount();
+    api.confirmCart = vi.fn().mockRejectedValue(apiError(402));
+    await settle();
+
+    peach.handlers().onCompleted();
+    await settle();
+    await vi.advanceTimersByTimeAsync(30_000);
+    await settle();
+
+    expect(api.confirmCart.mock.calls.length).toBeGreaterThan(1);
+    expect(screen.queryByText('Payment Failed')).toBeNull();
+  });
+});