@tokenoftrust/storefront-runner 2.5.3 → 2.5.5

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

@@ -141,11 +141,11 @@ body { overflow-x: clip; }
 .header-search svg { width: 20px; height: 20px; stroke: var(--color-primary); fill: none; stroke-width: 2; }
 
 .header-actions { display: flex; align-items: center; gap: 16px; }
-.header-actions a { display: inline-flex; align-items: center; color: var(--color-text); }
-.header-actions a:hover { color: var(--color-primary); }
-.header-actions svg { width: 24px; height: 24px; stroke: currentColor; fill: none; stroke-width: 1.8; }
-.header-actions .cart { position: relative; }
-.header-actions .cart .count {
+.header-actions a, .nav-mobile-actions a { display: inline-flex; align-items: center; color: var(--color-text); }
+.header-actions a:hover, .nav-mobile-actions a:hover { color: var(--color-primary); }
+.header-actions svg, .nav-mobile-actions svg { width: 24px; height: 24px; stroke: currentColor; fill: none; stroke-width: 1.8; }
+.header-actions .cart, .nav-mobile-actions .cart { position: relative; }
+.header-actions .cart .count, .nav-mobile-actions .cart .count {
   position: absolute; top: -6px; right: -8px; background: var(--color-primary); color: var(--color-primary-contrast);
   font-size: .62rem; font-weight: 700; min-width: 16px; height: 16px; border-radius: var(--radius-full);
   display: grid; place-items: center; padding: 0 4px;
@@ -158,13 +158,13 @@ body { overflow-x: clip; }
 .header-cta--primary {
   background: var(--color-accent); color: var(--color-accent-contrast);
 }
-.header-actions .header-cta--primary:hover { color: var(--color-accent-contrast); transform: translateY(-1px); }
+.header-actions .header-cta--primary:hover, .nav-mobile-actions .header-cta--primary:hover { color: var(--color-accent-contrast); transform: translateY(-1px); }
 .header-cta--secondary, .header-cta--ghost { border: 1px solid currentColor; }
-.header-actions .header-cta--secondary:hover, .header-actions .header-cta--ghost:hover { opacity: .8; }
+.header-actions .header-cta--secondary:hover, .nav-mobile-actions .header-cta--secondary:hover, .header-actions .header-cta--ghost:hover, .nav-mobile-actions .header-cta--ghost:hover { opacity: .8; }
 /* Labelled action links (chrome header.actionLinks): text with an optional leading icon. */
 .header-action { gap: 6px; font-size: .875rem; font-weight: 600; white-space: nowrap; }
-.header-actions .header-action svg { width: 20px; height: 20px; }
-.header-actions .header-action.cart .count { position: static; margin-left: 2px; }
+.header-actions .header-action svg, .nav-mobile-actions .header-action svg { width: 20px; height: 20px; }
+.header-actions .header-action.cart .count, .nav-mobile-actions .header-action.cart .count { position: static; margin-left: 2px; }
 /* A search form with a visible text submit (header.search.buttonLabel). */
 .header-search--labelled { display: flex; }
 .header-search--labelled input { padding-right: 18px; border-radius: var(--radius-full) 0 0 var(--radius-full); }
@@ -197,6 +197,7 @@ body { overflow-x: clip; }
 
 /* --- Primary nav + mega-menu ---------------------------------------------- */
 .primary-nav { flex: 1; }
+.nav-submenu-toggle, .nav-close, .nav-mobile-actions { display: none; }
 .primary-nav > ul { display: flex; flex-wrap: wrap; align-items: center; gap: clamp(10px, 1.6vw, 22px); }
 /* Flat primary links */
 .primary-nav a { font-weight: 600; font-size: .92rem; color: var(--color-text); padding: 6px 2px; border-bottom: 2px solid transparent; transition: color .15s, border-color .15s; }
@@ -478,8 +479,18 @@ a.article-card__tag:hover { text-decoration: underline; }
      by the hamburger. Gating the fixed/off-screen positioning behind .js-nav
      means a no-JS visitor always sees the nav in place — JS only changes its
      PRESENTATION, never its reachability. */
-  .js-nav .primary-nav { position: fixed; inset: 0 0 0 auto; width: min(84vw, 340px); background: var(--color-surface); box-shadow: var(--shadow-lg); transform: translateX(100%); transition: transform .25s ease; padding: 78px 20px 24px; overflow-y: auto; z-index: 120; }
+  .js-nav .primary-nav { position: fixed; inset: 0; width: 100vw; height: 100dvh; box-sizing: border-box; visibility: hidden; background: var(--color-surface); box-shadow: var(--shadow-lg); transform: translateX(100%); transition: transform .25s ease; padding: 78px 20px 24px; overflow-y: auto; z-index: 120; }
   .js-nav .primary-nav.open { transform: none; }
+  .js-nav .primary-nav.open { visibility: visible; }
+  .js-nav .primary-nav .nav-close { display: block; position: absolute; top: 16px; right: 20px; width: 44px; height: 44px; border: 0; background: transparent; color: inherit; font-size: 2rem; }
+  .js-nav .primary-nav .nav-item { display: grid; grid-template-columns: minmax(0, 1fr) 44px; align-items: center; }
+  .js-nav .primary-nav .nav-item > a { grid-column: 1; }
+  .js-nav .primary-nav .nav-item > a .caret { display: none; }
+  .js-nav .primary-nav .nav-submenu-toggle { display: grid; place-items: center; min-height: 44px; border: 0; background: transparent; color: inherit; }
+  .js-nav .primary-nav .nav-submenu-toggle[aria-expanded="true"] span { transform: rotate(180deg); }
+  .js-nav .primary-nav .mega { grid-column: 1 / -1; }
+  .js-nav .primary-nav .mega[hidden] { display: none; }
+  .js-nav .primary-nav .nav-mobile-actions { display: flex; flex-wrap: wrap; align-items: center; gap: 16px; padding-top: 24px; }
   /* header.mobile — menu button side, brand alignment, search placement. */
   .js-nav .site-header[data-mobile-menu="left"] .primary-nav { inset: 0 auto 0 0; transform: translateX(-100%); }
   .js-nav .site-header[data-mobile-menu="left"] .primary-nav.open { transform: none; }

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

@@ -235,7 +235,7 @@ const currentPath = Astro.url.pathname;
         }
         {
           !minimal && savedItemsHref && (
-            <a
+            <a data-mobile-menu-action
               href={withBase(basePath, savedItemsHref)}
               aria-label="Saved items"
               class="relative grid h-9 w-9 shrink-0 place-items-center rounded-full text-text transition-colors hover:text-accent-ink"
@@ -265,7 +265,7 @@ const currentPath = Astro.url.pathname;
                   index: i,
                 });
                 return (
-                  <a
+                  <a data-mobile-menu-action
                     href={withBase(basePath, cta.href)}
                     class={ctaClass(cta.variant)}
                     {...{ [idAttr.name]: idAttr.value }}
@@ -280,7 +280,7 @@ const currentPath = Astro.url.pathname;
         }
         {
           authLink && (
-            <a
+            <a data-mobile-menu-action
               href={authLink.href}
               class="inline-flex shrink-0 items-center rounded-full border border-current px-4 py-2 font-display text-sm font-medium transition-opacity hover:opacity-80"
             >
@@ -290,7 +290,7 @@ const currentPath = Astro.url.pathname;
         }
         {
           accountHref && (
-            <a
+            <a data-mobile-menu-action
               href={withBase(basePath, accountHref)}
               aria-label="Account"
               class="grid h-9 w-9 place-items-center rounded-full text-text transition-colors hover:text-accent-ink"
@@ -304,7 +304,7 @@ const currentPath = Astro.url.pathname;
         }
         {
           cartHref && (
-            <a
+            <a data-mobile-menu-action
               href={withBase(basePath, cartHref)}
               aria-label={`Cart, ${cartCount} ${cartCount === 1 ? "item" : "items"}`}
               class="relative grid h-9 w-9 place-items-center rounded-full text-text transition-colors hover:text-accent-ink"

package/apps/storefront/src/components/content/storefront/islands/MobileNav.tsx

@@ -60,11 +60,13 @@ function prefersReducedMotion(): boolean {
 
 export default function MobileNav({ nav, announcement, currentPath }: Props) {
   const [open, setOpen] = useState(false);
+  const [expanded, setExpanded] = useState<Set<number>>(new Set());
   const buttonRef = useRef<HTMLButtonElement>(null);
   const panelRef = useRef<HTMLDivElement>(null);
+  const actionsRef = useRef<HTMLDivElement>(null);
   const reduced = prefersReducedMotion();
 
-  const close = useCallback(() => setOpen(false), []);
+  const close = useCallback(() => { setOpen(false); setExpanded(new Set()); }, []);
 
   // The no-JS fallback nav is only needed when JS never runs. Since this
   // component mounting IS JS running, hide it in favor of the drawer above —
@@ -77,6 +79,29 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
       });
   }, []);
 
+  // Desktop navigation takes over at the same breakpoint as md:hidden.
+  useEffect(() => {
+    const desktop = window.matchMedia("(min-width: 768px)");
+    const onViewportChange = () => { if (desktop.matches) close(); };
+    desktop.addEventListener("change", onViewportChange);
+    onViewportChange();
+    return () => desktop.removeEventListener("change", onViewportChange);
+  }, [close]);
+
+  // Keep each governed action's DOM identity unique across header and drawer.
+  useEffect(() => {
+    if (!open || !actionsRef.current) return;
+    const mount = actionsRef.current;
+    const header = buttonRef.current?.closest("header");
+    const slots = Array.from(header?.querySelectorAll<HTMLElement>("[data-mobile-menu-action]") ?? []).map((node) => {
+      const marker = document.createComment("header-action");
+      node.parentNode!.insertBefore(marker, node);
+      mount.appendChild(node);
+      return { node, marker };
+    });
+    return () => slots.forEach(({ node, marker }) => marker.parentNode?.replaceChild(node, marker));
+  }, [open]);
+
   // Body scroll lock while open.
   useEffect(() => {
     if (!open) return;
@@ -100,7 +125,7 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
       return () => window.cancelAnimationFrame(id);
     }
     // On close, return focus to the hamburger.
-    buttonRef.current?.focus();
+    if (!window.matchMedia("(min-width: 768px)").matches) buttonRef.current?.focus();
     return undefined;
   }, [open]);
 
@@ -188,7 +213,7 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
             role="dialog"
             aria-modal="true"
             aria-label="Site menu"
-            class="absolute inset-y-0 right-0 flex w-[85vw] max-w-sm flex-col overflow-y-auto bg-surface text-text shadow-xl"
+            class="absolute inset-0 flex w-full flex-col overflow-y-auto bg-surface text-text shadow-xl"
             style={
               reduced
                 ? undefined
@@ -233,7 +258,7 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
                 {nav.map((item, i) => (
                   <li key={item.href}>
                     {item.children && item.children.length > 0 ? (
-                      <div class="px-3 py-2">
+                      <div class="grid grid-cols-[minmax(0,1fr)_44px] items-center px-3 py-2">
                         <a
                           href={item.href}
                           aria-current={
@@ -251,7 +276,21 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
                         >
                           {item.label}
                         </a>
-                        <ul class="mt-1 space-y-0.5 border-l border-border pl-3">
+                        <button
+                          type="button"
+                          aria-label={`Toggle ${item.label} submenu`}
+                          aria-expanded={expanded.has(i)}
+                          aria-controls={`${DRAWER_ID}-submenu-${i}`}
+                          class="grid h-11 w-11 place-items-center text-text"
+                          onClick={() => setExpanded((previous) => {
+                            const next = new Set(previous);
+                            if (next.has(i)) next.delete(i); else next.add(i);
+                            return next;
+                          })}
+                        >
+                          <span aria-hidden="true">{expanded.has(i) ? "▴" : "▾"}</span>
+                        </button>
+                        <ul id={`${DRAWER_ID}-submenu-${i}`} hidden={!expanded.has(i)} class="col-span-2 mt-1 space-y-0.5 border-l border-border pl-3">
                           {item.children.map((child, ci) => (
                             <li key={child.href}>
                               <a
@@ -297,6 +336,7 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
                   </li>
                 ))}
               </ul>
+              <div ref={actionsRef} class="mt-6 flex flex-wrap items-center gap-4 border-t border-border px-3 pt-4" />
             </nav>
           </div>
         </div>

package/apps/storefront/src/lib/catalog/d1/catalog.ts

@@ -195,7 +195,10 @@ export async function listAllActiveProducts(db: Queryable): Promise<CatalogProdu
   return rows.map((r) => JSON.parse(r.data) as CatalogProduct);
 }
 
-function sortClause(sort?: ListProductsQuery["sort"]): string {
+function sortClause(sort?: ListProductsQuery["sort"], collection = false): string {
+  if (collection && (!sort || sort === "featured")) {
+    return "ORDER BY COALESCE(cm.collection_position, 2147483647), p.position ASC, p.handle ASC";
+  }
   switch (sort) {
     case "price-asc":
       return "ORDER BY p.price_min ASC, p.title COLLATE NOCASE ASC";
@@ -378,10 +381,16 @@ export async function listProducts(
 
   // Pool: active products, optionally scoped to a collection.
   const poolJoin = query.collection
-    ? "JOIN product_collections pc ON pc.handle = p.handle AND pc.collection = ?"
+    ? `LEFT JOIN (SELECT j.value AS handle, MIN(CAST(j.key AS INTEGER)) AS collection_position
+        FROM collections c, json_each(c.data, '$.product_handles') j
+        WHERE c.handle = ? GROUP BY j.value) cm ON cm.handle = p.handle`
     : "";
   const poolParams: unknown[] = query.collection ? [query.collection] : [];
-  const poolSql = `FROM products p ${poolJoin} WHERE p.status = 'active' AND COALESCE(json_extract(p.data, '$.visibility'), 'public') = 'public'`;
+  const membership = query.collection
+    ? " AND (cm.handle IS NOT NULL OR EXISTS (SELECT 1 FROM product_collections pc WHERE pc.handle = p.handle AND pc.collection = ?))"
+    : "";
+  if (query.collection) poolParams.push(query.collection);
+  const poolSql = `FROM products p ${poolJoin} WHERE p.status = 'active' AND COALESCE(json_extract(p.data, '$.visibility'), 'public') = 'public'${membership}`;
 
   // Result filters layered on the pool.
   const clauses = buildFilterClauses(query);
@@ -398,7 +407,7 @@ export async function listProducts(
   const offset = (page - 1) * pageSize;
 
   const rows = await db.all<{ data: string }>(
-    `SELECT p.data AS data ${poolSql}${filterClause} ${sortClause(query.sort)} LIMIT ? OFFSET ?`,
+    `SELECT p.data AS data ${poolSql}${filterClause} ${sortClause(query.sort, !!query.collection)} LIMIT ? OFFSET ?`,
     ...resultParams, pageSize, offset,
   );
   const products = rows.map((r) => JSON.parse(r.data) as CatalogProduct);

package/apps/storefront/src/lib/catalog/tot/ToTClient.ts

@@ -23,7 +23,7 @@ import type {
   TenantConfig,
 } from "@tot/public-runtime";
 import { isPublicCatalogProduct } from "@tot/public-runtime";
-import { buildFacets, applyQuery, paginate } from "./query.js";
+import { buildFacets, applyQuery, paginate, collectionProducts } from "./query.js";
 import { D1ToTClient } from "./d1Client.js";
 import { fromD1, type D1Like } from "../d1/catalog.js";
 import { buildSearchIndex, type SearchIndex } from "../search/index.js";
@@ -67,11 +67,10 @@ export class FixtureToTClient implements ToTClient {
     let pool = active;
     if (query.collection) {
       const col = this.collections.find((c) => c.handle === query.collection);
-      const handles = new Set(col?.product_handles ?? []);
-      pool = active.filter((p) => handles.has(p.handle));
+      pool = col ? collectionProducts(active, col) : [];
     }
     const facets: Facet[] = buildFacets(pool, query);
-    const filtered = applyQuery(pool, query);
+    const filtered = applyQuery(pool, query, !!query.collection);
     const { items, page, pageSize, total } = paginate(filtered, query);
     return { products: items, page, pageSize, total, facets };
   }

package/apps/storefront/src/lib/catalog/tot/query.ts

@@ -197,12 +197,35 @@ function applyFilters(
   return out;
 }
 
+/** Declared members first (first duplicate wins), then product-side members in catalog order. */
+export function collectionProducts(pool: CatalogProduct[], collection: CatalogCollection): CatalogProduct[] {
+  const byHandle = new Map(pool.map((p) => [p.handle, p]));
+  const seen = new Set<string>();
+  const members: CatalogProduct[] = [];
+  for (const handle of collection.product_handles) {
+    const product = byHandle.get(handle);
+    if (product && !seen.has(handle)) {
+      members.push(product);
+      seen.add(handle);
+    }
+  }
+  for (const product of pool) {
+    if (!seen.has(product.handle) && product.collections.includes(collection.handle)) {
+      members.push(product);
+      seen.add(product.handle);
+    }
+  }
+  return members;
+}
+
 /** Apply filters + sort (NOT pagination). */
 export function applyQuery(
   pool: CatalogProduct[],
   query: ListProductsQuery,
+  manualOrder = false,
 ): CatalogProduct[] {
   const out = applyFilters(pool, query);
+  if (manualOrder && (!query.sort || query.sort === "featured")) return out;
   return sortProducts(out, query.sort, pool);
 }
 

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

@@ -0,0 +1,197 @@
+/**
+ * POST /api/commerce/checkout-handoff — the checkout-correlation MINT seam
+ * (ext-commerce-10).
+ *
+ * The shopper's analytics consent is a CLIENT-side decision (CMP / native banner),
+ * but the correlation token is minted under the SERVER-only signing secret. So at the
+ * handoff the client posts its LIVE consent snapshot and the server mints the token,
+ * returning ONLY the opaque passthrough cart field to attach to the managed-cart form.
+ * The signing secret never leaves the server; the token carries no PII and no secret.
+ *
+ * Server-owned by construction:
+ *   - The tenant and the {@link IntegrationEnvironment} stage come from `context.locals`
+ *     (the renderer-owned `BrowserEnvironment`), NEVER from the request body — a client
+ *     cannot mint a cross-tenant or cross-stage token.
+ *   - The consent snapshot is parsed FAIL-CLOSED (`parseConsentSnapshot`): an absent,
+ *     forged, or tampered snapshot collapses to default-deny → unattributed.
+ *   - No store on this tenant, consent withheld, or no signing key → an explicit
+ *     unattributed response; the handoff proceeds, checkout is never blocked.
+ */
+import type { APIContext } from "astro";
+import {
+  enforceCartSubmission,
+  foxyCartRedirectUrl,
+  parseConsentSnapshot,
+  defaultConsentSnapshot,
+  buildVariantCartPayload,
+  commerceTenantId,
+  MAX_CART_QUANTITY,
+  type CartDenialCode,
+  type CatalogProduct,
+  type TenantConfig,
+  type ResolvedManagedCheckout,
+} from "@tot/public-runtime";
+import { resolveCheckoutHandoffCorrelation } from "@/lib/checkout/commerce/checkoutHandoffCorrelation";
+import { resolveCartSigning, shopperCartDenialMessage } from "@/lib/checkout/shared/checkoutCommerce";
+import { readEnv } from "@/lib/publication/shared/runtimeEnv";
+
+export type SampleProductReader = (tenant: TenantConfig, handle: string, commerce: ResolvedManagedCheckout) => Promise<CatalogProduct | null>;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+interface HandoffBody {
+  /** The shopper's serialized consent snapshot (the `__TOT_INTEGRATION_CONSENT__` global). */
+  consent?: unknown;
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (ch) => {
+    if (ch === "&") return "&amp;";
+    if (ch === "<") return "&lt;";
+    if (ch === ">") return "&gt;";
+    if (ch === '"') return "&quot;";
+    return "&#39;";
+  });
+}
+
+function cartDenial(code: CartDenialCode, message: string, status: number): Response {
+  const body =
+    `<!doctype html><html><body><p data-cart-denial="${code}" data-payment-authorized="false">${escapeHtml(message)}</p></body></html>`;
+  return new Response(body, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+      "x-tot-payment-authorized": "false",
+    },
+  });
+}
+
+function isCartForm(request: Request): boolean {
+  const type = request.headers.get("content-type") ?? "";
+  return (
+    type.includes("application/x-www-form-urlencoded") ||
+    type.includes("multipart/form-data")
+  );
+}
+
+/** Native cart POST. Browser preflight is not consulted. Payment is never authorized. */
+async function cartFormPost(context: APIContext, readSampleProduct?: SampleProductReader): Promise<Response> {
+  const { tenant, commerce } = context.locals;
+  if (!commerce) {
+    return cartDenial(
+      "signing-unavailable",
+      "Checkout is unavailable because this store has no cart configured.",
+      409,
+    );
+  }
+  const signing = await resolveCartSigning(commerce);
+  if (!signing.enabled) {
+    return cartDenial(
+      "signing-unavailable",
+      shopperCartDenialMessage("signing-unavailable", signing.operatorError ?? ""),
+      503,
+    );
+  }
+  const form = await context.request.formData();
+  const entries: Array<[string, string]> = [];
+  for (const [name, value] of form.entries()) {
+    if (typeof value !== "string") return cartDenial("signature", "Invalid cart.", 422);
+    entries.push([name, value]);
+  }
+  if (form.has("sample_product") || form.has("sample_variant")) {
+    const sampleTenant = await readEnv("COMMERCE_SAMPLE_TENANT_ID");
+    if (
+      !sampleTenant || sampleTenant !== commerceTenantId(tenant) ||
+      await readEnv("COMMERCE_DEMO_CHECKOUT_TIER") !== "test" || commerce.mode !== "signed"
+    ) return cartDenial("tenant", "Invalid cart.", 422);
+    const allowed = new Set(["sample_product", "sample_variant", "quantity"]);
+    if (entries.length !== 3 || entries.some(([name]) => !allowed.has(name)) ||
+      new Set(entries.map(([name]) => name)).size !== 3) {
+      return cartDenial("signature", "Invalid cart.", 422);
+    }
+    const quantity = form.get("quantity") as string;
+    if (!/^[1-9][0-9]*$/.test(quantity) || !Number.isSafeInteger(Number(quantity)) || Number(quantity) > MAX_CART_QUANTITY) {
+      return cartDenial("quantity", "Invalid quantity.", 422);
+    }
+    const product = await readSampleProduct?.(tenant, form.get("sample_product") as string, commerce) ?? null;
+    const variant = product?.variants.find((v) => v.id === form.get("sample_variant"));
+    if (!product || product.status !== "active" || product.visibility === "hidden" || product.visibility === "unlisted" ||
+      !variant || !variant.inventory.available || product.tenant_id !== tenant.tot_data_scope ||
+      variant.tenant_id !== tenant.tot_data_scope) {
+      return cartDenial("signature", "Product is unavailable.", 422);
+    }
+    const payload = await buildVariantCartPayload(product, variant, {
+      mode: "signed", secret: signing.secret, tenantId: commerceTenantId(tenant),
+    });
+    entries.splice(0, entries.length, ...payload.hidden.map((f): [string, string] => [f.name, f.value]), [payload.quantityName, quantity]);
+  }
+  const result = await enforceCartSubmission({
+    entries,
+    mode: commerce.mode,
+    secret: signing.secret,
+    trustedTenantId: commerceTenantId(tenant),
+  });
+  if (!result.ok) {
+    const status = result.code === "signing-unavailable" ? 503 : 422;
+    return cartDenial(result.code, shopperCartDenialMessage(result.code, result.message), status);
+  }
+  return new Response(null, {
+    status: 303,
+    headers: {
+      location: foxyCartRedirectUrl(commerce.cartUrl, result.fields),
+      "cache-control": "no-store",
+      "x-tot-payment-authorized": "false",
+    },
+  });
+}
+
+export async function checkoutHandoffPost(context: APIContext, readSampleProduct?: SampleProductReader): Promise<Response> {
+  if (isCartForm(context.request)) return cartFormPost(context, readSampleProduct);
+  const { tenant, browserEnvironment, commerce } = context.locals;
+
+  // No managed checkout on this tenant → nothing to attribute.
+  if (!commerce) {
+    return json({ attributed: false, reason: "no-store" });
+  }
+
+  let body: HandoffBody;
+  try {
+    body = (await context.request.json()) as HandoffBody;
+  } catch {
+    body = {};
+  }
+
+  // Fail-closed: an absent/forged/tampered snapshot is default-deny (essential only).
+  const consent = parseConsentSnapshot(body.consent) ?? defaultConsentSnapshot();
+
+  const result = await resolveCheckoutHandoffCorrelation({
+    tenant: tenant.tenant_id,
+    // Env-consistency: the request's own resolved stage, never a client value.
+    environment: browserEnvironment.environment,
+    consent,
+    // Opaque per-handoff logical id the order join threads back to.
+    eventId: crypto.randomUUID(),
+  });
+
+  if (result.attributed) {
+    // Return ONLY the opaque passthrough field; the signing secret never leaves here.
+    return json({ attributed: true, cartField: result.cartField });
+  }
+  return json({ attributed: false, reason: result.reason });
+}
+
+export async function GET(): Promise<Response> {
+  return json({ error: "method_not_allowed" }, 405);
+}
+
+/** The renderer has no hosted preview catalog authority. */
+export const POST = (context: APIContext): Promise<Response> => checkoutHandoffPost(context);

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

@@ -265,8 +265,10 @@ function renderNavItem(item: ChromeNavItem, index: number, currentPath?: string)
       return `<div class="mega__col">${heading}${links}</div>`;
     })
     .join("");
-  const mega = `<div class="mega${wide}"><div class="mega__cols">${cols}</div></div>`;
-  return `<li class="nav-item">${link}${mega}</li>`;
+  const panelId = `nav-submenu-${index}`;
+  const toggle = `<button type="button" class="nav-submenu-toggle" aria-label="${esc(`Toggle ${item.label} submenu`)}" aria-expanded="false" aria-controls="${panelId}"><span aria-hidden="true">▾</span></button>`;
+  const mega = `<div class="mega${wide}" id="${panelId}"><div class="mega__cols">${cols}</div></div>`;
+  return `<li class="nav-item">${link}${toggle}${mega}</li>`;
 }
 
 /**
@@ -383,7 +385,9 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
   const primaryNav =
     `<nav class="primary-nav" id="primaryNav" aria-label="Primary">\n` +
     menuSearch +
+    `<button type="button" class="nav-close" aria-label="Close navigation menu">×</button>` +
     `        <ul>\n          ${navItems}\n        </ul>\n` +
+    `<div class="nav-mobile-actions"></div>` +
     `      </nav>`;
   const navBar = minimal
     ? ""
@@ -396,7 +400,7 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
       `  </nav>\n`;
   const compactSearch =
     compact && header.search
-      ? `<a class="header-search-trigger" href="${esc(header.search.action ?? "/search")}" aria-label="${esc(header.search.label ?? "Search")}">${ICON_SEARCH}</a>`
+      ? `<a class="header-search-trigger" data-header-fixed-action href="${esc(header.search.action ?? "/search")}" aria-label="${esc(header.search.label ?? "Search")}">${ICON_SEARCH}</a>`
       : "";
   const mobileBottom =
     compact
@@ -656,10 +660,81 @@ export const CHROME_BEHAVIOR_JS = `(function () {
   // Mobile nav drawer
   var burger = document.getElementById('hamburger');
   var nav = document.getElementById('primaryNav');
-  if (burger && nav) burger.addEventListener('click', function () {
-    var open = nav.classList.toggle('open');
-    burger.setAttribute('aria-expanded', open ? 'true' : 'false');
-  });
+  if (burger && nav) {
+    var mobileNavQuery = window.matchMedia('(max-width: 860px)');
+    var navClose = nav.querySelector('.nav-close');
+    var previousOverflow = null;
+    var actionMount = nav.querySelector('.nav-mobile-actions');
+    var header = burger.closest('.site-header');
+    var actionNodes = header ? Array.from(header.querySelectorAll('.header-actions > a:not([data-header-fixed-action])')) : [];
+    var actionSlots = actionNodes.map(function (node) {
+      return { node: node, marker: document.createComment('header-action') };
+    });
+    var placeActions = function (inMenu) {
+      actionSlots.forEach(function (slot) {
+        if (inMenu && actionMount && !slot.marker.parentNode) {
+          slot.node.parentNode.insertBefore(slot.marker, slot.node);
+          actionMount.appendChild(slot.node);
+        } else if (!inMenu && slot.marker.parentNode) {
+          slot.marker.parentNode.replaceChild(slot.node, slot.marker);
+        }
+      });
+    };
+    var setNavOpen = function (open, returnFocus) {
+      open = open && mobileNavQuery.matches;
+      nav.classList.toggle('open', open);
+      burger.setAttribute('aria-expanded', open ? 'true' : 'false');
+      nav.inert = mobileNavQuery.matches && !open;
+      placeActions(open);
+      if (open) {
+        previousOverflow = document.body.style.overflow;
+        document.body.style.overflow = 'hidden';
+        nav.setAttribute('role', 'dialog');
+        nav.setAttribute('aria-modal', 'true');
+        if (navClose) navClose.focus();
+      } else {
+        nav.removeAttribute('role');
+        nav.removeAttribute('aria-modal');
+        if (previousOverflow !== null) document.body.style.overflow = previousOverflow;
+        previousOverflow = null;
+        if (returnFocus) burger.focus();
+      }
+    };
+    var resetMobileNav = function () {
+      setNavOpen(false, false);
+      nav.querySelectorAll('.nav-submenu-toggle').forEach(function (toggle) {
+        toggle.setAttribute('aria-expanded', 'false');
+        var panel = document.getElementById(toggle.getAttribute('aria-controls'));
+        if (panel) panel.hidden = mobileNavQuery.matches;
+      });
+    };
+    nav.querySelectorAll('.nav-submenu-toggle').forEach(function (toggle) {
+      toggle.addEventListener('click', function () {
+        var panel = document.getElementById(toggle.getAttribute('aria-controls'));
+        var expanded = toggle.getAttribute('aria-expanded') !== 'true';
+        toggle.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+        if (panel) panel.hidden = !expanded;
+      });
+    });
+    burger.addEventListener('click', function () { setNavOpen(!nav.classList.contains('open'), true); });
+    if (navClose) navClose.addEventListener('click', function () { setNavOpen(false, true); });
+    nav.addEventListener('keydown', function (event) {
+      if (!nav.classList.contains('open')) return;
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        setNavOpen(false, true);
+      }
+      if (event.key !== 'Tab') return;
+      var links = Array.from(nav.querySelectorAll('a[href], button, input, [tabindex="0"]')).filter(function (el) {
+        return !el.disabled && !el.closest('[hidden]') && el.getClientRects().length;
+      });
+      var first = links[0], last = links[links.length - 1];
+      if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last.focus(); }
+      else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first.focus(); }
+    });
+    if (mobileNavQuery.addEventListener) mobileNavQuery.addEventListener('change', resetMobileNav);
+    resetMobileNav();
+  }
 
   // Announcement bar: dismiss (remembered) + rotate messages
   var bar = document.getElementById('announceBar');

package/apps/storefront/src/lib/publication/shared/routedApiParam.ts

@@ -0,0 +1,28 @@
+import type { APIContext } from "astro";
+
+const ROUTES = {
+  "pipeline-job": { path: /^\/api\/pipeline\/jobs\/([A-Za-z0-9._:-]{1,128})\/?$/, param: "jobId" },
+  "fulfillment-order": { path: /^\/api\/admin\/fulfillment\/orders\/([A-Za-z0-9._:-]{1,128})\/?$/, param: "id" },
+  "fulfillment-address": { path: /^\/api\/admin\/fulfillment\/orders\/([A-Za-z0-9._:-]{1,128})\/address\/?$/, param: "id" },
+} as const;
+
+export type RoutedApiKind = keyof typeof ROUTES;
+
+/** Resolve an opaque resource inside the server-routed tenant, including rewritten endpoints. */
+export function routedApiParam(context: APIContext, kind: RoutedApiKind): string | undefined {
+  if (!Object.hasOwn(ROUTES, kind)) return undefined;
+  const tenant = context.locals.tenant?.appDomain;
+  const prefix = context.locals.apiBasePath;
+  if (typeof tenant !== "string" || !/^[A-Za-z0-9][A-Za-z0-9.-]{0,252}$/.test(tenant)) return undefined;
+  if (typeof prefix !== "string" || (prefix !== "" && !/^\/[A-Za-z0-9][A-Za-z0-9.-]{0,252}$/.test(prefix))) return undefined;
+  let pathname: string;
+  try { pathname = new URL(context.request.url).pathname; } catch { return undefined; }
+  if (prefix && !pathname.startsWith(`${prefix}/`)) return undefined;
+  const relative = pathname.slice(prefix.length);
+  const route = ROUTES[kind];
+  const id = route.path.exec(relative)?.[1];
+  if (!id || id === "." || id === "..") return undefined;
+  const param = context.params[route.param];
+  if (param !== undefined && param !== "" && param !== id) return undefined;
+  return id;
+}

package/apps/storefront/src/pages/api/admin/fulfillment/orders/[id]/address.ts

@@ -1,3 +1,4 @@
+import { routedApiParam } from "@/lib/publication/shared/routedApiParam";
 /**
  * Owner-only retrieval of a stored ship-to address.
  * The read runs only after the owner gate admits the caller.
@@ -24,8 +25,8 @@ export async function GET(context: APIContext): Promise<Response> {
       },
     });
   }
-  const orderId = context.params.id ?? "";
-  if (!isOpaqueId(orderId)) return fulfillmentResultResponse({ ok: false, code: "not-found" }, () => ({}));
+  const orderId = routedApiParam(context, "fulfillment-address");
+  if (!orderId || !isOpaqueId(orderId)) return fulfillmentResultResponse({ ok: false, code: "not-found" }, () => ({}));
   const opened = await openFulfillment(context);
   if (!opened.ok) return opened.response;
   return fulfillmentResultResponse(await opened.service.readAddress(opened.actor, orderId), (address) => address);

package/apps/storefront/src/pages/api/admin/fulfillment/orders/[id].ts

@@ -1,3 +1,4 @@
+import { routedApiParam } from "@/lib/publication/shared/routedApiParam";
 /**
  * Authenticated owner API for one order's fulfillment commands.
  * The response is state codes and the fulfillment view. It never returns an address.
@@ -53,8 +54,8 @@ function fail(code: string): Response {
 export async function GET(context: APIContext): Promise<Response> {
   const refused = await requireOwner(context);
   if (refused) return refused;
-  const orderId = context.params.id ?? "";
-  if (!isOpaqueId(orderId)) return fail("not-found");
+  const orderId = routedApiParam(context, "fulfillment-order");
+  if (!orderId || !isOpaqueId(orderId)) return fail("not-found");
   const opened = await openFulfillment(context);
   if (!opened.ok) return opened.response;
   return fulfillmentResultResponse(await opened.service.get(opened.actor, orderId), (view) => view);
@@ -63,8 +64,8 @@ export async function GET(context: APIContext): Promise<Response> {
 export async function POST(context: APIContext): Promise<Response> {
   const refused = await requireOwner(context);
   if (refused) return refused;
-  const orderId = context.params.id ?? "";
-  if (!isOpaqueId(orderId)) return fail("not-found");
+  const orderId = routedApiParam(context, "fulfillment-order");
+  if (!orderId || !isOpaqueId(orderId)) return fail("not-found");
   const raw = await readJsonBody(context.request);
   if (!raw.ok) return fulfillmentResultResponse(raw, () => ({}));
   const parsed = parseFulfillmentBody(raw.value);

package/apps/storefront/src/pages/api/commerce/checkout-handoff.ts

@@ -1,191 +1,2 @@
-/**
- * POST /api/commerce/checkout-handoff — the checkout-correlation MINT seam
- * (ext-commerce-10).
- *
- * The shopper's analytics consent is a CLIENT-side decision (CMP / native banner),
- * but the correlation token is minted under the SERVER-only signing secret. So at the
- * handoff the client posts its LIVE consent snapshot and the server mints the token,
- * returning ONLY the opaque passthrough cart field to attach to the managed-cart form.
- * The signing secret never leaves the server; the token carries no PII and no secret.
- *
- * Server-owned by construction:
- *   - The tenant and the {@link IntegrationEnvironment} stage come from `context.locals`
- *     (the renderer-owned `BrowserEnvironment`), NEVER from the request body — a client
- *     cannot mint a cross-tenant or cross-stage token.
- *   - The consent snapshot is parsed FAIL-CLOSED (`parseConsentSnapshot`): an absent,
- *     forged, or tampered snapshot collapses to default-deny → unattributed.
- *   - No store on this tenant, consent withheld, or no signing key → an explicit
- *     unattributed response; the handoff proceeds, checkout is never blocked.
- */
-import type { APIContext } from "astro";
-import {
-  enforceCartSubmission,
-  foxyCartRedirectUrl,
-  parseConsentSnapshot,
-  defaultConsentSnapshot,
-  buildVariantCartPayload,
-  commerceTenantId,
-  MAX_CART_QUANTITY,
-  type CartDenialCode,
-} from "@tot/public-runtime";
-import { resolveCheckoutHandoffCorrelation } from "@/lib/checkout/commerce/checkoutHandoffCorrelation";
-import { resolveCartSigning, shopperCartDenialMessage } from "@/lib/checkout/shared/checkoutCommerce";
-import { readEnv } from "@/lib/publication/shared/runtimeEnv";
-
 export const prerender = false;
-
-function json(body: unknown, status = 200): Response {
-  return new Response(JSON.stringify(body), {
-    status,
-    headers: {
-      "content-type": "application/json; charset=utf-8",
-      "cache-control": "no-store",
-    },
-  });
-}
-
-interface HandoffBody {
-  /** The shopper's serialized consent snapshot (the `__TOT_INTEGRATION_CONSENT__` global). */
-  consent?: unknown;
-}
-
-function escapeHtml(value: string): string {
-  return value.replace(/[&<>"']/g, (ch) => {
-    if (ch === "&") return "&amp;";
-    if (ch === "<") return "&lt;";
-    if (ch === ">") return "&gt;";
-    if (ch === '"') return "&quot;";
-    return "&#39;";
-  });
-}
-
-function cartDenial(code: CartDenialCode, message: string, status: number): Response {
-  const body =
-    `<!doctype html><html><body><p data-cart-denial="${code}" data-payment-authorized="false">${escapeHtml(message)}</p></body></html>`;
-  return new Response(body, {
-    status,
-    headers: {
-      "content-type": "text/html; charset=utf-8",
-      "cache-control": "no-store",
-      "x-tot-payment-authorized": "false",
-    },
-  });
-}
-
-function isCartForm(request: Request): boolean {
-  const type = request.headers.get("content-type") ?? "";
-  return (
-    type.includes("application/x-www-form-urlencoded") ||
-    type.includes("multipart/form-data")
-  );
-}
-
-/** Native cart POST. Browser preflight is not consulted. Payment is never authorized. */
-async function cartFormPost(context: APIContext): Promise<Response> {
-  const { tenant, commerce } = context.locals;
-  if (!commerce) {
-    return cartDenial(
-      "signing-unavailable",
-      "Checkout is unavailable because this store has no cart configured.",
-      409,
-    );
-  }
-  const signing = await resolveCartSigning(commerce);
-  if (!signing.enabled) {
-    return cartDenial(
-      "signing-unavailable",
-      shopperCartDenialMessage("signing-unavailable", signing.operatorError ?? ""),
-      503,
-    );
-  }
-  const form = await context.request.formData();
-  const entries: Array<[string, string]> = [];
-  for (const [name, value] of form.entries()) {
-    if (typeof value !== "string") return cartDenial("signature", "Invalid cart.", 422);
-    entries.push([name, value]);
-  }
-  if (form.has("sample_product") || form.has("sample_variant")) {
-    const sampleTenant = await readEnv("COMMERCE_SAMPLE_TENANT_ID");
-    if (
-      !sampleTenant || sampleTenant !== commerceTenantId(tenant) ||
-      await readEnv("COMMERCE_DEMO_CHECKOUT_TIER") !== "test" || commerce.mode !== "signed"
-    ) return cartDenial("tenant", "Invalid cart.", 422);
-    const allowed = new Set(["sample_product", "sample_variant", "quantity"]);
-    if (entries.length !== 3 || entries.some(([name]) => !allowed.has(name)) ||
-      new Set(entries.map(([name]) => name)).size !== 3) {
-      return cartDenial("signature", "Invalid cart.", 422);
-    }
-    const quantity = form.get("quantity") as string;
-    if (!/^[1-9][0-9]*$/.test(quantity) || !Number.isSafeInteger(Number(quantity)) || Number(quantity) > MAX_CART_QUANTITY) {
-      return cartDenial("quantity", "Invalid quantity.", 422);
-    }
-    const product = await context.locals.tot.getProductByHandle(form.get("sample_product") as string);
-    const variant = product?.variants.find((v) => v.id === form.get("sample_variant"));
-    if (!product || product.status !== "active" || product.visibility === "hidden" || product.visibility === "unlisted" ||
-      !variant || !variant.inventory.available || product.tenant_id !== tenant.tot_data_scope ||
-      variant.tenant_id !== tenant.tot_data_scope) {
-      return cartDenial("signature", "Product is unavailable.", 422);
-    }
-    const payload = await buildVariantCartPayload(product, variant, {
-      mode: "signed", secret: signing.secret, tenantId: commerceTenantId(tenant),
-    });
-    entries.splice(0, entries.length, ...payload.hidden.map((f): [string, string] => [f.name, f.value]), [payload.quantityName, quantity]);
-  }
-  const result = await enforceCartSubmission({
-    entries,
-    mode: commerce.mode,
-    secret: signing.secret,
-    trustedTenantId: commerceTenantId(tenant),
-  });
-  if (!result.ok) {
-    const status = result.code === "signing-unavailable" ? 503 : 422;
-    return cartDenial(result.code, shopperCartDenialMessage(result.code, result.message), status);
-  }
-  return new Response(null, {
-    status: 303,
-    headers: {
-      location: foxyCartRedirectUrl(commerce.cartUrl, result.fields),
-      "cache-control": "no-store",
-      "x-tot-payment-authorized": "false",
-    },
-  });
-}
-
-export async function POST(context: APIContext): Promise<Response> {
-  if (isCartForm(context.request)) return cartFormPost(context);
-  const { tenant, browserEnvironment, commerce } = context.locals;
-
-  // No managed checkout on this tenant → nothing to attribute.
-  if (!commerce) {
-    return json({ attributed: false, reason: "no-store" });
-  }
-
-  let body: HandoffBody;
-  try {
-    body = (await context.request.json()) as HandoffBody;
-  } catch {
-    body = {};
-  }
-
-  // Fail-closed: an absent/forged/tampered snapshot is default-deny (essential only).
-  const consent = parseConsentSnapshot(body.consent) ?? defaultConsentSnapshot();
-
-  const result = await resolveCheckoutHandoffCorrelation({
-    tenant: tenant.tenant_id,
-    // Env-consistency: the request's own resolved stage, never a client value.
-    environment: browserEnvironment.environment,
-    consent,
-    // Opaque per-handoff logical id the order join threads back to.
-    eventId: crypto.randomUUID(),
-  });
-
-  if (result.attributed) {
-    // Return ONLY the opaque passthrough field; the signing secret never leaves here.
-    return json({ attributed: true, cartField: result.cartField });
-  }
-  return json({ attributed: false, reason: result.reason });
-}
-
-export async function GET(): Promise<Response> {
-  return json({ error: "method_not_allowed" }, 405);
-}
+export { GET, POST } from "@/lib/checkout/commerce/checkoutHandoffRoute";

package/package.json

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