@tokenoftrust/storefront-runner 2.5.6 → 3.0.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(";");
 }

package/packages/cli/src/publication-spaces.mjs

@@ -33,7 +33,7 @@ export const PLATFORM_PATHS = Object.freeze([
   "/apps", "/assets", "/auth", "/brand", "/capabilities", "/cockpit", "/dashboard", "/dev",
   "/favicon.svg", "/health", "/js", "/feed.json", "/llms.txt", "/publication-discovery",
   "/search-index.json", "/sitemap.xml", "/platform", "/preview", "/products", "/collections",
-  "/search", "/saved", "/robots.txt", "/shared", "/style-guide", "/tenants",
+  "/search", "/catalog-index.json", "/saved", "/robots.txt", "/shared", "/style-guide", "/tenants",
 ]);
 
 const SPACE_ID = /^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$/;

package/packages/public-runtime/package.json

@@ -15,6 +15,7 @@
     "./image-finding-dependencies": "./src/image-finding-dependencies.ts",
     "./image-finding-acceptance": "./src/image-finding-acceptance.ts",
     "./image-preview-rewrite-overlay": "./src/image-preview-rewrite-overlay.ts",
+    "./capture-rewrites": "./src/capture-rewrites.ts",
     "./hosted-image-media-types": "./src/hosted-image-media-types.ts",
     "./durable-assets": "./src/durable-assets.ts",
     "./catalog-files": "./src/catalog-files.ts",

package/packages/public-runtime/schemas/publication-space/v1/manifest.schema.json

@@ -207,7 +207,7 @@
     "mountPath": {
       "allOf": [
         { "$ref": "#/$defs/path" },
-        { "type": "string", "pattern": "^/(?!(?:\\.[wW][eE][lL][lL]-[kK][nN][oO][wW][nN]|__[eE][vV][iI][dD][eE][nN][cC][eE]|__[pP][rR][eE][vV][iI][eE][wW]|_[aA]|_[aA][sS][tT][rR][oO]|_[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[aA][dD][mM][iI][nN]|[aA][pP][iI]|[aA][pP][pP][sS]|[aA][sS][sS][eE][tT][sS]|[aA][uU][tT][hH]|[bB][rR][aA][nN][dD]|[cC][aA][pP][aA][bB][iI][lL][iI][tT][iI][eE][sS]|[cC][oO][cC][kK][pP][iI][tT]|[cC][oO][lL][lL][eE][cC][tT][iI][oO][nN][sS]|[dD][aA][sS][hH][bB][oO][aA][rR][dD]|[dD][eE][vV]|[fF][aA][vV][iI][cC][oO][nN]\\.[sS][vV][gG]|[fF][eE][eE][dD]\\.[jJ][sS][oO][nN]|[hH][eE][aA][lL][tT][hH]|[jJ][sS]|[lL][lL][mM][sS]\\.[tT][xX][tT]|[pP][lL][aA][tT][fF][oO][rR][mM]|[pP][rR][eE][vV][iI][eE][wW]|[pP][rR][oO][dD][uU][cC][tT][sS]|[pP][uU][bB][lL][iI][cC][aA][tT][iI][oO][nN]-[dD][iI][sS][cC][oO][vV][eE][rR][yY]|[rR][oO][bB][oO][tT][sS]\\.[tT][xX][tT]|[sS][aA][vV][eE][dD]|[sS][eE][aA][rR][cC][hH]|[sS][eE][aA][rR][cC][hH]-[iI][nN][dD][eE][xX]\\.[jJ][sS][oO][nN]|[sS][hH][aA][rR][eE][dD]|[sS][iI][tT][eE][mM][aA][pP]\\.[xX][mM][lL]|[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[tT][eE][nN][aA][nN][tT][sS])(?:/|$))" }
+        { "type": "string", "pattern": "^/(?!(?:\\.[wW][eE][lL][lL]-[kK][nN][oO][wW][nN]|__[eE][vV][iI][dD][eE][nN][cC][eE]|__[pP][rR][eE][vV][iI][eE][wW]|_[aA]|_[aA][sS][tT][rR][oO]|_[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[aA][dD][mM][iI][nN]|[aA][pP][iI]|[aA][pP][pP][sS]|[aA][sS][sS][eE][tT][sS]|[aA][uU][tT][hH]|[bB][rR][aA][nN][dD]|[cC][aA][pP][aA][bB][iI][lL][iI][tT][iI][eE][sS]|[cC][aA][tT][aA][lL][oO][gG]-[iI][nN][dD][eE][xX]\\.[jJ][sS][oO][nN]|[cC][oO][cC][kK][pP][iI][tT]|[cC][oO][lL][lL][eE][cC][tT][iI][oO][nN][sS]|[dD][aA][sS][hH][bB][oO][aA][rR][dD]|[dD][eE][vV]|[fF][aA][vV][iI][cC][oO][nN]\\.[sS][vV][gG]|[fF][eE][eE][dD]\\.[jJ][sS][oO][nN]|[hH][eE][aA][lL][tT][hH]|[jJ][sS]|[lL][lL][mM][sS]\\.[tT][xX][tT]|[pP][lL][aA][tT][fF][oO][rR][mM]|[pP][rR][eE][vV][iI][eE][wW]|[pP][rR][oO][dD][uU][cC][tT][sS]|[pP][uU][bB][lL][iI][cC][aA][tT][iI][oO][nN]-[dD][iI][sS][cC][oO][vV][eE][rR][yY]|[rR][oO][bB][oO][tT][sS]\\.[tT][xX][tT]|[sS][aA][vV][eE][dD]|[sS][eE][aA][rR][cC][hH]|[sS][eE][aA][rR][cC][hH]-[iI][nN][dD][eE][xX]\\.[jJ][sS][oO][nN]|[sS][hH][aA][rR][eE][dD]|[sS][iI][tT][eE][mM][aA][pP]\\.[xX][mM][lL]|[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[tT][eE][nN][aA][nN][tT][sS])(?:/|$))" }
       ]
     },
     "aliasPath": {

package/packages/public-runtime/schemas/publication-space/v1/normalized-mount.schema.json

@@ -67,7 +67,7 @@
     "mountPath": {
       "allOf": [
         { "$ref": "#/$defs/normalizedPath" },
-        { "type": "string", "pattern": "^/(?!(?:\\.[wW][eE][lL][lL]-[kK][nN][oO][wW][nN]|__[eE][vV][iI][dD][eE][nN][cC][eE]|__[pP][rR][eE][vV][iI][eE][wW]|_[aA]|_[aA][sS][tT][rR][oO]|_[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[aA][dD][mM][iI][nN]|[aA][pP][iI]|[aA][pP][pP][sS]|[aA][sS][sS][eE][tT][sS]|[aA][uU][tT][hH]|[bB][rR][aA][nN][dD]|[cC][aA][pP][aA][bB][iI][lL][iI][tT][iI][eE][sS]|[cC][oO][cC][kK][pP][iI][tT]|[cC][oO][lL][lL][eE][cC][tT][iI][oO][nN][sS]|[dD][aA][sS][hH][bB][oO][aA][rR][dD]|[dD][eE][vV]|[fF][aA][vV][iI][cC][oO][nN]\\.[sS][vV][gG]|[fF][eE][eE][dD]\\.[jJ][sS][oO][nN]|[hH][eE][aA][lL][tT][hH]|[jJ][sS]|[lL][lL][mM][sS]\\.[tT][xX][tT]|[pP][lL][aA][tT][fF][oO][rR][mM]|[pP][rR][eE][vV][iI][eE][wW]|[pP][rR][oO][dD][uU][cC][tT][sS]|[pP][uU][bB][lL][iI][cC][aA][tT][iI][oO][nN]-[dD][iI][sS][cC][oO][vV][eE][rR][yY]|[rR][oO][bB][oO][tT][sS]\\.[tT][xX][tT]|[sS][aA][vV][eE][dD]|[sS][eE][aA][rR][cC][hH]|[sS][eE][aA][rR][cC][hH]-[iI][nN][dD][eE][xX]\\.[jJ][sS][oO][nN]|[sS][hH][aA][rR][eE][dD]|[sS][iI][tT][eE][mM][aA][pP]\\.[xX][mM][lL]|[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[tT][eE][nN][aA][nN][tT][sS])(?:/|$))" }
+        { "type": "string", "pattern": "^/(?!(?:\\.[wW][eE][lL][lL]-[kK][nN][oO][wW][nN]|__[eE][vV][iI][dD][eE][nN][cC][eE]|__[pP][rR][eE][vV][iI][eE][wW]|_[aA]|_[aA][sS][tT][rR][oO]|_[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[aA][dD][mM][iI][nN]|[aA][pP][iI]|[aA][pP][pP][sS]|[aA][sS][sS][eE][tT][sS]|[aA][uU][tT][hH]|[bB][rR][aA][nN][dD]|[cC][aA][pP][aA][bB][iI][lL][iI][tT][iI][eE][sS]|[cC][aA][tT][aA][lL][oO][gG]-[iI][nN][dD][eE][xX]\\.[jJ][sS][oO][nN]|[cC][oO][cC][kK][pP][iI][tT]|[cC][oO][lL][lL][eE][cC][tT][iI][oO][nN][sS]|[dD][aA][sS][hH][bB][oO][aA][rR][dD]|[dD][eE][vV]|[fF][aA][vV][iI][cC][oO][nN]\\.[sS][vV][gG]|[fF][eE][eE][dD]\\.[jJ][sS][oO][nN]|[hH][eE][aA][lL][tT][hH]|[jJ][sS]|[lL][lL][mM][sS]\\.[tT][xX][tT]|[pP][lL][aA][tT][fF][oO][rR][mM]|[pP][rR][eE][vV][iI][eE][wW]|[pP][rR][oO][dD][uU][cC][tT][sS]|[pP][uU][bB][lL][iI][cC][aA][tT][iI][oO][nN]-[dD][iI][sS][cC][oO][vV][eE][rR][yY]|[rR][oO][bB][oO][tT][sS]\\.[tT][xX][tT]|[sS][aA][vV][eE][dD]|[sS][eE][aA][rR][cC][hH]|[sS][eE][aA][rR][cC][hH]-[iI][nN][dD][eE][xX]\\.[jJ][sS][oO][nN]|[sS][hH][aA][rR][eE][dD]|[sS][iI][tT][eE][mM][aA][pP]\\.[xX][mM][lL]|[sS][tT][yY][lL][eE]-[gG][uU][iI][dD][eE]|[tT][eE][nN][aA][nN][tT][sS])(?:/|$))" }
       ]
     },
     "aliasPath": {

package/packages/public-runtime/src/activity/catalog.ts

@@ -176,7 +176,7 @@ export const ACTION_CATALOG = {
     // A reconcile reached a terminal state (reconciled|blocked|failed). Low
     // volume, high value → timelined for the ops UI.
     actors: ["system"], source: "server", sinks: LIFECYCLE,
-    argsAllow: ["changeId", "result", "evidenceStatus", "evidencePushError", "prNumber", "forgeOpenVerified", "terminalSource"], renderedAllow: [],
+    argsAllow: ["changeId", "result", "evidenceStatus", "evidencePushError", "prNumber", "forgeOpenVerified", "terminalSource", "cause", "traceId"], renderedAllow: [],
     desc: "A candidate reconcile reached a terminal state.",
   },
   "candidate.closed": {
@@ -323,6 +323,13 @@ export const ACTION_CATALOG = {
     argsAllow: ["versionId", "scope"], renderedAllow: [],
     desc: "A tenant's checkout styling was saved to a version.",
   },
+  "content.checkout_requirements.saved": {
+    // A store's shared-test-store checkout requirements (Settings → Checkout requirements)
+    // were saved to a versioned test artifact. Same actors and spine as checkout styling.
+    actors: ["merchant", "admin"], source: "server", sinks: LIFECYCLE,
+    argsAllow: ["versionId", "scope"], renderedAllow: [],
+    desc: "A store's checkout requirements were saved to a version.",
+  },
   "change.go_live": {
     // Renamed from the orphaned, un-namespaced `go_live` (the ONE key that broke the
     // domain-prefix rule). The snake_case suffix is kept (the `deploy.version_observed`

package/packages/public-runtime/src/candidate-index.ts

@@ -78,6 +78,11 @@ export interface CandidateReconcileLifecycle {
     | "ready"
     | "blocked";
   correlationId: string;
+  /**
+   * The forge's `X-Gitea-Delivery` id MCP forwarded with this reconcile — the key that joins this
+   * record to MCP's delivery record (`preview_status.delivery`) and to Gitea's own delivery log.
+   */
+  deliveryId?: string | null;
   startedAt: string;
   lastUpdatedAt: string;
   elapsedMs: number;