@tokenoftrust/storefront-runner 4.3.4 → 4.5.0

package/apps/storefront/src/components/catalog/storefront/ProductCard.astro

@@ -16,7 +16,8 @@ import PriceDisplay from "@/components/catalog/storefront/commerce/PriceDisplay.
 import RatingStars from "@/components/catalog/storefront/commerce/RatingStars.astro";
 import { withBase } from "@/lib/publication/shared/basePath";
 import { pageUrlForm } from "@/lib/content/seo/urlForm";
-import { buildCardCartForm } from "@/lib/checkout/commerce/cardCartForm";
+import { buildCardCartForm, cardNeedsOptionChoice } from "@/lib/checkout/commerce/cardCartForm";
+import { isLocalSampleCheckout } from "@/config/declaredTenantConfig";
 
 interface Props {
   product: CatalogProduct;
@@ -95,6 +96,10 @@ const cardCart = await buildCardCartForm({
   environment: browserEnvironment.environment,
   contentVersionId,
 });
+// A product with options is chosen on its product page, never from the card.
+const productHref = withBase(basePath, pageUrlForm(`/products/${product.handle}`, tenant.seo));
+const selectOptions = available && cardNeedsOptionChoice(product) &&
+  (!!commerce || isLocalSampleCheckout(tenant.tenant_id));
 
 const quickview = {
   ...snapshot,
@@ -201,7 +206,7 @@ const quickview = {
       {/* `py-3` on an inline box raises the tap target to the 44px minimum
           without changing the line box, so the card layout is untouched. */}
       <a
-        href={withBase(basePath, pageUrlForm(`/products/${product.handle}`, tenant.seo))}
+        href={productHref}
         data-astro-prefetch
         class="py-3 after:absolute after:inset-0 after:z-0 transition-colors motion-safe:group-hover:text-primary"
       >
@@ -234,6 +239,18 @@ const quickview = {
         </form>
       )
     }
+    {
+      selectOptions && (
+        <a
+          href={productHref}
+          data-select-options
+          data-product-handle={product.handle}
+          class="relative z-10 mt-3 block w-full rounded-full bg-[var(--color-primary)] px-4 py-3 text-center font-display text-sm font-medium text-[var(--color-primary-contrast)]"
+        >
+          Select options
+        </a>
+      )
+    }
 
     {rating != null && <RatingStars rating={rating} count={reviewCount} class="mt-1.5" />}
 

package/apps/storefront/src/components/catalog/storefront/plp/FacetSidebar.astro

@@ -7,7 +7,7 @@
  * Encoding handled by src/lib/publication/shared/url.ts (opt.<Name>=<value>, tag=, price, avail).
  */
 import type { Facet, ListProductsQuery } from "@tot/public-runtime";
-import { toggleFacet, buildQueryString, isPriceBucketActive, togglePriceBucket } from "@/lib/publication/shared/url";
+import { toggleFacet, splitFacetValues, buildQueryString, isPriceBucketActive, togglePriceBucket } from "@/lib/publication/shared/url";
 import { PRICE_BUCKETS, bucketByKey } from "@/lib/catalog/shared/priceBuckets";
 
 interface Props {
@@ -52,17 +52,29 @@ const clearHref =
 
   <div class="space-y-7">
     {
-      ordered.map((facet) => (
-        <fieldset>
-          <legend class="mb-2.5 font-display text-[0.95rem] font-medium">
-            {facet.name === "tags"
-              ? "Tags"
-              : facet.name === "availability"
-              ? "Availability"
-              : facet.name}
-          </legend>
+      ordered.map((facet) => {
+        const hasSelected = facet.values.some((fv) => selected(facet.name, fv.value));
+        const label =
+          facet.name === "tags" ? "Tags" : facet.name === "availability" ? "Availability" : facet.name;
+        // The first values (plus any selected one) are listed; the rest sit in a nested
+        // "Show more" <details>. A selected value is never in the remainder.
+        const { shown, rest } = splitFacetValues(facet.values, (v) => selected(facet.name, v));
+        const segments = [
+          { more: false, values: shown },
+          ...(rest.length > 0 ? [{ more: true, values: rest }] : []),
+        ];
+        return (
+        <details open={hasSelected} data-facet-group={facet.name}>
+          <summary class="mb-2.5 cursor-pointer font-display text-[0.95rem] font-medium">
+            {label} ({facet.values.length})
+          </summary>
+          {segments.map((seg) => {
+          const Wrap = seg.more ? "details" : Fragment;
+          return (
+          <Wrap>
+          {seg.more && <summary class="cursor-pointer py-1 text-xs text-[var(--color-muted)]">Show more</summary>}
           <ul class="space-y-1.5">
-            {facet.values.map((fv) => {
+            {seg.values.map((fv) => {
               const isSel = selected(facet.name, fv.value);
               const href =
                 basePath + toggleFacet(query, facet.name, fv.value);
@@ -101,8 +113,12 @@ const clearHref =
               );
             })}
           </ul>
-        </fieldset>
-      ))
+          </Wrap>
+          );
+          })}
+        </details>
+        );
+      })
     }
 
     {/* Price range — bucketed quick-select (live counts) + a free-text form

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

@@ -64,6 +64,12 @@ interface Props {
    */
   layout?: HeaderVariant;
   sticky?: boolean;
+  /**
+   * Render the brand link inside `<h1 class="brand-h1">` (margin:0; font:inherit).
+   * The caller sets it on the home route only, and only when the page content
+   * supplies no h1 of its own — exactly one h1 per page.
+   */
+  brandAsH1?: boolean;
   class?: string;
 }
 
@@ -85,6 +91,7 @@ const {
   variant = "light",
   layout = "primary",
   sticky = true,
+  brandAsH1 = false,
   class: className,
 } = Astro.props;
 
@@ -96,7 +103,16 @@ const dark = variant === "dark";
 const minimal = layout === "minimal";
 const compact = layout === "compact-centered";
 
-const ctaClass = (v?: string) =>
+// Home brand heading: the brand link sits inside <h1 class="brand-h1"> (look unchanged);
+// the compact layout's positioning classes move to the h1, which is then the grid child.
+const brandCompactClass =
+  "absolute left-1/2 -translate-x-1/2 md:static md:translate-x-0 md:justify-self-center";
+const BrandWrap = brandAsH1 ? "h1" : Fragment;
+const brandWrapProps = brandAsH1
+  ? { class: ["brand-h1", compact && brandCompactClass].filter(Boolean).join(" "), style: "margin:0;font:inherit" }
+  : {};
+
+const ctaClass =(v?: string) =>
   v === "secondary" || v === "ghost"
     ? "inline-flex items-center rounded-full border border-current px-4 py-2 font-display text-sm font-medium transition-opacity hover:opacity-80"
     : "inline-flex items-center rounded-full bg-accent px-4 py-2 font-display text-sm font-medium text-accent-contrast transition-transform hover:-translate-y-0.5";
@@ -151,11 +167,12 @@ const currentPath = Astro.url.pathname;
         )
       }
       <!-- Logo / wordmark -->
+      <BrandWrap {...brandWrapProps}>
       <a
         href={homeHref}
         class:list={[
           "flex shrink-0 items-center transition-opacity hover:opacity-80",
-          compact && "absolute left-1/2 -translate-x-1/2 md:static md:translate-x-0 md:justify-self-center",
+          !brandAsH1 && compact && brandCompactClass,
         ]}
         aria-label={logo?.alt ?? wordmark ?? "Home"}
       >
@@ -203,6 +220,7 @@ const currentPath = Astro.url.pathname;
           )
         }
       </a>
+      </BrandWrap>
 
       <!-- Search (live typeahead island) -->
       {

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

@@ -29,7 +29,14 @@ import { organizationLd, websiteLd } from "@/lib/content/shared/jsonld";
 import { composeStructuredData, structuredDataProfile, type StructuredDataPage } from "@/lib/content/seo/structuredData";
 import { canonicalUrl } from "@/lib/content/seo/urlForm";
 import { documentTitle } from "@/lib/content/seo/documentTitle";
-import { nonceInlineTags, prefixSharedChrome, CHROME_BODY_MARKER } from "@/lib/content/shared/rawMarketingHtml";
+import {
+  nonceInlineTags,
+  prefixSharedChrome,
+  CHROME_BODY_MARKER,
+  demoteBrandH1,
+  hasContentH1,
+  isHomePath,
+} from "@/lib/content/shared/rawMarketingHtml";
 import { withBase } from "@/lib/publication/shared/basePath";
 import { CHROME_BEHAVIOR_JS, CHROME_HEAD_JS, sanitizeSharedChromeFragment } from "@/lib/content/shared/rawChrome";
 import { ASYNC_CSS_SWAP_JS } from "@/lib/content/shared/asyncCss";
@@ -218,6 +225,16 @@ if (chromeHtml && chromeHtml.includes(CHROME_BODY_MARKER)) {
   };
 }
 
+// One-h1 contract: on the home route the header brand is the page's <h1> unless the
+// page content supplies its own (then the brand stays a plain link). Only home
+// renders the slot to a string to inspect it.
+const isHome = isHomePath(path);
+const homeSlotHtml = isHome ? await Astro.slots.render("default") : null;
+const brandIsH1 = isHome && !hasContentH1(homeSlotHtml ?? "");
+if (sharedChrome && !brandIsH1) {
+  sharedChrome.header = demoteBrandH1(sharedChrome.header);
+}
+
 const compliance = tenant.compliance;
 const sections = complianceSections({
   compliance,
@@ -395,6 +412,7 @@ const footerWidgets = await renderWidgetSlot(
             nav={chrome.header.nav}
             variant={headerDark ? "dark" : "light"}
             layout={resolvedHeaderVariant}
+            brandAsH1={brandIsH1}
             announcement={chrome.header.announcement?.messages[0]}
             searchAction={
               features.productSearch
@@ -415,7 +433,7 @@ const footerWidgets = await renderWidgetSlot(
     )}
 
     <main id="main">
-      <slot />
+      {homeSlotHtml !== null ? <Fragment set:html={homeSlotHtml} /> : <slot />}
     </main>
 
     {sections.includes("pact-act") && (

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

@@ -1,7 +1,9 @@
 /**
- * Add-to-cart form for a catalog card. One default variant — the first
- * available one — signed the same way the product page signs its handoff.
- * No form when the product cannot be bought or the cart cannot be signed.
+ * Add-to-cart form for a catalog card. Only a product with a single variant
+ * buys from its card, signed the same way the product page signs its handoff;
+ * a product with options links to its product page ("Select options") so the
+ * card never adds a variant the shopper did not choose. No form when the
+ * product cannot be bought or the cart cannot be signed.
  */
 import type { CatalogProduct, CatalogVariant, ResolvedManagedCheckout, TenantConfig } from "@tot/public-runtime";
 import {
@@ -31,6 +33,11 @@ export function defaultCardVariant(product: CatalogProduct): CatalogVariant | nu
   return product.variants.find((variant) => variant.inventory.available) ?? null;
 }
 
+/** A product with more than one variant needs the shopper's choice on its product page. */
+export function cardNeedsOptionChoice(product: CatalogProduct): boolean {
+  return product.variants.length > 1;
+}
+
 export async function buildCardCartForm(input: {
   product: CatalogProduct;
   tenant: TenantConfig;
@@ -40,6 +47,7 @@ export async function buildCardCartForm(input: {
   /** Candidate content pin this card rendered. Ignored on a live page. */
   contentVersionId?: string;
 }): Promise<CardCartForm | null> {
+  if (cardNeedsOptionChoice(input.product)) return null;
   const variant = defaultCardVariant(input.product);
   if (!variant) return null;
   const sampleHandoff = isLocalSampleCheckout(input.tenant.tenant_id);

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

@@ -36,6 +36,16 @@ export function cartSessionCookiePath(basePath: string): string {
   return `${withLead.replace(/\/+$/, "")}/`;
 }
 
+/**
+ * True when a browser at `pathname` sends the cookie stored at `cookiePath`. A
+ * candidate preview page (`/preview/render/<tenant>/<change>/…`) is outside the
+ * tenant prefix, so the browser holds this store's session but does not send it there.
+ */
+export function cartSessionCookieVisible(pathname: string, cookiePath: string): boolean {
+  if (cookiePath === "/") return true;
+  return pathname.startsWith(cookiePath) || `${pathname}/` === cookiePath;
+}
+
 /** Cart URL that selects one Foxy session. Other params are kept. */
 export function withCartSession(cartUrl: string, id: string): string {
   const url = new URL(cartUrl);
@@ -47,12 +57,21 @@ function saneSessionId(value: unknown): value is string {
   return typeof value === "string" && CART_SESSION_ID.test(value);
 }
 
+/**
+ * An option name as one key. FC.json spells names for display (measured 2026-10-23:
+ * `return_url` reads "return url"), and a signed name carries `||<hash>`, so names
+ * compare trimmed, lowercased, and with spaces and underscores as one `_`.
+ */
+function optionKey(raw: string): string {
+  return (raw.split("||")[0] ?? "").trim().toLowerCase().replace(/[\s_]+/g, "_");
+}
+
 function optionBaseName(option: unknown): string | null {
   if (!option || typeof option !== "object") return null;
   const raw = (option as { name?: unknown; class?: unknown }).name
     ?? (option as { class?: unknown }).class;
   if (typeof raw !== "string" || raw.length === 0) return null;
-  return raw.split("||")[0] ?? "";
+  return optionKey(raw);
 }
 
 function optionValue(option: unknown): string | null {
@@ -72,7 +91,7 @@ function itemTenant(item: unknown): string | null {
   }
   if (options && typeof options === "object") {
     for (const [key, value] of Object.entries(options as Record<string, unknown>)) {
-      if (key.split("||")[0] === "tenant" && typeof value === "string") return value;
+      if (optionKey(key) === "tenant" && typeof value === "string") return value;
     }
   }
   return null;

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

@@ -30,6 +30,15 @@ export interface SeamView {
   codes?: readonly string[];
   /** Flavor labels that triggered a `flavored_prohibited` block, for the refusal. */
   flavors?: readonly string[];
+  /** Every refused block with the compliance engine's own shopper-facing sentence. */
+  lines?: readonly RefusedLine[];
+}
+
+export interface RefusedLine {
+  code: string;
+  message: string;
+  sku?: string;
+  title?: string;
 }
 
 export interface FinalCartRequest {

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/publication/shared/url.ts

@@ -96,6 +96,25 @@ export function buildQueryString(
   return s ? `?${s}` : "";
 }
 
+/** Facet values shown before the nested "Show more" disclosure. */
+export const FACET_VISIBLE_VALUES = 8;
+
+/**
+ * Split a facet group's values into the always-visible head and the collapsed
+ * remainder: the first FACET_VISIBLE_VALUES, plus every selected value wherever
+ * it sits, so a selected value is never hidden in the remainder.
+ */
+export function splitFacetValues<T extends { value: string }>(
+  values: readonly T[],
+  isSelected: (value: string) => boolean,
+  limit: number = FACET_VISIBLE_VALUES,
+): { shown: T[]; rest: T[] } {
+  const shown: T[] = [];
+  const rest: T[] = [];
+  values.forEach((fv, i) => (i < limit || isSelected(fv.value) ? shown : rest).push(fv));
+  return { shown, rest };
+}
+
 /** Toggle a single facet value on/off, returning the new querystring (page reset). */
 export function toggleFacet(
   current: ListProductsQuery,

package/apps/storefront/src/middleware/renderChain.ts

@@ -948,6 +948,9 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
     const key = pageKey;
     await timed(timing, "page-cache", () => putCachedPage(cache, key, response));
   }
+  // A preview-token (`test`) render is unpublished content shown to one viewer: no
+  // browser, proxy, or CDN may keep it or hand it to the next visitor of this URL.
+  if (customization.env === "test") response.headers.set("Cache-Control", "private, no-store");
   // MATERIALIZE-ONLY capture (ADR 0013): expose the tenant's resolved route-document
   // Cache-Control so the publish/materialize plane can bake it into the bundle
   // manifest (the same capture pattern as CSP). Gated on the materialize probe

package/apps/storefront/src/pages/api/commerce/final-cart-authorization.ts

@@ -2,13 +2,13 @@
 import type { APIContext } from "astro";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify, type JSONWebKeySet } from "jose";
 import {
-  commerceTenantId, totalsMatch, shippingMinorFor, isContentVersionId, catalogPinDigestFinding,
-  type CallerToken, type CatalogProduct, type CommerceEvidence, type CommerceEvidenceProvenance,
+  commerceTenantId, totalsMatch, shippingMinorFor, isContentVersionId, catalogPinDigestFinding, cartLineCode,
+  type CallerToken, type CatalogProduct, type CatalogVariant, type CommerceEvidence, type CommerceEvidenceProvenance,
   type CommerceProviderCartSnapshot, type FinalCartBinding, type TenantConfig,
 } from "@tot/public-runtime";
 import { fromD1 } from "@/lib/catalog/d1/catalog.js";
 import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
-import { evaluateFinalCart, type SeamView } from "@/lib/checkout/commerce/finalCartAuthorization.js";
+import { evaluateFinalCart, type RefusedLine, type SeamView } from "@/lib/checkout/commerce/finalCartAuthorization.js";
 import { d1CommerceRunner, reserveAllocation } from "@/lib/inventory/allocations.js";
 import { readMirrorBalance, readMirrorStock } from "@/lib/inventory/mirrorStock.js";
 import { admissionMatches, readCommerceAdmission, admissionSnapshotStatement } from "@/lib/checkout/commerce/commerceAdmission.js";
@@ -30,6 +30,17 @@ 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" } });
 }
 function deny(finding: string, status = 409, owner?: string): Response { return json({ ok: false, finding, ...(owner ? { owner } : {}) }, status); }
+/**
+ * Which check refused, and on which cart line (its index in the presented snapshot). Logged on
+ * the decision line only: closed check names and an index, never a SKU, price or cart value.
+ */
+interface RefusalDetail { check: string; line?: number }
+const refusalDetails = new WeakMap<Response, RefusalDetail>();
+function refuse(finding: string, detail: RefusalDetail, status = 409): Response {
+  const response = deny(finding, status);
+  refusalDetails.set(response, detail);
+  return response;
+}
 function list(value: string | undefined): string[] | null {
   if (!value) return null;
   try {
@@ -85,7 +96,11 @@ async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot,
     const { decision } = await evaluatePreflight({ locals: { tenant: context.locals.tenant, tot: {
       getProductByHandle: async (handle: string) => selected.get(handle) ?? null,
     } } } as APIContext, {
-      lines: snapshot.lines.map(line => ({ handle: products.find(p => p.variants.some(v => v.sku === line.sku))!.handle, sku: line.sku, quantity: line.quantity })),
+      lines: snapshot.lines.map(line => {
+        const product = products.find(p => p.variants.some(v => cartLineCode(v) === line.sku))!;
+        const variant = product.variants.find(v => cartLineCode(v) === line.sku)!;
+        return { handle: product.handle, variantId: variant.id, sku: line.sku, quantity: line.quantity };
+      }),
       destination: snapshot.destination,
       ...(policy.verification === "required" && snapshot.verificationRef ? { verificationRef: snapshot.verificationRef } : {}),
     }, { verification: policy.verification, rules: policy.rules });
@@ -93,8 +108,19 @@ async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot,
     const blocks = decision.blocks;
     if (blocks.length === 0) return { status: "clear", verified };
     const flavors = [...new Set(blocks.flatMap(block => block.code === "flavored_prohibited" ? block.flavors ?? [] : []))];
+    const titleOf = (sku: string) => products.find(p => p.variants.some(v => v.sku === sku))?.title;
+    const seen = new Set<string>();
+    const lines: RefusedLine[] = [];
+    for (const block of blocks) {
+      if (block.failedClosed === true || typeof block.message !== "string" || !block.message) continue;
+      const key = `${block.code}\n${block.sku ?? ""}\n${block.message}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const title = block.sku ? titleOf(block.sku) : undefined;
+      lines.push({ code: block.code, message: block.message, ...(block.sku ? { sku: block.sku } : {}), ...(title ? { title } : {}) });
+    }
     return { status: "blocked", verified, failedClosed: blocks.some(block => block.failedClosed === true), codes: blocks.map(block => block.code),
-      ...(flavors.length ? { flavors } : {}) };
+      ...(flavors.length ? { flavors } : {}), ...(lines.length ? { lines } : {}) };
   } catch { return { status: "absent", verified: false }; }
 }
 function fullCartProduct(value: unknown, handle: string, scope: string): value is CatalogProduct {
@@ -132,8 +158,11 @@ export async function POST(context: APIContext): Promise<Response> {
   if (response.status !== 200 || threw) {
     try { finding = String((await response.clone().json() as { finding?: unknown }).finding ?? "unreadable").slice(0, 80); } catch { finding = "unreadable"; }
   }
+  const detail = refusalDetails.get(response);
   try {
-    console.info("commerce-final-cart-decision", JSON.stringify({ correlationId, ok: response.status === 200, finding, status: response.status, threw, ms: Date.now() - started }));
+    console.info("commerce-final-cart-decision", JSON.stringify({ correlationId, ok: response.status === 200, finding,
+      ...(detail ? { check: detail.check, ...(detail.line === undefined ? {} : { line: detail.line }) } : {}),
+      status: response.status, threw, ms: Date.now() - started }));
   } catch { /* Diagnostic delivery cannot alter the decision. */ }
   return response;
 }
@@ -189,31 +218,39 @@ async function authorize(context: APIContext): Promise<Response> {
   try { listing = await tot.getAllActiveProducts(); } catch { return deny("catalog-unavailable", 503); }
   if (!Array.isArray(listing)) return deny("catalog-unavailable", 503);
   const selected = new Map<string, CatalogProduct>();
-  if (snapshot.currency !== resolveStoreCurrency(tenant.currency)) return deny("catalog-cart-mismatch");
-  for (const line of snapshot.lines) {
+  const mismatch = (check: string, line?: number) => refuse("catalog-cart-mismatch", line === undefined ? { check } : { check, line });
+  if (snapshot.currency !== resolveStoreCurrency(tenant.currency)) return mismatch("store-currency");
+  // A line's `sku` is the product code the page signed (`cartLineCode`): the SKU, or the
+  // variant id for a variant with none.
+  const coded = (line: { sku: string }) => (variant: CatalogVariant | null | undefined) => !!variant && cartLineCode(variant) === line.sku;
+  for (const [index, line] of snapshot.lines.entries()) {
     const matches = listing.flatMap(product => product && product.status === "active" && (!product.visibility || product.visibility === "public") && product.tenant_id === tenant.tot_data_scope && Array.isArray(product.variants)
-      ? product.variants.filter(v => v && v.sku === line.sku).map(variant => ({ product, variant })) : []);
-    if (matches.length !== 1) return deny("catalog-cart-mismatch");
+      ? product.variants.filter(coded(line)).map(variant => ({ product, variant })) : []);
+    if (matches.length !== 1) return mismatch(matches.length === 0 ? "sku-not-in-catalog" : "sku-ambiguous", index);
     const match = matches[0]!;
     const handle = match.product.handle;
-    if (typeof handle !== "string" || !handle) return deny("catalog-cart-mismatch");
+    if (typeof handle !== "string" || !handle) return mismatch("product-handle", index);
     if (!selected.has(handle)) {
       let detail: CatalogProduct | null;
       try { detail = await tot.getProductByHandle(handle); } catch { return deny("catalog-unavailable", 503); }
-      if (!fullCartProduct(detail, handle, tenant.tot_data_scope)) return deny("catalog-cart-mismatch");
+      if (!fullCartProduct(detail, handle, tenant.tot_data_scope)) return mismatch("product-detail", index);
       selected.set(handle, detail);
     }
     const detail = selected.get(handle)!;
-    if (detail.id !== match.product.id) return deny("catalog-cart-mismatch");
-    const variants = detail.variants.filter(variant => variant.sku === line.sku);
-    if (variants.length !== 1 || variants[0]!.id !== match.variant.id) return deny("catalog-cart-mismatch");
+    if (detail.id !== match.product.id) return mismatch("product-id", index);
+    const variants = detail.variants.filter(coded(line));
+    if (variants.length !== 1 || variants[0]!.id !== match.variant.id) return mismatch("variant-detail", index);
     const variant = variants[0]!;
     const digits = new Intl.NumberFormat("en", { style: "currency", currency: snapshot.currency }).resolvedOptions().maximumFractionDigits ?? 2;
     const scaled = variant.price * 10 ** digits;
-    if (!variant.inventory.available || variant.currency !== snapshot.currency || Math.abs(scaled - Math.round(scaled)) > 0.000001 || Math.round(scaled) !== line.unitMinor) return deny("catalog-cart-mismatch");
+    if (!variant.inventory.available) return mismatch("unavailable", index);
+    if (variant.currency !== snapshot.currency) return mismatch("variant-currency", index);
+    if (Math.abs(scaled - Math.round(scaled)) > 0.000001) return mismatch("price-precision", index);
+    if (Math.round(scaled) !== line.unitMinor) return mismatch("price", index);
   }
   const products = [...selected.values()];
-  if (snapshot.lines.some(line => products.flatMap(product => product.variants.filter(variant => variant.sku === line.sku)).length !== 1)) return deny("catalog-cart-mismatch");
+  const ambiguous = snapshot.lines.findIndex(line => products.flatMap(product => product.variants.filter(coded(line))).length !== 1);
+  if (ambiguous !== -1) return mismatch("sku-ambiguous", ambiguous);
   // Shipping is re-derived from the store's own declaration, never from the cart: a cart that
   // dropped, replayed or altered its signed `shipping_policy` option was charged another amount.
   if (tenant.shipping) {
@@ -280,8 +317,10 @@ async function authorize(context: APIContext): Promise<Response> {
     seam: seamView, catalogAvailable: true, browserConfirmed: false, token,
     trustedIssuers: issuers, expectedAudience: audience, activeKids, stockTracked, authorities });
   if (!decision.ok) {
-    if (decision.finding === "verification-refused:flavored_prohibited" && seamView.flavors) {
-      return json({ ok: false, finding: decision.finding, flavors: seamView.flavors }, 409);
+    if (decision.finding.startsWith("verification-refused") && (seamView.flavors || seamView.lines)) {
+      return json({ ok: false, finding: decision.finding,
+        ...(decision.finding === "verification-refused:flavored_prohibited" && seamView.flavors ? { flavors: seamView.flavors } : {}),
+        ...(seamView.lines ? { lines: seamView.lines } : {}) }, 409);
     }
     return deny(decision.finding, 409, decision.owner);
   }

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

@@ -1,28 +1,50 @@
 import type { APIRoute } from "astro";
 import { commerceTenantId } from "@tot/public-runtime";
-import { bindCartSession, CART_UNAVAILABLE_MESSAGE, withCartSession } from "@/lib/checkout/commerce/cartSession.js";
+import {
+  bindCartSession,
+  CART_UNAVAILABLE_MESSAGE,
+  cartSessionCookiePath,
+  cartSessionCookieVisible,
+  withCartSession,
+} from "@/lib/checkout/commerce/cartSession.js";
 import { managedCartHref } from "@/lib/content/chrome/managedCart.js";
 
 export const prerender = false;
 
+const NO_STORE = "private, no-store";
+
 /**
- * Backward-compatible entry for bookmarked or tenant-authored `/cart` links.
- * Chrome now links straight to managed checkout, but this route prevents stale
- * links from falling through the content catch-all to a misleading storefront
- * 404. Tenant resolution and preview authorization have already run in
- * middleware before this redirect is selected. The redirect carries this
- * tenant's Foxy session and never the shared cart.
+ * Entry for bookmarked or tenant-authored `/cart` links. Chrome links straight to
+ * managed checkout, but this route keeps those links from falling through the
+ * content catch-all to a misleading storefront 404. Tenant resolution and preview
+ * authorization have already run in middleware before this redirect is selected.
+ * The redirect carries this tenant's Foxy session and never the shared cart.
+ *
+ * The session cookie lives on the tenant prefix. A link on a pinned preview page
+ * arrives from outside it, without the cookie, so it is sent to the tenant prefix
+ * first: binding there reads the shopper's own session instead of minting an empty
+ * one over it.
  */
 export const GET: APIRoute = async (context) => {
   const location = managedCartHref(context.locals.commerce);
   if (!location || !context.locals.commerce) return new Response(null, { status: 404 });
+  // `basePath` is the prefix the browser is on: a pinned render overrides it to the
+  // pin's own prefix, while `apiBasePath` stays the tenant prefix the cookie lives on.
+  const cookiePath = cartSessionCookiePath(context.locals.apiBasePath ?? context.locals.basePath ?? "");
+  const pagePrefix = cartSessionCookiePath(context.locals.basePath ?? context.locals.apiBasePath ?? "");
+  if (!cartSessionCookieVisible(pagePrefix, cookiePath)) {
+    return new Response(null, {
+      status: 302,
+      headers: { location: `${cookiePath}cart`, "cache-control": NO_STORE },
+    });
+  }
   const tenantId = context.locals.tenant ? commerceTenantId(context.locals.tenant) : "";
   const sessionId = tenantId ? await bindCartSession(context, context.locals.commerce, tenantId) : null;
   if (!sessionId) {
     return new Response(CART_UNAVAILABLE_MESSAGE, {
       status: 503,
       headers: {
-        "cache-control": "private, no-store",
+        "cache-control": NO_STORE,
         "content-type": "text/plain; charset=utf-8",
       },
     });
@@ -31,7 +53,7 @@ export const GET: APIRoute = async (context) => {
     status: 302,
     headers: {
       location: withCartSession(location, sessionId),
-      "cache-control": "private, no-store",
+      "cache-control": NO_STORE,
     },
   });
 };

package/apps/storefront/src/pages/tenants/[id]/[...path].ts

@@ -158,16 +158,26 @@ export async function GET(context: APIContext): Promise<Response> {
   const previewVersionId = pinnedVersionId ?? sharedPreview.versionId;
 
   const pathname = url.pathname;
+  const publicationChannel =
+    sharedPreview.preview || context.locals.customizationEnv === "test" ? "preview" : "live";
   const fromPublication = await tryServePublicationRootAsset({
     tenant: context.locals.tenant,
     bucket: bucket as unknown as PublicationArtifactReadBucketV1,
     kvGet: (key) => kv.get(key),
     tenantId: urlTenant,
     pathname,
-    channel: sharedPreview.preview || context.locals.customizationEnv === "test" ? "preview" : "live",
+    channel: publicationChannel,
     ifNoneMatch: context.request.headers.get("if-none-match"),
   });
-  if (fromPublication) return fromPublication;
+  if (fromPublication) {
+    // Preview bytes answer a tokenless URL (the credential rides in a cookie), so
+    // they must never be cached where the next visitor of that URL would get them.
+    if (publicationChannel === "preview") {
+      fromPublication.headers.set("cache-control", "no-store");
+      fromPublication.headers.set("x-robots-tag", "noindex, nofollow");
+    }
+    return fromPublication;
+  }
 
   if (previewVersionId) {
     const overlay = await tryServePreviewRewriteOverlay({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.3.4",
+  "version": "4.5.0",
   "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/declared-config.mjs

@@ -782,6 +782,16 @@ export const CONSPICUITY_FLOOR = Object.freeze({ contrast: 7, fontSizePx: 12, fo
 /** Bounds on the size a custom style may declare, so the bar cannot swallow the header. */
 const MAX_FONT_SIZE_PX = 24;
 
+/** Bounds on the optional box and spacing keys; an unset key renders the preset's own frame. */
+export const NICOTINE_WARNING_BOX_BOUNDS = Object.freeze({
+  borderWidthPx: Object.freeze({ min: 0, max: 8, integer: true }),
+  paddingYPx: Object.freeze({ min: 0, max: 24, integer: true }),
+  letterSpacingPx: Object.freeze({ min: 0, max: 4, integer: false }),
+});
+
+/** Weight 500 is allowed only on a boxed bar that is at least this large, contrasty and bordered. */
+export const MEDIUM_WEIGHT_REQUIREMENTS = Object.freeze({ fontSizePx: 16, contrast: 7, borderWidthPx: 2 });
+
 export const DEFAULT_NICOTINE_WARNING_PRESET = "dark";
 
 /**
@@ -816,6 +826,9 @@ export const NICOTINE_WARNING_PRESETS = Object.freeze({
  *   textTransform: "uppercase" | "none",
  *   fontWeight: number,
  *   fontSizePx: number,
+ *   borderWidthPx?: number,
+ *   paddingYPx?: number,
+ *   letterSpacingPx?: number,
  * }} NicotineWarningPresentation
  */
 
@@ -824,9 +837,10 @@ export const NICOTINE_WARNING_KEYS = Object.freeze(["preset", "style", "checkWid
 
 export const NICOTINE_WARNING_STYLE_KEYS = Object.freeze([
   "background", "text", "border", "textTransform", "fontWeight", "fontSizePx",
+  "borderWidthPx", "paddingYPx", "letterSpacingPx",
 ]);
 const TEXT_TRANSFORMS = ["uppercase", "none"];
-const FONT_WEIGHTS = [600, 700, 800, 900];
+const FONT_WEIGHTS = [500, 600, 700, 800, 900];
 const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
 
 /** `#abc` / `#AABBCC` → `#aabbcc`. */
@@ -865,7 +879,15 @@ export function conspicuityProblems(p) {
     out.push(`font size ${p.fontSizePx}px is below the ${CONSPICUITY_FLOOR.fontSizePx}px floor`);
   }
   if (p.fontWeight < CONSPICUITY_FLOOR.fontWeight) {
-    out.push(`font weight ${p.fontWeight} is below the ${CONSPICUITY_FLOOR.fontWeight} floor`);
+    const need = MEDIUM_WEIGHT_REQUIREMENTS;
+    const medium = p.fontWeight === 500 && p.fontSizePx >= need.fontSizePx && ratio >= need.contrast
+      && (p.borderWidthPx ?? 0) >= need.borderWidthPx;
+    if (!medium) {
+      out.push(`font weight ${p.fontWeight} is below the ${CONSPICUITY_FLOOR.fontWeight} floor` +
+        (p.fontWeight === 500
+          ? ` (500 needs font size >= ${need.fontSizePx}px, contrast >= ${need.contrast}:1 and borderWidthPx >= ${need.borderWidthPx})`
+          : ""));
+    }
   }
   return out;
 }
@@ -885,6 +907,14 @@ function styleValueProblem(key, value) {
       return typeof value === "number" && Number.isFinite(value) && value >= CONSPICUITY_FLOOR.fontSizePx && value <= MAX_FONT_SIZE_PX
         ? null
         : `\`fontSizePx\` must be a number from ${CONSPICUITY_FLOOR.fontSizePx} to ${MAX_FONT_SIZE_PX}`;
+    case "borderWidthPx":
+    case "paddingYPx":
+    case "letterSpacingPx": {
+      const { min, max, integer } = NICOTINE_WARNING_BOX_BOUNDS[key];
+      return typeof value === "number" && Number.isFinite(value) && value >= min && value <= max && (!integer || Number.isInteger(value))
+        ? null
+        : `\`${key}\` must be ${integer ? "a whole number" : "a number"} from ${min} to ${max}`;
+    }
     default:
       return `\`${key}\` is not a nicotine-warning style key (allowed: ${NICOTINE_WARNING_STYLE_KEYS.join(", ")})`;
   }
@@ -993,7 +1023,10 @@ export function nicotineWarningCheckWidths(declaration) {
  */
 export function describeNicotineWarningPresentation(p) {
   return `background ${p.background}, text ${p.text}, border ${p.border}, ` +
-    `${p.textTransform === "uppercase" ? "uppercase" : "normal case"}, weight ${p.fontWeight}, ${p.fontSizePx}px`;
+    `${p.textTransform === "uppercase" ? "uppercase" : "normal case"}, weight ${p.fontWeight}, ${p.fontSizePx}px` +
+    (p.borderWidthPx === undefined ? "" : `, border width ${p.borderWidthPx}px`) +
+    (p.paddingYPx === undefined ? "" : `, vertical padding ${p.paddingYPx}px`) +
+    (p.letterSpacingPx === undefined ? "" : `, letter spacing ${p.letterSpacingPx}px`);
 }
 
 /**
@@ -1017,11 +1050,12 @@ export function describeNicotineWarningPresentation(p) {
  */
 export function nicotineWarningHtml(declaration, variant) {
   const { presentation, preset } = resolveNicotineWarning(declaration);
+  const barPadding = presentation.paddingYPx === undefined ? "0.5rem" : `${presentation.paddingYPx}px`;
   const attrs = `style="${nicotineWarningStyle(presentation, variant)}" role="note" aria-label="Health warning" ` +
     `data-compliance="nicotine-warning" data-nicotine-warning-preset="${preset ?? "custom"}"`;
   const text = NICOTINE_WARNING_TEXT_LOCK;
   return variant === "bar"
-    ? `<div ${attrs}><p class="container-prose" style="margin-block:0;padding-block:0.5rem;text-align:center;${text}">${NICOTINE_WARNING_TEXT}</p></div>`
+    ? `<div ${attrs}><p class="container-prose" style="margin-block:0;padding-block:${barPadding};text-align:center;${text}">${NICOTINE_WARNING_TEXT}</p></div>`
     : `<div ${attrs}><p style="margin:0;${text}">${NICOTINE_WARNING_TEXT}</p></div>`;
 }
 
@@ -1061,15 +1095,17 @@ const NICOTINE_WARNING_TEXT_LOCK = [
  */
 export function nicotineWarningStyle(p, variant) {
   const size = variant === "block" ? Math.max(p.fontSizePx, 14) : p.fontSizePx;
+  const boxed = `${p.borderWidthPx ?? 2}px`;
   const frame = variant === "bar"
-    ? [`border-bottom:2px solid ${p.border}`]
-    : [`border:2px solid ${p.border}`, "border-radius:var(--radius-md)", "padding:0.75rem 1rem"];
+    ? [p.borderWidthPx === undefined ? `border-bottom:2px solid ${p.border}` : `border:${boxed} solid ${p.border}`]
+    : [`border:${boxed} solid ${p.border}`, "border-radius:var(--radius-md)",
+      `padding:${p.paddingYPx === undefined ? "0.75rem" : `${p.paddingYPx}px`} 1rem`];
   return [
     ...frame,
     `background-color:${p.background}`,
     `color:${p.text}`,
     `text-transform:${p.textTransform}`,
-    `letter-spacing:${p.textTransform === "uppercase" ? "0.06em" : "normal"}`,
+    `letter-spacing:${p.letterSpacingPx !== undefined ? `${p.letterSpacingPx}px` : p.textTransform === "uppercase" ? "0.06em" : "normal"}`,
     `font-weight:${p.fontWeight}`,
     `font-size:${size}px`,
     "line-height:1.4",

package/packages/public-runtime/package.json

@@ -10,6 +10,7 @@
   "exports": {
     ".": "./src/index.ts",
     "./blog-visibility": "./src/blog-visibility.mjs",
+    "./preview-url": "./src/preview-url.mjs",
     "./publication-redirects": "./src/publication-redirects.mjs",
     "./image-dependencies": "./src/image-dependencies.ts",
     "./image-finding-dependencies": "./src/image-finding-dependencies.ts",

package/packages/public-runtime/src/checkout.ts

@@ -500,6 +500,14 @@ export function resolveManagedCheckout(
   };
 }
 
+/**
+ * The checkout product code for a variant: its SKU, or its id when it has none. Every field
+ * is hashed against it, and the final-cart authority finds a cart line's variant by it.
+ */
+export function cartLineCode(variant: Pick<CatalogVariant, "id" | "sku">): string {
+  return variant.sku && variant.sku.length ? variant.sku : variant.id;
+}
+
 /**
  * The raw (unsigned) cart fields for a variant: name, price, code, image, the
  * variant's options, and an editable quantity. `code` is the checkout product code
@@ -511,7 +519,7 @@ export function cartFieldsForVariant(
   purchaseOption?: ProductPurchaseOption,
   opts?: { signedPrice?: number; tenantId?: string; currency?: string; contentVersionId?: string },
 ): { code: string; fields: CartField[] } {
-  const code = variant.sku && variant.sku.length ? variant.sku : variant.id;
+  const code = cartLineCode(variant);
   const image = product.images.find((i) => i.id === variant.image_id)?.url ??
     product.images[0]?.url;
   // The signed price is either the caller's member-adjusted EFFECTIVE price

package/packages/public-runtime/src/preview-url.d.mts

@@ -0,0 +1,10 @@
+export const PREVIEW_URL_SHAPE: string;
+export function previewPath(store: string, subPath?: string): string;
+export function previewUrl(origin: string, store: string): string;
+export function previewPrUrl(origin: string, store: string, prNumber: number | string): string | null;
+export function previewRevUrl(origin: string, store: string, versionId: string): string;
+export function legacyPreviewLocation(
+  pathname: string,
+  search: string | undefined,
+  isStore: (segment: string) => boolean,
+): string | null;

package/packages/public-runtime/src/preview-url.mjs

@@ -0,0 +1,54 @@
+/**
+ * The one builder of preview URLs. A store's preview lives under the store, never under a
+ * `/preview/<store>` prefix:
+ *
+ *   <origin>/<store>/preview             the store's current shared preview
+ *   <origin>/<store>/preview/pr/<n>      candidate PR n
+ *   <origin>/<store>/preview/rev/<sha>/  an immutable revision
+ *
+ * Every producer (Worker, CLI) calls these; `apps/storefront/src/pages/preview/preview-url-routes.test.ts`
+ * resolves each shape against the page route table. `packages/cli/src/preview-url.mjs` is a
+ * byte-identical copy (a CLI test pins it).
+ */
+
+/** The canonical shapes, for messages that name the right URL. */
+export const PREVIEW_URL_SHAPE = "/<store>/preview[/pr/<n>]";
+
+function trimOrigin(origin) {
+  return String(origin).trim().replace(/\/+$/, "");
+}
+
+/** `/<store>/preview` with an optional sub-path (`/pr/5`). */
+export function previewPath(store, subPath = "") {
+  return `/${encodeURIComponent(store)}/preview${subPath}`;
+}
+
+export function previewUrl(origin, store) {
+  return `${trimOrigin(origin)}${previewPath(store)}`;
+}
+
+/** `null` when `prNumber` is not a positive integer. */
+export function previewPrUrl(origin, store, prNumber) {
+  const n = Number(prNumber);
+  if (!Number.isInteger(n) || n < 1) return null;
+  return `${trimOrigin(origin)}${previewPath(store, `/pr/${n}`)}`;
+}
+
+export function previewRevUrl(origin, store, versionId) {
+  return `${trimOrigin(origin)}${previewPath(store, `/rev/${encodeURIComponent(versionId)}/`)}`;
+}
+
+/**
+ * The canonical location for a legacy `/preview/<store>[/pr/<n>[/...]]` request, or `null` when
+ * the path is not that shape. `isStore` decides whether the first segment names a store
+ * (the caller owns what a store id looks like), so `/preview/pr/5`, `/preview/rev/...` and the
+ * other first-segment routes are never read as a store.
+ */
+export function legacyPreviewLocation(pathname, search, isStore) {
+  const m = /^\/preview\/([^/]+)(\/.*)?$/.exec(pathname);
+  if (!m) return null;
+  const store = m[1];
+  if (!/^[A-Za-z0-9.-]+$/.test(store) || !isStore(store)) return null;
+  const rest = (m[2] ?? "").replace(/\/+$/, "");
+  return `/${store}/preview${rest}${search ?? ""}`;
+}

package/packages/public-runtime/src/tenant.ts

@@ -296,6 +296,9 @@ export interface NicotineWarningDeclaration {
     textTransform?: "uppercase" | "none";
     fontWeight?: number;
     fontSizePx?: number;
+    borderWidthPx?: number;
+    paddingYPx?: number;
+    letterSpacingPx?: number;
   };
 }