@tokenoftrust/storefront-runner 2.2.126 → 2.3.1

package/package.json

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

@@ -17,7 +17,7 @@
 
 export const TOT_CONFIG_KEYS = [
   "$schema", "tenant", "scope", "mappings", "hostPlatform", "sample", "seed",
-  "siteType", "compliance", "capabilities", "features", "embeds",
+  "displayName", "siteType", "compliance", "capabilities", "features", "embeds",
 ];
 // Keys other tooling has written that the platform does NOT read, with the key it does.
 const RENAMED_CONFIG_KEYS = { appDomain: "scope", tenantId: "tenant" };
@@ -59,6 +59,99 @@ const ERROR = "error";
 const WARN = "warn";
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 
+/**
+ * Compliance coherence — the declared-config half of the hosted preview's `age_gate`,
+ * `excise` and `jurisdiction` evidence checks, so `tot validate` fails locally on
+ * exactly what the reconcile fails. Mirrors
+ * 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 function declaresJurisdictionNotice(compliance) {
+  const text = compliance?.shippingRestriction;
+  return compliance?.pactAct === true || (typeof text === "string" && text.trim().length > 0);
+}
+
+/**
+ * @param {Record<string, any> | null | undefined} compliance
+ * @returns {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>}
+ */
+export function complianceCoherenceFailures(compliance) {
+  /** @type {Partial<Record<"age_gate" | "excise" | "jurisdiction", { field: string, detail: string, hint: string }>>} */
+  const out = {};
+  if (!isRegulatedCompliance(compliance)) return out;
+  const minAge = typeof compliance?.minAge === "number" ? compliance.minAge : null;
+  if (minAge == null || minAge < 18) {
+    out.age_gate = {
+      field: "compliance.minAge",
+      detail: "Age-restricted/nicotine products require `compliance.minAge` (18 or higher) — none is set.",
+      hint: "Set `compliance.minAge` (18+) in .tot/config.json.",
+    };
+  }
+  if (compliance?.nicotineWarning && (minAge == null || minAge < 21)) {
+    out.excise = {
+      field: "compliance.minAge",
+      detail: "Nicotine products (`compliance.nicotineWarning`) require `compliance.minAge` of 21 or higher.",
+      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.",
+    };
+  }
+  return out;
+}
+
+/**
+ * The compliance findings `tot validate` reports for a declared block: an ERROR per
+ * coherence failure the hosted preview would fail (`evidence-<check>`), and a WARNING
+ * when a regulated store declares no `ruleProfile` — its preview renders, but going
+ * live refuses because no checkout rules resolve.
+ * @param {Record<string, any>} config
+ * @param {string} file
+ * @returns {Finding[]}
+ */
+export function complianceFindings(config, file = ".tot/config.json") {
+  const compliance = isObject(config?.compliance) ? config.compliance : null;
+  const out = [];
+  for (const [check, failure] of Object.entries(complianceCoherenceFailures(compliance))) {
+    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) {
+    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) {
+    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.",
+      "Remove `capabilities.exciseTax.enabled: false` from .tot/config.json."));
+  }
+  if (isRegulatedCompliance(compliance) && !compliance?.ruleProfile) {
+    out.push(mk(WARN, "compliance-rule-profile", `${file} compliance`,
+      "This store is regulated (`compliance.minAge`/`compliance.nicotineWarning`) 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.'));
+  }
+  return out;
+}
+
 /** @typedef {{level:string, rule:string, file:string, message:string, fix?:string}} Finding */
 function mk(level, rule, file, message, fix) {
   return { level, rule, file, message, fix };
@@ -160,12 +253,30 @@ export function droppedMandatedNotices(previous, current) {
     .map((key) => ({ key, notice: COMPLIANCE_NOTICES[/** @type {keyof typeof COMPLIANCE_NOTICES} */ (key)] }));
 }
 
+/**
+ * The FDA nicotine warning presentation this revision would put live that the live site does
+ * not already show: a custom (non-preset) presentation whose resolved values differ from the
+ * live revision's. Null when the warning is off, invalid, a validated preset, or unchanged.
+ * @param {Record<string, any> | null | undefined} current
+ * @param {Record<string, any> | null | undefined} previous
+ * @returns {string | null} the exact presentation, as describeNicotineWarningPresentation states it
+ */
+export function unreviewedNicotineWarningPresentation(current, previous) {
+  const now = resolveNicotineWarning(isObject(current?.compliance) ? current.compliance.nicotineWarning : undefined);
+  if (!now.enabled || !now.custom) return null;
+  const before = resolveNicotineWarning(isObject(previous?.compliance) ? previous.compliance.nicotineWarning : undefined);
+  const spec = describeNicotineWarningPresentation(now.presentation);
+  return before.enabled && before.custom && describeNicotineWarningPresentation(before.presentation) === spec ? null : spec;
+}
+
 /**
  * The publication validator's findings for a revision's declaration: an owner-approvable
- * `CONFIG:` finding per unknown key and a `COMPLIANCE:` finding per mandated notice the
- * live site shows and this revision drops. Both are QUALITY findings
- * (scripts/publish/lib/finding-severity.mjs): publication halts until the owner accepts
- * them through "Accept issue & continue".
+ * `CONFIG:` finding per unknown key or invalid nicotine-warning presentation, a `COMPLIANCE:`
+ * finding per mandated notice the live site shows and this revision drops, and a
+ * `COMPLIANCE:` finding for a custom nicotine-warning presentation the live site does not
+ * already show. All are QUALITY findings (scripts/publish/lib/finding-severity.mjs):
+ * publication halts until the owner accepts them through "Accept issue & continue", which
+ * records who accepted these exact findings, when, and why.
  * @param {Record<string, any> | null | undefined} current
  * @param {Record<string, any> | null | undefined} previous
  * @returns {string[]}
@@ -174,6 +285,10 @@ export function declarationFindings(current, previous) {
   const out = [];
   if (isObject(current)) {
     for (const unknown of unknownConfigKeys(current)) out.push(`CONFIG: ${unknownKeyMessage(unknown)}`);
+    const warning = resolveNicotineWarning(isObject(current.compliance) ? current.compliance.nicotineWarning : undefined);
+    if (warning.enabled && warning.problems.length > 0) {
+      out.push(`CONFIG: ${nicotineWarningProblemMessage(warning.problems)}`);
+    }
   }
   for (const { key, notice } of droppedMandatedNotices(previous, current)) {
     out.push(
@@ -181,9 +296,22 @@ export function declarationFindings(current, previous) {
         `declares it — publishing removes a mandated notice from the store.`,
     );
   }
+  const custom = unreviewedNicotineWarningPresentation(current, previous);
+  if (custom) {
+    out.push(
+      `COMPLIANCE: the FDA nicotine warning uses a custom presentation outside the validated presets — ${custom}. ` +
+        `Approving records that you reviewed exactly these values; changing any of them asks again.`,
+    );
+  }
   return out;
 }
 
+/** The owner-facing sentence for an invalid `compliance.nicotineWarning`. */
+function nicotineWarningProblemMessage(problems) {
+  return `\`compliance.nicotineWarning\` is not a valid presentation (${problems.join("; ")}). ` +
+    `The warning renders in the default "dark" preset instead.`;
+}
+
 /**
  * The validator's report on a `.tot/config.json`: a WARNING per unknown key (owner-approved
  * before publication), an error per wrong-shaped value of a known key.
@@ -202,6 +330,10 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
         ? `rename it to \`${unknown.suggestion}\`, or keep it and approve the warning when you publish`
         : "remove it, or keep it and approve the warning when you publish"));
   }
+  if (config.displayName !== undefined && !(typeof config.displayName === "string" && config.displayName.trim())) {
+    out.push(mk(ERROR, "config-display-name", file,
+      "`displayName` must be a non-empty string — the store's name as visitors read it (page titles, og:site_name, the copyright line)"));
+  }
   if (config.siteType !== undefined && !SITE_TYPES.includes(config.siteType)) {
     out.push(mk(ERROR, "config-site-type", file, `\`siteType\` is "${config.siteType}" — must be one of ${SITE_TYPES.join(", ")}`));
   }
@@ -210,6 +342,18 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
       out.push(mk(ERROR, `config-${field}`, file, `\`${field}\` must be an object`));
     }
   }
+  out.push(...complianceFindings(config, file));
+  const warning = resolveNicotineWarning(isObject(config.compliance) ? config.compliance.nicotineWarning : undefined);
+  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'));
+  } else if (warning.custom) {
+    out.push(mk(WARN, "config-nicotine-warning-custom", `${file} compliance`,
+      `\`compliance.nicotineWarning\` uses a custom presentation outside the validated presets — ` +
+        `${describeNicotineWarningPresentation(warning.presentation)}. It renders in preview; it goes live only ` +
+        `after you approve it in the go-live compliance review.`,
+      'use a preset (`"dark"`, `"light"`) to skip the review, or keep it and approve it when you publish'));
+  }
   if (config.capabilities !== undefined && !isObject(config.capabilities)) {
     out.push(mk(ERROR, "config-capabilities", file, "`capabilities` must be an object"));
   }
@@ -219,3 +363,254 @@ export function validateDeclaredConfig(config, file = ".tot/config.json") {
   }
   return out;
 }
+
+// ── The FDA nicotine warning (21 CFR 1143.3): what compliance.nicotineWarning may declare ──
+//
+// The wording is fixed by law and is not configurable. The presentation is one of the
+// validated presets, or a custom style built on one:
+//
+//   "nicotineWarning": true                                   → the "dark" preset
+//   "nicotineWarning": { "preset": "light" }                  → a validated preset
+//   "nicotineWarning": { "preset": "light", "style": {...} }  → a custom presentation
+//
+// 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:
+// declarationFindings raises it as a COMPLIANCE finding that spells out every resolved style
+// value, and the owner's "Accept issue & continue" records who approved exactly those values,
+// when, and why. Any change to the styling produces a different finding, so it is reviewed again.
+//
+// The style keys are a closed set of colours, case, weight and size. Nothing here can position,
+// hide, shrink below the floor, or dismiss the warning, and a declaration that is invalid renders
+// the default preset rather than nothing. The hosted renderer (NicotineWarning.astro and the
+// raw-HTML path) renders through nicotineWarningHtml, so every surface presents it identically.
+
+export const NICOTINE_WARNING_TEXT =
+  "WARNING: This product contains nicotine. Nicotine is an addictive chemical.";
+
+/** The floor every presentation clears: WCAG AAA text contrast, a 12px minimum, semibold or heavier. */
+export const CONSPICUITY_FLOOR = Object.freeze({ contrast: 7, fontSizePx: 12, fontWeight: 600 });
+
+/** Bounds on the size a custom style may declare, so the bar cannot swallow the header. */
+const MAX_FONT_SIZE_PX = 24;
+
+export const DEFAULT_NICOTINE_WARNING_PRESET = "dark";
+
+/**
+ * The validated presets. `dark` is the platform default; `light` matches a light bar with a
+ * dark border and bold normal-case text.
+ * @type {Readonly<Record<string, Readonly<NicotineWarningPresentation>>>}
+ */
+export const NICOTINE_WARNING_PRESETS = Object.freeze({
+  dark: Object.freeze({
+    background: "#111111",
+    text: "#ffffff",
+    border: "#111111",
+    textTransform: "uppercase",
+    fontWeight: 600,
+    fontSizePx: 12,
+  }),
+  light: Object.freeze({
+    background: "#e6e6e6",
+    text: "#000000",
+    border: "#000000",
+    textTransform: "none",
+    fontWeight: 700,
+    fontSizePx: 14,
+  }),
+});
+
+/**
+ * @typedef {{
+ *   background: string,
+ *   text: string,
+ *   border: string,
+ *   textTransform: "uppercase" | "none",
+ *   fontWeight: number,
+ *   fontSizePx: number,
+ * }} NicotineWarningPresentation
+ */
+
+export const NICOTINE_WARNING_STYLE_KEYS = Object.freeze([
+  "background", "text", "border", "textTransform", "fontWeight", "fontSizePx",
+]);
+const TEXT_TRANSFORMS = ["uppercase", "none"];
+const FONT_WEIGHTS = [600, 700, 800, 900];
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+/** `#abc` / `#AABBCC` → `#aabbcc`. */
+function normalizeHex(value) {
+  const hex = value.slice(1).toLowerCase();
+  return `#${hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex}`;
+}
+
+function luminance(hex) {
+  const n = normalizeHex(hex);
+  const [r, g, b] = [1, 3, 5].map((i) => {
+    const c = parseInt(n.slice(i, i + 2), 16) / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG 2 contrast ratio between two hex colours. */
+export function contrastRatio(a, b) {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/**
+ * Why a presentation is not conspicuous enough — empty when it clears the floor.
+ * @param {NicotineWarningPresentation} p
+ * @returns {string[]}
+ */
+export function conspicuityProblems(p) {
+  const out = [];
+  const ratio = contrastRatio(p.text, p.background);
+  if (ratio < CONSPICUITY_FLOOR.contrast) {
+    out.push(`text ${p.text} on background ${p.background} has contrast ${ratio.toFixed(2)}:1 — the floor is ${CONSPICUITY_FLOOR.contrast}:1`);
+  }
+  if (p.fontSizePx < CONSPICUITY_FLOOR.fontSizePx) {
+    out.push(`font size ${p.fontSizePx}px is below the ${CONSPICUITY_FLOOR.fontSizePx}px floor`);
+  }
+  if (p.fontWeight < CONSPICUITY_FLOOR.fontWeight) {
+    out.push(`font weight ${p.fontWeight} is below the ${CONSPICUITY_FLOOR.fontWeight} floor`);
+  }
+  return out;
+}
+
+/** Why one declared style value is not usable, or null. */
+function styleValueProblem(key, value) {
+  switch (key) {
+    case "background":
+    case "text":
+    case "border":
+      return typeof value === "string" && HEX.test(value) ? null : `\`${key}\` must be a hex colour like "#e6e6e6"`;
+    case "textTransform":
+      return TEXT_TRANSFORMS.includes(value) ? null : `\`textTransform\` must be one of ${TEXT_TRANSFORMS.map((t) => `"${t}"`).join(", ")}`;
+    case "fontWeight":
+      return FONT_WEIGHTS.includes(value) ? null : `\`fontWeight\` must be one of ${FONT_WEIGHTS.join(", ")}`;
+    case "fontSizePx":
+      return typeof value === "number" && Number.isFinite(value) && value >= CONSPICUITY_FLOOR.fontSizePx && value <= MAX_FONT_SIZE_PX
+        ? null
+        : `\`fontSizePx\` must be a number from ${CONSPICUITY_FLOOR.fontSizePx} to ${MAX_FONT_SIZE_PX}`;
+    default:
+      return `\`${key}\` is not a nicotine-warning style key (allowed: ${NICOTINE_WARNING_STYLE_KEYS.join(", ")})`;
+  }
+}
+
+function samePresentation(a, b) {
+  return NICOTINE_WARNING_STYLE_KEYS.every((k) => a[k] === b[k]);
+}
+
+/**
+ * @typedef {{
+ *   enabled: boolean,
+ *   presentation: NicotineWarningPresentation,
+ *   preset: string | null,
+ *   custom: boolean,
+ *   problems: string[],
+ * }} ResolvedNicotineWarning
+ */
+
+/**
+ * Resolve a `compliance.nicotineWarning` declaration to what renders.
+ *
+ * `preset` names the preset the presentation equals (null for a custom one); `custom` is
+ * true when the owner must review it; `problems` lists why the declaration is invalid, in
+ * which case the default preset renders. A disabled declaration (absent, `false`) resolves
+ * `enabled: false`.
+ * @param {unknown} declaration
+ * @returns {ResolvedNicotineWarning}
+ */
+export function resolveNicotineWarning(declaration) {
+  const fallback = NICOTINE_WARNING_PRESETS[DEFAULT_NICOTINE_WARNING_PRESET];
+  const resolved = (/** @type {Partial<ResolvedNicotineWarning>} */ fields) => ({
+    enabled: true,
+    presentation: { ...fallback },
+    preset: DEFAULT_NICOTINE_WARNING_PRESET,
+    custom: false,
+    problems: [],
+    ...fields,
+  });
+  if (!declaration) return resolved({ enabled: false });
+  if (declaration === true) return resolved({});
+  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 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(", ")}`);
+  }
+  if (style !== undefined && !isObject(style)) problems.push("`style` must be an object");
+  const declaredStyle = isObject(style) ? /** @type {Record<string, unknown>} */ (style) : {};
+  for (const [key, value] of Object.entries(declaredStyle)) {
+    const problem = styleValueProblem(key, value);
+    if (problem) problems.push(problem);
+  }
+  if (problems.length > 0 || !base) return resolved({ problems });
+
+  /** @type {NicotineWarningPresentation} */
+  const presentation = { ...base };
+  for (const [key, value] of Object.entries(declaredStyle)) {
+    presentation[/** @type {keyof NicotineWarningPresentation} */ (key)] =
+      /** @type {never} */ (typeof value === "string" && HEX.test(value) ? normalizeHex(value) : value);
+  }
+  const conspicuity = conspicuityProblems(presentation);
+  if (conspicuity.length > 0) return resolved({ problems: conspicuity });
+  const matching = Object.keys(NICOTINE_WARNING_PRESETS).find((name) => samePresentation(NICOTINE_WARNING_PRESETS[name], presentation));
+  return resolved({ presentation, preset: matching ?? null, custom: !matching });
+}
+
+/**
+ * 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
+ * differently.
+ * @param {NicotineWarningPresentation} p
+ */
+export function describeNicotineWarningPresentation(p) {
+  return `background ${p.background}, text ${p.text}, border ${p.border}, ` +
+    `${p.textTransform === "uppercase" ? "uppercase" : "normal case"}, weight ${p.fontWeight}, ${p.fontSizePx}px`;
+}
+
+/**
+ * The warning's markup — the one rendering shared by NicotineWarning.astro and the raw-HTML
+ * serve path, so both present the same declaration identically. "bar" is the strip at the top
+ * 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.
+ * @param {unknown} declaration the tenant's `compliance.nicotineWarning`
+ * @param {"bar" | "block"} variant
+ */
+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"}"`;
+  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>`;
+}
+
+/**
+ * Inline CSS for a presentation. `variant` "block" (the product page) never renders smaller
+ * than 14px.
+ * @param {NicotineWarningPresentation} p
+ * @param {"bar" | "block"} variant
+ */
+export function nicotineWarningStyle(p, variant) {
+  const size = variant === "block" ? Math.max(p.fontSizePx, 14) : p.fontSizePx;
+  const frame = variant === "bar"
+    ? [`border-bottom:2px solid ${p.border}`]
+    : [`border:2px solid ${p.border}`, "border-radius:var(--radius-md)", "padding:0.75rem 1rem"];
+  return [
+    ...frame,
+    `background-color:${p.background}`,
+    `color:${p.text}`,
+    `text-transform:${p.textTransform}`,
+    `letter-spacing:${p.textTransform === "uppercase" ? "0.06em" : "normal"}`,
+    `font-weight:${p.fontWeight}`,
+    `font-size:${size}px`,
+    "line-height:1.4",
+  ].join(";");
+}

package/packages/public-runtime/package.json

@@ -22,6 +22,7 @@
     "./retention-holds": "./src/retention-holds.ts",
     "./tenant-embed-defaults": "./src/tenant-embed-defaults.mjs",
     "./declared-tenant-config": "./src/declared-tenant-config.mjs",
+    "./compliance-coherence": "./src/compliance-coherence.mjs",
     "./integration/lifecycle-host-asset": "./src/integration/lifecycle-host-asset.mjs",
     "./integration/native-ga4-sandbox-asset": "./src/integration/native-ga4-sandbox-asset.mjs",
     "./integration/visitor-region": "./src/integration/visitor-region.mjs"

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

@@ -59,6 +59,19 @@ export interface ManagedCheckoutConfig {
   cartDrawerCss?: string;
 }
 
+/**
+ * The ONE shared ToT-owned demo checkout store (test mode, cart validation
+ * OFF, no secret). The local dev loop (`synthesizeDevTenant`) wires every
+ * local commerce checkout to this exact config; the hosted QA/test tier's
+ * demo-checkout fallback (`resolveTenantCommerce`) reuses this same constant
+ * rather than a second copy of the literal, so "the same as `tot dev`" stays
+ * true by construction instead of by two authors agreeing.
+ */
+export const SHARED_DEMO_CHECKOUT: ManagedCheckoutConfig = {
+  storeSubDomain: "tot-preview",
+  mode: "unsigned-demo",
+};
+
 /** Resolved, request-scoped commerce facts stashed on `Astro.locals`. */
 export interface ResolvedManagedCheckout extends ManagedCheckoutConfig {
   /** `https://<storeDomain>` — the loader + cart origin (for CSP + links). */

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

@@ -141,6 +141,35 @@ export interface ChromeSearch {
   placeholder?: string;
   /** sr-only label (defaults to "Search"). */
   label?: string;
+  /** Visible text on the submit button (e.g. "Search"). Omit for the icon button. */
+  buttonLabel?: string;
+}
+
+/**
+ * What a header action link stands for. "link" is a plain text link (e.g.
+ * "Register"); "account" and "cart" can show their icon, and a "cart" link is
+ * the cart affordance — bound to the managed checkout like the icon cart, with
+ * its item count.
+ */
+export const HEADER_ACTION_KINDS = ["link", "account", "cart"] as const;
+export type HeaderActionKind = (typeof HEADER_ACTION_KINDS)[number];
+
+/** A labelled link in the header's actions cluster (e.g. "Sign in", "Register", "Cart"). */
+export type ChromeHeaderActionLink = ChromeLink & {
+  /** Defaults to "link". */
+  kind?: HeaderActionKind;
+  /** Show the kind's icon before the label ("account" / "cart" only). */
+  icon?: boolean;
+};
+
+/** Narrow-viewport header arrangement. Every field defaults to the standard layout. */
+export interface ChromeHeaderMobile {
+  /** Side the menu button sits on (default "right"); "left" also opens the drawer from the left. */
+  menu?: "left" | "right";
+  /** Brand alignment in the bar (default "start"). */
+  brand?: "start" | "center";
+  /** Search placement (default "row", a full-width row under the bar); "menu" moves it into the menu drawer. */
+  search?: "row" | "menu";
 }
 
 /** The thin utility bar above the header: minor links, locale chips, social, cue. */
@@ -292,8 +321,18 @@ export interface ChromeHeader {
   announcement?: ChromeAnnouncement;
   /** Header-actions member-price cue (in addition to any utility-nav cue). */
   memberCue?: ChromeActionLink;
+  /** Icon account link. Not rendered when `actionLinks` is set. */
   accountHref?: string;
+  /** Icon cart link (bound to the managed checkout). Not rendered when `actionLinks` is set. */
   cartHref?: string;
+  /**
+   * Labelled action links (text, optional icon) in the header's actions
+   * cluster, in order. When set they replace the `accountHref` / `cartHref`
+   * icons; a `kind: "cart"` entry is the cart affordance.
+   */
+  actionLinks?: ChromeHeaderActionLink[];
+  /** Narrow-viewport arrangement (menu side, brand alignment, search placement). */
+  mobile?: ChromeHeaderMobile;
   /** Marketing conversion CTAs (non-commerce tenants), shown in the header's
    * actions cluster in place of the commerce search/saved controls. */
   ctas?: ChromeCta[];
@@ -308,8 +347,14 @@ export interface ChromeFooter {
   /** Accepted-payment marks (text tokens, e.g. "VISA"). */
   payments?: string[];
   social?: SocialLink[];
-  /** The bold compliance/nicotine warning block. */
+  /** The compliance/nicotine warning block, always led by a bold "WARNING:" label. */
   warning?: string;
+  /**
+   * The merchant's own legal/disclaimer copy (e.g. an FDA statement or PACT Act
+   * line), rendered verbatim with no label. Line breaks are kept. Never a
+   * substitute for `warning` or the declared compliance notices.
+   */
+  disclaimer?: string;
   /** Bottom bar: copyright + a legal note line. */
   bottom?: { copyright?: string; note?: string };
 }
@@ -325,6 +370,11 @@ export interface ChromeConfig {
   head?: ChromeHead;
   /** Skip-link target/label overrides (defaults to "#main" / "Skip to main content"). */
   skipLink?: { href?: string; label?: string };
+  /**
+   * Breadcrumb trail copy. `homeLabel` names the first crumb on every trail — the visible one and
+   * the `BreadcrumbList` structured data alike (defaults to "Home").
+   */
+  breadcrumbs?: { homeLabel?: string };
   /** FDA/compliance warning strip at the very top (e.g. the nicotine line). */
   warningBar?: string;
   /**
@@ -543,6 +593,34 @@ function validateAgeGate(v: unknown, path: string, errors: string[]): v is Chrom
   return errors.length === before;
 }
 
+function validateHeaderActionLink(v: unknown, path: string, errors: string[]): void {
+  if (!validateLink(v, path, errors)) return;
+  const link = v as Record<string, unknown>;
+  if (link.kind !== undefined && !(HEADER_ACTION_KINDS as readonly unknown[]).includes(link.kind)) {
+    errors.push(`${path}.kind: must be one of ${HEADER_ACTION_KINDS.join(", ")}`);
+  }
+  checkOptionalBoolean(link.icon, `${path}.icon`, errors);
+}
+
+const HEADER_MOBILE_OPTIONS = {
+  menu: ["left", "right"],
+  brand: ["start", "center"],
+  search: ["row", "menu"],
+} as const;
+
+function validateHeaderMobile(v: unknown, path: string, errors: string[]): void {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return;
+  }
+  for (const [field, allowed] of Object.entries(HEADER_MOBILE_OPTIONS)) {
+    const value = v[field];
+    if (value !== undefined && !(allowed as readonly unknown[]).includes(value)) {
+      errors.push(`${path}.${field}: must be one of ${allowed.join(", ")}`);
+    }
+  }
+}
+
 function validateHeader(v: unknown, path: string, errors: string[]): v is ChromeHeader {
   if (!isObject(v)) {
     errors.push(`${path}: required object`);
@@ -560,7 +638,15 @@ function validateHeader(v: unknown, path: string, errors: string[]): v is Chrome
   } else {
     v.nav.forEach((n, i) => validateNavItem(n, `${path}.nav[${i}]`, errors));
   }
-  if (v.search !== undefined && !isObject(v.search)) errors.push(`${path}.search: must be an object`);
+  if (v.search !== undefined) {
+    if (!isObject(v.search)) errors.push(`${path}.search: must be an object`);
+    else checkOptionalString(v.search.buttonLabel, `${path}.search.buttonLabel`, errors);
+  }
+  if (v.actionLinks !== undefined) {
+    if (!Array.isArray(v.actionLinks)) errors.push(`${path}.actionLinks: must be an array`);
+    else v.actionLinks.forEach((l, i) => validateHeaderActionLink(l, `${path}.actionLinks[${i}]`, errors));
+  }
+  if (v.mobile !== undefined) validateHeaderMobile(v.mobile, `${path}.mobile`, errors);
   if (v.utilityNav !== undefined) {
     const u = v.utilityNav;
     if (!isObject(u)) {
@@ -604,6 +690,7 @@ function validateFooter(v: unknown, path: string, errors: string[]): v is Chrome
     errors.push(`${path}.payments: must be an array of strings`);
   }
   checkOptionalString(v.warning, `${path}.warning`, errors);
+  checkOptionalString(v.disclaimer, `${path}.disclaimer`, errors);
   if (v.brand !== undefined && !isObject(v.brand)) errors.push(`${path}.brand: must be an object`);
   if (v.newsletter !== undefined && !isObject(v.newsletter)) errors.push(`${path}.newsletter: must be an object`);
   if (v.bottom !== undefined && !isObject(v.bottom)) errors.push(`${path}.bottom: must be an object`);
@@ -634,6 +721,10 @@ export function validateChromeConfig(raw: unknown): ChromeConfigValidationResult
   }
   if (raw.head !== undefined && !isObject(raw.head)) errors.push("head: must be an object");
   if (raw.skipLink !== undefined && !isObject(raw.skipLink)) errors.push("skipLink: must be an object");
+  if (raw.breadcrumbs !== undefined) {
+    if (!isObject(raw.breadcrumbs)) errors.push("breadcrumbs: must be an object");
+    else checkOptionalString(raw.breadcrumbs.homeLabel, "breadcrumbs.homeLabel", errors);
+  }
 
   if (errors.length > 0) return { ok: false, config: null, errors };
   return { ok: true, config: raw as unknown as ChromeConfig, errors: [] };

package/packages/public-runtime/src/compliance-coherence.d.mts

@@ -0,0 +1,17 @@
+/** Types for the dependency-free compliance-coherence module (compliance-coherence.mjs). */
+
+export type CoherenceCheckId = "age_gate" | "excise" | "jurisdiction";
+
+export interface CoherenceFailure {
+  /** The `compliance.*` field that resolves the failure. */
+  field: string;
+  detail: string;
+  hint: string;
+}
+
+export const COHERENCE_CHECK_IDS: readonly CoherenceCheckId[];
+export function isRegulatedCompliance(compliance: object | null | undefined): boolean;
+export function declaresJurisdictionNotice(compliance: object | null | undefined): boolean;
+export function complianceCoherenceFailures(
+  compliance: object | null | undefined,
+): Partial<Record<CoherenceCheckId, CoherenceFailure>>;