@tokenoftrust/storefront-runner 2.5.5 → 3.0.0

package/apps/storefront/src/pages/search.astro

@@ -1,13 +1,15 @@
 ---
 /**
- * /search — dual-purpose route (brief §5 Search).
+ * /search — the full results page: a no-JS <form>, the echoed query, a result
+ * count, and a product grid. Search runs through the ToTClient (D1 FTS5 when
+ * bound, else a Fuse index over the snapshot) over ACTIVE products only (drafts
+ * never surface). Results pages are `noindex` (standard practice — thin,
+ * parameterized, duplicative).
  *
- * 1. `?format=json` — returns `{ products: TypeaheadDoc[] }` for the header
- *    typeahead island. Search runs through the ToTClient (D1 FTS5 when bound, else
- *    a Fuse index over the snapshot) over ACTIVE products only (drafts never surface).
- * 2. Otherwise — the full results page: a no-JS <form>, the echoed query, a
- *    result count, and a product grid. Results pages are `noindex` (standard
- *    practice — thin, parameterized, duplicative).
+ * A static host serves this page without its `?q=`, so the rendered results
+ * carry the query they applied (`data-applied-query`) and CatalogQueryView
+ * searches the static catalog index in the browser whenever the URL asks for a
+ * different one. The header typeahead searches that same index.
  */
 import Layout from "@/layouts/Layout.astro";
 import Breadcrumbs from "@/components/content/storefront/Breadcrumbs.astro";
@@ -15,32 +17,21 @@ import { homeCrumbLabel, siteTrail } from "@/lib/content/shared/breadcrumbs";
 import ProductCard from "@/components/catalog/storefront/ProductCard.astro";
 import EmptyState from "@/components/content/storefront/EmptyState.astro";
 import Section from "@/components/content/storefront/Section.astro";
-import { toTypeaheadDoc } from "@/lib/catalog/search/index";
+import CatalogQueryView from "@/components/publication/storefront/islands/CatalogQueryView.tsx";
+import { SEARCH_RESULT_LIMIT } from "@/lib/catalog/shared/catalogQueryView";
+import { searchQueryFromUrl } from "@/lib/publication/shared/staticQuery";
 import { breadcrumbLd } from "@/lib/content/shared/jsonld";
 import { withBase } from "@/lib/publication/shared/basePath";
 
+// `?q=` never reaches a renderer on a static host: CatalogQueryView applies it there.
+export const STATIC_QUERY = "client-applied";
+
 const { tenant, tot, canonicalBase, basePath } = Astro.locals;
-// Commerce-only route (page + typeahead JSON): off for marketing tenants.
+// Commerce-only route: off for marketing tenants.
 if (!Astro.locals.features.productSearch) return new Response(null, { status: 404 });
-const url = new URL(Astro.request.url);
-const q = (url.searchParams.get("q") ?? "").trim();
-const isJson = url.searchParams.get("format") === "json";
-
-// Search goes through the ToTClient: D1 FTS5 when a D1 binding is wired, else a
-// Fuse index over the bundled snapshot (FixtureToTClient). It returns full
-// products, so the HTML grid renders directly and the typeahead just projects to
-// the compact shape.
-
-// --- JSON path: powers the header typeahead island. Must return BEFORE render.
-if (isJson) {
-  const docs = (await tot.search(q, 8)).map(toTypeaheadDoc);
-  return new Response(JSON.stringify({ products: docs }), {
-    headers: { "content-type": "application/json" },
-  });
-}
+const q = searchQueryFromUrl(Astro.url);
 
-// --- HTML path.
-const results = q ? await tot.search(q, 24) : [];
+const results = q ? await tot.search(q, SEARCH_RESULT_LIMIT) : [];
 const featured = q ? [] : await tot.getFeatured(8);
 
 const crumbs = siteTrail(
@@ -63,7 +54,7 @@ const crumbs = siteTrail(
   {/* Search hero + no-JS form (works without the island). */}
   <header class="container-prose pb-2 pt-8">
     <p class="eyebrow eyebrow--tick mb-3">Search</p>
-    <h1 class="display-xl">
+    <h1 class="display-xl" data-search-heading>
       {q ? <>Results for “{q}”</> : "What are you after?"}
     </h1>
     <form
@@ -103,13 +94,14 @@ const crumbs = siteTrail(
         Search
       </button>
     </form>
-    {q && (
-      <p class="mt-4 text-sm text-[var(--color-muted)]">
-        {results.length} {results.length === 1 ? "result" : "results"}
-      </p>
-    )}
   </header>
 
+  <div data-catalog-query-rendered data-applied-query={q}>
+  {q && (
+    <p class="container-prose mt-4 text-sm text-[var(--color-muted)]">
+      {results.length} {results.length === 1 ? "result" : "results"}
+    </p>
+  )}
   {q ? (
     results.length === 0 ? (
       <EmptyState
@@ -148,4 +140,12 @@ const crumbs = siteTrail(
       )}
     </>
   )}
+  </div>
+
+  <CatalogQueryView
+    client:only="preact"
+    mode="search"
+    trailingSlash={!!tenant.seo?.trailingSlash}
+    locale={tenant.locale}
+  />
 </Layout>

package/apps/storefront/src/pages/sitemap.xml.ts

@@ -9,7 +9,8 @@
  * loc is prefix-correct without special-casing here.
  */
 import type { APIContext } from "astro";
-import { nonEmptyCollections } from "@/lib/catalog/tot/query.js";
+import { activeMemberCount, nonEmptyCollections } from "@/lib/catalog/tot/query.js";
+import { collectionPageCount, collectionPagePath } from "@/lib/catalog/shared/collectionPaging.js";
 import { getBlogSettings, listBlogPosts } from "@/lib/content/blog/provider.js";
 import { authorSlug, categorySlug } from "@/lib/content/blog/collection.js";
 import { resolveBlogIndexCopy } from "@/lib/content/blog/pagination.js";
@@ -64,6 +65,11 @@ export async function GET(context: APIContext): Promise<Response> {
     urls.push({ loc: `${base}/collections` });
     for (const c of collections) {
       urls.push({ loc: `${base}/collections/${c.handle}` });
+      // Paginated pages (N≥2), same reasoning as /blog/page/N/ below: listing them
+      // is what makes every product of a large collection reachable on both
+      // serving planes, which publish one document per path.
+      const pages = collectionPageCount(activeMemberCount(c, products));
+      for (let n = 2; n <= pages; n++) urls.push({ loc: `${base}${collectionPagePath(c.handle, n)}` });
     }
     for (const p of products) {
       const entry: SitemapUrl = { loc: `${base}/products/${p.handle}` };

package/apps/storefront/vitest.config.cts

@@ -31,5 +31,8 @@ module.exports = defineConfig({
     include: ["src/**/*.test.ts", "e2e/a11y/**/*.test.ts"],
     environment: "node",
     cache: false,
+    // Folds and CI run many suites at once; a fixture-heavy test that takes 2s alone can pass 5s
+    // under that load. A genuinely hung test still fails, only later.
+    testTimeout: 30_000,
   },
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.5.5",
+  "version": "3.0.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

@@ -12,12 +12,14 @@
  *
  * Mirrors packages/public-runtime/src/declared-tenant-config.mjs (this package ships
  * to npm on its own); test/declared-config-parity.test.mjs pins the two together.
- * Dependency-free: the storefront runner copies this file as-is.
+ * Dependency-free: the storefront runner copies this file as-is, and the devkit page checks carry
+ * a byte-identical copy (docs/devkit-staging/tools/lib/declared-config.mjs, pinned by
+ * test/declared-config-devkit-copy.test.mjs) so their gates read a store's declaration the same way.
  */
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds", "seo", "currency", "shipping",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -26,10 +28,48 @@ export const COMPLIANCE_KEYS = [
   "adultSignature", "prop65", "purchaseLimit", "stateEligibility", "exciseTax",
 ];
 export const FEATURE_KEYS = [
-  "catalog", "productSearch", "savedItems", "quickView", "newsletter", "commerceSitemap", "productJsonLd", "ageGate",
+  "catalog", "productSearch", "savedItems", "quickView", "productBadges", "newsletter", "commerceSitemap", "productJsonLd", "ageGate",
 ];
 export const SITE_TYPES = ["commerce", "marketing"];
 
+/** The currency a store sells in when `.tot/config.json` declares none. */
+export const DEFAULT_CURRENCY = "USD";
+
+/** ISO 4217 codes a store may declare as its `currency`. */
+export const CURRENCY_CODES = Object.freeze(
+  ("AED AFN ALL AMD ANG AOA ARS AUD AWG AZN BAM BBD BDT BGN BHD BIF BMD BND BOB BRL BSD BTN BWP BYN BZD CAD CDF CHF CLP CNY COP " +
+    "CRC CUP CVE CZK DJF DKK DOP DZD EGP ERN ETB EUR FJD FKP GBP GEL GHS GIP GMD GNF GTQ GYD HKD HNL HTG HUF IDR ILS INR IQD IRR " +
+    "ISK JMD JOD JPY KES KGS KHR KMF KPW KRW KWD KYD KZT LAK LBP LKR LRD LSL LYD MAD MDL MGA MKD MMK MNT MOP MRU MUR MVR MWK MXN " +
+    "MYR MZN NAD NGN NIO NOK NPR NZD OMR PAB PEN PGK PHP PKR PLN PYG QAR RON RSD RUB RWF SAR SBD SCR SDG SEK SGD SHP SLE SOS SRD " +
+    "SSP STN SVC SYP SZL THB TJS TMT TND TOP TRY TTD TWD TZS UAH UGX USD UYU UZS VES VND VUV WST XAF XCD XCG XOF XPF YER ZAR ZMW ZWG").split(" "),
+);
+
+/**
+ * The ONE place a store's currency is resolved. A declared ISO 4217 code wins; anything
+ * else (absent, wrong shape, lowercase, unknown code) is USD. Every surface that prices,
+ * signs or formats an amount takes the currency from here, never from a literal. Only the
+ * store owner's `.tot/config.json` can change it: a shopper's request never reaches this.
+ *
+ * @param {unknown} declared
+ * @returns {string}
+ */
+export function resolveStoreCurrency(declared) {
+  return typeof declared === "string" && CURRENCY_CODES.includes(declared) ? declared : DEFAULT_CURRENCY;
+}
+
+/**
+ * What is wrong with a declared `currency`, one sentence; `[]` when it is valid.
+ *
+ * @param {unknown} currency
+ * @returns {string[]}
+ */
+export function currencyDeclarationProblems(currency) {
+  return typeof currency === "string" && CURRENCY_CODES.includes(currency)
+    ? []
+    : [`\`currency\` is ${JSON.stringify(currency)} — must be an uppercase ISO 4217 code such as "USD" or "CAD"`];
+}
+
+
 /** Every `seo` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
 export const SEO_KEYS = Object.freeze(["trailingSlash", "verbatimSeoTitles", "structuredData"]);
 
@@ -156,6 +196,46 @@ export function seoDeclarationProblems(seo) {
   return problems;
 }
 
+/** Every `shipping` key (mirrors packages/public-runtime/src/declared-tenant-config.mjs). */
+export const SHIPPING_KEYS = Object.freeze(["flatRate", "freeAtOrAbove"]);
+
+/** Largest shipping amount a declaration may state, in the cart's currency. */
+export const MAX_SHIPPING_AMOUNT = 100000;
+
+/** @param {unknown} value */
+const isShippingAmount = (value) =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= MAX_SHIPPING_AMOUNT
+  && Math.abs(value * 100 - Math.round(value * 100)) < 1e-6;
+
+/**
+ * What is wrong with a declared `shipping` value, one sentence per problem; `[]` when it is
+ * valid. A policy with any problem is refused whole, so checkout never charges half of one.
+ *
+ * @param {unknown} shipping
+ * @returns {string[]}
+ */
+export function shippingDeclarationProblems(shipping) {
+  if (!isPlainObject(shipping)) return ["`shipping` must be an object"];
+  const problems = [];
+  const source = /** @type {Record<string, unknown>} */ (shipping);
+  for (const key of Object.keys(source)) {
+    if (!SHIPPING_KEYS.includes(key)) problems.push(`\`shipping.${key}\` is not a shipping key (${SHIPPING_KEYS.join(", ")})`);
+  }
+  if (!isShippingAmount(source.flatRate)) {
+    problems.push(`\`shipping.flatRate\` must be an amount from 0 to ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  }
+  if (source.freeAtOrAbove !== undefined && !(isShippingAmount(source.freeAtOrAbove) && /** @type {number} */ (source.freeAtOrAbove) > 0)) {
+    problems.push(`\`shipping.freeAtOrAbove\` must be an amount above 0 and at most ${MAX_SHIPPING_AMOUNT} with at most two decimal places`);
+  }
+  return problems;
+}
+
+/** The owner-facing sentence for an invalid `shipping` declaration. */
+function shippingProblemMessage(problems) {
+  return `\`shipping\` is not a valid shipping policy (${problems.join("; ")}). ` +
+    "Checkout charges no shipping until it is fixed.";
+}
+
 
 /** What each compliance key puts on the page — the thing that is missing when it is. */
 export const COMPLIANCE_NOTICES = {
@@ -184,8 +264,43 @@ export const MANDATED_NOTICE_KEYS = [
 
 const ERROR = "error";
 const WARN = "warn";
+/** @type {(v: unknown) => v is Record<string, any>} */
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
+/**
+ * The platform's compliance obligations — the registry in
+ * packages/public-runtime/src/compliance-obligations.ts, mirrored here because this file
+ * is dependency-free: each duty's id, its compliance-authority surface, and the declared
+ * `compliance.*` keys that switch it on. packages/private-controlplane/tests/
+ * compliance-obligation-checks.test.ts pins this list to the registry, key for key.
+ */
+export const COMPLIANCE_OBLIGATIONS = Object.freeze([
+  { id: "age_gate", surface: "regulated", keys: ["minAge"] },
+  { id: "excise", surface: "regulated", keys: ["nicotineWarning", "exciseTax"] },
+  { id: "nicotine_warning", surface: "regulated", keys: ["nicotineWarning"] },
+  { id: "pact_act", surface: "regulated", keys: ["pactAct"] },
+  { id: "adult_signature", surface: "regulated", keys: ["adultSignature"] },
+  { id: "prop65", surface: "commerce", keys: ["prop65"] },
+  { id: "jurisdiction", surface: "commerce", keys: ["stateEligibility", "shippingRestriction"] },
+]);
+
+/**
+ * The obligations a declared compliance block switches on, as `resolveObligations` returns
+ * them (id + surface), in registry order.
+ * @param {Record<string, any> | null | undefined} compliance
+ * @returns {{ id: string, surface: string }[]}
+ */
+export function declaredObligations(compliance) {
+  return COMPLIANCE_OBLIGATIONS
+    .filter((o) => o.keys.some((key) => !!compliance?.[key]))
+    .map(({ id, surface }) => ({ id, surface }));
+}
+
+/** True when the declared block puts the store on the regulated surface. */
+export function isRegulatedCompliance(compliance) {
+  return isRegulatedObligationSet(declaredObligations(compliance));
+}
+
 /**
  * Compliance coherence — the declared-config half of the hosted preview's `age_gate`,
  * `excise` and `jurisdiction` evidence checks, so `tot validate` fails locally on
@@ -193,9 +308,42 @@ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v)
  * packages/public-runtime/src/compliance-coherence.mjs (the platform's single source);
  * test/declared-config-parity.test.mjs pins the two together.
  */
-export function isRegulatedCompliance(compliance) {
-  const minAge = compliance?.minAge;
-  return (typeof minAge === "number" && minAge > 0) || !!compliance?.nicotineWarning;
+export const COHERENCE_CHECK_IDS = Object.freeze(/** @type {const} */ (["age_gate", "excise", "jurisdiction"]));
+
+export const OBLIGATION_EVIDENCE_CHECK = Object.freeze({
+  age_gate: "age_gate",
+  excise: "excise",
+  nicotine_warning: "excise",
+  pact_act: "jurisdiction",
+  adult_signature: "jurisdiction",
+  jurisdiction: "jurisdiction",
+  prop65: null,
+});
+
+/** @param {readonly { id: string, surface: string }[]} obligations */
+export function isRegulatedObligationSet(obligations) {
+  return obligations.some((o) => o.surface === "regulated");
+}
+
+/**
+ * @param {readonly { id: string, surface: string }[]} obligations
+ * @returns {("age_gate" | "excise" | "jurisdiction")[]}
+ */
+export function coherenceChecksFor(obligations) {
+  const out = new Set();
+  if (isRegulatedObligationSet(obligations)) {
+    out.add("age_gate");
+    out.add("jurisdiction");
+  }
+  for (const { id } of obligations) {
+    if (!Object.hasOwn(OBLIGATION_EVIDENCE_CHECK, id)) {
+      for (const check of COHERENCE_CHECK_IDS) out.add(check);
+      continue;
+    }
+    const check = OBLIGATION_EVIDENCE_CHECK[/** @type {keyof typeof OBLIGATION_EVIDENCE_CHECK} */ (id)];
+    if (check) out.add(check);
+  }
+  return COHERENCE_CHECK_IDS.filter((c) => out.has(c));
 }
 
 export function declaresJurisdictionNotice(compliance) {
@@ -203,19 +351,48 @@ export function declaresJurisdictionNotice(compliance) {
   return compliance?.pactAct === true || (typeof text === "string" && text.trim().length > 0);
 }
 
+/** @param {unknown} declaration */
+function stateEligibilityHasContent(declaration) {
+  if (declaration === null || typeof declaration !== "object" || Array.isArray(declaration)) return false;
+  const d = /** @type {Record<string, unknown>} */ (declaration);
+  const listed = (v) => Array.isArray(v) && v.some((s) => typeof s === "string" && s.trim().length > 0);
+  return listed(d.restrictedStates) || listed(d.eligibleStates) || (typeof d.note === "string" && d.note.trim().length > 0);
+}
+
+const REGULATED_KEY_FOR = Object.freeze({
+  age_gate: "minAge",
+  excise: "exciseTax",
+  nicotine_warning: "nicotineWarning",
+  pact_act: "pactAct",
+  adult_signature: "adultSignature",
+});
+
+function regulatedBy(compliance, obligations) {
+  const keys = new Set();
+  for (const o of obligations) {
+    if (o.surface !== "regulated") continue;
+    const key = REGULATED_KEY_FOR[/** @type {keyof typeof REGULATED_KEY_FOR} */ (o.id)];
+    if (o.id === "excise" && !compliance?.exciseTax) continue;
+    if (key) keys.add(key);
+  }
+  return [...keys].map((k) => `\`compliance.${k}\``).join(", ") || "a regulated obligation";
+}
+
 /**
  * @param {Record<string, any> | null | undefined} compliance
+ * @param {readonly { id: string, surface: string }[]} [obligations] defaults to what the block declares
  * @returns {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>}
  */
-export function complianceCoherenceFailures(compliance) {
+export function complianceCoherenceFailures(compliance, obligations = declaredObligations(compliance)) {
   /** @type {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>} */
   const out = {};
-  if (!isRegulatedCompliance(compliance)) return out;
+  const checks = coherenceChecksFor(obligations);
+  const regulated = isRegulatedObligationSet(obligations);
   const minAge = typeof compliance?.minAge === "number" ? compliance.minAge : null;
-  if (minAge == null || minAge < 18) {
+  if (checks.includes("age_gate") && regulated && (minAge == null || minAge < 18)) {
     out.age_gate = {
       field: "compliance.minAge",
-      detail: "Age-restricted/nicotine products require `compliance.minAge` (18 or higher) — none is set.",
+      detail: `Age-restricted products (${regulatedBy(compliance, obligations)}) require \`compliance.minAge\` (18 or higher) — none is set.`,
       hint: "Set `compliance.minAge` (18+) in .tot/config.json.",
     };
   }
@@ -226,16 +403,29 @@ export function complianceCoherenceFailures(compliance) {
       hint: "Set `compliance.minAge` to 21 in .tot/config.json (nicotine requires 21+, not just 18+).",
     };
   }
-  if (!declaresJurisdictionNotice(compliance)) {
-    out.jurisdiction = {
-      field: "compliance.pactAct",
-      detail:
-        "Regulated products require a shipping/jurisdiction notice: set `compliance.pactAct: true` " +
-        "or `compliance.shippingRestriction` — neither is set.",
-      hint:
-        "Set `compliance.pactAct: true` for the platform's PACT Act notice, or " +
-        "`compliance.shippingRestriction` to your own restriction text, in .tot/config.json.",
-    };
+  if (checks.includes("jurisdiction")) {
+    if (regulated && !declaresJurisdictionNotice(compliance)) {
+      out.jurisdiction = {
+        field: "compliance.pactAct",
+        detail:
+          `Regulated products (${regulatedBy(compliance, obligations)}) require a shipping/jurisdiction notice: ` +
+          "set `compliance.pactAct: true` or `compliance.shippingRestriction` — neither is set.",
+        hint:
+          "Set `compliance.pactAct: true` for the platform's PACT Act notice, or " +
+          "`compliance.shippingRestriction` to your own restriction text, in .tot/config.json.",
+      };
+    } else if (!regulated && !declaresJurisdictionNotice(compliance)
+      && !stateEligibilityHasContent(compliance?.stateEligibility)) {
+      const field = compliance?.stateEligibility ? "compliance.stateEligibility" : "compliance.shippingRestriction";
+      out.jurisdiction = {
+        field,
+        detail:
+          `\`${field}\` is declared but gives its shipping/jurisdiction notice nothing to say, so no notice renders.`,
+        hint:
+          "Set `compliance.shippingRestriction` to your restriction text, or give `compliance.stateEligibility` " +
+          "`restrictedStates`, `eligibleStates` or a `note`, in .tot/config.json.",
+      };
+    }
   }
   return out;
 }
@@ -251,27 +441,29 @@ export function complianceCoherenceFailures(compliance) {
  */
 export function complianceFindings(config, file = ".tot/config.json") {
   const compliance = isObject(config?.compliance) ? config.compliance : null;
+  const obligations = declaredObligations(compliance);
+  const owed = new Set(obligations.map((o) => o.id));
   const out = [];
-  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance))) {
+  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance, obligations))) {
     out.push(mk(ERROR, `compliance-${check.replace("_", "-")}`, `${file} compliance`,
       `${failure.detail} The hosted preview fails its \`${check}\` check on this.`, failure.hint));
   }
   // The hosted reconcile refuses a declaration whose `capabilities` switch off the
   // compliance floor (packages/public-runtime/src/capabilities.ts capabilityFloorViolations).
   const capabilities = isObject(config?.capabilities) ? config.capabilities : {};
-  if (compliance?.minAge && capabilities.ageVerification?.enabled === false) {
+  if (owed.has("age_gate") && capabilities.ageVerification?.enabled === false) {
     out.push(mk(ERROR, "capability-compliance-floor", `${file} capabilities`,
       "`capabilities.ageVerification` cannot be disabled for a store with `compliance.minAge` — the hosted preview refuses this revision.",
       "Remove `capabilities.ageVerification.enabled: false` from .tot/config.json."));
   }
-  if (compliance?.nicotineWarning && capabilities.exciseTax?.enabled === false) {
+  if (owed.has("excise") && capabilities.exciseTax?.enabled === false) {
     out.push(mk(ERROR, "capability-compliance-floor", `${file} capabilities`,
-      "`capabilities.exciseTax` cannot be disabled for a store with `compliance.nicotineWarning` — the hosted preview refuses this revision.",
+      "`capabilities.exciseTax` cannot be disabled for a store with `compliance.nicotineWarning` or `compliance.exciseTax` — the hosted preview refuses this revision.",
       "Remove `capabilities.exciseTax.enabled: false` from .tot/config.json."));
   }
-  if (isRegulatedCompliance(compliance) && !compliance?.ruleProfile) {
+  if (isRegulatedObligationSet(obligations) && !compliance?.ruleProfile) {
     out.push(mk(WARN, "compliance-rule-profile", `${file} compliance`,
-      "This store is regulated (`compliance.minAge`/`compliance.nicotineWarning`) but declares no " +
+      `This store is regulated (${regulatedBy(compliance, obligations)}) but declares no ` +
         "`compliance.ruleProfile`, so no checkout rules resolve: the preview renders, but checkout blocks " +
         "and going live refuses.",
       'Declare `compliance.ruleProfile` (e.g. "vape-nicotine-us") in .tot/config.json.'));
@@ -416,6 +608,8 @@ export function declarationFindings(current, previous) {
     if (warning.enabled && warning.problems.length > 0) {
       out.push(`CONFIG: ${nicotineWarningProblemMessage(warning.problems)}`);
     }
+    const shipping = current.shipping === undefined ? [] : shippingDeclarationProblems(current.shipping);
+    if (shipping.length > 0) out.push(`CONFIG: ${shippingProblemMessage(shipping)}`);
   }
   for (const { key, notice } of droppedMandatedNotices(previous, current)) {
     out.push(
@@ -470,7 +664,13 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     }
   }
   out.push(...complianceFindings(config, file));
-  const warning = resolveNicotineWarning(isObject(config.compliance) ? config.compliance.nicotineWarning : undefined);
+  const declaration = isObject(config.compliance) ? config.compliance.nicotineWarning : undefined;
+  for (const problem of nicotineWarningCheckWidths(declaration).problems) {
+    out.push(mk(ERROR, "config-nicotine-warning-check-widths", `${file} compliance`,
+      `\`compliance.nicotineWarning\`: ${problem}. The page browser gate cannot check the warning at the widths you meant.`,
+      "list the widths where your layout changes (e.g. where your header becomes fixed), or remove `checkWidthsPx`"));
+  }
+  const warning = resolveNicotineWarning(declaration);
   if (warning.enabled && warning.problems.length > 0) {
     out.push(mk(ERROR, "config-nicotine-warning", `${file} compliance`, nicotineWarningProblemMessage(warning.problems),
       'use `true`, `{ "preset": "dark" }` or `{ "preset": "light" }`, or fix the style values named above'));
@@ -488,11 +688,23 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
     && !(Array.isArray(config.embeds) && config.embeds.every((/** @type {unknown} */ s) => typeof s === "string"))) {
     out.push(mk(ERROR, "config-embeds", file, '`embeds` must be an array of embed slugs, e.g. ["youtube"]'));
   }
+  if (config.currency !== undefined) {
+    for (const problem of currencyDeclarationProblems(config.currency)) {
+      out.push(mk(ERROR, "config-currency", file, `${problem} — the store sells in ${DEFAULT_CURRENCY} until it is fixed`));
+    }
+  }
   if (config.seo !== undefined) {
     for (const problem of seoDeclarationProblems(config.seo)) {
       out.push(mk(ERROR, "config-seo", `${file} seo`, `${problem} — the whole \`seo\` declaration is ignored until it is fixed`));
     }
   }
+  if (config.shipping !== undefined) {
+    const problems = shippingDeclarationProblems(config.shipping);
+    if (problems.length > 0) {
+      out.push(mk(ERROR, "config-shipping", `${file} shipping`, shippingProblemMessage(problems),
+        'declare e.g. `"shipping": { "flatRate": 5.99, "freeAtOrAbove": 100 }`, or remove `shipping` to charge none'));
+    }
+  }
   return out;
 }
 
@@ -504,6 +716,7 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
 //   "nicotineWarning": true                                   → the "dark" preset
 //   "nicotineWarning": { "preset": "light" }                  → a validated preset
 //   "nicotineWarning": { "preset": "light", "style": {...} }  → a custom presentation
+//   "nicotineWarning": { "checkWidthsPx": [800] }             → also checked seen at 800px wide
 //
 // Every presentation — preset or custom — must clear CONSPICUITY_FLOOR. A preset needs no
 // review. A custom presentation is a deviation the owner approves at go-live:
@@ -562,6 +775,9 @@ export const NICOTINE_WARNING_PRESETS = Object.freeze({
  * }} NicotineWarningPresentation
  */
 
+/** Every key a `compliance.nicotineWarning` object may declare. */
+export const NICOTINE_WARNING_KEYS = Object.freeze(["preset", "style", "checkWidthsPx"]);
+
 export const NICOTINE_WARNING_STYLE_KEYS = Object.freeze([
   "background", "text", "border", "textTransform", "fontWeight", "fontSizePx",
 ]);
@@ -669,8 +885,9 @@ export function resolveNicotineWarning(declaration) {
   if (!isObject(declaration)) {
     return resolved({ problems: ["must be `true` or an object like { \"preset\": \"light\" }"] });
   }
-  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, ...rest } = /** @type {Record<string, unknown>} */ (declaration);
-  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: preset, style)`);
+  const { preset: presetName = DEFAULT_NICOTINE_WARNING_PRESET, style, checkWidthsPx: _checkWidths, ...rest } =
+    /** @type {Record<string, unknown>} */ (declaration);
+  const problems = Object.keys(rest).map((k) => `\`${k}\` is not a nicotineWarning key (allowed: ${NICOTINE_WARNING_KEYS.join(", ")})`);
   const base = typeof presetName === "string" ? NICOTINE_WARNING_PRESETS[presetName] : undefined;
   if (!base) {
     problems.push(`\`preset\` must be one of ${Object.keys(NICOTINE_WARNING_PRESETS).map((p) => `"${p}"`).join(", ")}`);
@@ -695,6 +912,35 @@ export function resolveNicotineWarning(declaration) {
   return resolved({ presentation, preset: matching ?? null, custom: !matching });
 }
 
+/** The viewport widths a store may add to the page browser gate's nicotine-warning check. */
+export const NICOTINE_WARNING_CHECK_WIDTH_BOUNDS = Object.freeze({ min: 320, max: 3840 });
+
+/**
+ * The extra viewport widths at which the page browser gate checks the nicotine warning is seen.
+ *
+ * The gate always checks its own phone, tablet, laptop and desktop widths; `checkWidthsPx` adds
+ * the store's own breakpoints (e.g. the width where its header becomes fixed) and never removes
+ * a default. A store that does not declare the warning has no widths; `true` and an object
+ * without `checkWidthsPx` add none.
+ *
+ *   "nicotineWarning": { "preset": "dark", "checkWidthsPx": [800, 1180] }
+ *
+ * `problems` lists why a declared value is unusable, in which case no extra width is used.
+ * @param {unknown} declaration the store's `compliance.nicotineWarning`
+ * @returns {{ widths: number[], problems: string[] }}
+ */
+export function nicotineWarningCheckWidths(declaration) {
+  if (!isObject(declaration)) return { widths: [], problems: [] };
+  const value = /** @type {Record<string, unknown>} */ (declaration).checkWidthsPx;
+  if (value === undefined) return { widths: [], problems: [] };
+  const { min, max } = NICOTINE_WARNING_CHECK_WIDTH_BOUNDS;
+  const usable = (/** @type {unknown} */ w) => Number.isInteger(w) && /** @type {number} */ (w) >= min && /** @type {number} */ (w) <= max;
+  if (!Array.isArray(value) || value.length === 0 || !value.every(usable)) {
+    return { widths: [], problems: [`\`checkWidthsPx\` must be a non-empty array of whole pixel widths from ${min} to ${max}, e.g. [800]`] };
+  }
+  return { widths: [...new Set(/** @type {number[]} */ (value))].sort((a, b) => a - b), problems: [] };
+}
+
 /**
  * The exact, human-readable statement of a custom presentation — what the owner approves.
  * Every resolved value is in it, so two presentations that differ in any value describe
@@ -712,6 +958,16 @@ export function describeNicotineWarningPresentation(p) {
  * of every page; "block" is the reinforced box on the product page. Every interpolated value
  * is a validated hex colour, enum or number. Styling is inline (no utility classes), so the
  * markup renders the same wherever it is served, whatever stylesheet the page carries.
+ *
+ * Every presentation and visibility declaration is inline `!important`, which no tenant
+ * stylesheet rule can override: tenant CSS cannot hide, move, clip, fade or restyle the warning,
+ * and the text element re-asserts the warning's own presentation so a tenant `p { … }` rule does
+ * not reach it. What inline styles cannot stop is another element painting over the warning (a
+ * fixed or sticky header pinned to the top of the viewport). Raising the warning above page
+ * chrome would paint it over the tenant's own open menus and drawers, so occlusion is measured
+ * instead: the page browser gate (`validate-page-browser.mjs`, `nicotineWarning`) fails a page
+ * whose warning is covered at a phone, tablet or desktop width, or at a width the store declares
+ * in `checkWidthsPx`, and names the covering element.
  * @param {unknown} declaration the tenant's `compliance.nicotineWarning`
  * @param {"bar" | "block"} variant
  */
@@ -719,11 +975,40 @@ export function nicotineWarningHtml(declaration, variant) {
   const { presentation, preset } = resolveNicotineWarning(declaration);
   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">${NICOTINE_WARNING_TEXT}</p></div>`
-    : `<div ${attrs}><p style="margin:0">${NICOTINE_WARNING_TEXT}</p></div>`;
+    ? `<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 style="margin:0;${text}">${NICOTINE_WARNING_TEXT}</p></div>`;
 }
 
+/** Declarations that keep the warning on screen, at full opacity, in its own place. */
+const NICOTINE_WARNING_VISIBILITY_LOCK = [
+  "display:block",
+  "visibility:visible",
+  "opacity:1",
+  "position:relative",
+  "inset:auto",
+  "transform:none",
+  "clip-path:none",
+  "filter:none",
+  "height:auto",
+  "max-height:none",
+  "overflow:visible",
+];
+
+/** The text element inherits the warning's presentation, whatever a tenant `p` rule says. */
+const NICOTINE_WARNING_TEXT_LOCK = [
+  "display:block",
+  "visibility:visible",
+  "opacity:1",
+  "color:inherit",
+  "font-size:inherit",
+  "font-weight:inherit",
+  "text-transform:inherit",
+  "letter-spacing:inherit",
+  "line-height:inherit",
+].map((d) => `${d}!important`).join(";");
+
 /**
  * Inline CSS for a presentation. `variant` "block" (the product page) never renders smaller
  * than 14px.
@@ -744,5 +1029,6 @@ export function nicotineWarningStyle(p, variant) {
     `font-weight:${p.fontWeight}`,
     `font-size:${size}px`,
     "line-height:1.4",
-  ].join(";");
+    ...NICOTINE_WARNING_VISIBILITY_LOCK,
+  ].map((d) => `${d}!important`).join(";");
 }