@tokenoftrust/storefront-runner 2.5.5 → 3.0.0

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

@@ -0,0 +1,95 @@
+/**
+ * Who may check out on the shared ToT test store, and what evidence that store requires.
+ *
+ * Every registered tenant whose checkout resolves to the shared test store is admitted, until it
+ * installs its own store. The cart's `tenant` option is HMAC-signed by storefront and the shared
+ * store enforces cart validation, so a shopper cannot name another tenant; the shared store's cart
+ * secret is therefore never issued to a partner. Production never declares the test tier, so it
+ * admits no one here.
+ */
+import { commerceTenantId, SHARED_DEMO_CHECKOUT, type CustomizationEnv, type TenantConfig } from "@tot/public-runtime";
+import { resolveAdminTargetTenant } from "@/config/adminTargetTenant";
+import { resolveTenantCommerce } from "@/lib/checkout/shared/checkoutCommerce";
+import { readEnv } from "@/lib/publication/shared/runtimeEnv";
+import { readCheckoutRequirements, type CheckoutRequirements } from "./checkoutRequirements";
+
+export type SharedStoreFinding =
+  | "tenant-unregistered"
+  | "shared-store-unavailable"
+  | "checkout-unconfigured"
+  | "tenant-own-store";
+
+export type SharedStoreAdmission =
+  | { ok: true; tenant: TenantConfig }
+  | { ok: false; finding: SharedStoreFinding };
+
+/** Admit `tenantId` to the shared test store: registered, test tier, and its checkout resolves there. */
+export async function admitSharedStoreTenant(tenantId: string): Promise<SharedStoreAdmission> {
+  const tenant = await resolveAdminTargetTenant(tenantId);
+  if (!tenant || commerceTenantId(tenant) !== tenantId) return { ok: false, finding: "tenant-unregistered" };
+  if ((await readEnv("COMMERCE_DEMO_CHECKOUT_TIER")) !== "test") return { ok: false, finding: "shared-store-unavailable" };
+  const commerce = await resolveTenantCommerce(tenant);
+  if (!commerce || commerce.mode !== "signed") return { ok: false, finding: "checkout-unconfigured" };
+  if (commerce.storeSubDomain !== SHARED_DEMO_CHECKOUT.storeSubDomain) return { ok: false, finding: "tenant-own-store" };
+  return { ok: true, tenant };
+}
+
+export type EvidenceRequirement = "required" | "not-required";
+export type SharedStoreEvidencePolicy = Record<"verification" | "tax" | "risk", EvidenceRequirement> & {
+  /** Whether compliance rules (destination, flavor, purchase limits) block at final cart. */
+  rules: "enforce" | "off";
+};
+
+/** Provenance stamped on evidence the shared test store's policy does not require. */
+export const SHARED_STORE_POLICY_SOURCE = "shared-test-store-default";
+export const SHARED_STORE_POLICY_REVISION = "shared-test-store-v1";
+/** Provenance stamped on verification the live provider confirmed for a store that requires it. */
+export const SHARED_STORE_VERIFICATION_SOURCE = "tot-verification-provider";
+
+/**
+ * What the shared test store requires of a tenant, from the store's saved checkout requirements.
+ * Nothing blocks by default, regulated tenants included. Each switch the store turns on in /admin
+ * only adds a requirement. Requirements that cannot be read (`null`) require everything, so a
+ * corrupt or unreachable setting is never weaker than what the store saved. Nothing produces risk
+ * evidence, so risk is never required here.
+ */
+export function testStoreEvidencePolicy(requirements: CheckoutRequirements | null): SharedStoreEvidencePolicy {
+  const saved = requirements ?? { verification: true, tax: true, rules: true };
+  return {
+    verification: saved.verification ? "required" : "not-required",
+    tax: saved.tax ? "required" : "not-required",
+    risk: "not-required",
+    rules: saved.rules ? "enforce" : "off",
+  };
+}
+
+/**
+ * The shared test store's policy for a tenant whose checkout resolves there, or `null` for every
+ * other checkout (its own store, or any tier but test), which keeps the full fail-closed contract.
+ */
+export async function sharedStorePolicy(
+  tenant: Pick<TenantConfig, "tenant_id">,
+  commerce: { storeSubDomain?: string } | null | undefined,
+  env: CustomizationEnv,
+): Promise<SharedStoreEvidencePolicy | null> {
+  if (!(await usesSharedTestStore(commerce))) return null;
+  return testStoreEvidencePolicy(await readCheckoutRequirements(tenant.tenant_id, env));
+}
+
+/** True when this checkout resolves to the shared ToT test store on the test tier. */
+export async function usesSharedTestStore(commerce: { storeSubDomain?: string } | null | undefined): Promise<boolean> {
+  return commerce?.storeSubDomain === SHARED_DEMO_CHECKOUT.storeSubDomain && (await readEnv("COMMERCE_DEMO_CHECKOUT_TIER")) === "test";
+}
+
+/**
+ * Whether the storefront's checkout compliance gate runs before handoff. It follows the shared
+ * test store's policy for a tenant checking out there; every other checkout keeps the gate.
+ */
+export async function checkoutComplianceGateRequired(
+  tenant: Pick<TenantConfig, "tenant_id">,
+  commerce: { storeSubDomain?: string } | null | undefined,
+  env: CustomizationEnv,
+): Promise<boolean> {
+  const policy = await sharedStorePolicy(tenant, commerce, env);
+  return !policy || policy.rules === "enforce" || policy.verification === "required";
+}

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

@@ -0,0 +1,191 @@
+/**
+ * Deferred managed-checkout loader bootstrap.
+ *
+ * The provider loader pulls a cart-drawer bundle (jQuery + sidecart) that costs
+ * ~150 ms of main-thread time on mobile — and shoppers who never touch the cart
+ * pay it anyway. This bootstrap injects the provider's `loader.js` once, on the
+ * first of: shopper input that can reach a commerce control, or a quiet-period
+ * timer after `load`.
+ *
+ * Commerce intent is a pointer, touch or key press made while a commerce control
+ * (a managed add-to-cart form, or a link or form targeting the cart origin) is
+ * reachable — not inside an `inert` subtree. Focus is never intent: a dialog that
+ * takes focus on load (the age gate) fires a trusted `focusin` with no shopper
+ * input at all, and a keyboard shopper's own focus moves arrive as `keydown`.
+ * Input on a modal that has inerted the page cannot reach a cart control, so it
+ * does not count either.
+ *
+ * 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.
+ *
+ * On a store that is not public (`storeNotPublic`), a managed add-to-cart is
+ * checked before it leaves the page: the checkout route refuses a viewer admitted
+ * only by a preview grant, so instead of navigating to the gate's holding page
+ * the form says checkout is unavailable here and offers sign-in. A public store
+ * never pays that round trip.
+ *
+ * Emitted by <CheckoutLoader> with the page nonce (an attribute cannot carry
+ * one), and identical on the Cloudflare-served preview and the statically
+ * published (CloudFront/S3) output — both render Layout.astro.
+ */
+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;
+
+export const LAZY_CHECKOUT_LOADER_EVENTS = ["pointerdown", "keydown", "touchstart"] as const;
+
+/** The platform's add-to-cart form, which posts to the worker cart route rather than the cart origin. */
+export const MANAGED_CART_FORM_SELECTOR = "form[data-managed-cart]";
+
+export const STORE_NOT_PUBLIC_CHECKOUT_MESSAGE =
+  "This store isn't open to the public yet, so checkout is unavailable here. Sign in to the store to test checkout.";
+
+export interface LazyCheckoutLoaderOptions {
+  loaderSrc: string;
+  /** `https://<store domain>` — the cart origin whose links and forms the drawer takes over. */
+  cartOrigin: string;
+  /** The store is not public on this host, so its checkout route may refuse this viewer. */
+  storeNotPublic?: boolean;
+}
+
+/** JSON for a script literal: `<` is escaped so a value can never close the surrounding <script>. */
+function literal(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+export function lazyCheckoutLoaderJs(options: LazyCheckoutLoaderOptions): string {
+  const managedCart = literal(MANAGED_CART_FORM_SELECTOR);
+  return `(function () {
+  var src = ${literal(options.loaderSrc)};
+  var cartOrigin = ${literal(options.cartOrigin)};
+  var storeNotPublic = ${options.storeNotPublic ? "true" : "false"};
+  var events = ${literal(LAZY_CHECKOUT_LOADER_EVENTS)};
+  var state = 'idle';
+  var waiters = [];
+  function targetsCart(url) {
+    if (!url) return false;
+    try { return new URL(url, document.baseURI).origin === cartOrigin; } catch (e) { return false; }
+  }
+  function commerceReachable() {
+    var nodes = document.querySelectorAll(${managedCart} + ', a[href], form[action]');
+    for (var i = 0; i < nodes.length; i++) {
+      var n = nodes[i];
+      if (n.closest('[inert]')) continue;
+      if (n.matches(${managedCart}) || targetsCart(n.tagName === 'A' ? n.href : n.getAttribute('action'))) return true;
+    }
+    return false;
+  }
+  function ready() {
+    if (state === 'ready') return;
+    state = 'ready';
+    var run = waiters;
+    waiters = [];
+    for (var i = 0; i < run.length; i++) run[i]();
+  }
+  function start() {
+    if (state !== 'idle') return;
+    state = 'loading';
+    for (var i = 0; i < events.length; i++) document.removeEventListener(events[i], onInput, true);
+    setTimeout(ready, ${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.
+    s.addEventListener('load', function () {
+      var bundle = window.fc_script;
+      if (!bundle) return ready();
+      bundle.addEventListener('load', function () {
+        var client = window.FC && window.FC.client;
+        if (!client || typeof client.on !== 'function') return ready();
+        client.on('ready.done', ready);
+      });
+      bundle.addEventListener('error', ready);
+    });
+    s.addEventListener('error', ready);
+    document.body.appendChild(s);
+  }
+  function whenReady(fn) {
+    if (state === 'ready') return fn();
+    waiters.push(fn);
+    start();
+  }
+  function onInput() {
+    if (commerceReachable()) start();
+  }
+  for (var i = 0; i < events.length; i++) {
+    document.addEventListener(events[i], onInput, { capture: true, passive: true });
+  }
+  function arm() { setTimeout(start, ${LAZY_CHECKOUT_LOADER_IDLE_MS}); }
+  if (document.readyState === 'complete') arm();
+  else window.addEventListener('load', arm);
+
+  window.addEventListener('click', function (event) {
+    if (state === 'ready' || event.defaultPrevented) return;
+    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    var anchor = event.target && event.target.closest ? event.target.closest('a[href]') : null;
+    if (!anchor || anchor.target === '_blank' || !targetsCart(anchor.href)) return;
+    event.preventDefault();
+    whenReady(function () { anchor.click(); });
+  });
+
+  function resubmit(form) {
+    if (typeof form.requestSubmit === 'function') form.requestSubmit();
+    else form.submit();
+  }
+  function showUnavailable(form, signIn) {
+    var next = form.nextElementSibling;
+    if (next && next.hasAttribute('data-checkout-unavailable')) return;
+    var note = document.createElement('p');
+    note.setAttribute('role', 'alert');
+    note.setAttribute('data-checkout-unavailable', '');
+    note.className = 'mt-2 text-sm';
+    note.textContent = ${literal(STORE_NOT_PUBLIC_CHECKOUT_MESSAGE)} + ' ';
+    var link = document.createElement('a');
+    link.className = 'underline';
+    link.textContent = 'Sign in';
+    var login;
+    try { login = new URL(signIn || '/auth/login', location.origin); } catch (e) { login = new URL('/auth/login', location.origin); }
+    login.searchParams.set('next', location.pathname);
+    link.href = login.pathname + login.search;
+    note.appendChild(link);
+    form.insertAdjacentElement('afterend', note);
+  }
+  function proceed(form) {
+    form.dataset.checkoutReachable = '1';
+    resubmit(form);
+  }
+  window.addEventListener('submit', function (event) {
+    if (event.defaultPrevented) return;
+    var form = event.target;
+    if (!form || typeof form.getAttribute !== 'function') return;
+    if (storeNotPublic && form.matches(${managedCart}) && form.dataset.checkoutReachable !== '1') {
+      event.preventDefault();
+      // The handoff route's JSON form only mints an unattributed correlation, so it answers
+      // "may this viewer reach checkout?" without starting one. Any other answer, or no
+      // answer, submits natively and the route decides.
+      fetch(form.action, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: '{}',
+        credentials: 'same-origin',
+      }).then(function (res) {
+        if (res.status === 401 && res.headers.get('x-tot-gate') === 'store-not-public') {
+          return res.json().then(function (body) { return body && body.signIn; }, function () { return null; })
+            .then(function (signIn) { showUnavailable(form, signIn); });
+        }
+        proceed(form);
+      }, function () { proceed(form); });
+      return;
+    }
+    if (state === 'ready' || !targetsCart(form.getAttribute('action'))) return;
+    event.preventDefault();
+    whenReady(function () { resubmit(form); });
+  });
+})();`;
+}

package/apps/storefront/src/lib/compliance/browser/checkoutVerificationFlow.ts

@@ -234,6 +234,15 @@ export function verificationRefKey(
   return `tot:verify-ref:${preflightUrl}:${line.handle}:${variant}`;
 }
 
+/**
+ * sessionStorage key for the ref a cleared verification produced on this store. Every later
+ * line in the same session reuses it, so the whole cart carries one ref and the shopper
+ * verifies once; the server still re-reads its status on every preflight.
+ */
+export function verifiedRefKey(preflightUrl: string): string {
+  return `tot:verified-ref:${preflightUrl}`;
+}
+
 export function readStoredRef(key: string): string | null {
   try {
     const v = sessionStorage.getItem(key);

package/apps/storefront/src/lib/compliance/enforcement.ts

@@ -1,7 +1,7 @@
 /**
  * Compliance enforcement ADAPTER — the request-scoped bridge between a resolved
  * tenant and the pure `@tot/public-runtime` enforcement engine. It:
- *   - decides whether a tenant is REGULATED (age/nicotine),
+ *   - decides whether a tenant is REGULATED (from the obligation registry),
  *   - resolves its data-driven ruleset (fail-closed: regulated + no ruleset ⇒ null),
  *   - wires the LIVE verification provider from operational env
  *     (`TOT_VERIFICATION_PROVIDER`) — absent ⇒ the verification gate fails closed,
@@ -17,16 +17,18 @@ import type {
   ComplianceRuleset,
   EnforcementEvidenceSignals,
 } from "@tot/public-runtime";
-import { enforcementSignals } from "@tot/public-runtime";
+import { enforcementSignals, isRegulated } from "@tot/public-runtime";
 import { readEnv } from "@/lib/publication/shared/env";
 import { COMPLIANCE_RULE_PROFILES } from "@/config/compliance/rulesets";
 
-/** True when the tenant sells age/nicotine-restricted goods (drives fail-closed). */
+/**
+ * True when the tenant's declared obligations put it on the regulated surface (drives
+ * fail-closed). The obligation registry decides; this never restates which keys count.
+ */
 export function isRegulatedTenant(
   tenant: Pick<TenantConfig, "compliance">,
 ): boolean {
-  const c = tenant.compliance;
-  return !!c && ((c.minAge != null && c.minAge > 0) || !!c.nicotineWarning);
+  return isRegulated({ compliance: tenant.compliance });
 }
 
 /**

package/apps/storefront/src/lib/content/seo/structuredData.ts

@@ -23,8 +23,7 @@ type Node = Record<string, unknown>;
 type Profile = NonNullable<NonNullable<TenantConfig["seo"]>["structuredData"]>;
 
 /** What a page knows about itself, for the nodes that describe it. Every field is optional. */
-export interface StructuredDataPage {
-  pageType: StructuredDataPageType;
+interface StructuredDataPageFields {
   /** The page's primary image, site-relative or absolute. */
   image?: string | null;
   author?: { name: string; url?: string } | null;
@@ -41,6 +40,16 @@ export interface StructuredDataPage {
   items?: { title: string; url: string }[];
 }
 
+/**
+ * A `collection` page names its breadcrumb trail: a declared `BreadcrumbList` has nothing to emit
+ * without one, so an archive that omits it would render no JSON-LD at all.
+ */
+export type StructuredDataPage = StructuredDataPageFields &
+  (
+    | { pageType: Exclude<StructuredDataPageType, "collection"> }
+    | { pageType: "collection"; crumbs: NonNullable<StructuredDataPageFields["crumbs"]> }
+  );
+
 /** The tenant's declared profile, or null when it declares none. */
 export function structuredDataProfile(tenant: Pick<TenantConfig, "seo"> | undefined): Profile | null {
   return tenant?.seo?.structuredData ?? null;
@@ -50,7 +59,7 @@ export function structuredDataProfile(tenant: Pick<TenantConfig, "seo"> | undefi
  * A product with more than one variant is a `productGroup` when the profile declares that graph;
  * every other page type maps to itself.
  */
-export function productPageType(profile: Profile | null, product: CatalogProduct): StructuredDataPageType {
+export function productPageType(profile: Profile | null, product: CatalogProduct): "product" | "productGroup" {
   return product.variants.length > 1 && profile?.graphs.productGroup ? "productGroup" : "product";
 }
 

package/apps/storefront/src/lib/content/storyblok/provider.ts

@@ -29,7 +29,7 @@ import {
   readPublishedArtifact,
   readVersionArtifact,
   resolvePublishedArtifactKey,
-  resolveVersionArtifactKey,
+  resolveCapturedVersionArtifactKey,
   tenantDirRelative,
   tenantDirSegment,
 } from "@tot/public-runtime";
@@ -718,8 +718,10 @@ export class PublishedContentProvider implements ContentProvider {
     return page ?? ((await this.usesVersionedContent()) ? null : this.base.getPage(slug));
   }
   async listPages(): Promise<EditorialPage[]> {
+    // Editorial enumeration follows its source, not the generic artifact fallback.
+    if (!(await this.usesVersionedContent())) return this.base.listPages();
     const paths = await this.listArtifactPaths("pages/");
-    if (paths === null) return this.base.listPages();
+    if (paths === null) return [];
     const pages = await Promise.all(
       paths
         .filter((path) => path.endsWith(".json"))
@@ -728,8 +730,10 @@ export class PublishedContentProvider implements ContentProvider {
     return pages.filter((page): page is EditorialPage => page !== null);
   }
 
-  readArtifact(relative: string): Promise<string | null> {
-    return this.publishedRaw(relative);
+  async readArtifact(relative: string): Promise<string | null> {
+    const raw = await this.publishedRaw(relative);
+    if (raw !== null) return raw;
+    return (await this.usesVersionedContent()) ? null : this.base.readArtifact(relative);
   }
 
   async derivedArtifact(name: string): Promise<DerivedArtifact | null> {
@@ -743,8 +747,9 @@ export class PublishedContentProvider implements ContentProvider {
   async listArtifactPaths(prefix = ""): Promise<string[] | null> {
     const root = contentArtifactPath(this.tenantId, "");
     const paths = await this.versionedPaths();
-    return paths?.filter((path) => path.startsWith(`${root}${prefix}`))
-      .map((path) => path.slice(root.length)) ?? null;
+    if (paths === null) return this.base.listArtifactPaths(prefix);
+    return paths.filter((path) => path.startsWith(`${root}${prefix}`))
+      .map((path) => path.slice(root.length));
   }
 }
 
@@ -839,7 +844,9 @@ export class VersionPinnedContentProvider implements ContentProvider {
 
   async derivedArtifact(name: string): Promise<DerivedArtifact | null> {
     const get = this.get;
-    const key = await resolveVersionArtifactKey(
+    // The catalog listing projection names every catalog image, so it reads through the capture
+    // overlay exactly as the product files it was derived from do.
+    const key = await resolveCapturedVersionArtifactKey(
       get, this.tenantId, this.versionId, derivedArtifactPath(this.tenantId, name),
     );
     return key ? { key, read: () => get(key) } : null;

package/apps/storefront/src/lib/observability/shared/serverTiming.ts

@@ -0,0 +1,110 @@
+/**
+ * `Server-Timing` for every Worker response: where the time before the first byte went.
+ *
+ * Each phase the request waits on (tenant resolution, the preview gate, D1 reads, the content
+ * source, the render) is timed and summed by name, and the middleware stamps the result on the
+ * way out:
+ *
+ *   curl -s -o /dev/null -D - '<url>' | grep -i server-timing
+ *   server-timing: isolate;desc="cold", tenant;dur=41, gate;dur=3, installs;dur=88, ..., total;dur=512
+ *
+ * Browsers show the same entries in DevTools (Network → Timing) and expose them to page script as
+ * `performance.getEntriesByType("navigation")[0].serverTiming`.
+ *
+ * The Workers clock advances only across I/O, so a duration here is time spent WAITING (KV, R2,
+ * D1, the cache, a subrequest), not CPU. A phase that reads 0 did no I/O; Worker CPU time is in
+ * `wrangler tail`'s `cpuTime`. `isolate;desc="cold"` marks the first request a Worker isolate
+ * served, which also pays module initialization.
+ *
+ * Phase names and durations only — never a tenant id, path, or anything request-derived.
+ */
+
+/** Requests this isolate has served; the first one is the cold start. */
+let isolateRequests = 0;
+
+const PHASE_NAME = /^[a-z][a-z0-9-]*$/;
+
+export class ServerTiming {
+  readonly #now: () => number;
+  readonly #start: number;
+  readonly #durations = new Map<string, number>();
+  readonly #notes = new Map<string, string>();
+
+  constructor(now: () => number = defaultClock) {
+    this.#now = now;
+    this.#start = now();
+    isolateRequests += 1;
+    if (isolateRequests === 1) this.#notes.set("isolate", "cold");
+  }
+
+  /** Time `run`, adding its duration to `name` (a phase timed twice reports the sum). */
+  async time<T>(name: string, run: () => Promise<T> | T): Promise<T> {
+    const started = this.#now();
+    try {
+      return await run();
+    } finally {
+      this.add(name, this.#now() - started);
+    }
+  }
+
+  /** Add `ms` to phase `name`. */
+  add(name: string, ms: number): void {
+    if (!PHASE_NAME.test(name)) throw new Error(`invalid Server-Timing phase name: ${name}`);
+    this.#durations.set(name, (this.#durations.get(name) ?? 0) + Math.max(0, ms));
+  }
+
+  /** A duration-less entry carrying a fixed description, e.g. `cache;desc="hit"`. */
+  note(name: string, desc: string): void {
+    if (!PHASE_NAME.test(name)) throw new Error(`invalid Server-Timing phase name: ${name}`);
+    this.#notes.set(name, desc.replace(/["\\\r\n]/g, ""));
+  }
+
+  /** The header value: notes, phases in first-timed order, then `total`. */
+  header(): string {
+    const entries: string[] = [];
+    for (const [name, desc] of this.#notes) entries.push(`${name};desc="${desc}"`);
+    for (const [name, ms] of this.#durations) entries.push(`${name};dur=${round(ms)}`);
+    entries.push(`total;dur=${round(this.#now() - this.#start)}`);
+    return entries.join(", ");
+  }
+}
+
+/** `timing.time(name, run)` when a recorder is present (a request); `run()` otherwise (a test). */
+export async function timed<T>(
+  timing: ServerTiming | undefined,
+  name: string,
+  run: () => Promise<T> | T,
+): Promise<T> {
+  return timing ? timing.time(name, run) : await run();
+}
+
+function defaultClock(): number {
+  return typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+}
+
+function round(ms: number): number {
+  return Math.round(ms * 10) / 10;
+}
+
+/**
+ * Stamp `timing` onto `response`. A response whose headers are immutable (one returned straight
+ * from `fetch` or the Cache API) is re-wrapped so the header can still be set.
+ */
+export function withServerTiming(response: Response, timing: ServerTiming): Response {
+  const value = timing.header();
+  try {
+    response.headers.set("Server-Timing", value);
+    return response;
+  } catch {
+    const copy = new Response(response.body, response);
+    copy.headers.set("Server-Timing", value);
+    return copy;
+  }
+}
+
+/** Test seam: forget the isolate's request count. */
+export function resetIsolateForTest(): void {
+  isolateRequests = 0;
+}

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

@@ -31,13 +31,12 @@ const DEFAULT_TTL = 300;
 const DEFAULT_SWR = 86_400;
 
 /**
- * Routes worth caching. Excludes the JSON typeahead (`?format=json`, high-q
- * cardinality), `/api/*`, and anything with a preview token (handled upstream).
+ * Routes worth caching. Excludes `/api/*` and anything with a preview token
+ * (handled upstream).
  * Single-segment slugs (e.g. /about, /shipping-returns) cover editorial pages;
  * non-200 responses are filtered at store time, so unknown slugs never persist.
  */
-export function isCacheablePath(pathname: string, params: URLSearchParams): boolean {
-  if (params.get("format") === "json") return false;
+export function isCacheablePath(pathname: string): boolean {
   if (pathname.startsWith("/api/")) return false;
   // Authenticated operator surfaces are per-viewer and MUST NOT be edge-cached —
   // the bare `/dashboard` index is a single-segment slug that would otherwise

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

@@ -0,0 +1,64 @@
+/**
+ * The query contract between a listing/search page's render and the browser.
+ *
+ * A static host serves one prerendered document per path, so the query string
+ * never reaches a renderer there; the Worker and the local dev loop render with
+ * it. Each render stamps the key of the query it applied
+ * (`data-applied-query`), and the browser recomputes the key from `location`:
+ * equal means the render already answered the URL, different means a static
+ * host dropped the query and the page must apply it itself
+ * (components/publication/storefront/islands/CatalogQueryView.tsx).
+ */
+import type { ListProductsQuery } from "@tot/public-runtime";
+import { isPathPageable, withPathPage } from "../../catalog/shared/collectionPaging.js";
+import { buildQueryString, parseQuery } from "./url.js";
+
+/** The listing query a collection view at `url` applies (page from the path when the query names none). */
+export function effectiveCollectionQuery(url: URL, pathPage?: number): ListProductsQuery {
+  return withPathPage(parseQuery(url), pathPage);
+}
+
+/** A stable key for the query a listing view applied. */
+export function listQueryKey(query: ListProductsQuery): string {
+  const { collection: _collection, ...rest } = query;
+  return buildQueryString(rest);
+}
+
+/** The search query the URL asks for (trimmed `q`); it is also the search page's applied key. */
+export function searchQueryFromUrl(url: URL): string {
+  return (url.searchParams.get("q") ?? "").trim();
+}
+
+export type CollectionQueryPlan =
+  | { kind: "rendered" }
+  | { kind: "redirect"; href: string }
+  | { kind: "apply"; query: ListProductsQuery };
+
+/**
+ * What a collection page must do with its URL. `rendered`: the render applied
+ * this query. `redirect`: the query is only a page number, which has a path
+ * variant. `apply`: compute the view client-side.
+ */
+export function planCollectionQuery(opts: {
+  url: URL;
+  pathPage: number;
+  appliedKey: string | null;
+  /** Tenant-prefixed collection path, unformed (`/collections/<h>`). */
+  pageBase: string;
+  trailingSlash: boolean;
+}): CollectionQueryPlan {
+  const query = effectiveCollectionQuery(opts.url, opts.pathPage);
+  if (opts.appliedKey !== null && listQueryKey(query) === opts.appliedKey) return { kind: "rendered" };
+  if (isPathPageable(query)) {
+    const page = query.page ?? 1;
+    let href = page > 1 ? `${opts.pageBase}/page/${page}` : opts.pageBase;
+    if (opts.trailingSlash && !href.endsWith("/")) href += "/";
+    // Params the listing does not read (a preview token, campaign tags) ride along.
+    const rest = new URLSearchParams(opts.url.search);
+    rest.delete("page");
+    rest.delete("pageSize");
+    const tail = rest.toString();
+    return { kind: "redirect", href: tail ? `${href}?${tail}` : href };
+  }
+  return { kind: "apply", query };
+}