@tokenoftrust/storefront-runner 2.5.6 → 3.0.1

package/packages/public-runtime/src/compliance-coherence.mjs

@@ -1,8 +1,8 @@
 /**
- * Compliance COHERENCE: what a regulated tenant's declared `compliance` block must hold
- * together before its preview can pass the `age_gate`, `excise` and `jurisdiction`
- * evidence checks. Every rule here reads declared config only, so it is checkable from
- * a checkout with no platform state:
+ * Compliance COHERENCE: what a tenant's declared `compliance` block must hold together
+ * before its preview can pass the `age_gate`, `excise` and `jurisdiction` evidence checks.
+ * Every rule here reads declared config only, so it is checkable from a checkout with no
+ * platform state:
  *
  *   - the hosted reconcile grades these checks with it
  *     (packages/private-controlplane/src/evidence-producer.ts);
@@ -10,6 +10,12 @@
  *     (packages/cli/src/declared-config.mjs), pinned to this one by
  *     packages/cli/test/declared-config-parity.test.mjs.
  *
+ * WHICH checks apply is never decided here. The caller passes the tenant's resolved
+ * obligations (`resolveObligations` in compliance-obligations.ts — the one registry of
+ * compliance duties), and each obligation names the evidence check that judges it in
+ * {@link OBLIGATION_EVIDENCE_CHECK}. A tenant is regulated when any applied obligation
+ * sits on the `regulated` surface.
+ *
  * Each failure names the exact `compliance.*` field that resolves it, in both the
  * detail and the hint, so the first failure a developer sees is actionable.
  *
@@ -21,14 +27,58 @@
 export const COHERENCE_CHECK_IDS = Object.freeze(["age_gate", "excise", "jurisdiction"]);
 
 /**
- * True when the declared compliance block marks the tenant regulated (an age minimum
- * or the FDA nicotine warning).
- *
- * @param {Record<string, unknown> | null | undefined} compliance
+ * The evidence check that judges each registered obligation, or null for a duty no
+ * promotion check grades (the Prop 65 warning renders from its declaration alone). Every
+ * id in the obligation registry has an entry: packages/private-controlplane/tests/
+ * compliance-obligation-checks.test.ts fails on one that does not.
  */
-export function isRegulatedCompliance(compliance) {
-  const minAge = compliance?.minAge;
-  return (typeof minAge === "number" && minAge > 0) || !!compliance?.nicotineWarning;
+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,
+});
+
+/**
+ * @typedef {{ id: string, surface: string }} AppliedObligation
+ * @typedef {"age_gate" | "excise" | "jurisdiction"} CoherenceCheckId
+ */
+
+/**
+ * True when an applied obligation puts the tenant on the `regulated` surface.
+ * @param {readonly AppliedObligation[]} obligations
+ */
+export function isRegulatedObligationSet(obligations) {
+  return obligations.some((o) => o.surface === "regulated");
+}
+
+/**
+ * The evidence checks the tenant's obligations make applicable, in report order. A
+ * regulated tenant owes an age gate and a shipping/jurisdiction notice whatever made it
+ * regulated; every applied obligation also brings the check that judges it. An id with no
+ * entry in {@link OBLIGATION_EVIDENCE_CHECK} brings every check: an unknown duty is judged,
+ * never waved through.
+ * @param {readonly AppliedObligation[]} obligations
+ * @returns {CoherenceCheckId[]}
+ */
+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));
 }
 
 /**
@@ -44,21 +94,58 @@ export function declaresJurisdictionNotice(compliance) {
 }
 
 /**
- * Every coherence failure in a declared compliance block, keyed by evidence check id.
- * An unregulated block has none. An absent key means that check is coherent.
+ * True when `compliance.stateEligibility` gives its notice something to say: a restricted
+ * or eligible jurisdiction, or a note.
+ *
+ * @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);
+}
+
+/** The `compliance.*` keys that switch on a regulated-surface duty, named in failure text. */
+const REGULATED_KEY_FOR = Object.freeze({
+  age_gate: "minAge",
+  excise: "exciseTax",
+  nicotine_warning: "nicotineWarning",
+  pact_act: "pactAct",
+  adult_signature: "adultSignature",
+});
+
+/** The declared keys that made the tenant regulated, e.g. "`compliance.pactAct`". */
+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";
+}
+
+/**
+ * Every coherence failure in a declared compliance block, keyed by evidence check id. A
+ * block whose obligations make no check applicable has none. An absent key means that
+ * check is coherent.
  *
  * @param {Record<string, unknown> | null | undefined} compliance
- * @returns {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>}
+ * @param {readonly AppliedObligation[]} obligations the tenant's resolved obligations
+ * @returns {Partial<Record<CoherenceCheckId, { field: string, detail: string, hint: string }>>}
  */
-export function complianceCoherenceFailures(compliance) {
-  /** @type {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>} */
+export function complianceCoherenceFailures(compliance, obligations) {
+  /** @type {Partial<Record<CoherenceCheckId, { 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.",
     };
   }
@@ -69,16 +156,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;
 }

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

@@ -303,9 +303,14 @@ export async function resolvePublishedArtifactKey(
 
   const channel = channelFromEnv(env);
   if (pointer.channels?.[channel]) {
-    // Versioned model engaged for this channel — authoritative.
+    // Versioned model engaged for this channel — authoritative. The shared preview renders a
+    // version's captured images the way a pinned preview of it does; `live` never reads the
+    // overlay (its public path is the published bundle, which carries its own rewrites).
     const { versionId } = await resolveServableChannelVersion(get, tenantId, channel);
-    return versionId ? resolveVersionArtifactKey(get, tenantId, versionId, path) : null;
+    if (!versionId) return null;
+    return channel === "preview"
+      ? resolveCapturedVersionArtifactKey(get, tenantId, versionId, path)
+      : resolveVersionArtifactKey(get, tenantId, versionId, path);
   }
 
   // Legacy per-path selection.
@@ -313,6 +318,63 @@ export async function resolvePublishedArtifactKey(
   return versionId ? customizationArtifactKey(tenantId, versionId) : null;
 }
 
+/**
+ * Revision-bound overlay of capture-rewritten artifacts (`POST /api/preview/image-capture`). A
+ * site version is immutable; once its images are captured and sealed, the rewritten bytes of each
+ * artifact that named them are stored content-addressed and mapped here, so a preview of that
+ * version references platform-owned `/_a/` URLs instead of the source.
+ */
+export type ImagePreviewRewriteOverlay = {
+  version: 1;
+  revisionId: string;
+  /** Capture-manifest digest bound at write time; mismatched rewrite loses CAS. */
+  captureManifestDigest: string;
+  /** Full artifact path → content hash (same keys as SiteVersionManifest.artifacts). */
+  artifacts: Record<string, string>;
+};
+
+export function imagePreviewRewriteOverlayKey(tenantId: string, revisionId: string): string {
+  return `cust:image-preview-rewrite:${tenantId}:${revisionId}`;
+}
+
+export async function readImagePreviewRewriteOverlay(
+  get: KvGet,
+  tenantId: string,
+  revisionId: string,
+): Promise<ImagePreviewRewriteOverlay | null> {
+  try {
+    const raw = await get(imagePreviewRewriteOverlayKey(tenantId, revisionId));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<ImagePreviewRewriteOverlay>;
+    if (parsed.version !== 1 || parsed.revisionId !== revisionId) return null;
+    if (typeof parsed.captureManifestDigest !== "string") return null;
+    if (!/^sha256:[0-9a-f]{64}$/.test(parsed.captureManifestDigest)) return null;
+    if (!parsed.artifacts || typeof parsed.artifacts !== "object") return null;
+    return {
+      version: 1,
+      revisionId,
+      captureManifestDigest: parsed.captureManifestDigest,
+      artifacts: { ...parsed.artifacts },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The KV key of one artifact of an immutable version as a preview renders it: the capture
+ * overlay's rewritten bytes when the version's images are sealed, else the version's own.
+ */
+export async function resolveCapturedVersionArtifactKey(
+  get: KvGet,
+  tenantId: string,
+  versionId: string,
+  path: string,
+): Promise<string | null> {
+  const hash = (await readImagePreviewRewriteOverlay(get, tenantId, versionId))?.artifacts[path];
+  return hash ? customizationArtifactKey(tenantId, hash) : resolveVersionArtifactKey(get, tenantId, versionId, path);
+}
+
 /** The KV key of one artifact in an immutable site version, or null when the version lacks it. */
 export async function resolveVersionArtifactKey(
   get: KvGet,

package/packages/public-runtime/src/declared-tenant-config.d.mts

@@ -1,7 +1,7 @@
 /** Types for the dependency-free declared-tenant-config module (declared-tenant-config.mjs). */
 import type { TenantConfig } from "./tenant.js";
 
-export type DeclaredTenantConfigField = "displayName" | "siteType" | "compliance" | "capabilities" | "features" | "embeds" | "seo";
+export type DeclaredTenantConfigField = "displayName" | "siteType" | "compliance" | "capabilities" | "features" | "embeds" | "seo" | "currency" | "shipping";
 export type DeclaredTenantConfig = Partial<Pick<TenantConfig, DeclaredTenantConfigField>>;
 
 export const DECLARED_TENANT_CONFIG_FIELDS: readonly DeclaredTenantConfigField[];
@@ -9,6 +9,10 @@ export const TOT_CONFIG_KEYS: readonly string[];
 export const COMPLIANCE_KEYS: readonly string[];
 export const FEATURE_KEYS: readonly string[];
 export const SITE_TYPES_LIST: readonly string[];
+export const DEFAULT_CURRENCY: "USD";
+export const CURRENCY_CODES: readonly string[];
+export function resolveStoreCurrency(declared: unknown): string;
+export function currencyDeclarationProblems(currency: unknown): string[];
 export const SEO_KEYS: readonly string[];
 export const STRUCTURED_DATA_KEYS: readonly string[];
 export const STRUCTURED_DATA_PAGE_TYPES: readonly import("./tenant.js").StructuredDataPageType[];
@@ -16,11 +20,18 @@ export const STRUCTURED_DATA_NODE_TOKENS: readonly import("./tenant.js").Structu
 export const STRUCTURED_DATA_NAMED_TYPES: readonly string[];
 export const STRUCTURED_DATA_NAME_SOURCES: readonly string[];
 export function seoDeclarationProblems(seo: unknown): string[];
+export const SHIPPING_KEYS: readonly string[];
+export const MAX_SHIPPING_AMOUNT: number;
+export function shippingDeclarationProblems(shipping: unknown): string[];
 export function declaredTenantConfig(config: unknown): DeclaredTenantConfig;
 export function isEmptyDeclaredTenantConfig(declared: DeclaredTenantConfig | null | undefined): boolean;
+/**
+ * `declared` is a declaration that was READ. An unread one (`null`) is not accepted: applying it
+ * would render or judge the store by its bare record — decide what unread means first.
+ */
 export function applyDeclaredTenantConfig<T extends Partial<Pick<TenantConfig, DeclaredTenantConfigField>>>(
   tenant: T,
-  declared: DeclaredTenantConfig | null | undefined,
+  declared: DeclaredTenantConfig,
 ): T;
 export function readDeclaredTenantConfigAt(
   source: { readFile(path: string, ref: string): Promise<string | null> },

package/packages/public-runtime/src/declared-tenant-config.mjs

@@ -26,6 +26,8 @@ export const DECLARED_TENANT_CONFIG_FIELDS = Object.freeze([
   "features",
   "embeds",
   "seo",
+  "currency",
+  "shipping",
 ]);
 
 /**
@@ -65,6 +67,7 @@ export const FEATURE_KEYS = Object.freeze([
   "productSearch",
   "savedItems",
   "quickView",
+  "productBadges",
   "newsletter",
   "commerceSitemap",
   "productJsonLd",
@@ -109,6 +112,43 @@ export const STRUCTURED_DATA_NODE_TOKENS = Object.freeze([
 export const STRUCTURED_DATA_NAMED_TYPES = Object.freeze(["Product", "ProductGroup", "Article", "BlogPosting"]);
 export const STRUCTURED_DATA_NAME_SOURCES = Object.freeze(["documentTitle", "title"]);
 
+/** 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"`];
+}
+
 const SITE_TYPES = new Set(SITE_TYPES_LIST);
 
 const isPlainObject = (value) =>
@@ -202,6 +242,40 @@ export function seoDeclarationProblems(seo) {
   return problems;
 }
 
+/** Every `shipping` key (ShippingPolicy, tenant.ts). */
+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 declared TenantConfig fields from a parsed `.tot/config.json`. A field whose
  * value has the wrong shape is omitted, never coerced (`tot validate` reports it).
@@ -212,7 +286,7 @@ export function declaredTenantConfig(config) {
   /** @type {Record<string, unknown>} */
   const out = {};
   if (!isPlainObject(config)) return out;
-  const { displayName, siteType, compliance, capabilities, features, embeds, seo } = /** @type {Record<string, unknown>} */ (config);
+  const { displayName, siteType, compliance, capabilities, features, embeds, seo, currency, shipping } = /** @type {Record<string, unknown>} */ (config);
   // The store's name as visitors read it: the `<title>` suffix, og:site_name,
   // Organization JSON-LD, breadcrumbs, the default blog heading, the copyright line.
   if (typeof displayName === "string" && displayName.trim()) out.displayName = displayName.trim();
@@ -223,6 +297,14 @@ export function declaredTenantConfig(config) {
   if (Array.isArray(embeds) && embeds.every((slug) => typeof slug === "string")) out.embeds = embeds;
   // URL form and the structured-data profile: refused whole when any part is malformed.
   if (seo !== undefined && seoDeclarationProblems(seo).length === 0) out.seo = seo;
+  // Wrong-shaped or unknown codes are omitted: the store sells in USD (`tot validate` reports it).
+  if (currency !== undefined && currencyDeclarationProblems(currency).length === 0) out.currency = currency;
+  // The shipping charge: refused whole when any part is malformed (`tot validate` and the
+  // reconcile report it), so checkout keeps charging no shipping rather than a guess.
+  if (shipping !== undefined && shippingDeclarationProblems(shipping).length === 0) {
+    const policy = /** @type {Record<string, number>} */ (shipping);
+    out.shipping = { flatRate: policy.flatRate, ...(policy.freeAtOrAbove === undefined ? {} : { freeAtOrAbove: policy.freeAtOrAbove }) };
+  }
   return out;
 }
 

package/packages/public-runtime/src/image-preview-rewrite-overlay.ts

@@ -4,21 +4,21 @@
  * Site-version manifests are immutable; successful `/_a/<sha>` rewrites are
  * stored as content-addressed artifact bytes plus this overlay map. Preview
  * reads prefer the overlay so candidate documents reference platform-owned URLs.
+ * The record and its key-level resolution live in `customization-runtime.ts`,
+ * which every versioned read goes through.
  */
-import { contentArtifactPath, customizationArtifactKey, themeArtifactPath } from "./customization-runtime.js";
+import {
+  contentArtifactPath,
+  customizationArtifactKey,
+  readImagePreviewRewriteOverlay,
+  themeArtifactPath,
+} from "./customization-runtime.js";
 
-export type ImagePreviewRewriteOverlay = {
-  version: 1;
-  revisionId: string;
-  /** Capture-manifest digest bound at write time; mismatched rewrite loses CAS. */
-  captureManifestDigest: string;
-  /** Full artifact path → content hash (same keys as SiteVersionManifest.artifacts). */
-  artifacts: Record<string, string>;
-};
-
-export function imagePreviewRewriteOverlayKey(tenantId: string, revisionId: string): string {
-  return `cust:image-preview-rewrite:${tenantId}:${revisionId}`;
-}
+export {
+  imagePreviewRewriteOverlayKey,
+  readImagePreviewRewriteOverlay,
+  type ImagePreviewRewriteOverlay,
+} from "./customization-runtime.js";
 
 /** Map a repo-relative capture artifact path to the preview manifest artifact path. */
 export function previewManifestPathFor(tenantId: string, repoPath: string): string {
@@ -29,30 +29,6 @@ export function previewManifestPathFor(tenantId: string, repoPath: string): stri
   return `tenants/${tenantId}/${repoPath}`;
 }
 
-export async function readImagePreviewRewriteOverlay(
-  get: (key: string) => Promise<string | null>,
-  tenantId: string,
-  revisionId: string,
-): Promise<ImagePreviewRewriteOverlay | null> {
-  try {
-    const raw = await get(imagePreviewRewriteOverlayKey(tenantId, revisionId));
-    if (!raw) return null;
-    const parsed = JSON.parse(raw) as Partial<ImagePreviewRewriteOverlay>;
-    if (parsed.version !== 1 || parsed.revisionId !== revisionId) return null;
-    if (typeof parsed.captureManifestDigest !== "string") return null;
-    if (!/^sha256:[0-9a-f]{64}$/.test(parsed.captureManifestDigest)) return null;
-    if (!parsed.artifacts || typeof parsed.artifacts !== "object") return null;
-    return {
-      version: 1,
-      revisionId,
-      captureManifestDigest: parsed.captureManifestDigest,
-      artifacts: { ...parsed.artifacts },
-    };
-  } catch {
-    return null;
-  }
-}
-
 /** Prefer overlay bytes for a full artifact path when present. */
 export async function readWithImagePreviewRewriteOverlay(
   get: (key: string) => Promise<string | null>,

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

@@ -278,6 +278,8 @@ export interface MemberSignedCartPayloadOptions {
   autopilotEnabled: boolean;
   /** Tenant id written onto the signed `tenant` field when present. */
   tenantId?: string;
+  /** The store's currency, signed into the cart (see {@link BuildVariantCartPayloadOptions.currency}). */
+  currency?: string;
 }
 
 /**
@@ -312,6 +314,7 @@ export async function buildMemberSignedCartPayload(
     signedPrice: effective.price,
     autopilotEnabled: opts.autopilotEnabled,
     tenantId: opts.tenantId,
+    currency: opts.currency,
   });
 }
 

package/packages/public-runtime/src/publication-space.ts

@@ -90,6 +90,7 @@ export const PUBLICATION_SPACE_RESERVED_MOUNTS = [
   "/products",
   "/collections",
   "/search",
+  "/catalog-index.json",
   "/saved",
   "/robots.txt",
   "/shared",

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

@@ -12,7 +12,6 @@ import type { IntegrationDeclarationInput } from "./integration/resolve.js";
 import type { EuUkVisitorPolicy } from "./integration/plan.js";
 import type { PublicationSpaceManifestV1 } from "./publication-space.js";
 import type { HtmlCachePolicy } from "./html-cache-policy.js";
-import type { SyntheticCommerceAuthorityPolicy } from "./checkout-orders.js";
 
 /**
  * The shared semantic COLOR contract — the widget library's public API.
@@ -430,6 +429,8 @@ export interface TenantFeatures {
   savedItems: boolean;
   /** Product quick-view dialog island. */
   quickView: boolean;
+  /** Promotional product badges (Sale, New, Compliant) on cards and the PDP. Sold out always shows. */
+  productBadges: boolean;
   /** Newsletter capture forms (footer + homepage block). */
   newsletter: boolean;
   /** Product/collection URLs in the XML sitemap. */
@@ -445,6 +446,7 @@ const COMMERCE_FEATURES: TenantFeatures = {
   productSearch: true,
   savedItems: true,
   quickView: true,
+  productBadges: true,
   newsletter: true,
   commerceSitemap: true,
   productJsonLd: true,
@@ -456,6 +458,7 @@ const MARKETING_FEATURES: TenantFeatures = {
   productSearch: false,
   savedItems: false,
   quickView: false,
+  productBadges: false,
   newsletter: false,
   commerceSitemap: false,
   productJsonLd: false,
@@ -512,7 +515,11 @@ export interface TenantConfig {
   tot_data_scope: string;
   /** Per-tenant theme overrides; merged over the reference theme defaults. */
   theme_tokens: DeepPartial<ThemeTokens>;
-  /** Currency for display formatting. */
+  /**
+   * The ISO 4217 code the store sells in: priced, signed into the cart and formatted. USD unless
+   * `.tot/config.json` declares another; read it through `resolveStoreCurrency`
+   * (declared-tenant-config.mjs), never as a literal.
+   */
   currency: string;
   locale: string;
   /** Explicit publication spaces for this tenant, including one canonical root. */
@@ -610,8 +617,6 @@ export interface TenantConfig {
    */
   commerce?: {
     checkout?: ManagedCheckoutConfig;
-    /** Server-owned applicability for nonbillable synthetic fixtures; never waives regulated rules. */
-    authorityPolicy?: SyntheticCommerceAuthorityPolicy;
     /**
      * Autopilot (subscription) program visibility. Absent → subscription
      * purchase options render wherever a product authors them (framework/dev
@@ -759,6 +764,25 @@ export interface TenantConfig {
    * canonical URL shape and the JSON-LD graph its rankings were earned under.
    */
   seo?: SeoDeclaration;
+  /**
+   * What checkout charges for shipping, declared in `.tot/config.json` (validated by
+   * `shippingDeclarationProblems`, declared-tenant-config.mjs). Absent ⇒ checkout charges no
+   * shipping. Amounts are in the cart's own currency.
+   */
+  shipping?: ShippingPolicy;
+}
+
+/**
+ * A store's shipping charge: one flat rate per order, waived when the order's item subtotal
+ * is at or above `freeAtOrAbove`. The cart carries it as the signed `shipping_policy` option;
+ * the checkout store charges it and the final-cart authority re-derives it from this
+ * declaration (checkout.ts `shippingMinorFor`).
+ */
+export interface ShippingPolicy {
+  /** Charged once per order, in the cart's currency. `0` ships every order free. */
+  flatRate: number;
+  /** Item subtotal at or above which shipping is free, in the cart's currency. */
+  freeAtOrAbove?: number;
 }
 
 /** Page types a structured-data profile declares a graph for (STRUCTURED_DATA_PAGE_TYPES). */