@tokenoftrust/storefront-runner 2.4.35 → 2.4.37

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

@@ -321,7 +321,11 @@ a.article-card__tag:hover { text-decoration: underline; }
 
 /* --- Age gate (21+ interstitial; remembered per device) ------------------- */
 /* Overlay + on-dark surfaces derive from --color-text (deep ink) so no brand hex. */
-.age-gate { position: fixed; inset: 0; z-index: 1000; display: none; align-items: center; justify-content: center; padding: 24px; background: color-mix(in srgb, var(--color-text) 78%, transparent); }
+/* Sized by viewport units, not `inset: 0`: on a phone the fixed containing block is the
+   LAYOUT viewport, which widens with content wider than the screen and shrinks as it
+   settles, so a panel centered in it moves with the page and can sit off-screen. The
+   shadow spread carries the backdrop over any layout viewport wider than the screen. */
+.age-gate { box-sizing: border-box; position: fixed; top: 0; left: 0; width: 100vw; height: 100svh; overflow-y: auto; z-index: 1000; display: none; align-items: center; justify-content: center; padding: 24px; background: color-mix(in srgb, var(--color-text) 78%, transparent); box-shadow: 0 0 0 200vmax color-mix(in srgb, var(--color-text) 78%, transparent); }
 .age-gate.is-open { display: flex; }
 .age-gate__panel { width: min(30rem, 100%); background: var(--color-surface); border-radius: var(--radius-lg); box-shadow: var(--shadow-lg); padding: clamp(24px, 4vw, 40px); text-align: center; }
 .age-gate__mark { font-family: var(--font-display); font-weight: 800; letter-spacing: .04em; font-size: 1.05rem; color: var(--color-text); }

package/apps/storefront/src/components/islands/AgeGate.tsx

@@ -8,7 +8,7 @@
  */
 import { useEffect, useRef, useState } from "preact/hooks";
 import type { ChromeAgeGate } from "@/lib/chrome/model";
-import { deriveAgeGateStorageKey, resolveAgeGateCopy } from "@/lib/chrome/model";
+import { deriveAgeGateStorageKey, isSafeAgeGateHref, resolveAgeGateCopy } from "@/lib/chrome/model";
 
 export interface Props {
   minAge: number;
@@ -40,6 +40,18 @@ export function resolveAgeGateRuntime({
       resolveAgeGateCopy(presentation?.denyText, minAge) ??
       `You must be ${minAge} or older to view this store. Please close this tab.`,
     fineText: resolveAgeGateCopy(presentation?.fineText, minAge),
+    showNo: presentation?.showNo !== false,
+    eyebrow:
+      presentation?.eyebrow === false
+        ? null
+        : (resolveAgeGateCopy(presentation?.eyebrow, minAge) ?? "Age verification"),
+    helpLink:
+      presentation?.helpLink && isSafeAgeGateHref(presentation.helpLink.href)
+        ? {
+            label: resolveAgeGateCopy(presentation.helpLink.label, minAge)!,
+            href: presentation.helpLink.href,
+          }
+        : null,
   };
 }
 
@@ -47,7 +59,7 @@ export default function AgeGate({ minAge, brand, tenantId, presentation, onBlock
   const [state, setState] = useState<"hidden" | "ask" | "denied">("hidden");
   const yesRef = useRef<HTMLButtonElement>(null);
   const retryRef = useRef<HTMLButtonElement>(null);
-  const { storageKey, compact, title, lede, yesLabel, noLabel, denyText, fineText } =
+  const { storageKey, compact, title, lede, yesLabel, noLabel, denyText, fineText, showNo, eyebrow, helpLink } =
     resolveAgeGateRuntime({ minAge, brand, tenantId, presentation });
 
   useEffect(() => {
@@ -91,24 +103,36 @@ export default function AgeGate({ minAge, brand, tenantId, presentation, onBlock
   // attributes are intentionally admitted by style-src-attr. Keep the modal
   // self-contained, token-driven, and responsive without opening either the
   // shadow root or the CSP.
+  // The backdrop covers the fixed containing block, which on mobile is the LAYOUT
+  // viewport: it grows with any content wider than the screen and shrinks as that
+  // content settles. Centering the panel in it let the page under the gate move the
+  // panel (CLS 0.30 on product pages). The panel is placed in a frame sized only
+  // by viewport units, which no document content can change.
   const overlayStyle = {
     boxSizing: "border-box",
     position: "fixed" as const,
     inset: "0",
-    display: "flex",
-    alignItems: compact ? "flex-start" : "center",
-    justifyContent: "center",
-    width: "100%",
-    height: "100%",
-    padding: compact ? "min(24px, 4vw)" : "20px",
     background: compact ? "rgba(0, 0, 0, 0.5)" : "color-mix(in srgb, var(--color-text, #111) 75%, transparent)",
     backdropFilter: compact ? undefined : "blur(4px)",
     color: "var(--color-text, #171717)",
     fontFamily: "var(--font-body, system-ui, sans-serif)",
     pointerEvents: "auto",
   };
+  const frameStyle = {
+    boxSizing: "border-box",
+    position: "absolute" as const,
+    top: "0",
+    left: "0",
+    width: "100vw",
+    height: "100svh",
+    display: "flex",
+    overflowY: "auto" as const,
+    padding: compact ? "min(24px, 4vw)" : "20px",
+  };
   const panelStyle = {
     boxSizing: "border-box",
+    // Auto margins center without clipping a panel taller than the viewport.
+    margin: compact ? "0 auto auto" : "auto",
     width: compact ? "min(600px, calc(100vw - 32px))" : "min(480px, calc(100vw - 40px))",
     minHeight: compact ? "min(382px, calc(100vh - 48px))" : undefined,
     maxHeight: compact ? "calc(100vh - 48px)" : undefined,
@@ -141,7 +165,7 @@ export default function AgeGate({ minAge, brand, tenantId, presentation, onBlock
       onKeyDown={(event) => {
         if (event.key !== "Tab") return;
         const controls = Array.from(
-          event.currentTarget.querySelectorAll<HTMLButtonElement>("button:not([disabled])"),
+          event.currentTarget.querySelectorAll<HTMLElement>("button:not([disabled]), a[href]"),
         );
         if (controls.length === 0) return;
         const first = controls[0]!;
@@ -155,6 +179,7 @@ export default function AgeGate({ minAge, brand, tenantId, presentation, onBlock
         }
       }}
     >
+      <div style={frameStyle}>
       <div style={panelStyle}>
         {state === "ask" ? (
           <>
@@ -164,9 +189,9 @@ export default function AgeGate({ minAge, brand, tenantId, presentation, onBlock
                   <span class={part.className}>{part.text}</span>
                 ))}
               </p>
-            ) : (
-              <p style={{ margin: "0 0 16px", fontFamily: "var(--font-display, system-ui, sans-serif)", fontSize: "12px", fontWeight: 700, letterSpacing: ".12em", textTransform: "uppercase", color: "var(--color-muted, #616161)" }}>Age verification</p>
-            )}
+            ) : eyebrow ? (
+              <p style={{ margin: "0 0 16px", fontFamily: "var(--font-display, system-ui, sans-serif)", fontSize: "12px", fontWeight: 700, letterSpacing: ".12em", textTransform: "uppercase", color: "var(--color-muted, #616161)" }}>{eyebrow}</p>
+            ) : null}
             <h2 id="agegate-title" style={{ margin: 0, fontFamily: "var(--font-display, system-ui, sans-serif)", fontSize: "clamp(24px, 4vw, 32px)", fontWeight: 600, lineHeight: 1.1, letterSpacing: "-.02em" }}>
               {title}
             </h2>
@@ -182,14 +207,23 @@ export default function AgeGate({ minAge, brand, tenantId, presentation, onBlock
               >
                 {yesLabel}
               </button>
-              <button
-                type="button"
-                onClick={() => setState("denied")}
-                style={{ ...buttonBase, width: compact ? "100%" : undefined, border: "1px solid var(--color-border, #d0d0d0)", background: "transparent", color: "var(--color-text, #171717)", fontWeight: 500 }}
-              >
-                {noLabel}
-              </button>
+              {showNo && (
+                <button
+                  type="button"
+                  onClick={() => setState("denied")}
+                  style={{ ...buttonBase, width: compact ? "100%" : undefined, border: "1px solid var(--color-border, #d0d0d0)", background: "transparent", color: "var(--color-text, #171717)", fontWeight: 500 }}
+                >
+                  {noLabel}
+                </button>
+              )}
             </div>
+            {helpLink && (
+              <p style={{ margin: "16px 0 0", fontSize: "14px", lineHeight: 1.45 }}>
+                <a href={helpLink.href} style={{ color: "var(--color-accent-ink, var(--color-primary, #111))", textDecoration: "underline" }}>
+                  {helpLink.label}
+                </a>
+              </p>
+            )}
             {fineText && (
               <p style={{ maxWidth: "32rem", margin: "20px auto 0", color: "var(--color-muted, #616161)", fontSize: "12px", lineHeight: 1.45 }}>
                 {fineText}
@@ -213,6 +247,7 @@ export default function AgeGate({ minAge, brand, tenantId, presentation, onBlock
           </>
         )}
       </div>
+      </div>
     </div>
   );
 }

package/apps/storefront/src/components/islands/CheckoutComplianceGate.tsx

@@ -375,17 +375,20 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
 
   return (
     <div
-      class="fixed inset-0 z-[110] grid place-items-center bg-[color-mix(in_srgb,var(--color-text)_75%,transparent)] p-5 backdrop-blur-sm"
+      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="cgate-title"
       onClick={(e) => {
-        if (e.target === e.currentTarget) close();
+        if (e.target === e.currentTarget || (e.target as HTMLElement).hasAttribute("data-viewport-frame")) close();
       }}
     >
+      {/* The fixed box is the LAYOUT viewport, which content wider than a phone
+          stretches; place the dialog in a frame sized to what the visitor sees. */}
+      <div data-viewport-frame class="absolute left-0 top-0 flex h-[100svh] w-[100vw] overflow-y-auto p-5">
       <div
         ref={dialogRef}
-        class="w-[min(32rem,100%)] rounded-[var(--radius-lg)] bg-[var(--color-surface)] p-7 text-left shadow-[var(--shadow-lg)]"
+        class="m-auto w-[min(32rem,100%)] rounded-[var(--radius-lg)] bg-[var(--color-surface)] p-7 text-left shadow-[var(--shadow-lg)]"
       >
         <p class="eyebrow eyebrow--tick mb-3 w-fit">Compliance check</p>
         <h2 id="cgate-title" class="display-sm">
@@ -606,6 +609,7 @@ export default function CheckoutComplianceGate({ preflightUrl, minAge }: Props)
           </button>
         </div>
       </div>
+      </div>
     </div>
   );
 }

package/apps/storefront/src/components/islands/IsolatedAgeGate.tsx

@@ -118,6 +118,7 @@ export function isolateAgeGateBackground(host: HTMLElement): BackgroundIsolation
 }
 
 const HOST_MARKER = "data-tot-compliance";
+const HOST_MOVES_PER_TASK = 20;
 let mountedHost: HTMLElement | null = null;
 const HOST_STYLE_FLOOR = {
   all: "initial",
@@ -217,23 +218,58 @@ export function mountIsolatedAgeGate({ minAge, brand, tenantId, presentation }:
     mount,
   );
 
-  // Re-assert: restore the host if tenant code detaches or hides it.
+  // Re-assert: restore the host if tenant code detaches or hides it. The repair
+  // writes exactly what this observer watches, so it runs disconnected: a repair
+  // that is not perfectly idempotent can never re-trigger itself and spin the
+  // main thread in an unbounded microtask loop.
+  //
+  // Another script that also keeps itself last in <body> would answer every move
+  // with one of its own, and two observers can ping-pong forever without either
+  // re-triggering itself. Moves are budgeted per task; past the budget the repair
+  // yields to the event loop and resumes on the next task.
+  let active = true;
+  let moves = 0;
+  let resumeScheduled = false;
+  const spendMove = () => {
+    if (!resumeScheduled) {
+      resumeScheduled = true;
+      setTimeout(() => {
+        resumeScheduled = false;
+        moves = 0;
+        if (active) ensure();
+      }, 0);
+    }
+    return ++moves <= HOST_MOVES_PER_TASK;
+  };
+  const observeHost = () => {
+    observer.observe(document.body, { childList: true });
+    observer.observe(host, {
+      attributes: true,
+      attributeFilter: ["style", "class", "hidden"],
+    });
+  };
   const ensure = () => {
-    if (!host.isConnected || document.body.lastElementChild !== host) {
-      document.body.appendChild(host);
+    observer.disconnect();
+    try {
+      if ((!host.isConnected || document.body.lastElementChild !== host) && spendMove()) {
+        // Moving the host blurs whatever the gate had focused; give it back so a
+        // keyboard visitor is never stranded by a script appending to <body>.
+        const focused = shadow.activeElement as HTMLElement | null;
+        document.body.appendChild(host);
+        focused?.focus({ preventScroll: true });
+      }
+      if (host.hasAttribute("hidden")) host.removeAttribute("hidden");
+      hardenComplianceHost(host);
+      backgroundIsolation?.refresh();
+    } finally {
+      observeHost();
     }
-    if (host.hasAttribute("hidden")) host.removeAttribute("hidden");
-    hardenComplianceHost(host);
-    backgroundIsolation?.refresh();
   };
   const observer = new MutationObserver(ensure);
-  observer.observe(document.body, { childList: true });
-  observer.observe(host, {
-    attributes: true,
-    attributeFilter: ["style", "class", "hidden"],
-  });
+  observeHost();
 
   return () => {
+    active = false;
     observer.disconnect();
     stylesheetObserver.disconnect();
     backgroundIsolation?.release();

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

@@ -167,7 +167,9 @@ export default function MobileNav({ nav, announcement, currentPath }: Props) {
 
       {open && (
         <div
-          class="fixed inset-0 z-50"
+          // Sized to what the visitor sees, not `inset-0`: on a phone the fixed box is the
+          // layout viewport, which wide page content stretches past the screen's edge.
+          class="fixed left-0 top-0 z-50 h-[100dvh] w-[100vw]"
           // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions
           onKeyDown={onKeyDown}
         >

package/apps/storefront/src/lib/chrome/model.ts

@@ -33,6 +33,7 @@ export {
   CHROME_AGE_GATE_VARIANTS,
   type ChromeAgeGateVariant,
   deriveAgeGateStorageKey,
+  isSafeAgeGateHref,
   resolveAgeGateCopy,
   type ChromeFooterBrand,
   type ChromeTrustMark,

package/docs/widget-library-guide.md

@@ -1426,7 +1426,8 @@ stable `id` (a governed-action-registry substitute, independent of the visible `
 to `ChromeHeader`/`ChromeFooter`, it exports `ChromeBrand`, `ChromeSearch`, `ChromeUtilityNav`,
 `ChromeAnnouncement` (`{ variant: "marquee" | "bar" | "solid"; messages: string[]; label?;
 dismissible?; rotateMs?; storageKey? }`), `ChromeAgeGate` (`{ minAge: number; storageKey?; title?;
-lede?; yesLabel?; noLabel?; denyText?; fineText?; mark? }`), `ChromeFooterBrand`, `ChromeTrustMark`,
+lede?; yesLabel?; noLabel?; denyText?; fineText?; mark?; showNo?; eyebrow?: string | false;
+helpLink?: { label; href } }`), `ChromeFooterBrand`, `ChromeTrustMark`,
 `ChromeHead`, `ChromeCta`, `ChromeNavItem`, and `ChromeConfig` itself.
 
 ### `lib/chrome/parseConfig.ts` — the validation gate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.35",
+  "version": "2.4.37",
   "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/public-runtime/src/chrome.ts

@@ -228,6 +228,17 @@ export interface ChromeAgeGate {
   fineText?: string;
   /** Optional styled wordmark above the title (spans, like ChromeBrand.wordmark). */
   mark?: { text: string; className?: string }[];
+  /** `false` renders a single affirm button; the deny flow is the default. */
+  showNo?: boolean;
+  /** The line above the title when no `mark` is set: text replaces "Age verification"; `false` omits it. */
+  eyebrow?: string | false;
+  /** Help/FAQ link under the actions. `href` is a same-site path or an https URL. */
+  helpLink?: { label: string; href: string };
+}
+
+/** A help link the platform-owned gate will render: a same-site path or an https URL. */
+export function isSafeAgeGateHref(href: string): boolean {
+  return /^\/(?![/\\])/.test(href) || /^https:\/\/[^/\\]/i.test(href);
 }
 
 /** Platform-owned persistence scope for a tenant's enforced age affirmation. */
@@ -590,6 +601,24 @@ function validateAgeGate(v: unknown, path: string, errors: string[]): v is Chrom
       });
     }
   }
+  if (v.showNo !== undefined && typeof v.showNo !== "boolean") {
+    errors.push(`${path}.showNo: must be a boolean`);
+  }
+  if (v.eyebrow !== undefined && v.eyebrow !== false && !isNonEmptyString(v.eyebrow)) {
+    errors.push(`${path}.eyebrow: must be a non-empty string or false`);
+  }
+  if (v.helpLink !== undefined) {
+    if (!isObject(v.helpLink)) {
+      errors.push(`${path}.helpLink: must be an object`);
+    } else {
+      if (!isNonEmptyString(v.helpLink.label)) {
+        errors.push(`${path}.helpLink.label: required non-empty string`);
+      }
+      if (typeof v.helpLink.href !== "string" || !isSafeAgeGateHref(v.helpLink.href)) {
+        errors.push(`${path}.helpLink.href: required; a same-site path ("/pages/faq") or an https:// URL`);
+      }
+    }
+  }
   return errors.length === before;
 }