@tokenoftrust/storefront-runner 4.7.5 → 4.7.7

package/apps/storefront/public/shared/commerce-chrome.css

@@ -150,6 +150,7 @@ body { overflow-x: clip; }
   font-size: .62rem; font-weight: 700; min-width: 16px; height: 16px; border-radius: var(--radius-full);
   display: grid; place-items: center; padding: 0 4px;
 }
+.header-actions .cart .count[hidden], .nav-mobile-actions .cart .count[hidden] { display: none; }
 .header-cta {
   border-radius: var(--radius-full); padding: 8px 16px;
   font-family: var(--font-display, inherit); font-size: .875rem; font-weight: 500;

package/apps/storefront/src/components/checkout/storefront/commerce/CartState.astro

@@ -0,0 +1,34 @@
+---
+/**
+ * <CartState> — the header cart count and the add-to-cart confirmation.
+ *
+ * Rendered for commerce tenants with a store, on every Layout page, next to the
+ * checkout loader. It carries the store's cart URL, session route and cookie path as
+ * data, and `cartState.ts` does the rest in the browser: no cart, no request. The
+ * same markup is served by the Worker and by the statically published CloudFront/S3
+ * output. See `lib/checkout/shared/cartState.ts`.
+ */
+import CartAddedDialog from "@/components/checkout/storefront/islands/CartAddedDialog.tsx";
+import { cartSessionCookiePath } from "@/lib/checkout/commerce/cartSession";
+
+const { commerce, apiBasePath, basePath } = Astro.locals;
+const apiBase = apiBasePath ?? basePath ?? "";
+---
+{
+  commerce && (
+    <>
+      <div
+        hidden
+        data-cart-state
+        data-cart-url={commerce.cartUrl}
+        data-session-href={`${apiBase}/api/commerce/cart-session`}
+        data-cookie-path={cartSessionCookiePath(apiBase)}
+      />
+      <CartAddedDialog client:idle />
+      <script>
+        import { bootCartStateFromDom } from "@/lib/checkout/shared/cartState";
+        bootCartStateFromDom(window);
+      </script>
+    </>
+  )
+}

package/apps/storefront/src/components/checkout/storefront/islands/CartAddedDialog.tsx

@@ -0,0 +1,147 @@
+/**
+ * <CartAddedDialog> — the "Item added to your cart" confirmation.
+ *
+ * Opens when `cartState.ts` reports a finished add (the shopper stays on the page):
+ * the product, its selected options, the quantity added, a View my cart (n) link to
+ * the managed cart, and Continue shopping. When the provider could not confirm the
+ * add, the same dialog says so and offers the cart, so the shopper is never left
+ * guessing. Focus moves into the dialog, Tab stays inside it, Escape and the
+ * backdrop close it, and focus returns to the control that opened it.
+ *
+ * Styled from the theme tokens the compliance dialog uses, so it follows the tenant.
+ */
+import { useEffect, useRef, useState } from "preact/hooks";
+import {
+  CART_ADDED_EVENT,
+  takePendingCartAdded,
+  type CartAddedDetail,
+} from "../../../../lib/checkout/shared/cartState.js";
+
+const FOCUSABLE = 'a[href], button:not([disabled])';
+
+export default function CartAddedDialog() {
+  const [detail, setDetail] = useState<CartAddedDetail | null>(null);
+  const panel = useRef<HTMLDivElement>(null);
+  const opener = useRef<Element | null>(null);
+
+  useEffect(() => {
+    const show = (next: CartAddedDetail | null) => {
+      if (!next) return;
+      opener.current = document.activeElement;
+      setDetail(next);
+    };
+    const onAdded = (event: Event) => show((event as CustomEvent<CartAddedDetail>).detail);
+    window.addEventListener(CART_ADDED_EVENT, onAdded);
+    show(takePendingCartAdded(window));
+    return () => window.removeEventListener(CART_ADDED_EVENT, onAdded);
+  }, []);
+
+  useEffect(() => {
+    if (!detail) return;
+    document.documentElement.style.overflow = "hidden";
+    panel.current?.querySelector<HTMLElement>(FOCUSABLE)?.focus();
+    const close = () => setDetail(null);
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        close();
+        return;
+      }
+      if (event.key !== "Tab" || !panel.current) return;
+      const items = [...panel.current.querySelectorAll<HTMLElement>(FOCUSABLE)];
+      const first = items[0];
+      const last = items[items.length - 1];
+      if (!first || !last) return;
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      document.documentElement.style.overflow = "";
+      if (opener.current instanceof HTMLElement) opener.current.focus();
+    };
+  }, [detail]);
+
+  if (!detail) return null;
+  const close = () => setDetail(null);
+  const added = detail.status === "added";
+  const buttonClass =
+    "rounded-full px-6 py-3 text-center font-display text-sm font-medium uppercase tracking-[0.08em] transition-opacity hover:opacity-90";
+
+  return (
+    <div
+      class="fixed inset-0 z-[110] bg-[color-mix(in_srgb,var(--color-text)_75%,transparent)] backdrop-blur-sm"
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="cart-added-title"
+      data-cart-added={detail.status}
+      onClick={(e) => {
+        if (e.target === e.currentTarget || (e.target as HTMLElement).hasAttribute("data-viewport-frame")) close();
+      }}
+    >
+      <div data-viewport-frame class="absolute left-0 top-0 flex h-[100svh] w-[100vw] overflow-y-auto p-5">
+        <div
+          ref={panel}
+          class="m-auto w-[min(28rem,100%)] rounded-[var(--radius-lg)] bg-[var(--color-surface)] p-7 text-left shadow-[var(--shadow-lg)]"
+        >
+          <h2 id="cart-added-title" class="display-sm">
+            {added ? "Item added to your cart" : "We couldn't confirm your cart"}
+          </h2>
+
+          {detail.status === "added" ? (
+            <div class="mt-5 flex gap-4" data-cart-added-item>
+              {detail.image && (
+                <img
+                  src={detail.image}
+                  alt=""
+                  width="72"
+                  height="72"
+                  class="h-[72px] w-[72px] flex-none rounded-[var(--radius-md)] border border-[var(--color-border)] object-cover"
+                />
+              )}
+              <div class="min-w-0">
+                <p class="font-display text-base font-semibold text-[var(--color-text)]">{detail.title}</p>
+                {detail.options.length > 0 && (
+                  <dl class="mt-1 text-sm text-[var(--color-muted)]">
+                    {detail.options.map((option) => (
+                      <div key={option.name} class="flex gap-1">
+                        <dt>{option.name}:</dt>
+                        <dd>{option.value}</dd>
+                      </div>
+                    ))}
+                  </dl>
+                )}
+                <p class="mt-1 text-sm text-[var(--color-muted)]">Quantity: {detail.quantity}</p>
+              </div>
+            </div>
+          ) : (
+            <p class="mt-3 text-sm text-[var(--color-text)]">
+              Check your cart to see whether the item was added.
+            </p>
+          )}
+
+          <div class="mt-6 flex flex-col gap-3">
+            <a
+              href={detail.cartHref}
+              class={`${buttonClass} bg-[var(--color-primary)] text-[var(--color-primary-contrast)]`}
+            >
+              {detail.status === "added" ? `View my cart (${detail.count})` : "View my cart"}
+            </a>
+            <button
+              type="button"
+              onClick={close}
+              class={`${buttonClass} border border-[var(--color-border)] text-[var(--color-text)] hover:border-[var(--color-text)]`}
+            >
+              Continue shopping
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/apps/storefront/src/components/content/storefront/chrome/SiteHeader.astro

@@ -11,7 +11,8 @@
  * session/feature/theme state and passes it down; this component stays pure.
  *
  * COMMERCE BOUNDARY: the cart is a LINK only — no cart state, no add-to-cart.
- * The count is a static affordance the managed cart can hydrate later.
+ * The count renders hidden at zero; `lib/checkout/shared/cartState.ts` fills the
+ * `[data-cart-count]` badge from the managed cart after load and after an add.
  */
 import type { ChromeNavItem, ChromeLogo, ChromeCta, HeaderVariant } from "@/lib/content/chrome/model";
 import MegaMenu from "@/components/content/storefront/chrome/MegaMenu.astro";
@@ -336,7 +337,9 @@ const currentPath = Astro.url.pathname;
               </svg>
               <span
                 data-cart-count
-                class="absolute -right-0.5 -top-0.5 grid h-4 min-w-4 place-items-center rounded-full bg-[var(--color-sale)] px-1 font-mono text-[0.6rem] font-medium text-white"
+                aria-live="polite"
+                hidden={cartCount === 0}
+                class="absolute -right-0.5 -top-0.5 grid h-4 min-w-4 place-items-center rounded-full bg-[var(--color-sale)] px-1 font-mono text-[0.6rem] font-medium text-white [&[hidden]]:hidden"
               >
                 {cartCount}
               </span>

package/apps/storefront/src/layouts/Layout.astro

@@ -14,6 +14,7 @@ import SiteHeader from "@/components/content/storefront/chrome/SiteHeader.astro"
 import SiteFooter from "@/components/content/storefront/chrome/SiteFooter.astro";
 import QuickView from "@/components/catalog/storefront/islands/QuickView.tsx";
 import CheckoutLoader from "@/components/checkout/storefront/commerce/CheckoutLoader.astro";
+import CartState from "@/components/checkout/storefront/commerce/CartState.astro";
 import CartDrawerStyles from "@/components/checkout/storefront/commerce/CartDrawerStyles.astro";
 import NicotineWarning from "@/components/compliance/storefront/compliance/NicotineWarning.astro";
 import PactActNotice from "@/components/compliance/storefront/compliance/PactActNotice.astro";
@@ -518,6 +519,7 @@ const footerWidgets = await renderWidgetSlot(
     {/* Checkout loader — turns add-to-cart forms into the cart drawer + hosted
         checkout. Only for commerce tenants with a store. */}
     <CheckoutLoader nonce={cspNonce} />
+    <CartState />
 
     {/* Brand the in-page cart drawer to the tenant theme (baseline + optional
         per-tenant commerce.checkout.cartDrawerCss override). Commerce tenants only. */}

package/apps/storefront/src/lib/checkout/commerce/checkoutHandoffRoute.ts

@@ -220,6 +220,18 @@ async function cartFormPost(context: APIContext): Promise<Response> {
   });
   const location = await sessionedCartLocation(context, commerce, tenant, returned);
   if (!location) return cartDenial("signing-unavailable", CART_UNAVAILABLE_MESSAGE, 503);
+  // The page adds the line itself (cartState.ts) and asks for the signed cart URL as data.
+  if ((context.request.headers.get("accept") ?? "").includes("application/json")) {
+    return new Response(JSON.stringify({ location }), {
+      status: 200,
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        "cache-control": "no-store",
+        "referrer-policy": CHECKOUT_NAVIGATION_REFERRER_POLICY,
+        "x-tot-payment-authorized": "false",
+      },
+    });
+  }
   return new Response(null, {
     status: 303,
     headers: {

package/apps/storefront/src/lib/checkout/shared/cartState.ts

@@ -0,0 +1,511 @@
+/**
+ * Browser cart state for a statically served store: the header cart count and the
+ * add-to-cart confirmation.
+ *
+ * The cart session lives on the managed checkout's origin, so a store page cannot
+ * read it with `fetch` (the provider's cart JSON carries no CORS headers). The
+ * provider answers a `callback` parameter with a script, so the page reads the cart
+ * the way the provider's own drawer does: a script tag to the checkout origin,
+ * carrying this store's session id. That id comes from the store's own
+ * `/api/commerce/cart-session` route, which the checkout loader already calls.
+ *
+ * Nothing here puts compute in front of a public page. A visitor with no cart makes
+ * no request at all: the last known count is kept in this browser's own storage and
+ * a read happens only when that count is above zero. The same code and markup are
+ * served by the Cloudflare Worker and by the statically published CloudFront/S3
+ * output; both reach the checkout origin and `/api/*` the same way.
+ *
+ * An add-to-cart submit that the compliance gate and the checkout loader have
+ * released is sent to the store's cart route as JSON, the signed provider cart URL
+ * it returns is loaded as a script (which adds the line and returns the cart), and
+ * the shopper stays on the page with a confirmation. Any failure before the provider
+ * is asked hands the form back to the native submit, which opens the cart page. A
+ * failure after the provider is asked never resubmits: that could add the line twice.
+ */
+
+/** Window event carrying a {@link CartAddedDetail}. */
+export const CART_ADDED_EVENT = "tot:cart-added";
+
+/** Mirrors `INTERNAL_CART_FIELDS` in `@tot/public-runtime`; a test pins the two together. */
+export const INTERNAL_CART_OPTIONS: readonly string[] = [
+  "currency",
+  "tenant",
+  "verification",
+  "shipping_policy",
+  "return_url",
+  "content_version",
+];
+
+const MANAGED_CART_FORM = "form[data-managed-cart]";
+const COUNT_SELECTOR = "[data-cart-count], .cart .count";
+const JSONP_TIMEOUT_MS = 8000;
+const SESSION_TIMEOUT_MS = 5000;
+
+export interface CartStateConfig {
+  /** `https://<checkout origin>/cart`. */
+  cartUrl: string;
+  /** Same-origin URL returning this store's `{ fcsid }`. */
+  sessionHref: string;
+  /** The store's cookie path; keys the stored count so tenants on one host stay apart. */
+  cookiePath: string;
+}
+
+export interface CartOption {
+  name: string;
+  value: string;
+}
+
+export interface CartLine {
+  code: string;
+  name: string;
+  quantity: number;
+  image: string | null;
+  options: CartOption[];
+}
+
+export interface ParsedCart {
+  count: number;
+  sessionId: string | null;
+  lines: CartLine[];
+  /** Messages the provider refused the request with. Empty when it accepted. */
+  errors: string[];
+}
+
+export type CartAddedDetail =
+  | {
+      status: "added";
+      title: string;
+      options: CartOption[];
+      quantity: number;
+      image: string | null;
+      count: number;
+      cartHref: string;
+    }
+  | { status: "error"; cartHref: string };
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/** An option name as one key: signed suffix dropped, spaces and underscores equal. */
+export function optionKey(raw: string): string {
+  return (raw.split("||")[0] ?? "").trim().toLowerCase().replace(/[\s_]+/g, "_");
+}
+
+function optionLabel(raw: string): string {
+  return (raw.split("||")[0] ?? "").trim().replace(/_/g, " ");
+}
+
+function readOptions(raw: unknown): CartOption[] {
+  const out: CartOption[] = [];
+  const push = (name: unknown, value: unknown) => {
+    if (typeof name !== "string" || typeof value !== "string") return;
+    const key = optionKey(name);
+    const text = value.trim();
+    if (!key || !text || INTERNAL_CART_OPTIONS.includes(key)) return;
+    out.push({ name: optionLabel(name), value: text });
+  };
+  if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      const option = record(entry);
+      if (option) push(option.name ?? option.class, option.value);
+    }
+  } else {
+    const map = record(raw);
+    if (map) for (const [name, value] of Object.entries(map)) push(name, value);
+  }
+  return out;
+}
+
+function imageUrl(raw: unknown): string | null {
+  if (typeof raw !== "string" || !raw) return null;
+  if (raw.startsWith("/") && !raw.startsWith("//")) return raw;
+  return /^https:\/\/[^\s/]+/.test(raw) ? raw : null;
+}
+
+function wholeNumber(raw: unknown): number {
+  const n = typeof raw === "number" ? raw : Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+
+/** The provider's cart JSON as a typed cart, or null when the body is not a cart. */
+export function parseCart(body: unknown): ParsedCart | null {
+  const cart = record(body);
+  if (!cart) return null;
+  const rawItems = Array.isArray(cart.items) ? cart.items : null;
+  if (!rawItems && typeof cart.item_count !== "number") return null;
+  const lines: CartLine[] = [];
+  for (const entry of rawItems ?? []) {
+    const item = record(entry);
+    if (!item) continue;
+    lines.push({
+      code: typeof item.code === "string" ? item.code : "",
+      name: typeof item.name === "string" ? item.name : "",
+      quantity: wholeNumber(item.quantity),
+      image: imageUrl(item.image),
+      options: readOptions(item.options),
+    });
+  }
+  const count = lines.length > 0
+    ? lines.reduce((sum, line) => sum + line.quantity, 0)
+    : wholeNumber(cart.item_count);
+  const messages = record(cart.messages);
+  const errors = Array.isArray(messages?.errors)
+    ? messages.errors.flatMap((e) => {
+        const message = record(e)?.message;
+        return typeof message === "string" ? [message] : [];
+      })
+    : [];
+  const session = cart.session_id;
+  return {
+    count,
+    sessionId: typeof session === "string" && /^[a-z0-9]{10,64}$/.test(session) ? session : null,
+    lines,
+    errors,
+  };
+}
+
+export function cartAriaLabel(count: number): string {
+  return count > 0 ? `Cart, ${count} ${count === 1 ? "item" : "items"}` : "Cart";
+}
+
+/**
+ * Show `count` in every header cart badge: text, hidden at zero, polite live region,
+ * and the cart link's own label when it carries one.
+ */
+export function renderCartCount(doc: Document, count: number): void {
+  for (const badge of doc.querySelectorAll<HTMLElement>(COUNT_SELECTOR)) {
+    badge.textContent = String(count);
+    badge.hidden = count === 0;
+    // A tenant stylesheet that sets `display` on the badge outranks [hidden].
+    badge.style.display = count === 0 ? "none" : "";
+    badge.setAttribute("aria-live", "polite");
+    const link = badge.closest("a");
+    if (link && /^Cart\b/i.test(link.getAttribute("aria-label") ?? "")) {
+      link.setAttribute("aria-label", cartAriaLabel(count));
+    }
+  }
+}
+
+export function storedCountKey(cookiePath: string): string {
+  return `tot:cart-count:${cookiePath}`;
+}
+
+export function readStoredCount(storage: Pick<Storage, "getItem"> | null, key: string): number {
+  try {
+    return wholeNumber(storage?.getItem(key));
+  } catch {
+    return 0;
+  }
+}
+
+export function writeStoredCount(
+  storage: Pick<Storage, "setItem" | "removeItem"> | null,
+  key: string,
+  count: number,
+): void {
+  try {
+    if (count > 0) storage?.setItem(key, String(count));
+    else storage?.removeItem(key);
+  } catch {
+    /* storage disabled: the count then lives only until the next read */
+  }
+}
+
+export interface CartEnv {
+  doc: Document;
+  win: Window;
+  fetch: typeof fetch;
+  storage: Storage | null;
+}
+
+type JsonpHost = Window & Record<string, unknown>;
+
+/**
+ * Load `url` (a checkout-origin cart URL) as a script that answers with the cart JSON.
+ * Rejects when the URL is not on the checkout origin, the script fails, or it is silent.
+ */
+export function loadCartJsonp(
+  url: string,
+  cartOrigin: string,
+  env: Pick<CartEnv, "doc" | "win">,
+  timeoutMs = JSONP_TIMEOUT_MS,
+): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    let target: URL;
+    try {
+      target = new URL(url);
+    } catch {
+      reject(new Error("cart-url"));
+      return;
+    }
+    if (target.origin !== cartOrigin) {
+      reject(new Error("cart-origin"));
+      return;
+    }
+    const host = env.win as JsonpHost;
+    const name = `totCart${Math.random().toString(36).slice(2, 10)}`;
+    const script = env.doc.createElement("script");
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const done = () => {
+      if (timer) clearTimeout(timer);
+      delete host[name];
+      script.remove();
+    };
+    host[name] = (body: unknown) => {
+      done();
+      resolve(body);
+    };
+    target.searchParams.set("output", "json");
+    target.searchParams.set("callback", name);
+    script.src = target.toString();
+    script.async = true;
+    script.addEventListener("error", () => {
+      done();
+      reject(new Error("cart-script"));
+    });
+    timer = setTimeout(() => {
+      done();
+      reject(new Error("cart-timeout"));
+    }, timeoutMs);
+    env.doc.head.appendChild(script);
+  });
+}
+
+/** A read that failed is not an empty cart: callers keep what they showed. */
+export type CartRead =
+  | { status: "cart"; cart: ParsedCart }
+  | { status: "unreadable"; reason: string };
+
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message || error.name : "error";
+}
+
+async function readSessionId(
+  config: CartStateConfig,
+  env: CartEnv,
+): Promise<{ status: "session"; id: string } | { status: "unreadable"; reason: string }> {
+  try {
+    const res = await env.fetch(config.sessionHref, {
+      credentials: "same-origin",
+      cache: "no-store",
+      signal: AbortSignal.timeout(SESSION_TIMEOUT_MS),
+    });
+    if (!res.ok) return { status: "unreadable", reason: `session-${res.status}` };
+    const id = record(await res.json())?.fcsid;
+    return typeof id === "string" && /^[a-z0-9]{10,64}$/.test(id)
+      ? { status: "session", id }
+      : { status: "unreadable", reason: "session-id" };
+  } catch (error) {
+    return { status: "unreadable", reason: reasonOf(error) };
+  }
+}
+
+/** This store's cart as the provider holds it. */
+export async function readCart(config: CartStateConfig, env: CartEnv): Promise<CartRead> {
+  const session = await readSessionId(config, env);
+  if (session.status !== "session") return session;
+  const url = new URL(config.cartUrl);
+  url.searchParams.set("fcsid", session.id);
+  try {
+    const cart = parseCart(await loadCartJsonp(url.toString(), url.origin, env));
+    if (!cart) return { status: "unreadable", reason: "not-a-cart" };
+    if (cart.errors.length > 0) return { status: "unreadable", reason: "refused" };
+    return { status: "cart", cart };
+  } catch (error) {
+    return { status: "unreadable", reason: reasonOf(error) };
+  }
+}
+
+function fieldBase(name: string): string {
+  return name.split("||")[0] ?? "";
+}
+
+function submittedField(data: FormData, base: string): string {
+  for (const [name, value] of data.entries()) {
+    if (fieldBase(name) === base && typeof value === "string") return value;
+  }
+  return "";
+}
+
+function cartHrefFor(config: CartStateConfig, sessionId: string | null): string {
+  if (!sessionId) return config.cartUrl;
+  const url = new URL(config.cartUrl);
+  url.searchParams.set("fcsid", sessionId);
+  return url.toString();
+}
+
+/**
+ * The cart line a submitted form produced: the line carrying its `code`, else the
+ * last line the cart holds.
+ */
+export function addedLine(cart: ParsedCart, code: string): CartLine | null {
+  const match = code ? cart.lines.find((line) => line.code === code) : undefined;
+  return match ?? cart.lines[cart.lines.length - 1] ?? null;
+}
+
+export function describeAdded(
+  cart: ParsedCart,
+  form: { title: string; code: string; quantity: number },
+  cartHref: string,
+): CartAddedDetail {
+  const line = addedLine(cart, form.code);
+  return {
+    status: "added",
+    title: form.title || line?.name || "Item",
+    options: line?.options ?? [],
+    quantity: form.quantity,
+    image: line?.image ?? null,
+    count: cart.count,
+    cartHref,
+  };
+}
+
+function announce(env: CartEnv, detail: CartAddedDetail): void {
+  (env.win as JsonpHost).__totPendingCartAdded = detail;
+  env.win.dispatchEvent(new CustomEvent(CART_ADDED_EVENT, { detail }));
+}
+
+/** The confirmation raised before its dialog was ready, handed over once. */
+export function takePendingCartAdded(win: Window): CartAddedDetail | null {
+  const host = win as JsonpHost;
+  const detail = host.__totPendingCartAdded as CartAddedDetail | undefined;
+  delete host.__totPendingCartAdded;
+  return detail ?? null;
+}
+
+/**
+ * Add `form`'s line without leaving the page. Resolves false when nothing was sent
+ * to the provider, so the caller hands the form to the native submit; true once the
+ * provider was asked, whatever it answered.
+ */
+export async function addFromForm(
+  form: HTMLFormElement,
+  config: CartStateConfig,
+  env: CartEnv,
+): Promise<boolean> {
+  const cartOrigin = new URL(config.cartUrl).origin;
+  const data = new FormData(form);
+  let location: string;
+  try {
+    const res = await env.fetch(form.action, {
+      method: "POST",
+      body: data,
+      headers: { accept: "application/json" },
+      credentials: "same-origin",
+    });
+    if (!res.ok) return false;
+    const next = record(await res.json())?.location;
+    if (typeof next !== "string" || new URL(next).origin !== cartOrigin) return false;
+    location = next;
+  } catch {
+    return false;
+  }
+  const key = storedCountKey(config.cookiePath);
+  const quantity = wholeNumber(submittedField(data, "quantity")) || 1;
+  try {
+    const cart = parseCart(await loadCartJsonp(location, cartOrigin, env));
+    if (!cart || cart.errors.length > 0) {
+      announce(env, { status: "error", cartHref: config.cartUrl });
+      return true;
+    }
+    writeStoredCount(env.storage, key, cart.count);
+    renderCartCount(env.doc, cart.count);
+    announce(
+      env,
+      describeAdded(
+        cart,
+        { title: form.dataset.productTitle ?? "", code: submittedField(data, "code"), quantity },
+        cartHrefFor(config, cart.sessionId),
+      ),
+    );
+  } catch {
+    announce(env, { status: "error", cartHref: config.cartUrl });
+  }
+  return true;
+}
+
+/**
+ * Boot from the `[data-cart-state]` element the layout renders with this store's
+ * cart URL, session route and cookie path. No element, no cart: nothing runs.
+ */
+export function bootCartStateFromDom(win: Window): void {
+  const el = win.document.querySelector<HTMLElement>("[data-cart-state]");
+  const { cartUrl, sessionHref, cookiePath } = el?.dataset ?? {};
+  if (!cartUrl || !sessionHref || !cookiePath) return;
+  let storage: Storage | null = null;
+  try {
+    storage = win.localStorage;
+  } catch {
+    storage = null;
+  }
+  bootCartState(
+    { cartUrl, sessionHref, cookiePath },
+    { doc: win.document, win, fetch: win.fetch.bind(win), storage },
+  );
+}
+
+/**
+ * Wire the page: show the last known count at once, refresh it from the cart when
+ * it is above zero, keep it current across tabs and back-forward restores, and take
+ * over released add-to-cart submits.
+ */
+export function bootCartState(config: CartStateConfig, env: CartEnv): () => void {
+  const key = storedCountKey(config.cookiePath);
+  const known = () => readStoredCount(env.storage, key);
+  renderCartCount(env.doc, known());
+
+  async function refresh(): Promise<void> {
+    if (known() === 0) return;
+    const read = await readCart(config, env);
+    if (read.status !== "cart") return;
+    writeStoredCount(env.storage, key, read.cart.count);
+    renderCartCount(env.doc, read.cart.count);
+  }
+  void refresh();
+
+  const onStorage = (event: StorageEvent) => {
+    if (event.key === key) renderCartCount(env.doc, known());
+  };
+  const onPageShow = (event: PageTransitionEvent) => {
+    if (event.persisted) void refresh();
+  };
+  const onVisible = () => {
+    if (env.doc.visibilityState === "visible") void refresh();
+  };
+  // The checkout loader releases a managed form by setting `cartSession` and
+  // submitting it again; that second submit is the one taken here. Registered on the
+  // document, ahead of the loader's window listener, so a prevented event ends its flow.
+  const onSubmit = (event: Event) => {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement) || !form.matches(MANAGED_CART_FORM)) return;
+    if (form.dataset.cartSession !== "1" || form.dataset.cartNative === "1") return;
+    event.preventDefault();
+    if (form.getAttribute("aria-busy") === "true") return;
+    form.setAttribute("aria-busy", "true");
+    void addFromForm(form, config, env).then((handled) => {
+      form.removeAttribute("aria-busy");
+      if (handled) return;
+      // Nothing reached the provider: the native submit, which opens the cart page.
+      form.dataset.cartNative = "1";
+      try {
+        if (typeof form.requestSubmit === "function") form.requestSubmit();
+        else form.submit();
+      } finally {
+        delete form.dataset.cartNative;
+      }
+    });
+  };
+  env.win.addEventListener("storage", onStorage);
+  env.win.addEventListener("pageshow", onPageShow);
+  env.doc.addEventListener("visibilitychange", onVisible);
+  env.doc.addEventListener("submit", onSubmit);
+  return () => {
+    env.win.removeEventListener("storage", onStorage);
+    env.win.removeEventListener("pageshow", onPageShow);
+    env.doc.removeEventListener("visibilitychange", onVisible);
+    env.doc.removeEventListener("submit", onSubmit);
+  };
+}

package/apps/storefront/src/lib/content/shared/rawChrome.ts

@@ -301,6 +301,12 @@ function renderSearchForm(search: ChromeSearch, placement: "row" | "menu" | "pho
   );
 }
 
+/**
+ * The header cart badge: hidden at zero, a polite live region.
+ * `lib/checkout/shared/cartState.ts` fills it from the managed cart.
+ */
+const CART_COUNT_BADGE = `<span class="count" aria-live="polite" hidden>0</span>`;
+
 /**
  * Labelled header action links, in authored order. A `kind: "cart"` link carries
  * the `cart` class, so bindManagedCartAnchors (lib/content/chrome/managedCart.ts) binds it
@@ -320,7 +326,7 @@ function renderActionLinks(links: ChromeHeaderActionLink[]): string {
         index: i,
       });
       const cls = kind === "cart" ? "header-action cart" : "header-action";
-      const count = kind === "cart" ? `<span class="count">0</span>` : "";
+      const count = kind === "cart" ? CART_COUNT_BADGE : "";
       return (
         `<a class="${cls}" data-kind="${kind}" href="${esc(l.href)}"${relFor(l)}${stamp}>` +
         `${icon}<span class="header-action__label">${esc(l.label)}</span>${count}</a>`
@@ -348,7 +354,7 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
     ? `<a href="${esc(header.accountHref)}" aria-label="Account">${ICON_ACCOUNT}</a>`
     : "";
   const cart = !actionLinks && header.cartHref
-    ? `<a class="cart" href="${esc(header.cartHref)}" aria-label="Cart">${ICON_CART}<span class="count">0</span></a>`
+    ? `<a class="cart" href="${esc(header.cartHref)}" aria-label="Cart">${ICON_CART}${CART_COUNT_BADGE}</a>`
     : "";
   const compact = variant === "compact-centered";
   // "minimal" (e.g. checkout/policy pages): brand + a reduced action set only —

package/apps/storefront/src/pages/_sitemap.ts

@@ -169,9 +169,18 @@ export async function sitemapIndexResponse(context: APIContext): Promise<Respons
   return new Response(renderSitemapIndexV1(context.locals.canonicalBase, children), { headers: XML_HEADERS });
 }
 
+/**
+ * The child path a request names: the last segment of the URL path. Read from the URL, never from
+ * `context.params`: a path-routed request (`/<domain>/sitemap-pages-1.xml`) reaches this endpoint
+ * through the middleware's rewrite, which leaves the catch-all's params on the context.
+ */
+export function sitemapChildPathOf(context: APIContext): string {
+  return `/${context.url.pathname.split("/").pop() ?? ""}`;
+}
+
 /** `/sitemap-<group>-<page>.xml`: one child's `<urlset>`, or 404 when the index names no such child. */
-export async function sitemapChildResponse(context: APIContext, childPath: string): Promise<Response> {
-  const named = parseSitemapChildPathV1(childPath);
+export async function sitemapChildResponse(context: APIContext): Promise<Response> {
+  const named = parseSitemapChildPathV1(sitemapChildPathOf(context));
   if (!named) return new Response("Not found", { status: 404, headers: { "content-type": "text/plain; charset=utf-8" } });
   const children = await tenantSitemapChildren(context.locals);
   const child = children.find((c) => c.group === named.group && c.page === named.page);

package/apps/storefront/src/pages/sitemap-[child].xml.ts

@@ -6,5 +6,5 @@ import type { APIContext } from "astro";
 import { sitemapChildResponse } from "./_sitemap.js";
 
 export function GET(context: APIContext): Promise<Response> {
-  return sitemapChildResponse(context, `/sitemap-${String(context.params.child ?? "")}.xml`);
+  return sitemapChildResponse(context);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.7.5",
+  "version": "4.7.7",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/cli/src/publication-spaces.mjs

@@ -17,6 +17,7 @@
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { parseSitemapChildPathV1 } from "./sitemap-index.mjs";
 
 /** Where `tot clone` puts each mounted space, relative to the root checkout: `spaces/<spaceId>/`. */
 export const SPACES_DIR = "spaces";
@@ -26,7 +27,9 @@ export const TOPOLOGY_VERSION = 1;
 
 /**
  * Platform-owned paths no space serves (packages/public-runtime PUBLICATION_SPACE_RESERVED_MOUNTS;
- * the ownership parity test holds the two equal).
+ * the ownership parity test holds the two equal). Child sitemaps (`/sitemap-<group>-<page>.xml`) are
+ * platform-owned too, recognized by `parseSitemapChildPathV1` (a byte-identical copy of
+ * packages/public-runtime/src/sitemap-index.mjs, pinned by test/sitemap-index-copy.test.mjs).
  */
 export const PLATFORM_PATHS = Object.freeze([
   "/.well-known", "/__evidence", "/__preview", "/_a", "/_astro", "/_style-guide", "/admin", "/api",
@@ -167,7 +170,9 @@ export function owningSpace(topology, urlPath) {
   const path = normalizeRequestPath(urlPath);
   if (path === null) return null;
   const folded = path.toLowerCase();
-  if (PLATFORM_PATHS.some((reserved) => mountMatchesPath(reserved, folded))) return { space: null, via: "platform" };
+  if (PLATFORM_PATHS.some((reserved) => mountMatchesPath(reserved, folded)) || parseSitemapChildPathV1(folded) !== null) {
+    return { space: null, via: "platform" };
+  }
   /** @type {{ space: TopologySpace, via: "mount"|"alias", mount: string } | null} */
   let best = null;
   for (const space of topology.spaces) {

package/packages/public-runtime/src/sitemap-index.mjs

@@ -44,8 +44,9 @@ export function sitemapChildPathV1(group, page) {
 export function parseSitemapChildPathV1(path) {
   if (typeof path !== "string") return null;
   const match = CHILD_PATH.exec(path);
-  if (!match || !SITEMAP_GROUPS_V1.includes(match[1])) return null;
-  return { group: match[1], page: Number(match[2]) };
+  const group = match?.[1];
+  if (!match || group === undefined || !SITEMAP_GROUPS_V1.includes(group)) return null;
+  return { group, page: Number(match[2]) };
 }
 
 /** True for `/sitemap.xml` and for every well-formed child sitemap path. @param {string} path */
@@ -139,7 +140,7 @@ export function isSitemapIndexXmlV1(xml) {
  */
 export function sitemapIndexLocsV1(xml) {
   if (!isSitemapIndexXmlV1(xml)) return [];
-  return [...xml.matchAll(/<sitemap>\s*<loc>([^<]*)<\/loc>/g)].map((match) => match[1].trim());
+  return [...xml.matchAll(/<sitemap>\s*<loc>([^<]*)<\/loc>/g)].map((match) => (match[1] ?? "").trim());
 }
 
 /**