@final-commerce/command-frame 0.10.0-staging.6 → 0.10.1-online.1

package/dist/actions/get-shipping-options/types.d.ts

@@ -0,0 +1,43 @@
+import type { ShippingNoOptionReason, ShippingOptionType } from '@final-commerce/common';
+export interface ShippingPickupView {
+    outletId: string;
+    /** The store's name, e.g. "Duckworth Street". */
+    name: string;
+    /** One line per open day, e.g. "Mon–Fri 9:00 AM – 6:00 PM". Empty when the store set no hours. */
+    hours: string[];
+}
+export interface ShippingOptionView {
+    optionId: string;
+    type: ShippingOptionType | `${ShippingOptionType}`;
+    /** "Standard shipping", or "Pickup at Duckworth Street". */
+    name: string;
+    /** What this option costs on this cart, minor units, before its tax. */
+    amount: number;
+    /** "$10.00" or "Free". */
+    priceText: string;
+    /** "Add $20.00 more for free shipping", when a free-shipping line exists and isn't reached. */
+    freeShippingHint: string | null;
+    /** "Arrives Tue, Oct 20 – Fri, Oct 23", counted in business days from today. Null for pickup. */
+    arrivalText: string | null;
+    pickup: ShippingPickupView | null;
+    /** The option on the cart now. The cheapest is chosen by default. */
+    selected: boolean;
+}
+export interface GetShippingOptionsResponse {
+    /**
+     * False when this store doesn't ship at all (no shipping set up) or the cart has
+     * nothing to ship: show no shipping step.
+     */
+    required: boolean;
+    /** Ship options cheapest first, then pickups. */
+    options: ShippingOptionView[];
+    /** Why there is nothing to choose; null when `options` isn't empty. */
+    reason: ShippingNoOptionReason | `${ShippingNoOptionReason}` | null;
+    /**
+     * What to tell the customer: the store's "we don't ship here" message, or the
+     * default for the reason ("Sorry, we only ship within Canada."). Null when there are options.
+     */
+    message: string | null;
+    timestamp: string;
+}
+export type GetShippingOptions = () => Promise<GetShippingOptionsResponse>;

package/dist/actions/get-shipping-options/types.js

@@ -0,0 +1 @@
+export {};

package/dist/actions/process-partial-refund/types.d.ts

@@ -134,7 +134,7 @@ export interface ProcessPartialRefundParams {
         /** internalId or variantId, customSaleId, or a booking's own internalId. */
         itemKey: string;
         quantity: number;
-        type?: 'product' | 'customSale' | 'fee' | 'tip' | 'reservation';
+        type?: 'product' | 'customSale' | 'fee' | 'tip' | 'reservation' | 'shipping';
         /**
          * Per-item stock disposition for a refunded **product** line — the
          * headless equivalent of the old refund popup's per-row restock/damaged

package/dist/actions/resume-checkout/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resume Checkout action
+ * Calls the resumeCheckout action on the parent window
+ */
+import type { ResumeCheckout } from './types';
+export declare const resumeCheckout: ResumeCheckout;

package/dist/actions/resume-checkout/action.js

@@ -0,0 +1,8 @@
+/**
+ * Resume Checkout action
+ * Calls the resumeCheckout action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const resumeCheckout = async (params) => {
+    return await commandFrameClient.call('resumeCheckout', params ?? {});
+};

package/dist/actions/resume-checkout/mock.d.ts

@@ -0,0 +1,16 @@
+import { ResumeCheckout } from './types';
+/**
+ * Standalone mock of the checkout return leg.
+ *
+ * It reads the SAME query parameters the real provider sends a shopper back
+ * with, so a builder can exercise the redirect path in preview by appending
+ * them by hand:
+ *
+ *   ?sessionId=CS_MOCK&redirectResult=MOCK
+ *
+ * Without them it answers `{ resumed: false }` and does nothing, which is what
+ * the real command does on an ordinary page load. That is the branch a
+ * checkout screen hits on every normal visit, so it is the one worth getting
+ * right in a mock.
+ */
+export declare const mockResumeCheckout: ResumeCheckout;

package/dist/actions/resume-checkout/mock.js

@@ -0,0 +1,51 @@
+import { mockPublishEvent } from '../../demo/database';
+/**
+ * Standalone mock of the checkout return leg.
+ *
+ * It reads the SAME query parameters the real provider sends a shopper back
+ * with, so a builder can exercise the redirect path in preview by appending
+ * them by hand:
+ *
+ *   ?sessionId=CS_MOCK&redirectResult=MOCK
+ *
+ * Without them it answers `{ resumed: false }` and does nothing, which is what
+ * the real command does on an ordinary page load. That is the branch a
+ * checkout screen hits on every normal visit, so it is the one worth getting
+ * right in a mock.
+ */
+export const mockResumeCheckout = async (params) => {
+    console.log('[Mock] resumeCheckout called', params);
+    const href = params?.url ?? (typeof window === 'undefined' ? '' : window.location.href);
+    let redirectResult = null;
+    try {
+        redirectResult = new URL(href).searchParams.get('redirectResult');
+    }
+    catch {
+        redirectResult = null;
+    }
+    if (!redirectResult) {
+        return {
+            success: true,
+            timestamp: new Date().toISOString(),
+            checkout: { resumed: false },
+        };
+    }
+    const suffix = String(Date.now()).slice(-6);
+    const checkout = {
+        resumed: true,
+        orderId: `mock-order-${suffix}`,
+        receiptId: `ON-001-${suffix}`,
+        // `Authorised` is what the real provider reports for a completed redirect.
+        // It is NOT settlement — see the checkout topic docs.
+        resultCode: 'Authorised',
+        sessionResult: `mock-session-result-${suffix}`,
+        orderPassword: `mock-pw-${suffix}`,
+    };
+    mockPublishEvent('checkout', 'payment-completed', {
+        orderId: checkout.orderId,
+        receiptId: checkout.receiptId,
+        resultCode: checkout.resultCode,
+        sessionResult: checkout.sessionResult,
+    });
+    return { success: true, timestamp: new Date().toISOString(), checkout };
+};

package/dist/actions/resume-checkout/types.d.ts

@@ -0,0 +1,59 @@
+export interface ResumeCheckoutParams {
+    /**
+     * Where to read the provider's return data from. Defaults to the current
+     * page URL, which is where the shopper has just landed.
+     *
+     * Only override this if you moved the query string somewhere else before
+     * calling — for example if your router strips it on mount.
+     */
+    url?: string;
+}
+/**
+ * What the return leg produced. Every field past `resumed` is absent when
+ * `resumed` is `false`.
+ */
+export interface ResumeCheckoutResult {
+    /**
+     * `false` means THIS WAS AN ORDINARY PAGE LOAD — no provider return data was
+     * in the URL, so there was nothing to finish and nothing happened. It is not
+     * an error, and it is the answer on every normal visit to the page. Call this
+     * unconditionally when your checkout or confirmation screen mounts and branch
+     * on this field.
+     */
+    resumed: boolean;
+    orderId?: string;
+    receiptId?: string;
+    /**
+     * The provider's result code for the completed attempt, e.g. `Authorised` or
+     * `Refused`. As everywhere else in this topic, `Authorised` is an
+     * authorisation and NOT a settlement.
+     */
+    resultCode?: string;
+    /** Opaque proof of the payment — see `PaymentCompletedPayload.sessionResult`. */
+    sessionResult?: string;
+    /**
+     * The one-time order password from the original checkout, recovered from
+     * browser storage. The page that held it in memory is gone, so this is the
+     * only way back to the order's status after a redirect.
+     */
+    orderPassword?: string;
+}
+export interface ResumeCheckoutResponse {
+    success: boolean;
+    timestamp: string;
+    checkout: ResumeCheckoutResult;
+}
+/**
+ * Finish a checkout the shopper was redirected away from.
+ *
+ * SAFE TO CALL ON EVERY PAGE LOAD, and that is how it is meant to be used: on
+ * an ordinary visit it finds no return data and answers `{ resumed: false }`
+ * without touching the network. Calling it twice for one return is also safe —
+ * the return data is consumed the first time.
+ *
+ * The outcome is ALSO published on the `checkout` topic (`payment-completed` or
+ * `payment-failed`), exactly as it would have been had the shopper never left,
+ * so a page that already subscribes needs no second code path. Subscribe first,
+ * then call this, or the event fires before you are listening.
+ */
+export type ResumeCheckout = (params?: ResumeCheckoutParams) => Promise<ResumeCheckoutResponse>;

package/dist/actions/resume-checkout/types.js

@@ -0,0 +1,13 @@
+// Resume Checkout Types
+//
+// The RETURN LEG of an online checkout. Some payment methods — and 3-D Secure
+// on a card — take the shopper away to their bank or wallet and send them back
+// to `returnUrl` on a FRESH PAGE LOAD. The payment is not finished at that
+// point: the provider hands the browser a one-time result in the URL, and it
+// has to be handed back to the provider to complete the charge.
+//
+// `startCheckout` cannot do this. It ran in the page that is now gone.
+//
+// Served ONLY by the storefront runtime (a published website), like
+// `startCheckout`. On a register it does not exist.
+export {};

package/dist/actions/select-shipping-option/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SelectShippingOption action
+ * Calls the selectShippingOption action on the parent window
+ */
+import type { SelectShippingOption } from './types';
+export declare const selectShippingOption: SelectShippingOption;

package/dist/actions/select-shipping-option/action.js

@@ -0,0 +1,8 @@
+/**
+ * SelectShippingOption action
+ * Calls the selectShippingOption action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const selectShippingOption = async (params) => {
+    return await commandFrameClient.call('selectShippingOption', params);
+};

package/dist/actions/select-shipping-option/mock.d.ts

@@ -0,0 +1,3 @@
+import type { SelectShippingOption } from './types';
+/** Standalone mock: refuses an option the cart isn't offered, like the runtime does. */
+export declare const mockSelectShippingOption: SelectShippingOption;

package/dist/actions/select-shipping-option/mock.js

@@ -0,0 +1,31 @@
+import { MOCK_CART, mockPublishEvent } from '../../demo/database';
+import { mockShippingOptions } from '../../demo/shipping';
+/** Standalone mock: refuses an option the cart isn't offered, like the runtime does. */
+export const mockSelectShippingOption = async (params) => {
+    console.log('[Mock] selectShippingOption called', params);
+    if (!params)
+        throw new Error('Params required');
+    const previous = MOCK_CART.shippingTotal ?? 0;
+    if (params.optionId === null) {
+        MOCK_CART.shipping = null;
+    }
+    else {
+        const option = mockShippingOptions().resolution.options.find((o) => o.optionId === params.optionId);
+        if (!option)
+            throw new Error('selectShippingOption: this option is not offered for this cart');
+        MOCK_CART.shipping = {
+            zoneId: option.zoneId,
+            optionId: option.optionId,
+            type: option.type,
+            name: option.name,
+            amount: option.amount,
+            minDays: option.minDays,
+            maxDays: option.maxDays,
+            outletId: option.outletId,
+        };
+    }
+    MOCK_CART.shippingTotal = MOCK_CART.shipping?.amount ?? 0;
+    MOCK_CART.total += MOCK_CART.shippingTotal - previous;
+    mockPublishEvent('cart', 'cart-updated', { shipping: MOCK_CART.shipping });
+    return { shipping: MOCK_CART.shipping, cart: MOCK_CART, timestamp: new Date().toISOString() };
+};

package/dist/actions/select-shipping-option/types.d.ts

@@ -0,0 +1,15 @@
+import type { CFActiveCart, CFCartShipping } from '../../CommonTypes';
+export interface SelectShippingOptionParams {
+    /** An `optionId` from `getShippingOptions`. `null` takes shipping off the cart. */
+    optionId: string | null;
+}
+export interface SelectShippingOptionResponse {
+    shipping: CFCartShipping | null;
+    cart: CFActiveCart;
+    timestamp: string;
+}
+/**
+ * THROWS for an option this cart isn't offered: one from another address, a
+ * website-only option at the till, or one the store has since removed.
+ */
+export type SelectShippingOption = (params: SelectShippingOptionParams) => Promise<SelectShippingOptionResponse>;

package/dist/actions/select-shipping-option/types.js

@@ -0,0 +1 @@
+export {};

package/dist/actions/set-order-address/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SetOrderAddress action
+ * Calls the setOrderAddress action on the parent window
+ */
+import type { SetOrderAddress } from './types';
+export declare const setOrderAddress: SetOrderAddress;

package/dist/actions/set-order-address/action.js

@@ -0,0 +1,8 @@
+/**
+ * SetOrderAddress action
+ * Calls the setOrderAddress action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const setOrderAddress = async (params) => {
+    return await commandFrameClient.call('setOrderAddress', params);
+};

package/dist/actions/set-order-address/mock.d.ts

@@ -0,0 +1,7 @@
+import type { SetOrderAddress } from './types';
+/**
+ * Standalone mock of putting an address on the cart. It refuses what the runtime refuses (no
+ * country, an unreadable one, a shipping address without street and city) so a checkout form
+ * that looks finished in preview doesn't lose orders on the published site.
+ */
+export declare const mockSetOrderAddress: SetOrderAddress;

package/dist/actions/set-order-address/mock.js

@@ -0,0 +1,29 @@
+import { normalizeAddress } from '@final-commerce/common';
+import { MOCK_CART, mockPublishEvent } from '../../demo/database';
+/**
+ * Standalone mock of putting an address on the cart. It refuses what the runtime refuses (no
+ * country, an unreadable one, a shipping address without street and city) so a checkout form
+ * that looks finished in preview doesn't lose orders on the published site.
+ */
+export const mockSetOrderAddress = async (params) => {
+    console.log('[Mock] setOrderAddress called', params);
+    if (!params || (params.type !== 'shipping' && params.type !== 'billing')) {
+        throw new Error("setOrderAddress: type must be 'shipping' or 'billing'");
+    }
+    const key = params.type === 'shipping' ? 'shippingAddress' : 'billingAddress';
+    let address = params.address;
+    if (address) {
+        const read = normalizeAddress(address);
+        if (!read.country)
+            throw new Error('setOrderAddress: choose a country');
+        if (params.type === 'shipping' && (!address.address1?.trim() || !address.city?.trim())) {
+            throw new Error('setOrderAddress: a shipping address needs a street and a city');
+        }
+        address = { ...address, country: read.country, state: read.province ?? address.state, fromCustomer: false };
+    }
+    MOCK_CART[key] = address;
+    if (params.type === 'shipping')
+        MOCK_CART.shipping = null;
+    mockPublishEvent('cart', 'cart-updated', { [key]: address });
+    return { address, cart: MOCK_CART, timestamp: new Date().toISOString() };
+};

package/dist/actions/set-order-address/types.d.ts

@@ -0,0 +1,19 @@
+import type { CFActiveCart, CFCartAddress } from '../../CommonTypes';
+export type OrderAddressType = 'shipping' | 'billing';
+export interface SetOrderAddressParams {
+    type: OrderAddressType;
+    /** `null` clears it. Country and province may be codes or names; the runtime stores codes. */
+    address: CFCartAddress | null;
+}
+export interface SetOrderAddressResponse {
+    /** As stored: country as ISO-2, province as its code, postal code tidied. */
+    address: CFCartAddress | null;
+    /** The cart after the change. A new shipping address re-checks the chosen shipping option. */
+    cart: CFActiveCart;
+    timestamp: string;
+}
+/**
+ * THROWS when the address can't be used: no country, a country we can't read, or a
+ * shipping address without a street and city. The message says which, for the form.
+ */
+export type SetOrderAddress = (params: SetOrderAddressParams) => Promise<SetOrderAddressResponse>;

package/dist/actions/set-order-address/types.js

@@ -0,0 +1 @@
+export {};

package/dist/actions/set-outlet/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Set Outlet action
+ * Calls the setOutlet action on the parent window
+ */
+import type { SetOutlet } from './types';
+export declare const setOutlet: SetOutlet;

package/dist/actions/set-outlet/action.js

@@ -0,0 +1,8 @@
+/**
+ * Set Outlet action
+ * Calls the setOutlet action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const setOutlet = async (params) => {
+    return await commandFrameClient.call('setOutlet', params);
+};

package/dist/actions/set-outlet/mock.d.ts

@@ -0,0 +1,13 @@
+import type { SetOutlet } from './types';
+/**
+ * Standalone mock of switching location.
+ *
+ * It mirrors the two REFUSALS the real command makes — a missing id, and an
+ * outlet that cannot take a payment — because those are the mistakes a builder
+ * actually hits. A mock that accepted anything would let a location picker look
+ * finished and then strand a shopper at a dead payment step on the real site.
+ *
+ * The unconnected id comes from the `getOutlets` mock rather than being repeated
+ * here, so the two cannot drift into telling different stories.
+ */
+export declare const mockSetOutlet: SetOutlet;

package/dist/actions/set-outlet/mock.js

@@ -0,0 +1,24 @@
+import { MOCK_UNCONNECTED_OUTLET_ID } from '../get-outlets/mock';
+/**
+ * Standalone mock of switching location.
+ *
+ * It mirrors the two REFUSALS the real command makes — a missing id, and an
+ * outlet that cannot take a payment — because those are the mistakes a builder
+ * actually hits. A mock that accepted anything would let a location picker look
+ * finished and then strand a shopper at a dead payment step on the real site.
+ *
+ * The unconnected id comes from the `getOutlets` mock rather than being repeated
+ * here, so the two cannot drift into telling different stories.
+ */
+export const mockSetOutlet = async (params) => {
+    console.log('[Mock] setOutlet called', params);
+    if (!params)
+        throw new Error('Params required');
+    if (!params.outletId || !params.outletId.trim()) {
+        throw new Error('setOutlet: outletId is required');
+    }
+    if (params.outletId === MOCK_UNCONNECTED_OUTLET_ID) {
+        throw new Error(`setOutlet: outlet ${params.outletId} cannot take an online payment — offer only outlets with connected: true`);
+    }
+    return { outletId: params.outletId, rehydrated: true, timestamp: new Date().toISOString() };
+};

package/dist/actions/set-outlet/types.d.ts

@@ -0,0 +1,31 @@
+export interface SetOutletParams {
+    /** An `id` from `getOutlets`. */
+    outletId: string;
+}
+export interface SetOutletResponse {
+    /** The location now in effect. */
+    outletId: string;
+    /**
+     * `true` when the catalog and tax tables were re-pulled for this location.
+     *
+     * `false` means the switch took effect but the refresh could not reach the
+     * server — the shop is running on what it already had cached. Totals may be
+     * the previous location's until the next refresh pass lands, so a flow can
+     * tell the shopper to try again rather than quietly showing stale tax.
+     */
+    rehydrated: boolean;
+    timestamp: string;
+}
+/**
+ * Switch the shop to another of the company's locations.
+ *
+ * REFUSES AN OUTLET THAT CANNOT TAKE A PAYMENT, and one that does not belong to
+ * this company, rather than letting either fail later at the payment step. Check
+ * `connected` from `getOutlets` and do not offer those, so this refusal is a
+ * backstop rather than something a shopper ever sees.
+ *
+ * The cart survives the switch. Its lines are kept and re-priced; a line that is
+ * not purchasable at the new location is not silently dropped here, it is
+ * reported when the checkout is next priced.
+ */
+export type SetOutlet = (params: SetOutletParams) => Promise<SetOutletResponse>;

package/dist/actions/set-outlet/types.js

@@ -0,0 +1,21 @@
+// Set Outlet Types
+//
+// Choose which of the company's locations this shop is ordering from.
+//
+// WHAT IT ACTUALLY CHANGES. An outlet decides three things, and a shop that lets
+// a shopper pick one has to move all three together:
+//
+//   tax           rates follow the outlet's own address, so the total moves
+//   availability  stock is counted per location, and a product can be hidden at one
+//   fulfilment    the order records where the goods come from, so the right
+//                 location's stock is the one that is drawn down
+//
+// So this is not a display preference. It re-pulls the catalog for the new
+// location, re-hydrates the tax tables, and re-prices the cart. The totals a
+// flow reads afterwards are the new location's.
+//
+// SAFE MID-CHECKOUT. Checkout starts when a shopper ARRIVES, so by the time
+// anyone changes their mind an order usually already exists. That order is
+// re-priced and moved to the new outlet in place, keeping its id and its receipt
+// id, rather than being abandoned and replaced.
+export {};

package/dist/actions/start-checkout/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Start Checkout action
+ * Calls the startCheckout action on the parent window
+ */
+import type { StartCheckout } from './types';
+export declare const startCheckout: StartCheckout;

package/dist/actions/start-checkout/action.js

@@ -0,0 +1,8 @@
+/**
+ * Start Checkout action
+ * Calls the startCheckout action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const startCheckout = async (params) => {
+    return await commandFrameClient.call('startCheckout', params);
+};

package/dist/actions/start-checkout/mock.d.ts

@@ -0,0 +1,16 @@
+import { StartCheckout } from './types';
+/**
+ * Standalone mock of the storefront checkout.
+ *
+ * It mirrors the REFUSALS of the real command (empty cart,
+ * container not on the page) in the same order, because those are what a
+ * builder actually hits first — a mock that accepted anything would let a
+ * checkout screen look finished and fail on the published site.
+ *
+ * The mounted box is deliberately labelled as a mock. The real command mounts
+ * the provider's hosted card fields (iframes owned by the payment provider);
+ * nothing here takes a card number, and the placeholder must never look like
+ * it does. Its button publishes `payment-completed` so a flow's subscriber —
+ * the only way the outcome ever arrives — can be exercised in preview.
+ */
+export declare const mockStartCheckout: StartCheckout;

package/dist/actions/start-checkout/mock.js

@@ -0,0 +1,80 @@
+import { MOCK_CART, MOCK_COMPANY, mockPublishEvent } from '../../demo/database';
+/**
+ * Standalone mock of the storefront checkout.
+ *
+ * It mirrors the REFUSALS of the real command (empty cart,
+ * container not on the page) in the same order, because those are what a
+ * builder actually hits first — a mock that accepted anything would let a
+ * checkout screen look finished and fail on the published site.
+ *
+ * The mounted box is deliberately labelled as a mock. The real command mounts
+ * the provider's hosted card fields (iframes owned by the payment provider);
+ * nothing here takes a card number, and the placeholder must never look like
+ * it does. Its button publishes `payment-completed` so a flow's subscriber —
+ * the only way the outcome ever arrives — can be exercised in preview.
+ */
+export const mockStartCheckout = async (params) => {
+    console.log('[Mock] startCheckout called', params);
+    if (!params)
+        throw new Error('Params required');
+    // No email check: contact is optional now, because checkout starts on arrival.
+    // Refusing here would make "start on arrival" fail in PREVIEW while working on
+    // the published site, which is the worst way for this to be wrong.
+    if (!params.container || typeof params.container !== 'string') {
+        throw new Error('startCheckout: container must be a CSS selector string (e.g. "#card-fields") — a DOM element cannot cross the command boundary');
+    }
+    const lineCount = (MOCK_CART.products?.length ?? 0) + (MOCK_CART.customSales?.length ?? 0);
+    if (!lineCount) {
+        throw new Error('startCheckout: cannot check out an empty cart');
+    }
+    // Resolved BEFORE the order is "created", exactly as the real command does:
+    // finding out the selector is wrong after an order exists would leave an
+    // unpaid order behind for a typo that cost nothing to catch first.
+    const container = typeof document === 'undefined' ? null : document.querySelector(params.container);
+    if (!container) {
+        throw new Error(`startCheckout: checkout container "${params.container}" was not found on the page`);
+    }
+    const serverTotal = Math.round(MOCK_CART.amountToBeCharged || MOCK_CART.total);
+    const currency = MOCK_COMPANY.settings?.currency ?? 'USD';
+    const suffix = String(Date.now()).slice(-6);
+    const order = {
+        orderId: `mock-order-${suffix}`,
+        receiptId: `ON-001-${suffix}`,
+        serverTotal,
+        currency,
+        paymentStatus: 'ready',
+        orderPassword: `mock-pw-${suffix}`,
+    };
+    mockPublishEvent('checkout', 'checkout-started', { ...order });
+    container.replaceChildren();
+    const box = document.createElement('div');
+    box.setAttribute('data-mock-checkout', 'true');
+    box.style.cssText =
+        'border:1px dashed #9aa;border-radius:8px;padding:16px;font:14px system-ui,sans-serif;text-align:center;color:#334';
+    const label = document.createElement('div');
+    label.textContent = 'Mock payment fields — the published site shows the real hosted card fields here.';
+    label.style.cssText = 'margin-bottom:12px;opacity:.75';
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = `Simulate paying ${(serverTotal / 100).toFixed(2)} ${currency}`;
+    button.style.cssText =
+        'padding:10px 16px;border:0;border-radius:6px;background:#111;color:#fff;font-size:14px;cursor:pointer';
+    button.addEventListener('click', () => {
+        button.disabled = true;
+        // `Authorised` is what the real provider reports for a successful card
+        // entry. It is NOT settlement — see the checkout topic docs.
+        mockPublishEvent('checkout', 'payment-completed', {
+            orderId: order.orderId,
+            receiptId: order.receiptId,
+            resultCode: 'Authorised',
+        });
+    });
+    box.appendChild(label);
+    box.appendChild(button);
+    container.appendChild(box);
+    return {
+        success: true,
+        timestamp: new Date().toISOString(),
+        order,
+    };
+};