@tokenoftrust/storefront-runner 4.4.0 → 4.6.0

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

@@ -17,10 +17,24 @@
  *
  * A cart-origin link click or form submit that beats the drawer is held, not
  * lost: it is cancelled, the loader is fetched, and the same control is activated
- * again once the drawer reports ready (or after a bounded wait), so it opens in
- * the drawer exactly as it would have. Holding runs in the window bubble phase,
- * after every page handler, so an action another handler already took over (the
- * compliance gate) is left alone.
+ * again once the drawer client reports `ready.done`, so it opens in the drawer
+ * exactly as it would have. Foxy binds its cart-link handler in `FC.client.init`
+ * and initialises the side cart on `ready.done`; before that a cart link is a
+ * plain navigation to the full cart page. So a held action waits for that signal,
+ * not a clock: it follows the link to the cart page only when the drawer cannot
+ * come up (the loader or bundle errors, no client appears, or nothing reports
+ * within LAZY_CHECKOUT_READY_TIMEOUT_MS). A held action never outlives the page
+ * that held it. Holding runs in the window bubble phase, after every page
+ * handler, so an action another handler already took over (the compliance gate,
+ * or the drawer itself) is left alone.
+ *
+ * Every cart action that reaches the window still unhandled once the drawer has
+ * settled is about to navigate to the cart page. That is recorded: a
+ * `[tot-cart]` console warning, a `tot:cart-fallthrough` window event, and
+ * `data-cart-fallthrough="<reason>[:<cause>]"` on the root element. The detail
+ * carries only the reason, the cause, elapsed ms, whether the action was held,
+ * whether `FC.client` existed, Foxy's own full-page and bypass decisions, the
+ * document ready state and viewport/screen/body widths — never a URL or session.
  *
  * Every cart open waits for this store's Foxy session. The id comes from the
  * same-origin session endpoint (an HttpOnly cookie the browser cannot read) and
@@ -43,8 +57,12 @@ import { CART_UNAVAILABLE_MESSAGE } from "@/lib/checkout/commerce/cartSession";
 
 export const LAZY_CHECKOUT_LOADER_IDLE_MS = 8000;
 
-/** Upper bound on waiting for the drawer to report ready before replaying a held action. */
-export const LAZY_CHECKOUT_READY_TIMEOUT_MS = 4000;
+/**
+ * Upper bound on waiting for the drawer client to report ready before a held action
+ * follows its link to the full cart page. Long enough for a cold drawer bundle on a
+ * slow phone; reached only when the drawer is not coming up at all.
+ */
+export const LAZY_CHECKOUT_READY_TIMEOUT_MS = 12000;
 
 export const LAZY_CHECKOUT_LOADER_EVENTS = ["pointerdown", "keydown", "touchstart"] as const;
 
@@ -81,7 +99,11 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
   var referrerPolicy = ${literal(CHECKOUT_NAVIGATION_REFERRER_POLICY)};
   var storeNotPublic = ${options.storeNotPublic ? "true" : "false"};
   var events = ${literal(LAZY_CHECKOUT_LOADER_EVENTS)};
+  // idle → loading → ready (the drawer client reported ready.done) | failed (it cannot come up).
   var state = 'idle';
+  var failure = null;
+  var armedAt = 0;
+  var replaying = null;
   var waiters = [];
   var sessionId = null;
   var sessionPromise = null;
@@ -143,7 +165,10 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
   document.addEventListener("visibilitychange", function () {
     if (document.visibilityState === "hidden") endCartNavigation();
   });
-  window.addEventListener("pagehide", endCartNavigation);
+  window.addEventListener("pagehide", function () {
+    endCartNavigation();
+    dropHeld();
+  });
   window.addEventListener("pageshow", function (event) {
     if (event.persisted) endCartNavigation();
   });
@@ -201,20 +226,75 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
     });
     return sessionPromise;
   }
-  function markSessionUnavailable() {
+  function release(held) {
+    if (held.el && held.el.removeAttribute) held.el.removeAttribute('aria-busy');
+  }
+  function dropHeld() {
+    var dropped = waiters;
     waiters = [];
+    for (var i = 0; i < dropped.length; i++) release(dropped[i]);
+  }
+  function markSessionUnavailable() {
+    dropHeld();
     state = 'idle';
     document.documentElement.setAttribute('data-cart-session', 'unavailable');
     for (var i = 0; i < events.length; i++) {
       document.addEventListener(events[i], onInput, { capture: true, passive: true });
     }
   }
+  function settled() {
+    return state === 'ready' || state === 'failed';
+  }
+  function runHeld() {
+    var run = waiters;
+    waiters = [];
+    for (var i = 0; i < run.length; i++) {
+      release(run[i]);
+      run[i].fn();
+    }
+  }
   function ready() {
     if (state === 'ready') return;
     state = 'ready';
-    var run = waiters;
-    waiters = [];
-    for (var i = 0; i < run.length; i++) run[i]();
+    failure = null;
+    runHeld();
+  }
+  function fail(cause) {
+    if (state !== 'loading') return;
+    state = 'failed';
+    failure = cause;
+    runHeld();
+  }
+  // A cart action reaching the window unhandled after the drawer settled navigates
+  // to the full cart page. Record why, with no URL or session in the record.
+  function fallthrough(kind, el) {
+    var fc = window.FC || {};
+    var fullpage = null;
+    try {
+      if (fc.sidecart && typeof fc.sidecart.shouldUseFullpageCart === 'function') fullpage = !!fc.sidecart.shouldUseFullpageCart();
+    } catch (e) {}
+    var body = document.body;
+    function bypassed(node) {
+      return !!(node && node.classList && (node.classList.contains('fc-sidecart--bypass') || node.hasAttribute('data-fc-sidecart-bypass')));
+    }
+    var reason = state === 'ready' ? 'drawer-declined' : 'drawer-unavailable';
+    var detail = {
+      reason: reason,
+      cause: failure,
+      kind: kind,
+      held: replaying === el,
+      elapsedMs: armedAt ? Date.now() - armedAt : null,
+      fcClient: !!fc.client,
+      fullpage: fullpage,
+      bypass: bypassed(body) || bypassed(el),
+      docState: document.readyState,
+      viewport: window.innerWidth,
+      screenWidth: window.screen ? window.screen.availWidth : null,
+      bodyWidth: body ? body.clientWidth : null
+    };
+    document.documentElement.setAttribute('data-cart-fallthrough', reason + (failure ? ':' + failure : ''));
+    try { console.warn('[tot-cart] cart fell through to the cart page', detail); } catch (e) {}
+    try { window.dispatchEvent(new window.CustomEvent('tot:cart-fallthrough', { detail: detail })); } catch (e) {}
   }
   function armDrawer(id) {
     document.documentElement.removeAttribute('data-cart-session');
@@ -225,23 +305,25 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
       window.FC.settings.cookiepath = cookiePath;
       window.FC.settings.sitedomain = location.hostname;
     };
-    setTimeout(ready, ${LAZY_CHECKOUT_READY_TIMEOUT_MS});
+    armedAt = Date.now();
+    setTimeout(function () { fail('ready-timeout'); }, ${LAZY_CHECKOUT_READY_TIMEOUT_MS});
     var s = document.createElement('script');
     s.src = src;
     s.async = true;
-    // The loader appends the drawer bundle and exposes it as fc_script; the drawer is
-    // ready once that bundle has run and its client reports ready.done.
+    // The loader appends the drawer bundle and exposes it as fc_script. The bundle's
+    // FC.client.init binds the cart-link handler and ready.done initialises the side
+    // cart, so ready.done is the only signal that a cart link will open the drawer.
     s.addEventListener('load', function () {
       var bundle = window.fc_script;
-      if (!bundle) return ready();
+      if (!bundle) return fail('no-bundle');
       bundle.addEventListener('load', function () {
         var client = window.FC && window.FC.client;
-        if (!client || typeof client.on !== 'function') return ready();
+        if (!client || typeof client.on !== 'function') return fail('no-client');
         client.on('ready.done', ready);
       });
-      bundle.addEventListener('error', ready);
+      bundle.addEventListener('error', function () { fail('bundle-error'); });
     });
-    s.addEventListener('error', ready);
+    s.addEventListener('error', function () { fail('loader-error'); });
     document.body.appendChild(s);
   }
   function start() {
@@ -253,11 +335,16 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
       armDrawer(id);
     });
   }
-  function whenReady(fn) {
-    if (state === 'ready') return fn();
-    waiters.push(fn);
+  function whenReady(el, fn) {
+    if (settled()) return fn();
+    el.setAttribute('aria-busy', 'true');
+    waiters.push({ el: el, fn: fn });
     start();
   }
+  function replay(el, fn) {
+    replaying = el;
+    try { fn(); } finally { replaying = null; }
+  }
   function onInput() {
     if (commerceReachable()) start();
   }
@@ -292,16 +379,19 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
     var anchor = event.target && event.target.closest ? event.target.closest('a[href]') : null;
     if (!anchor || anchor.target === '_blank' || !targetsCart(anchor.href)) return;
     anchor.referrerPolicy = referrerPolicy;
-    if (state === 'ready') {
+    if (settled()) {
       stampAnchor(anchor);
-      if (!event.defaultPrevented) revealForNavigation();
+      if (!event.defaultPrevented) {
+        fallthrough('link', anchor);
+        revealForNavigation();
+      }
       return;
     }
     if (event.defaultPrevented) return;
     event.preventDefault();
-    whenReady(function () {
+    whenReady(anchor, function () {
       stampAnchor(anchor);
-      anchor.click();
+      replay(anchor, function () { anchor.click(); });
     });
   });
 
@@ -352,10 +442,11 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
     var cartForm = targetsCart(form.getAttribute('action'));
     if (!managed && !cartForm) return;
     if (form.dataset.cartSession === '1') {
-      if (!cartForm || state === 'ready') {
-        if (!event.defaultPrevented && state === 'ready') {
+      if (!cartForm || settled()) {
+        if (!event.defaultPrevented && settled()) {
           form.referrerPolicy = referrerPolicy;
           if (cartForm) {
+            fallthrough('form', form);
             form.setAttribute("referrerpolicy", referrerPolicy);
             loosenReferrer();
             revealForNavigation();
@@ -364,7 +455,7 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
         return;
       }
       event.preventDefault();
-      whenReady(function () { stampForm(form); resubmit(form); });
+      whenReady(form, function () { stampForm(form); replay(form, function () { resubmit(form); }); });
       return;
     }
     event.preventDefault();
@@ -372,7 +463,7 @@ export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string
       openSessionThen(form, function () {
         if (cartForm) {
           stampForm(form);
-          whenReady(function () { resubmit(form); });
+          whenReady(form, function () { replay(form, function () { resubmit(form); }); });
           return;
         }
         resubmit(form);

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

@@ -24,7 +24,12 @@
  * stray quote/angle-bracket can't break out of an attribute or element; this is
  * defense-in-depth, not a sanitizer for untrusted input.
  */
-import { CHROME_BODY_MARKER, CHROME_HEAD_MARKER } from "./rawMarketingHtml.js";
+import {
+  BRAND_H1_CLASS,
+  CHROME_BODY_MARKER,
+  CHROME_HEAD_MARKER,
+  isHomePath,
+} from "./rawMarketingHtml.js";
 import { isCurrentNavHref } from "../chrome/navCurrent.js";
 import { ctaIdentityAttr } from "../chrome/ctaIdentity.js";
 import { CHROME_PLACEMENT } from "../chrome/trackingPlacements.js";
@@ -325,6 +330,14 @@ function renderActionLinks(links: ChromeHeaderActionLink[]): string {
 }
 
 function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?: string): string {
+  // One-h1 contract: on the home route (header only, never the footer) the brand
+  // renders inside <h1 class="brand-h1">. When the spliced page body supplies its
+  // own <h1>, wrapFragmentInChrome / Layout unwrap this one (demoteBrandH1), so
+  // every page carries exactly one h1.
+  const brandLink = renderBrand(header.brand);
+  const brandBlock = isHomePath(currentPath)
+    ? `<h1 class="${BRAND_H1_CLASS}" style="margin:0;font:inherit">${brandLink}</h1>`
+    : brandLink;
   const search = header.search ? renderSearchForm(header.search) : "";
   const memberCue = header.memberCue
     ? `<a class="member-cue" href="${esc(header.memberCue.href)}" aria-label="${esc(header.memberCue.label)}">${esc(header.memberCue.label)}</a>`
@@ -424,7 +437,7 @@ function renderHeader(header: ChromeHeader, variant: HeaderVariant, currentPath?
     `  <div class="container header-row">\n` +
     (menuLeft && hamburger ? `    ${hamburger}\n` : "") +
     (compact ? `    ${primaryNav}\n` : "") +
-    `    ${renderBrand(header.brand)}\n` +
+    `    ${brandBlock}\n` +
     (!minimal && !compact && search ? `    ${search}\n` : "") +
     `    <div class="header-actions">${memberCue}${ctas}${compactSearch}${actionLinks}${account}${cart}${menuLeft ? "" : hamburger}</div>\n` +
     `  </div>\n` +

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

@@ -56,13 +56,39 @@ export function isFullDocument(html: string): boolean {
   return /^\s*<!doctype/i.test(html) || /<html[\s>]/i.test(html);
 }
 
+/** Class of the home-route header brand heading (`<h1 class="brand-h1">`). */
+export const BRAND_H1_CLASS = "brand-h1";
+
+/** True for the home route ("/" with optional query/hash); false when no path is known. */
+export function isHomePath(path: string | undefined): boolean {
+  return path !== undefined && (path.split(/[?#]/)[0] ?? "") === "/";
+}
+
+/** True when page content already supplies an `<h1>`. */
+export function hasContentH1(html: string): boolean {
+  return /<h1[\s>]/i.test(html);
+}
+
+/**
+ * Unwrap the home brand heading (keeping the brand link) so a page whose own
+ * content supplies an `<h1>` ends up with exactly one h1.
+ */
+export function demoteBrandH1(html: string): string {
+  return html.replace(
+    new RegExp(`<h1 class="${BRAND_H1_CLASS}"[^>]*>([\\s\\S]*?)</h1>`),
+    "$1",
+  );
+}
+
 /**
  * Splice a body-only fragment into a tenant chrome wrapper at CHROME_BODY_MARKER.
+ * When the fragment carries its own `<h1>`, the wrapper's brand h1 is unwrapped.
  * If the wrapper has no marker (misconfigured), the fragment is returned unwrapped
  * so a page never disappears.
  */
 export function wrapFragmentInChrome(fragment: string, chromeWrapper: string): string {
   if (!chromeWrapper.includes(CHROME_BODY_MARKER)) return fragment;
+  if (hasContentH1(fragment)) chromeWrapper = demoteBrandH1(chromeWrapper);
   // A fragment may lead with a <head>…</head> of page-specific SEO tags. Split it
   // out so the shared wrapper keeps per-page title/meta/canonical/JSON-LD.
   let head = "";

package/apps/storefront/src/lib/inventory/allocations.ts

@@ -15,12 +15,12 @@ import {
   type PaymentState,
   type StockState,
 } from "@tot/public-runtime";
+import { isStoredSku } from "@tot/public-runtime/sku";
 
 export const RESERVATION_AUTHORITY_HEADER = "x-tot-reservation-authority";
 export const RESERVATION_AUTHORITY_NONE = "none";
 export const VERIFICATION_PROVIDER_OWNER = "tot-9577-tot-verification-provider";
 
-const SKU_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
 const ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
 const TENANT_RE = /^[a-z0-9][a-z0-9.-]{0,253}$/;
 const LOCATION_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,80}$/;
@@ -153,7 +153,7 @@ export function readMirrorAuthority(value: unknown): MirrorStockAuthority | null
   const record = value as Record<string, unknown>;
   if (record.provider !== "mirror" || record.readable !== true) return null;
   if (typeof record.locationId !== "string" || !LOCATION_RE.test(record.locationId)) return null;
-  if (typeof record.sku !== "string" || !SKU_RE.test(record.sku)) return null;
+  if (typeof record.sku !== "string" || !isStoredSku(record.sku)) return null;
   if (typeof record.onHand !== "number" || !Number.isSafeInteger(record.onHand) || record.onHand < 0) return null;
   if (typeof record.asOf !== "string" || record.asOf.trim() === "" || record.asOf.length > 40) return null;
   return {
@@ -252,7 +252,7 @@ function reserveShape(input: ReserveInput): ReserveResult | null {
   if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor < 0) return { ok: false, finding: "malformed-request" };
   if (input.holds.length < 1) return { ok: false, finding: "malformed-request" };
   for (const hold of input.holds) {
-    if (!SKU_RE.test(hold.sku) || !LOCATION_RE.test(hold.locationId)) return { ok: false, finding: "malformed-request" };
+    if (!isStoredSku(hold.sku) || !LOCATION_RE.test(hold.locationId)) return { ok: false, finding: "malformed-request" };
     if (!Number.isSafeInteger(hold.quantity) || hold.quantity < 1) return { ok: false, finding: "malformed-request" };
     if (!Number.isSafeInteger(hold.onHand) || hold.onHand < 0) return { ok: false, finding: "malformed-request" };
   }

package/apps/storefront/src/lib/inventory/mirrorStock.ts

@@ -1,6 +1,7 @@
 /** Tenant-scoped inventory authority. Catalog availability never supplies a balance. */
 import type { Queryable } from "../catalog/d1/catalog.js";
 import type { CommerceStage } from "@tot/public-runtime";
+import { isStoredSku } from "@tot/public-runtime/sku";
 import type { MirrorStockAuthority } from "./allocations.js";
 
 const ID = /^[A-Za-z0-9._:-]{1,128}$/;
@@ -25,9 +26,10 @@ export interface MirrorMovement {
 }
 export async function appendMirrorMovement(db: Queryable, input: MirrorMovement): Promise<void> {
   if (
-    ![input.tenantId, input.source, input.sourceEventId, input.sku, input.locationId, input.actorId].every((v) =>
+    ![input.tenantId, input.source, input.sourceEventId, input.locationId, input.actorId].every((v) =>
       ID.test(v),
     ) ||
+    !isStoredSku(input.sku) ||
     !Number.isSafeInteger(input.quantityDelta) ||
     !Number.isFinite(Date.parse(input.asOf)) ||
     !["preview", "publication"].includes(input.stage)