From d86e98071a0a42960f5e5cd9cd851ad0db61c990 Mon Sep 17 00:00:00 2001
From: tiagocandido <tiago.santos@shopify.com>
Date: Mon, 28 Sep 2026 17:10:07 +0200
Subject: [PATCH] Show received Universal Checkout events in the sample overlay

---
 platforms/web/sample/styles.css               |  14 +-
 platforms/web/sample/universal-main.ts        |  66 +++-
 platforms/web/sample/universal.html           |  44 ++-
 .../sample/universal/event-history.test.ts    | 212 +++++++++++
 .../web/sample/universal/event-history.ts     | 346 ++++++++++++++++++
 .../web/sample/universal/overlay-view.ts      | 200 ++++++++++
 platforms/web/sample/universal/overlay.css    | 293 +++++++++++++++
 .../web/sample/universal/overlay.test.ts      | 236 ++++++++++++
 platforms/web/sample/universal/overlay.ts     | 155 ++++++++
 .../sample/universal/source-selection.test.ts |  69 ++++
 .../web/sample/universal/source-selection.ts  | 106 ++++++
 .../web/sample/universal/source-view.test.ts  |  55 +++
 platforms/web/sample/universal/source-view.ts |  43 +++
 13 files changed, 1836 insertions(+), 3 deletions(-)
 create mode 100644 platforms/web/sample/universal/event-history.test.ts
 create mode 100644 platforms/web/sample/universal/event-history.ts
 create mode 100644 platforms/web/sample/universal/overlay-view.ts
 create mode 100644 platforms/web/sample/universal/overlay.css
 create mode 100644 platforms/web/sample/universal/overlay.test.ts
 create mode 100644 platforms/web/sample/universal/overlay.ts
 create mode 100644 platforms/web/sample/universal/source-selection.test.ts
 create mode 100644 platforms/web/sample/universal/source-selection.ts
 create mode 100644 platforms/web/sample/universal/source-view.test.ts
 create mode 100644 platforms/web/sample/universal/source-view.ts

diff --git a/platforms/web/sample/styles.css b/platforms/web/sample/styles.css
index b5c4255aa..13e366293 100644
--- a/platforms/web/sample/styles.css
+++ b/platforms/web/sample/styles.css
@@ -1264,6 +1264,19 @@ button:disabled {
   display: none;
 }
 
+.universal-page .product-scroll {
+  flex: none;
+  overflow: visible;
+}
+
+@media (min-width: 1181px) {
+  .universal-page .workspace {
+    overflow-y: auto;
+    scrollbar-gutter: stable;
+    overscroll-behavior: contain;
+  }
+}
+
 @media (max-width: 1180px) {
   html.universal-page {
     height: auto;
@@ -1297,7 +1310,6 @@ button:disabled {
     overflow: visible;
   }
 
-  body.universal-page .product-scroll,
   body.universal-page .runtime-scroll {
     overflow: visible;
   }
diff --git a/platforms/web/sample/universal-main.ts b/platforms/web/sample/universal-main.ts
index cb19e75bb..b2bfe7387 100644
--- a/platforms/web/sample/universal-main.ts
+++ b/platforms/web/sample/universal-main.ts
@@ -1,10 +1,19 @@
+import "@shopify/checkout-kit/universal";
+
 import { normalizeQuantity } from "./cart";
 import { createColumnResizer } from "./column-resizer";
-import { setDevelopmentContinuationHost } from "./universal/browser-policy";
+import { $ } from "./dom";
+import {
+  isConfiguredContinuationUrl,
+  setDevelopmentContinuationHost,
+} from "./universal/browser-policy";
 import { loadSampleConfiguration } from "./universal/configuration";
 import { createUniversalController } from "./universal/controller";
+import { mountUniversalOverlay } from "./universal/overlay";
 import { createSessionPreparationController } from "./universal/preparation";
 import { isBuyerCountry, isCheckoutEnvironment } from "./universal/policy";
+import { createSourceSelection } from "./universal/source-selection";
+import { querySourceViewRefs, renderSourceView } from "./universal/source-view";
 import {
   createInitialState,
   createUniversalStore,
@@ -22,9 +31,24 @@ import { queryUniversalRefs, renderUniversalApp, renderUniversalChange } from ".
 import "./styles.css";
 
 const refs = queryUniversalRefs();
+const sourceRefs = querySourceViewRefs();
 const store = createUniversalStore(createInitialState(loadUniversalDisplay()));
 const controller = createUniversalController({ store });
 const preparation = createSessionPreparationController({ store });
+const sourceSelection = createSourceSelection(isConfiguredContinuationUrl);
+const overlay = mountUniversalOverlay({
+  parent: document.body,
+  hostLog: $<HTMLElement>("#event-log"),
+  hostHeader: $<HTMLElement>(".events-header"),
+  hostNotice: refs.runtimeNotice,
+  validateSource: (value) =>
+    isConfiguredContinuationUrl(value, store.getState().environment) ? value : undefined,
+  onChange: (snapshot) => {
+    if (store.getState().runtime.notice !== snapshot.notice) {
+      controller.setRuntimeNotice(snapshot.notice);
+    }
+  },
+});
 const resizer = createColumnResizer({
   layout: refs.layout,
   leftPanel: refs.settingsPanel,
@@ -37,9 +61,22 @@ const resizer = createColumnResizer({
 
 const unsubscribe = store.subscribe((state, previous) => {
   renderUniversalChange(refs, state, previous);
+  syncSelectedSource();
   resizer.reposition();
 });
 
+function syncSelectedSource(): void {
+  const state = store.getState();
+  const selected = sourceSelection.select(state.preparation, state.environment);
+  renderSourceView(sourceRefs, sourceSelection.mode, sourceSelection.pastedDraft, selected);
+  overlay.configure({
+    src: selected.url,
+    target: state.display.target,
+    appearance: state.display.appearance,
+    logLevel: state.display.logLevel,
+  });
+}
+
 function updateDisplay(partial: Partial<DisplayState>): void {
   const display = { ...store.getState().display, ...partial };
   store.update((state) => ({ ...state, display }));
@@ -56,6 +93,30 @@ refs.form.addEventListener("submit", (event) => {
 
 refs.domainInput.addEventListener("input", controller.clearAddError);
 
+sourceRefs.generatedInput.addEventListener("change", () => {
+  if (!sourceRefs.generatedInput.checked) return;
+  sourceSelection.setMode("generated");
+  syncSelectedSource();
+});
+
+sourceRefs.pastedInput.addEventListener("change", () => {
+  if (!sourceRefs.pastedInput.checked) return;
+  sourceSelection.setMode("pasted");
+  syncSelectedSource();
+  sourceRefs.pastedUrl.focus();
+});
+
+sourceRefs.pastedUrl.addEventListener("input", () => {
+  sourceSelection.setPastedDraft(sourceRefs.pastedUrl.value);
+  syncSelectedSource();
+});
+
+sourceRefs.openButton.addEventListener("click", () => {
+  const state = store.getState();
+  if (!sourceSelection.select(state.preparation, state.environment).ready) return;
+  overlay.attemptOpen();
+});
+
 refs.form.addEventListener("change", (event) => {
   const target = event.target;
   if (!(target instanceof HTMLSelectElement)) return;
@@ -150,6 +211,7 @@ refs.shopList.addEventListener("change", (event) => {
 });
 
 renderUniversalApp(refs, store.getState());
+syncSelectedSource();
 resizer.applyWidths();
 void loadSampleConfiguration()
   .then((configuration) => {
@@ -158,6 +220,7 @@ void loadSampleConfiguration()
       if (!store.getState().shops.some((shop) => shop.domain === domain))
         controller.addShop(domain);
     }
+    syncSelectedSource();
     return undefined;
   })
   .catch(() => {
@@ -169,6 +232,7 @@ window.addEventListener("resize", resizer.reposition);
 window.addEventListener("pagehide", (event) => {
   if (event.persisted) return;
   unsubscribe();
+  overlay.dispose();
   controller.dispose();
   preparation.dispose();
   window.removeEventListener("resize", resizer.reposition);
diff --git a/platforms/web/sample/universal.html b/platforms/web/sample/universal.html
index fa8a3d64d..723beb20b 100644
--- a/platforms/web/sample/universal.html
+++ b/platforms/web/sample/universal.html
@@ -77,7 +77,7 @@ <h2 id="settings-heading">Settings</h2>
               <span>target</span>
               <select id="uc-target" name="target">
                 <option value="popup">popup (window)</option>
-                <option value="auto">auto (new tab)</option>
+                <option value="auto">auto (browser window)</option>
               </select>
             </label>
             <label>
@@ -155,6 +155,48 @@ <h2 id="uc-cart-heading">Selected carts</h2>
             </div>
           </section>
 
+          <section class="uc-open-card" aria-labelledby="uc-open-heading">
+            <div class="uc-open-heading">
+              <h2 id="uc-open-heading">Open with Checkout Kit</h2>
+              <p class="muted">
+                Checkout Kit displays events from each shop in its checkout overlay.
+              </p>
+            </div>
+            <fieldset class="uc-source-options">
+              <legend>Checkout URL source</legend>
+              <label>
+                <input id="uc-source-generated" type="radio" name="uc-source-mode" checked />
+                <span>Use the URL created from selected carts</span>
+              </label>
+              <label>
+                <input id="uc-source-pasted" type="radio" name="uc-source-mode" />
+                <span>Advanced: paste an existing Universal Checkout URL</span>
+              </label>
+            </fieldset>
+            <div id="uc-pasted-fields" class="uc-pasted-fields" hidden>
+              <label for="uc-pasted-url">Existing Universal Checkout URL</label>
+              <input
+                id="uc-pasted-url"
+                type="url"
+                inputmode="url"
+                autocomplete="off"
+                autocapitalize="off"
+                spellcheck="false"
+                placeholder="https://shop.app/checkouts/uc/…"
+                aria-describedby="uc-source-status"
+              />
+              <p class="field-help">
+                This advanced input stays on this page only and is cleared when you change modes.
+              </p>
+            </div>
+            <p id="uc-source-status" class="notice" data-tone="info" role="status">
+              Create a Universal Checkout URL from the selected carts first.
+            </p>
+            <button id="uc-open" type="button" class="primary-action" disabled>
+              Open Universal Checkout
+            </button>
+          </section>
+
           <div class="panel-header storefront-header">
             <h2>Shop catalogs</h2>
             <span id="uc-shop-count" class="status-pill">0 shops</span>
diff --git a/platforms/web/sample/universal/event-history.test.ts b/platforms/web/sample/universal/event-history.test.ts
new file mode 100644
index 000000000..4b07ebaa5
--- /dev/null
+++ b/platforms/web/sample/universal/event-history.test.ts
@@ -0,0 +1,212 @@
+import { describe, expect, it } from "vitest";
+
+import { MAX_EVENT_ENTRIES, UniversalEventHistory } from "./event-history";
+
+const CHECKOUT_ID = "gid://shopify/Checkout/secret-123";
+const SHOP_ID = "gid://shopify/Shop/secret-456";
+const SESSION_ID = "secret-session-789";
+const SECRET_URL = "https://shop.app/checkout?token=private-token";
+const PRIVATE_EMAIL = "buyer@example.test";
+
+function checkout(status = "incomplete") {
+  return {
+    id: CHECKOUT_ID,
+    status,
+    currency: "USD",
+    lineItems: [{ id: "line-secret", buyer: { email: PRIVATE_EMAIL } }],
+    buyer: { email: PRIVATE_EMAIL },
+    continueUrl: SECRET_URL,
+    messages: [{ content: '<img src=x onerror="alert(1)">' }],
+    order: undefined,
+  };
+}
+
+function aggregate(status = "incomplete") {
+  return {
+    sessionId: SESSION_ID,
+    revision: 1,
+    resources: [{ id: CHECKOUT_ID, shopId: SHOP_ID, checkout: checkout(status) }],
+  };
+}
+
+function resourceEntry(status = "incomplete") {
+  return {
+    context: { sessionId: SESSION_ID, revision: 1, shopId: SHOP_ID },
+    checkout: checkout(status),
+  };
+}
+
+describe("Universal event history", () => {
+  it("projects detail and aggregate immediately without keeping IDs, URLs, PII or HTML", () => {
+    const history = new UniversalEventHistory(() => new Date("2026-09-25T12:00:00Z"));
+    history.beginPresentation();
+    const event = resourceEntry();
+    const current = aggregate();
+    history.receive("start", [event], current, undefined);
+    event.checkout.buyer.email = "changed@example.test";
+    current.resources[0]!.checkout.buyer.email = "changed@example.test";
+
+    const snapshot = history.snapshot;
+    expect(snapshot.phase).toBe("active");
+    expect(snapshot.entries).toHaveLength(1);
+    expect(snapshot.entries[0]).toMatchObject({
+      name: "start",
+      label: "Shop 1",
+      status: "incomplete",
+    });
+    expect(snapshot.resources).toEqual([
+      { label: "Shop 1", status: "incomplete", lineItemCount: 1, currency: "USD" },
+    ]);
+    expect(snapshot.entries[0]!.detail).toContain('"resource": "Shop 1"');
+    expect(snapshot.entries[0]!.detail).toContain('"order": "absent"');
+    const safeState = JSON.stringify(snapshot);
+    for (const sensitive of [
+      CHECKOUT_ID,
+      SHOP_ID,
+      SESSION_ID,
+      SECRET_URL,
+      PRIVATE_EMAIL,
+      "changed@example.test",
+      "<img",
+      "private-token",
+    ]) {
+      expect(safeState).not.toContain(sensitive);
+    }
+  });
+
+  it("keeps labels stable across an array batch and does not infer a selected domain", () => {
+    const history = new UniversalEventHistory();
+    history.beginPresentation();
+    const secondShop = "gid://shopify/Shop/second-secret";
+    const second = {
+      context: { sessionId: SESSION_ID, revision: 1, shopId: secondShop },
+      checkout: { ...checkout(), status: "ready_for_complete" },
+    };
+    history.receive(
+      "start",
+      [resourceEntry(), second],
+      {
+        sessionId: SESSION_ID,
+        revision: 1,
+        resources: [
+          { id: CHECKOUT_ID, shopId: SHOP_ID, checkout: checkout() },
+          { id: "second-checkout-secret", shopId: secondShop, checkout: second.checkout },
+        ],
+      },
+      undefined,
+    );
+    history.receive("update", resourceEntry("completed"), aggregate("completed"), undefined);
+    expect(history.snapshot.entries.map((entry) => entry.label)).toEqual([
+      "Shop 1",
+      "Shop 2",
+      "Shop 1",
+    ]);
+    expect(history.snapshot.resources[0]?.status).toBe("completed");
+    expect(JSON.stringify(history.snapshot)).not.toContain(secondShop);
+  });
+
+  it("bounds each presentation to 200 entries and keeps checkout state after Clear", () => {
+    const history = new UniversalEventHistory();
+    history.beginPresentation();
+    for (let revision = 1; revision <= MAX_EVENT_ENTRIES + 1; revision += 1) {
+      history.receive(
+        "update",
+        [{ ...resourceEntry(), context: { sessionId: SESSION_ID, revision, shopId: SHOP_ID } }],
+        aggregate(),
+        undefined,
+      );
+    }
+    expect(history.snapshot.entries).toHaveLength(MAX_EVENT_ENTRIES);
+    expect(history.snapshot.entries[0]?.detail).toContain('"revision": 2');
+    history.clear();
+    expect(history.snapshot.entries).toHaveLength(0);
+    expect(history.snapshot.resources).toHaveLength(1);
+    expect(history.snapshot.phase).toBe("active");
+  });
+
+  it("keeps resource errors local, redacts messages and records close before reset", () => {
+    const history = new UniversalEventHistory();
+    history.beginPresentation();
+    history.receive("start", [resourceEntry()], aggregate(), undefined);
+    history.receive(
+      "error",
+      [
+        {
+          context: { sessionId: SESSION_ID, revision: 2, shopId: SHOP_ID },
+          scope: "resource",
+          error: {
+            code: "invalid_cart",
+            message: `Private buyer ${PRIVATE_EMAIL} at ${SECRET_URL}`,
+            httpStatusCode: 422,
+          },
+        },
+      ],
+      aggregate(),
+      {
+        sessionId: SESSION_ID,
+        errors: [
+          {
+            scope: "resource",
+            shopId: SHOP_ID,
+            error: { code: "invalid_cart", message: PRIVATE_EMAIL },
+          },
+        ],
+      },
+    );
+    expect(history.snapshot.phase).toBe("active");
+    expect(history.snapshot.errors).toEqual([
+      { label: "Shop 1", scope: "resource", code: "invalid_cart" },
+    ]);
+    expect(history.snapshot.entries.at(-1)?.detail).toContain('"message": "[redacted]"');
+    expect(JSON.stringify(history.snapshot)).not.toContain(PRIVATE_EMAIL);
+    history.receive("close", undefined, aggregate(), undefined);
+    expect(history.snapshot.phase).toBe("closed");
+    expect(history.snapshot.errors).toEqual([
+      { label: "Shop 1", scope: "resource", code: "invalid_cart" },
+    ]);
+    expect(history.snapshot.entries.at(-1)?.name).toBe("close");
+    history.receive("update", [resourceEntry()], aggregate(), undefined);
+    expect(history.snapshot.entries.at(-1)?.name).toBe("close");
+
+    history.beginPresentation();
+    expect(history.snapshot.presentation).toBe(2);
+    expect(history.snapshot.phase).toBe("opening");
+    expect(history.snapshot.entries).toHaveLength(0);
+    expect(history.snapshot.resources).toHaveLength(0);
+  });
+
+  it("clears a recovered resource's error badge when Kit has no current error aggregate", () => {
+    const history = new UniversalEventHistory();
+    history.beginPresentation();
+    history.receive(
+      "error",
+      [{ scope: "resource", context: { shopId: SHOP_ID }, error: { code: "invalid_cart" } }],
+      aggregate(),
+      {
+        sessionId: SESSION_ID,
+        errors: [{ scope: "resource", shopId: SHOP_ID, error: { code: "invalid_cart" } }],
+      },
+    );
+    expect(history.snapshot.errors).toHaveLength(1);
+
+    history.receive("start", [resourceEntry()], aggregate(), undefined);
+
+    expect(history.snapshot.errors).toEqual([]);
+    expect(history.snapshot.entries.at(-1)?.name).toBe("start");
+  });
+
+  it("treats a session failure as a failure without exposing arbitrary error text or codes", () => {
+    const history = new UniversalEventHistory();
+    history.beginPresentation();
+    history.receive(
+      "error",
+      [{ scope: "session", error: { code: "<script>", message: PRIVATE_EMAIL } }],
+      undefined,
+      undefined,
+    );
+    expect(history.snapshot.phase).toBe("failed");
+    expect(history.snapshot.entries[0]?.label).toBe("Session");
+    expect(history.snapshot.entries[0]?.detail).toContain('"code": "unknown"');
+    expect(JSON.stringify(history.snapshot)).not.toContain(PRIVATE_EMAIL);
+  });
+});
diff --git a/platforms/web/sample/universal/event-history.ts b/platforms/web/sample/universal/event-history.ts
new file mode 100644
index 000000000..fb646437e
--- /dev/null
+++ b/platforms/web/sample/universal/event-history.ts
@@ -0,0 +1,346 @@
+/** A bounded, deliberately lossy view of Checkout Kit events for the sample. */
+
+export type KitEventName = "start" | "update" | "complete" | "error" | "close";
+export type PresentationPhase = "idle" | "opening" | "active" | "complete" | "failed" | "closed";
+
+export interface DisplayResource {
+  readonly label: string;
+  readonly status: string;
+  readonly lineItemCount: number | null;
+  readonly currency?: string;
+}
+
+export interface DisplayError {
+  readonly label: string;
+  readonly scope: "resource" | "session";
+  readonly code: string;
+}
+
+export interface DisplayEvent {
+  readonly id: number;
+  readonly time: string;
+  readonly name: KitEventName;
+  readonly label: string;
+  readonly status: string;
+  /** Only contains allowlisted values. Never store a raw event or checkout object. */
+  readonly detail: string;
+}
+
+export interface EventHistorySnapshot {
+  readonly presentation: number;
+  readonly phase: PresentationPhase;
+  readonly notice: string;
+  readonly entries: readonly DisplayEvent[];
+  readonly resources: readonly DisplayResource[];
+  readonly errors: readonly DisplayError[];
+}
+
+export const MAX_EVENT_ENTRIES = 200;
+
+const MAX_RESOURCE_LABELS = 200;
+const MAX_VISIBLE_RESOURCES = 50;
+const CHECKOUT_STATUSES = new Set([
+  "incomplete",
+  "requires_escalation",
+  "ready_for_complete",
+  "complete_in_progress",
+  "completed",
+  "canceled",
+  "unknown",
+]);
+const ERROR_CODES = new Set([
+  "storefront_password_required",
+  "customer_account_required",
+  "cart_expired",
+  "cart_completed",
+  "invalid_cart",
+  "sdk_error",
+  "unknown",
+]);
+
+type UnknownRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): UnknownRecord | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : undefined;
+}
+
+function entriesOf(detail: unknown): readonly unknown[] {
+  if (Array.isArray(detail)) return detail;
+  return asRecord(detail) ? [detail] : [];
+}
+
+function safeStatus(value: unknown): string {
+  return typeof value === "string" && CHECKOUT_STATUSES.has(value) ? value : "unknown";
+}
+
+function safeErrorCode(value: unknown): string {
+  return typeof value === "string" && ERROR_CODES.has(value) ? value : "unknown";
+}
+
+function safeCurrency(value: unknown): string | undefined {
+  return typeof value === "string" && /^[A-Z]{3}$/.test(value) ? value : undefined;
+}
+
+function safeRevision(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+
+function safeHttpStatus(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isInteger(value) && value >= 100 && value <= 599
+    ? value
+    : undefined;
+}
+
+interface DisplayCheckout {
+  readonly status: string;
+  readonly lineItemCount: number | null;
+  readonly currency?: string;
+  readonly order: "present" | "absent";
+  readonly fulfillment: "present" | "absent";
+}
+
+function projectCheckout(value: unknown): DisplayCheckout {
+  const checkout = asRecord(value);
+  const currency = safeCurrency(checkout?.["currency"]);
+  return {
+    status: safeStatus(checkout?.["status"]),
+    lineItemCount: Array.isArray(checkout?.["lineItems"]) ? checkout["lineItems"].length : null,
+    ...(currency ? { currency } : {}),
+    order: checkout?.["order"] == null ? "absent" : "present",
+    fulfillment: checkout?.["fulfillment"] == null ? "absent" : "present",
+  };
+}
+
+function projectFailure(value: unknown): {
+  readonly code: string;
+  readonly message: "[redacted]";
+  readonly httpStatusCode?: number;
+} {
+  const error = asRecord(value);
+  const httpStatusCode = safeHttpStatus(error?.["httpStatusCode"]);
+  return {
+    code: safeErrorCode(error?.["code"]),
+    message: "[redacted]",
+    ...(httpStatusCode === undefined ? {} : { httpStatusCode }),
+  };
+}
+
+function noticeFor(phase: PresentationPhase, outcome: "none" | "complete" | "failed"): string {
+  switch (phase) {
+    case "idle":
+      return "Open a universal checkout to see received events.";
+    case "opening":
+      return "Opening checkout. Waiting for Checkout Kit events.";
+    case "active":
+      return "Checkout Kit is receiving events from this presentation.";
+    case "complete":
+      return "Universal checkout completed. The checkout window remains available.";
+    case "failed":
+      return "Checkout could not continue. Review the redacted error event.";
+    case "closed":
+      if (outcome === "complete") return "Checkout window closed after completion.";
+      if (outcome === "failed") return "Checkout window closed after a checkout error.";
+      return "Checkout window closed. Open again for a new presentation.";
+  }
+}
+
+/**
+ * Keeps only safe display projections. Resource IDs exist solely as temporary
+ * keys for stable local labels and are never copied into entries or markup.
+ */
+export class UniversalEventHistory {
+  readonly #now: () => Date;
+  readonly #labels = new Map<string, string>();
+  #nextEntryId = 1;
+  #presentation = 0;
+  #phase: PresentationPhase = "idle";
+  #outcome: "none" | "complete" | "failed" = "none";
+  #active = false;
+  #entries: DisplayEvent[] = [];
+  #resources: DisplayResource[] = [];
+  #errors: DisplayError[] = [];
+
+  constructor(now: () => Date = () => new Date()) {
+    this.#now = now;
+  }
+
+  get snapshot(): EventHistorySnapshot {
+    return {
+      presentation: this.#presentation,
+      phase: this.#phase,
+      notice: noticeFor(this.#phase, this.#outcome),
+      entries: this.#entries,
+      resources: this.#resources,
+      errors: this.#errors,
+    };
+  }
+
+  beginPresentation(): void {
+    this.#presentation += 1;
+    this.#active = true;
+    this.#phase = "opening";
+    this.#outcome = "none";
+    this.#entries = [];
+    this.#resources = [];
+    this.#errors = [];
+    this.#labels.clear();
+  }
+
+  clear(): void {
+    this.#entries = [];
+  }
+
+  receive(
+    name: KitEventName,
+    detail: unknown,
+    checkoutAggregate: unknown,
+    errorAggregate: unknown,
+  ): void {
+    if (!this.#active) return;
+
+    const aggregate = this.#projectAggregate(checkoutAggregate);
+    const errors = this.#projectErrorAggregate(errorAggregate);
+    if (aggregate !== undefined) this.#resources = aggregate.resources;
+    if (errors !== undefined) this.#errors = errors;
+    else if (errorAggregate === undefined && name !== "close") this.#errors = [];
+
+    if (name === "close") {
+      this.#append("close", "Presentation", "closed", {
+        event: "close",
+        aggregate: aggregate?.detail,
+      });
+      this.#active = false;
+      this.#phase = "closed";
+      return;
+    }
+
+    const eventEntries = entriesOf(detail);
+    if (eventEntries.length === 0) {
+      this.#append(name, name === "error" ? "Session" : "Unknown shop", "unknown", {
+        event: name,
+        aggregate: aggregate?.detail,
+      });
+      return;
+    }
+
+    for (const eventEntry of eventEntries) {
+      const entry = asRecord(eventEntry);
+      const context = asRecord(entry?.["context"]);
+      const revision = safeRevision(context?.["revision"]);
+
+      if (name === "error") {
+        const scope = entry?.["scope"] === "resource" ? "resource" : "session";
+        const label = scope === "resource" ? this.#labelFor(context?.["shopId"]) : "Session";
+        const failure = projectFailure(entry?.["error"]);
+        this.#append(name, label, "error", {
+          event: name,
+          scope,
+          resource: label,
+          ...(revision === undefined ? {} : { revision }),
+          error: failure,
+          aggregate: aggregate?.detail,
+          errors: errors ?? this.#errors,
+        });
+        if (scope === "session") {
+          this.#outcome = "failed";
+          this.#phase = "failed";
+        } else if (this.#phase === "opening") {
+          // A resource can fail while the other shops remain interactive.
+          this.#phase = "active";
+        }
+        continue;
+      }
+
+      const label = this.#labelFor(context?.["shopId"]);
+      const checkout = projectCheckout(entry?.["checkout"]);
+      this.#append(name, label, checkout.status, {
+        event: name,
+        resource: label,
+        ...(revision === undefined ? {} : { revision }),
+        checkout,
+        aggregate: aggregate?.detail,
+      });
+      if (name === "complete") {
+        this.#outcome = "complete";
+        this.#phase = "complete";
+      } else if (this.#phase === "opening") {
+        this.#phase = "active";
+      }
+    }
+  }
+
+  #labelFor(value: unknown): string {
+    if (typeof value !== "string" || value.length === 0 || value.length > 512) {
+      return "Unknown shop";
+    }
+    const known = this.#labels.get(value);
+    if (known) return known;
+    if (this.#labels.size >= MAX_RESOURCE_LABELS) return "Additional shop";
+    const label = `Shop ${this.#labels.size + 1}`;
+    this.#labels.set(value, label);
+    return label;
+  }
+
+  #projectAggregate(
+    value: unknown,
+  ): { resources: DisplayResource[]; detail: UnknownRecord } | undefined {
+    const aggregate = asRecord(value);
+    if (!aggregate) return undefined;
+    const rawResources = Array.isArray(aggregate["resources"]) ? aggregate["resources"] : [];
+    const resources = rawResources.slice(0, MAX_VISIBLE_RESOURCES).map((rawResource) => {
+      const resource = asRecord(rawResource);
+      const checkout = projectCheckout(resource?.["checkout"]);
+      return {
+        label: this.#labelFor(resource?.["shopId"]),
+        status: checkout.status,
+        lineItemCount: checkout.lineItemCount,
+        ...(checkout.currency ? { currency: checkout.currency } : {}),
+      };
+    });
+    const revision = safeRevision(aggregate["revision"]);
+    return {
+      resources,
+      detail: {
+        ...(revision === undefined ? {} : { revision }),
+        resourceCount: rawResources.length,
+        resources,
+        ...(rawResources.length > resources.length
+          ? { additionalResourceCount: rawResources.length - resources.length }
+          : {}),
+      },
+    };
+  }
+
+  #projectErrorAggregate(value: unknown): DisplayError[] | undefined {
+    const aggregate = asRecord(value);
+    if (!aggregate) return undefined;
+    const rawErrors = Array.isArray(aggregate["errors"]) ? aggregate["errors"] : [];
+    return rawErrors.slice(0, MAX_VISIBLE_RESOURCES).map((rawError) => {
+      const entry = asRecord(rawError);
+      const context = asRecord(entry?.["context"]);
+      const scope = entry?.["scope"] === "resource" ? "resource" : "session";
+      return {
+        label:
+          scope === "resource"
+            ? this.#labelFor(entry?.["shopId"] ?? context?.["shopId"])
+            : "Session",
+        scope,
+        code: projectFailure(entry?.["error"]).code,
+      };
+    });
+  }
+
+  #append(name: KitEventName, label: string, status: string, detail: UnknownRecord): void {
+    const event: DisplayEvent = {
+      id: this.#nextEntryId++,
+      time: this.#now().toLocaleTimeString(),
+      name,
+      label,
+      status,
+      detail: JSON.stringify(detail, null, 2),
+    };
+    this.#entries = [...this.#entries.slice(-(MAX_EVENT_ENTRIES - 1)), event];
+  }
+}
diff --git a/platforms/web/sample/universal/overlay-view.ts b/platforms/web/sample/universal/overlay-view.ts
new file mode 100644
index 000000000..1ae939033
--- /dev/null
+++ b/platforms/web/sample/universal/overlay-view.ts
@@ -0,0 +1,200 @@
+import type { DisplayEvent, EventHistorySnapshot } from "./event-history";
+
+export interface OverlayView {
+  readonly surface: HTMLElement;
+  readonly focusButton: HTMLButtonElement;
+  readonly closeButton: HTMLButtonElement;
+  readonly clearButton: HTMLButtonElement;
+  readonly hostClearButton: HTMLButtonElement;
+  render(snapshot: EventHistorySnapshot): void;
+  dispose(): void;
+}
+
+function button(label: string, className: string): HTMLButtonElement {
+  const element = document.createElement("button");
+  element.type = "button";
+  element.className = className;
+  element.textContent = label;
+  return element;
+}
+
+function eventItem(entry: DisplayEvent): HTMLLIElement {
+  const item = document.createElement("li");
+  item.className = "event-entry uc-event-entry";
+  item.dataset["entryId"] = String(entry.id);
+
+  const disclosure = document.createElement("details");
+  const summary = document.createElement("summary");
+  summary.className = "uc-event-summary";
+
+  const name = document.createElement("span");
+  name.className = "event-entry-name";
+  name.textContent = entry.name;
+  const resource = document.createElement("span");
+  resource.className = "uc-event-resource";
+  resource.textContent = entry.label;
+  const status = document.createElement("span");
+  status.className = "uc-event-status";
+  status.textContent = entry.status;
+  const time = document.createElement("time");
+  time.className = "event-entry-time";
+  time.textContent = entry.time;
+
+  summary.append(name, resource, status, time);
+  const attribution = document.createElement("p");
+  attribution.className = "uc-event-attribution";
+  attribution.textContent = "Received from Checkout Kit · redacted display";
+  const detail = document.createElement("pre");
+  detail.textContent = entry.detail;
+  disclosure.append(summary, attribution, detail);
+  item.append(disclosure);
+  return item;
+}
+
+/** Reuse existing nodes so a focused/expanded event stays put during later events. */
+function renderTimeline(list: HTMLElement, entries: readonly DisplayEvent[]): void {
+  const wanted = new Set(entries.map((entry) => String(entry.id)));
+  const present = new Map<string, HTMLElement>();
+  for (const child of Array.from(list.children)) {
+    const element = child as HTMLElement;
+    const key = element.dataset["entryId"];
+    if (!key || !wanted.has(key)) element.remove();
+    else present.set(key, element);
+  }
+  for (const entry of entries) {
+    if (!present.has(String(entry.id))) list.append(eventItem(entry));
+  }
+}
+
+function renderResources(list: HTMLElement, snapshot: EventHistorySnapshot): void {
+  const items: HTMLLIElement[] = [];
+  for (const resource of snapshot.resources) {
+    const item = document.createElement("li");
+    const name = document.createElement("strong");
+    name.textContent = resource.label;
+    const status = document.createElement("span");
+    status.className = "status-pill";
+    status.textContent = resource.status;
+    const extra = document.createElement("span");
+    extra.className = "muted";
+    const lines =
+      resource.lineItemCount === null
+        ? "line items unavailable"
+        : `${resource.lineItemCount} ${resource.lineItemCount === 1 ? "line item" : "line items"}`;
+    extra.textContent = resource.currency ? `${lines} · ${resource.currency}` : lines;
+    item.append(name, status, extra);
+    const error = snapshot.errors.find(
+      (entry) => entry.scope === "resource" && entry.label === resource.label,
+    );
+    if (error) {
+      const errorStatus = document.createElement("span");
+      errorStatus.className = "uc-resource-error";
+      errorStatus.textContent = `Error: ${error.code}`;
+      item.append(errorStatus);
+    }
+    items.push(item);
+  }
+  list.replaceChildren(...items);
+}
+
+export function createOverlayView(options: {
+  readonly hostLog: HTMLElement;
+  readonly hostHeader: HTMLElement;
+  readonly hostNotice: HTMLElement;
+  readonly onFocus: () => void;
+  readonly onClose: () => void;
+  readonly onClear: () => void;
+}): OverlayView {
+  const surface = document.createElement("section");
+  surface.className = "uc-overlay-surface";
+  surface.slot = "overlay";
+  surface.setAttribute("aria-label", "Universal checkout activity");
+
+  const header = document.createElement("header");
+  header.className = "uc-overlay-header";
+  const headingGroup = document.createElement("div");
+  const eyebrow = document.createElement("p");
+  eyebrow.className = "uc-overlay-eyebrow";
+  eyebrow.textContent = "Checkout Kit · received events";
+  const heading = document.createElement("h2");
+  heading.textContent = "Universal checkout activity";
+  headingGroup.append(eyebrow, heading);
+  const controls = document.createElement("div");
+  controls.className = "uc-overlay-controls";
+  const focusButton = button("Focus checkout", "secondary-action");
+  const closeButton = button("Close checkout", "secondary-action");
+  controls.append(focusButton, closeButton);
+  header.append(headingGroup, controls);
+
+  const notice = document.createElement("p");
+  notice.className = "uc-overlay-notice";
+  notice.setAttribute("role", "status");
+
+  const resourceSection = document.createElement("section");
+  resourceSection.className = "uc-overlay-resources";
+  const resourceHeading = document.createElement("h3");
+  resourceHeading.textContent = "Resource state";
+  const resourceEmpty = document.createElement("p");
+  resourceEmpty.className = "muted";
+  resourceEmpty.textContent = "No checkout state received yet.";
+  const resourceList = document.createElement("ol");
+  resourceList.setAttribute("aria-label", "Checkout resources");
+  resourceSection.append(resourceHeading, resourceEmpty, resourceList);
+
+  const activitySection = document.createElement("section");
+  activitySection.className = "uc-overlay-activity";
+  const activityHeader = document.createElement("div");
+  activityHeader.className = "uc-overlay-activity-header";
+  const activityHeading = document.createElement("h3");
+  activityHeading.textContent = "Event timeline";
+  const clearButton = button("Clear events", "secondary-action");
+  activityHeader.append(activityHeading, clearButton);
+  const overlayLog = document.createElement("ol");
+  overlayLog.className = "uc-overlay-event-log";
+  overlayLog.setAttribute("aria-label", "Checkout Kit received events");
+  const overlayEmpty = document.createElement("p");
+  overlayEmpty.className = "muted";
+  overlayEmpty.textContent = "Received checkout events appear here.";
+  activitySection.append(activityHeader, overlayLog, overlayEmpty);
+
+  surface.append(header, notice, resourceSection, activitySection);
+
+  const hostClearButton = button("Clear", "secondary-action uc-event-clear");
+  hostClearButton.setAttribute("aria-label", "Clear received checkout events");
+  options.hostHeader.append(hostClearButton);
+
+  focusButton.addEventListener("click", options.onFocus);
+  closeButton.addEventListener("click", options.onClose);
+  clearButton.addEventListener("click", options.onClear);
+  hostClearButton.addEventListener("click", options.onClear);
+
+  return {
+    surface,
+    focusButton,
+    closeButton,
+    clearButton,
+    hostClearButton,
+    render(snapshot) {
+      heading.textContent =
+        snapshot.presentation === 0
+          ? "Universal checkout activity"
+          : `Universal checkout · presentation ${snapshot.presentation}`;
+      notice.textContent = snapshot.notice;
+      options.hostNotice.textContent = snapshot.notice;
+      resourceEmpty.hidden = snapshot.resources.length > 0;
+      renderResources(resourceList, snapshot);
+      renderTimeline(overlayLog, snapshot.entries);
+      renderTimeline(options.hostLog, snapshot.entries);
+      overlayEmpty.hidden = snapshot.entries.length > 0;
+      clearButton.disabled = snapshot.entries.length === 0;
+      hostClearButton.disabled = snapshot.entries.length === 0;
+    },
+    dispose() {
+      focusButton.removeEventListener("click", options.onFocus);
+      closeButton.removeEventListener("click", options.onClose);
+      clearButton.removeEventListener("click", options.onClear);
+      hostClearButton.removeEventListener("click", options.onClear);
+      hostClearButton.remove();
+    },
+  };
+}
diff --git a/platforms/web/sample/universal/overlay.css b/platforms/web/sample/universal/overlay.css
new file mode 100644
index 000000000..41d842221
--- /dev/null
+++ b/platforms/web/sample/universal/overlay.css
@@ -0,0 +1,293 @@
+.universal-page .uc-open-card {
+  display: flex;
+  flex: none;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 0;
+  padding: 14px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  box-shadow: var(--shadow-md);
+}
+
+.universal-page .uc-open-heading h2,
+.universal-page .uc-open-heading p {
+  margin: 0;
+}
+
+.universal-page .uc-open-heading h2 {
+  font-size: 12px;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.universal-page .uc-open-heading p {
+  margin-top: 4px;
+  font-size: 12px;
+}
+
+.universal-page .uc-source-options {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px 14px;
+  padding: 8px 10px;
+}
+
+.universal-page .uc-source-options label {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  cursor: pointer;
+  font-size: 12px;
+}
+
+.universal-page .uc-source-options input {
+  margin: 0;
+  accent-color: var(--accent);
+}
+
+.universal-page .uc-pasted-fields {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.universal-page .uc-pasted-fields label {
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.universal-page .uc-pasted-fields input {
+  width: 100%;
+}
+
+.universal-page .uc-pasted-fields .field-help {
+  margin: 0;
+}
+
+.universal-page #uc-source-status {
+  margin: 0;
+  padding: 8px 10px;
+  font-size: 12px;
+}
+
+.universal-page #uc-open {
+  align-self: flex-end;
+}
+
+.universal-page .uc-checkout-host {
+  position: fixed;
+  width: 0;
+  height: 0;
+}
+
+.universal-page .uc-checkout-host:not(:defined) > [slot="overlay"] {
+  display: none;
+}
+
+.universal-page .uc-overlay-surface {
+  display: grid;
+  grid-template-rows: auto auto auto minmax(0, 1fr);
+  gap: 14px;
+  width: min(760px, calc(100vw - 32px));
+  max-height: min(820px, calc(100dvh - 40px));
+  padding: 20px;
+  overflow: hidden;
+  color: var(--text);
+  text-align: left;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  box-shadow: 0 24px 80px rgba(0, 0, 0, 0.3);
+  font-family: var(--font-sans);
+  font-size: 14px;
+  line-height: 1.4;
+}
+
+.universal-page .uc-overlay-header,
+.universal-page .uc-overlay-activity-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 12px;
+}
+
+.universal-page .uc-overlay-header h2 {
+  margin: 2px 0 0;
+  font-size: 20px;
+  line-height: 1.2;
+}
+
+.universal-page .uc-overlay-eyebrow {
+  margin: 0;
+  color: var(--text-muted);
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.universal-page .uc-overlay-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.universal-page .uc-overlay-controls button,
+.universal-page .uc-overlay-activity-header button {
+  white-space: nowrap;
+}
+
+.universal-page .uc-overlay-notice {
+  margin: 0;
+  padding: 10px 12px;
+  color: var(--info-text);
+  background: var(--info-bg);
+  border-radius: 8px;
+  font-size: 13px;
+}
+
+.universal-page .uc-overlay-resources,
+.universal-page .uc-overlay-activity {
+  min-height: 0;
+  padding: 12px;
+  background: var(--surface-subdued);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+}
+
+.universal-page .uc-overlay-resources h3,
+.universal-page .uc-overlay-activity h3 {
+  margin: 0;
+  font-size: 12px;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.universal-page .uc-overlay-resources p {
+  margin: 8px 0 0;
+}
+
+.universal-page .uc-overlay-resources ol {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  max-height: 112px;
+  margin: 8px 0 0;
+  padding: 0;
+  overflow-y: auto;
+  list-style: none;
+}
+
+.universal-page .uc-overlay-resources li {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 6px 10px;
+  overflow-wrap: anywhere;
+  font-size: 12px;
+}
+
+.universal-page .uc-resource-error {
+  color: var(--error);
+  font-weight: 600;
+}
+
+.universal-page .uc-overlay-activity {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  overflow: hidden;
+}
+
+.universal-page .uc-overlay-activity > p {
+  margin: 0;
+}
+
+.universal-page .uc-overlay-event-log {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 0;
+  margin: 0;
+  padding: 0 4px 0 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  list-style: none;
+}
+
+.universal-page .uc-event-entry {
+  min-width: 0;
+}
+
+.universal-page .uc-event-entry details > summary {
+  cursor: pointer;
+  list-style: none;
+}
+
+.universal-page .uc-event-entry details > summary::-webkit-details-marker {
+  display: none;
+}
+
+.universal-page .uc-event-entry details > summary::before {
+  content: "▸";
+  color: var(--text-muted);
+}
+
+.universal-page .uc-event-entry details[open] > summary::before {
+  content: "▾";
+}
+
+.universal-page .uc-event-summary {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 4px 8px;
+}
+
+.universal-page .uc-event-resource {
+  font-weight: 600;
+}
+
+.universal-page .uc-event-status {
+  color: var(--text-muted);
+  overflow-wrap: anywhere;
+}
+
+.universal-page .uc-event-attribution {
+  margin: 8px 0 6px;
+  color: var(--text-muted);
+  font-size: 11px;
+}
+
+.universal-page .uc-event-clear {
+  margin-left: auto;
+  padding: 5px 9px;
+  font-size: 11px;
+}
+
+@media (min-width: 1181px) {
+  .universal-page .events-collapsed .uc-event-clear {
+    display: none;
+  }
+}
+
+.universal-page .uc-overlay-surface button:focus-visible,
+.universal-page .uc-event-entry summary:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+@media (max-width: 640px) {
+  .universal-page .uc-overlay-surface {
+    width: calc(100vw - 16px);
+    max-height: calc(100dvh - 16px);
+    gap: 10px;
+    padding: 14px;
+  }
+
+  .universal-page .uc-overlay-header {
+    flex-direction: column;
+  }
+}
diff --git a/platforms/web/sample/universal/overlay.test.ts b/platforms/web/sample/universal/overlay.test.ts
new file mode 100644
index 000000000..4d0c8020c
--- /dev/null
+++ b/platforms/web/sample/universal/overlay.test.ts
@@ -0,0 +1,236 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { mountUniversalOverlay, type UniversalCheckoutElement } from "./overlay";
+
+const SHOP_ID = "gid://shopify/Shop/private-123";
+const SECRET = "buyer@example.test";
+
+function fixture() {
+  document.body.className = "universal-page";
+  document.body.innerHTML = `
+    <input id="shop-draft" value="typing.example.test">
+    <section class="runtime-panel">
+      <div class="events-header"><h2>Events</h2></div>
+      <p id="notice"></p>
+      <ul id="event-log"></ul>
+    </section>
+  `;
+  return {
+    header: document.querySelector<HTMLElement>(".events-header")!,
+    notice: document.querySelector<HTMLElement>("#notice")!,
+    log: document.querySelector<HTMLElement>("#event-log")!,
+    draft: document.querySelector<HTMLInputElement>("#shop-draft")!,
+  };
+}
+
+function fakeElement() {
+  const element = document.createElement("shopify-universal-checkout") as UniversalCheckoutElement;
+  let checkout: unknown;
+  let error: unknown;
+  Object.assign(element, {
+    src: "",
+    target: "auto",
+    appearance: "storefront",
+    logLevel: "warn",
+  });
+  Object.defineProperties(element, {
+    checkout: { get: () => checkout },
+    error: { get: () => error },
+  });
+  const open = vi.fn();
+  const focus = vi.fn();
+  const close = vi.fn(() => element.dispatchEvent(new Event("close")));
+  element.open = open;
+  element.focus = focus;
+  element.close = close;
+  return {
+    element,
+    open,
+    focus,
+    close,
+    setCheckout(value: unknown) {
+      checkout = value;
+    },
+    setError(value: unknown) {
+      error = value;
+    },
+  };
+}
+
+function startEntry(status = "incomplete") {
+  return {
+    context: { sessionId: "private-session", revision: 1, shopId: SHOP_ID },
+    checkout: {
+      id: "private-checkout",
+      status,
+      currency: "EUR",
+      lineItems: [{ id: "private-line", buyer: SECRET }],
+      buyer: { email: SECRET },
+      messages: [{ content: '<script>alert("private")</script>' }],
+      continueUrl: "https://shop.app/checkout?token=private-token",
+    },
+  };
+}
+
+function aggregate(status = "incomplete") {
+  return {
+    sessionId: "private-session",
+    revision: 1,
+    resources: [{ shopId: SHOP_ID, checkout: startEntry(status).checkout }],
+  };
+}
+
+beforeEach(() => {
+  document.body.replaceChildren();
+  document.body.className = "";
+});
+
+describe("Universal sample overlay", () => {
+  it("opens synchronously and renders safe received events inside the slotted panel", () => {
+    const refs = fixture();
+    const fake = fakeElement();
+    const overlay = mountUniversalOverlay({
+      parent: document.body,
+      hostLog: refs.log,
+      hostHeader: refs.header,
+      hostNotice: refs.notice,
+      element: fake.element,
+    });
+    const sequence: string[] = [];
+    fake.open.mockImplementation(() => sequence.push("open"));
+    expect(
+      overlay.configure({
+        src: "https://shop.app/checkout?token=private-token",
+        target: "popup",
+        appearance: "app:light",
+        logLevel: "warn",
+      }),
+    ).toBe(true);
+    const button = document.createElement("button");
+    button.addEventListener("click", () => {
+      overlay.attemptOpen();
+      sequence.push("after");
+    });
+    button.click();
+    expect(sequence).toEqual(["open", "after"]);
+    expect(fake.element.target).toBe("popup");
+    expect(fake.element.querySelector('[slot="overlay"]')).not.toBeNull();
+    expect(fake.element.querySelectorAll(".uc-overlay-controls button")).toHaveLength(2);
+
+    fake.setCheckout(aggregate());
+    fake.element.dispatchEvent(new CustomEvent("start", { detail: [startEntry()] }));
+    const slottedLog = fake.element.querySelector<HTMLOListElement>(".uc-overlay-event-log")!;
+    expect(slottedLog.children).toHaveLength(1);
+    expect(refs.log.children).toHaveLength(1);
+    expect(slottedLog.textContent).toContain("Shop 1");
+    expect(fake.element.querySelector(".uc-overlay-resources")?.textContent).toContain(
+      "incomplete",
+    );
+    for (const secret of [SHOP_ID, SECRET, "private-token", "<script>", "private-session"]) {
+      expect(slottedLog.textContent).not.toContain(secret);
+      expect(refs.log.textContent).not.toContain(secret);
+    }
+    expect(slottedLog.querySelector("script")).toBeNull();
+    overlay.dispose();
+  });
+
+  it("preserves an expanded event and shop-draft focus while later events arrive", () => {
+    const refs = fixture();
+    const fake = fakeElement();
+    const overlay = mountUniversalOverlay({
+      parent: document.body,
+      hostLog: refs.log,
+      hostHeader: refs.header,
+      hostNotice: refs.notice,
+      element: fake.element,
+    });
+    overlay.configure({
+      src: "https://shop.app/checkout",
+      target: "auto",
+      appearance: "",
+      logLevel: "warn",
+    });
+    overlay.attemptOpen();
+    fake.setCheckout(aggregate());
+    fake.element.dispatchEvent(new CustomEvent("start", { detail: [startEntry()] }));
+    const first = refs.log.firstElementChild!;
+    const details = first.querySelector("details")!;
+    details.open = true;
+    refs.draft.focus();
+    fake.setCheckout(aggregate("ready_for_complete"));
+    fake.element.dispatchEvent(
+      new CustomEvent("update", { detail: [startEntry("ready_for_complete")] }),
+    );
+    expect(refs.log.firstElementChild).toBe(first);
+    expect(details.open).toBe(true);
+    expect(document.activeElement).toBe(refs.draft);
+    expect(refs.draft.value).toBe("typing.example.test");
+    overlay.dispose();
+  });
+
+  it("keeps state on Clear, provides focus/close controls and resets only on reopening", () => {
+    const refs = fixture();
+    const fake = fakeElement();
+    const overlay = mountUniversalOverlay({
+      parent: document.body,
+      hostLog: refs.log,
+      hostHeader: refs.header,
+      hostNotice: refs.notice,
+      element: fake.element,
+    });
+    overlay.configure({
+      src: "https://shop.app/checkout",
+      target: "popup",
+      appearance: "",
+      logLevel: "warn",
+    });
+    overlay.attemptOpen();
+    fake.setCheckout(aggregate());
+    fake.element.dispatchEvent(new CustomEvent("start", { detail: [startEntry()] }));
+    overlay.element.querySelector<HTMLButtonElement>(".uc-overlay-controls button")!.click();
+    expect(fake.focus).toHaveBeenCalledOnce();
+    refs.header.querySelector<HTMLButtonElement>("button")!.click();
+    expect(refs.log.children).toHaveLength(0);
+    expect(overlay.snapshot.resources).toHaveLength(1);
+    expect(fake.element.querySelector(".uc-overlay-resources")?.textContent).toContain("Shop 1");
+
+    overlay.element.querySelectorAll<HTMLButtonElement>(".uc-overlay-controls button")[1]!.click();
+    expect(overlay.snapshot.entries.at(-1)?.name).toBe("close");
+    expect(overlay.snapshot.phase).toBe("closed");
+    fake.element.dispatchEvent(new CustomEvent("update", { detail: [startEntry()] }));
+    expect(overlay.snapshot.entries).toHaveLength(1);
+    overlay.attemptOpen();
+    expect(overlay.snapshot.presentation).toBe(2);
+    expect(overlay.snapshot.entries).toHaveLength(0);
+    fake.element.dispatchEvent(new CustomEvent("start", { detail: [startEntry()] }));
+    expect(overlay.snapshot.entries).toHaveLength(1);
+    overlay.dispose();
+    fake.element.dispatchEvent(new CustomEvent("start", { detail: [startEntry()] }));
+    expect(overlay.snapshot.entries).toHaveLength(1);
+    expect(refs.header.querySelector("button")).toBeNull();
+  });
+
+  it("rejects unsafe sources before opening", () => {
+    const refs = fixture();
+    const fake = fakeElement();
+    const overlay = mountUniversalOverlay({
+      parent: document.body,
+      hostLog: refs.log,
+      hostHeader: refs.header,
+      hostNotice: refs.notice,
+      element: fake.element,
+      validateSource: (value) => (value === "https://shop.app/checkout" ? value : undefined),
+    });
+    expect(
+      overlay.configure({
+        src: "https://shop.app.evil.test/checkout",
+        target: "popup",
+        appearance: "",
+        logLevel: "warn",
+      }),
+    ).toBe(false);
+    expect(overlay.attemptOpen()).toBe(false);
+    expect(fake.open).not.toHaveBeenCalled();
+    overlay.dispose();
+  });
+});
diff --git a/platforms/web/sample/universal/overlay.ts b/platforms/web/sample/universal/overlay.ts
new file mode 100644
index 000000000..51dceb659
--- /dev/null
+++ b/platforms/web/sample/universal/overlay.ts
@@ -0,0 +1,155 @@
+import {
+  UniversalEventHistory,
+  type EventHistorySnapshot,
+  type KitEventName,
+} from "./event-history";
+import { createOverlayView } from "./overlay-view";
+import "./overlay.css";
+
+/**
+ * This narrow structural boundary lets the sample use the public custom
+ * element without importing any private Kit parser, reducer or presentation.
+ */
+export interface UniversalCheckoutElement extends HTMLElement {
+  src: string;
+  target: string;
+  appearance: string;
+  logLevel: string;
+  readonly checkout?: unknown;
+  readonly error?: unknown;
+  open(): void;
+  close(): void;
+  focus(): void;
+}
+
+export interface OverlayConfiguration {
+  readonly src: string;
+  readonly target: string;
+  readonly appearance: string;
+  readonly logLevel: string;
+}
+
+export interface UniversalOverlay {
+  readonly element: UniversalCheckoutElement;
+  readonly snapshot: EventHistorySnapshot;
+  configure(configuration: OverlayConfiguration): boolean;
+  /** Synchronous browser-gesture attempt. Its return value is not an outcome. */
+  attemptOpen(): boolean;
+  clearHistory(): void;
+  dispose(): void;
+}
+
+export interface MountUniversalOverlayOptions {
+  readonly parent: HTMLElement;
+  readonly hostLog: HTMLElement;
+  readonly hostHeader: HTMLElement;
+  readonly hostNotice: HTMLElement;
+  readonly element?: UniversalCheckoutElement;
+  readonly now?: () => Date;
+  /** Use the sample's session destination validator for both generated and pasted URLs. */
+  readonly validateSource?: (value: string) => string | undefined;
+  readonly onChange?: (snapshot: EventHistorySnapshot) => void;
+}
+
+/** Basic transport guard; the caller supplies the stricter configured host policy. */
+export function validateHttpsCheckoutSource(value: string): string | undefined {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && !url.username && !url.password ? url.toString() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function mountUniversalOverlay(options: MountUniversalOverlayOptions): UniversalOverlay {
+  const element =
+    options.element ??
+    (document.createElement("shopify-universal-checkout") as UniversalCheckoutElement);
+  const history = new UniversalEventHistory(options.now);
+  const view = createOverlayView({
+    hostLog: options.hostLog,
+    hostHeader: options.hostHeader,
+    hostNotice: options.hostNotice,
+    onFocus: () => element.focus(),
+    onClose: () => element.close(),
+    onClear: () => {
+      history.clear();
+      render();
+    },
+  });
+  const listeners = new AbortController();
+  let configuredSource = "";
+  let disposed = false;
+
+  element.classList.add("uc-checkout-host");
+  element.append(view.surface);
+  options.parent.append(element);
+
+  const names: readonly KitEventName[] = ["start", "update", "complete", "error", "close"];
+  for (const name of names) {
+    element.addEventListener(
+      name,
+      (event: Event) => {
+        const detail = "detail" in event ? event.detail : undefined;
+        history.receive(name, detail, element.checkout, element.error);
+        render();
+      },
+      { signal: listeners.signal },
+    );
+  }
+
+  function render(): void {
+    const snapshot = history.snapshot;
+    view.render(snapshot);
+    options.onChange?.(snapshot);
+  }
+
+  render();
+
+  return {
+    element,
+    get snapshot() {
+      return history.snapshot;
+    },
+    configure(configuration) {
+      if (disposed) return false;
+      const source = (options.validateSource ?? validateHttpsCheckoutSource)(configuration.src);
+      if (!source) {
+        configuredSource = "";
+        if (element.src) element.src = "";
+        return false;
+      }
+      if (element.src !== source) element.src = source;
+      if (element.target !== configuration.target) element.target = configuration.target;
+      if (element.appearance !== configuration.appearance) {
+        element.appearance = configuration.appearance;
+      }
+      if (element.logLevel !== configuration.logLevel) element.logLevel = configuration.logLevel;
+      configuredSource = source;
+      return true;
+    },
+    attemptOpen() {
+      if (disposed || !configuredSource || element.src !== configuredSource) return false;
+      // A close notification for an old presentation belongs to its old history.
+      element.close();
+      history.beginPresentation();
+      render();
+      // The call stays in the click stack; no network work or promise precedes it.
+      element.open();
+      return true;
+    },
+    clearHistory() {
+      if (disposed) return;
+      history.clear();
+      render();
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      listeners.abort();
+      view.dispose();
+      element.close();
+      element.remove();
+    },
+  };
+}
diff --git a/platforms/web/sample/universal/source-selection.test.ts b/platforms/web/sample/universal/source-selection.test.ts
new file mode 100644
index 000000000..98005f776
--- /dev/null
+++ b/platforms/web/sample/universal/source-selection.test.ts
@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+
+import { isContinuationUrl } from "./policy";
+import { createSourceSelection } from "./source-selection";
+
+const VALID_URL = "https://shop.app/checkouts/uc/example?key=private";
+const prepared = {
+  phase: "ready",
+  generation: 2,
+  readyGeneration: 2,
+  url: VALID_URL,
+};
+
+describe("Universal sample source selection", () => {
+  it("accepts only the exact configured continuation host and path", () => {
+    expect(isContinuationUrl(VALID_URL, "production")).toBe(true);
+    expect(isContinuationUrl(VALID_URL, "development")).toBe(false);
+    expect(
+      isContinuationUrl(
+        "https://shop.app.evil.test/checkouts/uc/example?key=private",
+        "production",
+      ),
+    ).toBe(false);
+    expect(isContinuationUrl("https://shop.app/cart/example?key=private", "production")).toBe(
+      false,
+    );
+  });
+
+  it("uses only a validated URL prepared for the current generation", () => {
+    const source = createSourceSelection(
+      (url, environment) => environment === "production" && url === VALID_URL,
+    );
+    expect(source.select(prepared, "production")).toMatchObject({
+      mode: "generated",
+      url: VALID_URL,
+      ready: true,
+    });
+    expect(source.select({ ...prepared, generation: 3 }, "production").ready).toBe(false);
+    expect(source.select(prepared, "development").ready).toBe(false);
+    expect(source.select({ ...prepared, phase: "error" }, "production").ready).toBe(false);
+  });
+
+  it("keeps pasted input in memory and clears it when switching modes", () => {
+    const source = createSourceSelection((url) => url === VALID_URL);
+    source.setMode("pasted");
+    source.setPastedDraft(`  ${VALID_URL}  `);
+    expect(source.select({ ...prepared, phase: "editing" }, "production")).toMatchObject({
+      mode: "pasted",
+      url: VALID_URL,
+      ready: true,
+    });
+    source.setMode("generated");
+    expect(source.pastedDraft).toBe("");
+    source.setMode("pasted");
+    expect(source.select(prepared, "production").ready).toBe(false);
+    expect(source.pastedDraft).toBe("");
+  });
+
+  it("does not pass a pasted lookalike or stale environment URL to the element", () => {
+    const source = createSourceSelection(
+      (url, environment) => environment === "production" && url === VALID_URL,
+    );
+    source.setMode("pasted");
+    source.setPastedDraft("https://shop.app.evil.test/checkouts/uc/example?key=private");
+    expect(source.select(prepared, "production").url).toBe("");
+    source.setPastedDraft(VALID_URL);
+    expect(source.select(prepared, "development").url).toBe("");
+  });
+});
diff --git a/platforms/web/sample/universal/source-selection.ts b/platforms/web/sample/universal/source-selection.ts
new file mode 100644
index 000000000..3323b3d2e
--- /dev/null
+++ b/platforms/web/sample/universal/source-selection.ts
@@ -0,0 +1,106 @@
+import type { CheckoutEnvironment } from "./policy";
+
+export type CheckoutSourceMode = "generated" | "pasted";
+
+export interface PreparedSource {
+  readonly phase: string;
+  readonly generation: number;
+  readonly readyGeneration: number | null;
+  readonly url: string;
+}
+
+export interface SelectedSource {
+  readonly mode: CheckoutSourceMode;
+  readonly url: string;
+  readonly ready: boolean;
+  readonly hint: string;
+}
+
+/**
+ * Pasted URLs are an advanced, memory-only input. Both modes cross the same
+ * strict destination validator before they can reach the Checkout Kit element.
+ */
+export function createSourceSelection(
+  isAllowed: (url: string, environment: CheckoutEnvironment) => boolean,
+): {
+  readonly mode: CheckoutSourceMode;
+  readonly pastedDraft: string;
+  setMode(mode: CheckoutSourceMode): void;
+  setPastedDraft(value: string): void;
+  select(prepared: PreparedSource, environment: CheckoutEnvironment): SelectedSource;
+} {
+  let mode: CheckoutSourceMode = "generated";
+  let pastedDraft = "";
+
+  return {
+    get mode() {
+      return mode;
+    },
+    get pastedDraft() {
+      return pastedDraft;
+    },
+    setMode(next) {
+      if (next === mode) return;
+      mode = next;
+      // Never carry a previously pasted secret into a later presentation.
+      pastedDraft = "";
+    },
+    setPastedDraft(value) {
+      pastedDraft = value;
+    },
+    select(prepared, environment) {
+      if (mode === "pasted") {
+        const url = pastedDraft.trim();
+        if (!url) {
+          return {
+            mode,
+            url: "",
+            ready: false,
+            hint: "Paste an existing Universal Checkout URL to open it.",
+          };
+        }
+        if (!isAllowed(url, environment)) {
+          return {
+            mode,
+            url: "",
+            ready: false,
+            hint: "Use a valid Universal Checkout URL for the selected environment.",
+          };
+        }
+        return {
+          mode,
+          url,
+          ready: true,
+          hint: "Pasted URL is ready. Open it with Checkout Kit.",
+        };
+      }
+
+      if (
+        prepared.phase !== "ready" ||
+        prepared.readyGeneration !== prepared.generation ||
+        !prepared.url
+      ) {
+        return {
+          mode,
+          url: "",
+          ready: false,
+          hint: "Create a Universal Checkout URL from the selected carts first.",
+        };
+      }
+      if (!isAllowed(prepared.url, environment)) {
+        return {
+          mode,
+          url: "",
+          ready: false,
+          hint: "The prepared URL does not match the selected environment. Create it again.",
+        };
+      }
+      return {
+        mode,
+        url: prepared.url,
+        ready: true,
+        hint: "The Universal Checkout URL is ready. Open it with Checkout Kit.",
+      };
+    },
+  };
+}
diff --git a/platforms/web/sample/universal/source-view.test.ts b/platforms/web/sample/universal/source-view.test.ts
new file mode 100644
index 000000000..586b9c0f2
--- /dev/null
+++ b/platforms/web/sample/universal/source-view.test.ts
@@ -0,0 +1,55 @@
+import { beforeEach, describe, expect, it } from "vitest";
+
+import page from "../universal.html?raw";
+import { querySourceViewRefs, renderSourceView } from "./source-view";
+
+beforeEach(() => {
+  const start = page.indexOf('<main id="layout">');
+  const end = page.indexOf("</main>", start);
+  document.body.innerHTML = page.slice(start, end + "</main>".length);
+});
+
+describe("Universal checkout source controls", () => {
+  it("keeps the pasted input mounted while readiness changes", () => {
+    const refs = querySourceViewRefs();
+    const input = refs.pastedUrl;
+    const selected = {
+      mode: "pasted" as const,
+      url: "",
+      ready: false,
+      hint: "Use a valid Universal Checkout URL.",
+    };
+    renderSourceView(refs, "pasted", "partial input", selected);
+    input.focus();
+    renderSourceView(refs, "pasted", "partial input", {
+      ...selected,
+      ready: true,
+      hint: "Ready.",
+    });
+    expect(refs.pastedUrl).toBe(input);
+    expect(document.activeElement).toBe(input);
+    expect(input.value).toBe("partial input");
+    expect(refs.openButton.disabled).toBe(false);
+    expect(refs.pastedFields.hidden).toBe(false);
+  });
+
+  it("disables Open and clears the advanced input when generated mode is restored", () => {
+    const refs = querySourceViewRefs();
+    renderSourceView(refs, "pasted", "https://shop.app/checkouts/uc/example?key=private", {
+      mode: "pasted",
+      url: "",
+      ready: false,
+      hint: "Invalid.",
+    });
+    renderSourceView(refs, "generated", "", {
+      mode: "generated",
+      url: "",
+      ready: false,
+      hint: "Create a URL first.",
+    });
+    expect(refs.pastedFields.hidden).toBe(true);
+    expect(refs.pastedUrl.value).toBe("");
+    expect(refs.openButton.disabled).toBe(true);
+    expect(refs.status.textContent).toBe("Create a URL first.");
+  });
+});
diff --git a/platforms/web/sample/universal/source-view.ts b/platforms/web/sample/universal/source-view.ts
new file mode 100644
index 000000000..38cf7d5bb
--- /dev/null
+++ b/platforms/web/sample/universal/source-view.ts
@@ -0,0 +1,43 @@
+import { $ } from "../dom";
+import type { CheckoutSourceMode, SelectedSource } from "./source-selection";
+
+export interface SourceViewRefs {
+  readonly generatedInput: HTMLInputElement;
+  readonly pastedInput: HTMLInputElement;
+  readonly pastedFields: HTMLElement;
+  readonly pastedUrl: HTMLInputElement;
+  readonly status: HTMLElement;
+  readonly openButton: HTMLButtonElement;
+}
+
+export function querySourceViewRefs(): SourceViewRefs {
+  return {
+    generatedInput: $<HTMLInputElement>("#uc-source-generated"),
+    pastedInput: $<HTMLInputElement>("#uc-source-pasted"),
+    pastedFields: $<HTMLElement>("#uc-pasted-fields"),
+    pastedUrl: $<HTMLInputElement>("#uc-pasted-url"),
+    status: $<HTMLElement>("#uc-source-status"),
+    openButton: $<HTMLButtonElement>("#uc-open"),
+  };
+}
+
+/** Update persistent controls in place so checkout events cannot steal focus. */
+export function renderSourceView(
+  refs: SourceViewRefs,
+  mode: CheckoutSourceMode,
+  pastedDraft: string,
+  selected: SelectedSource,
+): void {
+  refs.generatedInput.checked = mode === "generated";
+  refs.pastedInput.checked = mode === "pasted";
+  refs.pastedFields.hidden = mode !== "pasted";
+  refs.pastedUrl.disabled = mode !== "pasted";
+  if (refs.pastedUrl.value !== pastedDraft) refs.pastedUrl.value = pastedDraft;
+  refs.pastedUrl.setAttribute(
+    "aria-invalid",
+    String(mode === "pasted" && pastedDraft.trim() !== "" && !selected.ready),
+  );
+  refs.status.textContent = selected.hint;
+  refs.status.dataset["tone"] = selected.ready ? "success" : "info";
+  refs.openButton.disabled = !selected.ready;
+}