@code-collective/booking-widget 1.0.10 → 1.0.13

package/src/lib/index.ts

@@ -1,8 +1,8 @@
 import './app.css';
 import { mount, unmount } from 'svelte';
-import type { WizardPages, CartOverviewDisplay } from './config';
-import type { BookingApi } from './api';
-import type { CheckoutCartDetailDto } from './client-types';
+import type { CartOverviewDisplay, CartOverviewState } from './config';
+import type { BookingHost, BookingHostConfig } from './host.svelte';
+import { createBookingHost } from './host.svelte';
 import { ApiClient, ApiError } from './api';
 import { SessionManager } from './session-manager';
 import { CartManager } from './cart-manager';
@@ -17,180 +17,226 @@ export { default as Checkout } from './Checkout.svelte';
 export { default as CartOverview } from './CartOverview.svelte';
 export { default as CartBar } from './CartBar.svelte';
 export { default as CartOverviewButton } from './CartOverviewButton.svelte';
+// Required if you are not using the elements build: it owns the "still shopping?" warning, the expired view
+// and the payment-timeout hand-over, and nothing else on the page does. createBookingHost mounts it for you;
+// export it for consumers composing everything by hand.
+export { default as CartExpiryGuard } from './CartExpiryGuard.svelte';
+// Supplies the host to everything beneath it, so components need no api/cartManager props of their own.
+export { default as BookingProvider } from './BookingProvider.svelte';
 
 // Re-export utilities
 export { ApiClient, ApiError, SessionManager, CartManager };
 export { resolveWizardPages, resolveEditPages, DEFAULT_WIZARD_PAGES } from './config';
+export { createBookingHost, setBookingDefaults, getBookingDefaults, requestCheckoutOpen, requestCheckoutClose } from './host.svelte';
+export { portal } from './portal';
+export { setPeachSdk } from './peach-sdk';
+export type { PeachEnv } from './peach-sdk';
+export { getBookingHostContext } from './booking-context';
+export { onWidgetMessage, postMessage } from './messages';
 export type { BookingApi } from './api';
-export type { WizardPages, WizardPageConfig, CartOverviewDisplay, WidgetMode, WizardWidgetType } from './config';
+export type { BookingHost, BookingHostConfig, BookingDefaults, ResolvedBookingOptions } from './host.svelte';
+export type {
+  WizardPages, WizardPageConfig, CartOverviewDisplay, CartOverviewState, CheckoutMode, WidgetMode, WizardWidgetType,
+} from './config';
+export type {
+  WidgetMessage, WidgetMessageType, CartChangeMessage, CartUpdatedMessage, CartExpiredMessage,
+  ModalOpenMessage, ModalCloseMessage, OrderCompleteMessage, PaymentStartedMessage, PaymentEndedMessage,
+  PaymentTimedOutMessage,
+} from './messages';
 export type { components, operations, paths } from './generated-types';
 export type * from './client-types';
 
 // --- Mount function configs ---
 
-interface BaseConfig {
-  apiBaseUrl?: string;
-  checkoutKey?: string;
-  // Cart-global, not tied to any one mount function - fires after any add/edit/remove, anywhere on the page,
-  // carrying the same cart TicketConfigurator/CheckoutModal already fetch for their own internal use. Lets a
-  // consumer build a custom cart summary (item count, remaining time, item details) without calling the
-  // checkout API directly.
-  onCartUpdated?: (cart: CheckoutCartDetailDto | null) => void;
-  // Fires when the cart's own clock ran out (or, for mountCheckout, when it loads onto a cart the server has
-  // already let go) - see messages.ts's own cart:expired doc comment for why this is narrower than an
-  // onCartUpdated(null) call, which a manual clear can also produce.
-  onCartExpired?: () => void;
-}
+// Every mount function takes the same host options, so a consumer mounting more than one widget can hand all
+// of them the same host and get one session, one cart and one expiry guard - see `host` below.
+type BaseConfig = Omit<BookingHostConfig, 'onCheckoutOpenChange'> & {
+  // An existing host to mount into. Without one each mount function builds its own, which means its own
+  // session and its own cart - fine for a single widget on a page, wrong for two.
+  host?: BookingHost;
+};
 
 export interface ConfiguratorConfig extends BaseConfig {
   productId: string;
   currency?: string;
-  wizardPages?: WizardPages;
-  autoSelectSingleTimeSlot?: boolean;
   cancelable?: boolean;
-  onCartChange?: (detail: { itemCount: number; cartItemId: string; totalFormatted: string }) => void;
+  // onCartChange and the other cart callbacks come from BookingHostConfig - see createBookingHost.
   onCancel?: () => void;
 }
 
 export interface CheckoutConfig extends BaseConfig {
-  wizardPages?: WizardPages;
-  editPages?: WizardPages;
-  autoSelectSingleTimeSlot?: boolean;
+  // Inline by default - the mount target is a container the consumer positioned itself. Pass 'modal' for the
+  // portalled overlay the custom-elements build shows.
+  mode?: 'inline' | 'modal';
   onClose?: () => void;
-  onOrderConfirmed?: (detail: { cartToken: string; value: number; currency: string }) => void;
 }
 
 export interface CartOverviewConfig extends BaseConfig {
   display?: CartOverviewDisplay;
   onCheckout?: () => void;
+  /** Distinguishes an empty cart from one that could not be read - see CartOverview. */
+  onStateChange?: (state: CartOverviewState) => void;
 }
 
 export interface MountedWidget {
   destroy: () => void;
 }
 
-// --- Shared bootstrap ---
+// --- Mount functions ---
 
-function bootstrap(config: BaseConfig): { api: BookingApi; sessionManager: SessionManager; cartManager: CartManager } {
-  const api: BookingApi = new ApiClient(config.apiBaseUrl ?? '');
+interface MountContext {
+  host: BookingHost;
+  /** Tearing the widget down tears the host down too - but only the host this mount built itself. */
+  release: () => void;
+}
 
-  const sessionManager = new SessionManager(api);
-  const cartManager = new CartManager(api);
-  sessionManager.startBackgroundRefresh();
+/**
+ * Resolves the host a mount function will use. A host passed in is the consumer's to destroy - other widgets
+ * are probably still using it - so this mount only unsubscribes the callbacks it added to it.
+ */
+/**
+ * Waits for the session, releasing whatever the mount just acquired if it is refused. Without this a
+ * rejected ready - an unallowlisted checkout key, the failure consumers are told to expect - left the
+ * host's message subscription, its session-refresh interval and its expiry-guard refcount behind, and that
+ * leaked refcount pins CartExpiryGuard on <body> for the life of the page.
+ */
+async function readyOrRelease(context: MountContext): Promise<void> {
+  try {
+    await context.host.ready;
+  } catch (e) {
+    context.release();
+    throw e;
+  }
+}
 
-  return { api, sessionManager, cartManager };
+function hostFor(config: BaseConfig): MountContext {
+  if (!config.host) {
+    const host = createBookingHost(config);
+    return { host, release: () => host.destroy() };
+  }
+
+  // The host was built elsewhere and already carries its own callbacks, so the ones on this config would
+  // otherwise be dropped on the floor - a consumer following the documented `{ host, onOrderConfirmed }`
+  // shape would get a checkout that never reports a confirmed order. They are wired to the same messages
+  // the host itself listens to.
+  return { host: config.host, release: subscribeCallbacks(config) };
 }
 
-// --- Mount functions ---
+function subscribeCallbacks(config: BaseConfig): () => void {
+  const { onCartChange, onCartUpdated, onCartExpired, onOrderConfirmed } = config;
+  if (!onCartChange && !onCartUpdated && !onCartExpired && !onOrderConfirmed) return () => {};
+
+  return onWidgetMessage((d) => {
+    if (d.type === 'cart:change') {
+      onCartChange?.({
+        itemCount: d.itemCount,
+        cartItemId: d.cartItemId,
+        totalFormatted: d.totalFormatted,
+      });
+    }
+    if (d.type === 'cart:updated') onCartUpdated?.(d.cart);
+    if (d.type === 'cart:expired') onCartExpired?.();
+    if (d.type === 'order:complete') {
+      onOrderConfirmed?.({ cartToken: d.cartToken, value: d.value, currency: d.currency });
+    }
+  });
+}
 
 export async function mountConfigurator(target: HTMLElement, config: ConfiguratorConfig): Promise<MountedWidget> {
-  const { api, sessionManager, cartManager } = bootstrap(config);
+  const context = hostFor(config);
+  const { host, release } = context;
 
-  await sessionManager.ensureSession(config.checkoutKey ?? '');
+  await readyOrRelease(context);
 
   const component = mount(TicketConfiguratorComponent, {
     target,
     props: {
-      api,
-      cartManager,
+      api: host.api,
+      cartManager: host.cartManager,
       productId: config.productId,
-      wizardPages: config.wizardPages,
-      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? false,
+      wizardPages: config.wizardPages ?? host.options.wizardPages,
+      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? host.options.autoSelectSingleTimeSlot,
+      // Stated per configurator so this and the host's own autoOpenCheckout meet in the same branch - see
+      // host.svelte.ts. Both have to say yes for an add to open checkout, which is what lets one configurator
+      // on a page opt out (the ES equivalent of the element's no-auto-checkout) without silencing the rest.
+      autoOpenCheckout: config.autoOpenCheckout !== false,
       onCancel: config.onCancel,
     },
   });
 
-  // Listen for postMessage events and forward to callbacks
-  const stopListening = onWidgetMessage((d) => {
-    if (d.type === 'cart:change' && config.onCartChange) {
-      config.onCartChange({
-        itemCount: (d.itemCount as number) ?? 0,
-        cartItemId: (d.cartItemId as string) ?? '',
-        totalFormatted: (d.totalFormatted as string) ?? '',
-      });
-    }
-    if (d.type === 'cart:updated' && 'cart' in d) {
-      config.onCartUpdated?.(d.cart as CheckoutCartDetailDto | null);
-    }
-    if (d.type === 'cart:expired') config.onCartExpired?.();
-  });
-
   return {
     destroy() {
-      stopListening();
-      sessionManager.stop();
       unmount(component);
+      release();
     },
   };
 }
 
 export async function mountCheckout(target: HTMLElement, config: CheckoutConfig): Promise<MountedWidget> {
-  const { api, sessionManager, cartManager } = bootstrap(config);
+  const context = hostFor(config);
+  const { host, release } = context;
 
-  await sessionManager.ensureSession(config.checkoutKey ?? '');
+  await readyOrRelease(context);
 
   const component = mount(CheckoutComponent, {
     target,
     props: {
-      api,
-      cartManager,
-      wizardPages: config.wizardPages,
-      editPages: config.editPages,
-      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? false,
+      api: host.api,
+      cartManager: host.cartManager,
+      wizardPages: config.wizardPages ?? host.options.wizardPages,
+      editPages: config.editPages ?? host.options.editPages,
+      autoSelectSingleTimeSlot: config.autoSelectSingleTimeSlot ?? host.options.autoSelectSingleTimeSlot,
+      mode: config.mode ?? 'inline',
+      // The modal opens and closes with the host, which is what an add-to-cart and the cart bar's button
+      // both reach. A consumer wanting to drive it directly can call host.openCheckout().
+      get open() {
+        return host.isCheckoutOpen;
+      },
+      // Fires for every dismissal, not just the scrim - Checkout answers the modal:close message rather
+      // than only its own overlay click.
+      onClose: config.onClose,
     },
   });
 
-  const stopListening = onWidgetMessage((d) => {
-    if (d.type === 'modal:close' && config.onClose) config.onClose();
-    if (d.type === 'order:complete' && config.onOrderConfirmed) {
-      config.onOrderConfirmed({
-        cartToken: (d.cartToken as string) ?? '',
-        value: (d.value as number) ?? 0,
-        currency: (d.currency as string) ?? 'ZAR',
-      });
-    }
-    if (d.type === 'cart:updated' && 'cart' in d) {
-      config.onCartUpdated?.(d.cart as CheckoutCartDetailDto | null);
-    }
-    if (d.type === 'cart:expired') config.onCartExpired?.();
-  });
-
   return {
     destroy() {
-      stopListening();
-      sessionManager.stop();
       unmount(component);
+      release();
     },
   };
 }
 
 export async function mountCartOverview(target: HTMLElement, config: CartOverviewConfig): Promise<MountedWidget> {
-  const { api, sessionManager, cartManager } = bootstrap(config);
+  const context = hostFor(config);
+  const { host, release } = context;
 
-  await sessionManager.ensureSession(config.checkoutKey ?? '');
+  await readyOrRelease(context);
 
   const component = mount(CartOverviewComponent, {
     target,
     props: {
-      api,
-      cartManager,
+      api: host.api,
+      cartManager: host.cartManager,
       display: config.display ?? 'bar',
+      onStateChange: config.onStateChange,
     },
   });
 
-  const stopListening = onWidgetMessage((d) => {
-    if (d.type === 'modal:open' && config.onCheckout) config.onCheckout();
-    if (d.type === 'cart:updated' && 'cart' in d) {
-      config.onCartUpdated?.(d.cart as CheckoutCartDetailDto | null);
-    }
-    if (d.type === 'cart:expired') config.onCartExpired?.();
-  });
+  const stopListening = config.onCheckout
+    ? onCheckoutRequested(config.onCheckout)
+    : () => {};
 
   return {
     destroy() {
       stopListening();
-      sessionManager.stop();
       unmount(component);
+      release();
     },
   };
 }
+
+function onCheckoutRequested(onCheckout: () => void): () => void {
+  return onWidgetMessage((d) => {
+    if (d.type === 'modal:open') onCheckout();
+  });
+}

package/src/lib/layout.svelte.ts

@@ -0,0 +1,52 @@
+/**
+ * The configurator is presented two different ways by its host, and the two need different chrome.
+ * The marketing site (city-sightseeing-site/marketing-site/apps/web/src/components/BookingWidget.svelte)
+ * splits on Tailwind's `lg`: at and above it the widget sits inline in the product page's sticky
+ * sidebar, below it that sidebar is display:none and the widget is opened as a full-screen sheet
+ * instead. Matching that exact breakpoint here is what keeps the widget's own layout in step with
+ * the host's - a widget that thought it was inline while sitting in a full-screen sheet would show
+ * a duplicate header and a card that refuses to fill the screen.
+ */
+export const INLINE_LAYOUT_QUERY = '(min-width: 1024px)';
+
+// The one place that knows whether this environment can answer the question at all. SSR has no window,
+// and jsdom (this package's test environment) has no matchMedia, so both the seed and the subscription
+// below go through here rather than each guarding differently - or, as happened once, one not guarding.
+function inlineLayoutQuery(): MediaQueryList | null {
+  if (typeof window === 'undefined' || !window.matchMedia) return null;
+  return window.matchMedia(INLINE_LAYOUT_QUERY);
+}
+
+function matchesInlineLayout(): boolean {
+  // Where the question cannot be asked, inline is the safer answer: it is the variant whose chrome the
+  // host never duplicates.
+  return inlineLayoutQuery()?.matches ?? true;
+}
+
+export interface InlineLayout {
+  readonly isInline: boolean;
+}
+
+/**
+ * Tracks which of the two presentations the widget is currently in. Call during component
+ * initialisation - it registers an $effect that follows viewport changes for the component's
+ * lifetime, so a desktop window dragged narrow re-lays out rather than keeping stale chrome.
+ */
+export function createInlineLayout(): InlineLayout {
+  // Seeded synchronously rather than waiting for the effect below, so the first paint is already
+  // the right variant instead of rendering full-screen and visibly correcting itself on desktop.
+  let isInline = $state(matchesInlineLayout());
+
+  $effect(() => {
+    const query = inlineLayoutQuery();
+    if (!query) return;
+    isInline = query.matches;
+    const onChange = (e: MediaQueryListEvent) => { isInline = e.matches; };
+    query.addEventListener('change', onChange);
+    return () => query.removeEventListener('change', onChange);
+  });
+
+  return {
+    get isInline() { return isInline; },
+  };
+}

package/src/lib/messages.ts

@@ -3,28 +3,100 @@
 // Svelte tree. That makes every one of these messages same-window and same-origin, and the guards below exist
 // to keep it that way.
 
-/** Messages this widget sends itself. Anything else on the wire is not ours. */
-const WIDGET_MESSAGE_TYPES = new Set([
+import type { CheckoutCartDetailDto } from './client-types';
+
+/** An item was added to the cart from a configurator. */
+export interface CartChangeMessage {
+  type: 'cart:change';
+  itemCount: number;
+  cartItemId: string;
+  totalFormatted: string;
+  // Whether this add should carry the shopper on into checkout. The single source of truth for auto-open on
+  // both builds - createBookingHost reads it directly, and register.ts reaches it through the same host - so
+  // the elements build and the ES build cannot drift on when checkout opens.
+  openCheckout: boolean;
+}
+
+/** The cart's contents changed, anywhere on the page. `cart` is null once the cart is gone. */
+export interface CartUpdatedMessage {
+  type: 'cart:updated';
+  cart: CheckoutCartDetailDto | null;
+}
+
+/**
+ * The cart's window ran out and the cart is gone - distinct from the `cart:updated` with a null cart that
+ * also accompanies it, which a confirmed order posts too. A host telling the shopper "your cart expired"
+ * needs the difference.
+ */
+export interface CartExpiredMessage {
+  type: 'cart:expired';
+}
+
+/** Something asked for checkout to be shown - the cart bar's button, or the expiry guard resuming a payment. */
+export interface ModalOpenMessage {
+  type: 'modal:open';
+}
+
+/** Checkout was dismissed. */
+export interface ModalCloseMessage {
+  type: 'modal:close';
+}
+
+/** Payment completed *and* was confirmed. Does not fire while a confirmation webhook is still pending. */
+export interface OrderCompleteMessage {
+  type: 'order:complete';
+  cartToken: string;
+  value: number;
+  currency: string;
+}
+
+/**
+ * A Peach checkout is open for the cart / has been abandoned so the cart is Open again. Posted by
+ * CheckoutModal for CartExpiryGuard, which keeps prompting but stops acting on the deadline itself while the
+ * server exempts the cart from expiry.
+ */
+export interface PaymentStartedMessage {
+  type: 'payment:started';
+}
+
+export interface PaymentEndedMessage {
+  type: 'payment:ended';
+}
+
+/**
+ * The cart's one clock ran out while a Peach checkout was open. Posted by CartExpiryGuard for CheckoutModal,
+ * which tears the attempt down (Peach's real status permitting) so the shopper sees the cart expire there
+ * too, rather than an ever-open card form for a cart that is already gone.
+ */
+export interface PaymentTimedOutMessage {
+  type: 'payment:timed-out';
+}
+
+/** Every message this widget sends itself. Anything else on the wire is not ours. */
+export type WidgetMessage =
+  | CartChangeMessage
+  | CartUpdatedMessage
+  | CartExpiredMessage
+  | ModalOpenMessage
+  | ModalCloseMessage
+  | OrderCompleteMessage
+  | PaymentStartedMessage
+  | PaymentEndedMessage
+  | PaymentTimedOutMessage;
+
+export type WidgetMessageType = WidgetMessage['type'];
+
+const WIDGET_MESSAGE_TYPES = new Set<string>([
   'cart:change',
   'cart:updated',
-  // The cart the widget was holding onto is gone because its clock ran out - a strict subset of
-  // cart:updated's own cart:null case (see that message's own callers), fired alongside it so a host that
-  // wants to react to expiry specifically (analytics, a redirect, its own message) does not have to infer it
-  // from an absent cart, which cart:updated also carries for an ordinary manual clear.
   'cart:expired',
   'modal:open',
   'modal:close',
   'order:complete',
-  // A Peach checkout is open for the cart / has been abandoned so the cart is Open again. Posted by
-  // CheckoutModal for CartExpiryGuard, which keeps prompting but stops acting on the deadline itself while
-  // the server exempts the cart from expiry.
   'payment:started',
   'payment:ended',
-  // The cart's one clock ran out while a Peach checkout was open. Posted by CartExpiryGuard for
-  // CheckoutModal, which tears the attempt down (Peach's real status permitting) so the shopper sees the
-  // cart expire there too, rather than an ever-open card form for a cart that is already gone.
   'payment:timed-out',
-]);
+] satisfies WidgetMessageType[]);
 
 /**
  * Sends a widget message.
@@ -34,12 +106,16 @@ const WIDGET_MESSAGE_TYPES = new Set([
  * '*' that went to whatever origin happened to be framing the widget, which in the standalone iframe build is
  * not necessarily anyone we trust.
  */
-export function postMessage(data: Record<string, unknown>): void {
+export function postMessage(data: WidgetMessage): void {
+  // No window means a server render - an Astro island is server-rendered before it hydrates, and a host
+  // built during that pass would otherwise take the whole page down with a ReferenceError.
+  if (typeof window === 'undefined') return;
   window.parent?.postMessage(JSON.stringify(data), window.location.origin);
 }
 
 /**
- * Subscribes to widget messages, ignoring anything that did not come from this widget.
+ * Subscribes to widget messages, ignoring anything that did not come from this widget. Returns an
+ * unsubscribe function.
  *
  * The elements mount directly into the merchant's own document (shadow: 'none'), so these listeners sit on
  * the top-level window of a third-party page. Without this check, any iframe already on that page - an ad, a
@@ -50,13 +126,17 @@ export function postMessage(data: Record<string, unknown>): void {
  * Checking `source` is what does the real work: a message from another frame carries that frame's own window,
  * never ours, and it cannot be spoofed. The origin check is belt-and-braces for the same-window case.
  */
-export function onWidgetMessage(handler: (data: Record<string, unknown>) => void): () => void {
+export function onWidgetMessage(handler: (data: WidgetMessage) => void): () => void {
+  // Same reason as postMessage above: nothing to subscribe to on the server, and createBookingHost
+  // subscribes the moment it is built.
+  if (typeof window === 'undefined') return () => {};
+
   function listener(e: MessageEvent) {
     if (e.source !== window || e.origin !== window.location.origin) {
       return;
     }
 
-    let data: Record<string, unknown>;
+    let data: WidgetMessage;
     try {
       data = typeof e.data === 'string' ? JSON.parse(e.data) : e.data;
     } catch {

package/src/lib/peach-sdk.ts

@@ -4,23 +4,69 @@ const SDK_URLS: Record<string, string> = {
 };
 
 let loadPromise: Promise<void> | null = null;
+let configuredUrl: string | null = null;
+let loadedUrl: string | null = null;
+
+/** Which SDK was actually loaded. Only worth knowing when Peach then refuses to render - see PaymentPage. */
+export function loadedPeachSdkUrl(): string | null {
+  return loadedUrl;
+}
+
+export type PeachEnv = 'prod' | 'qa';
+
+/**
+ * Chooses which Peach SDK to load, for consumers with no window globals to set.
+ *
+ * window.BW_CHECKOUT_ENV is the custom-elements build's convention, read off the page that loaded the
+ * script. An ES consumer has no such page - it passes apiBaseUrl to createBookingHost and nothing else -
+ * so without this it silently got the production SDK while its checkout API was creating sandbox
+ * checkoutIds, and Peach answered with "An unrecoverable error has occurred while attempting to render the
+ * checkout experience". createBookingHost calls this for you; it is exported for anyone composing without
+ * a host.
+ */
+export function setPeachSdk(options: { url?: string; env?: PeachEnv }): void {
+  const next = options.url ?? (options.env ? SDK_URLS[options.env] : undefined);
+  if (!next || next === configuredUrl) return;
+  configuredUrl = next;
+  // A different SDK than the one already promised has to be fetched afresh.
+  loadPromise = null;
+}
 
 // Lazily injects Peach's Copy&Pay SDK the first time PaymentPage mounts, so consumers embedding the widget
 // (any of the three integration options) never have to know this script exists, let alone which
 // environment's URL to point at - same window.BW_CHECKOUT_ENV convention elements/env.ts already uses for
 // the checkout API base URL, with an explicit override for anything that doesn't fit that pattern.
 export function loadPeachSdk(): Promise<void> {
-  if ((window as any).Checkout) {
+  const w = window as any;
+  const env: string = w.BW_CHECKOUT_ENV ?? 'prod';
+  // Explicit window override first (it is the most specific thing a page can say), then whatever a host
+  // was configured with, then the elements build's env global, then production.
+  const src: string = w.BW_CHECKOUT_PEACH_SDK_URL ?? configuredUrl ?? SDK_URLS[env] ?? SDK_URLS.prod;
+
+  // Peach's SDK cannot be swapped once it has installed window.Checkout, so a page that already loaded one
+  // - its own <script> tag, or an earlier host configured differently - is stuck with it. Resolving in
+  // silence is what made this hard to find the first time: the only symptom is Peach's opaque
+  // "unrecoverable error" card, from a production SDK holding a sandbox checkoutId.
+  if (w.Checkout) {
+    if (loadedUrl !== null && loadedUrl !== src) {
+      console.warn(
+        `[booking-widget] Peach SDK already loaded from ${loadedUrl}, so ${src} was not used. ` +
+          `Configure peachEnv before the first payment, or set window.BW_CHECKOUT_PEACH_SDK_URL.`,
+      );
+    } else if (loadedUrl === null) {
+      console.warn(
+        `[booking-widget] Peach SDK was already on the page when the widget first needed it, so ${src} ` +
+          `was not used. If its environment does not match the checkout API, the card form will not render.`,
+      );
+    }
     return Promise.resolve();
   }
+
   if (loadPromise) {
     return loadPromise;
   }
 
-  const w = window as any;
-  const env: string = w.BW_CHECKOUT_ENV ?? 'prod';
-  const src: string = w.BW_CHECKOUT_PEACH_SDK_URL ?? SDK_URLS[env] ?? SDK_URLS.prod;
-
+  loadedUrl = src;
   loadPromise = new Promise((resolve, reject) => {
     const existing = document.querySelector(`script[src="${src}"]`);
     if (existing) {

package/src/lib/portal.ts

@@ -0,0 +1,23 @@
+/**
+ * Moves an element out to `document.body` (or another target) for as long as it is mounted, and puts nothing
+ * back - the node is removed with the component.
+ *
+ * `position: fixed` only escapes to the viewport while no ancestor has established a containing block for it.
+ * A `transform`, `filter`, `backdrop-filter`, `perspective`, `contain` or `will-change` anywhere above, and a
+ * `position: sticky` ancestor's stacking context, are all enough to trap a fixed overlay inside the subtree
+ * and let the host's own header paint over it. No z-index inside that subtree can win, because the contest is
+ * between the ancestor and the header, not between the overlay and anything.
+ *
+ * Consumers hit this the moment they put checkout in a sticky sidebar, which is the ordinary way to lay a
+ * product page out - so the modal portals itself rather than leaving each host to discover the rule.
+ */
+export function portal(node: HTMLElement, target?: HTMLElement | null) {
+  const destination = target ?? (typeof document === 'undefined' ? null : document.body);
+  destination?.appendChild(node);
+
+  return {
+    destroy() {
+      node.remove();
+    },
+  };
+}