@tokenoftrust/storefront-runner 2.2.126 → 2.3.0

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

@@ -0,0 +1,84 @@
+/**
+ * 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:
+ *
+ *   - the hosted reconcile grades these checks with it
+ *     (packages/private-controlplane/src/evidence-producer.ts);
+ *   - `tot validate` reports the same failures locally, from the CLI's own copy
+ *     (packages/cli/src/declared-config.mjs), pinned to this one by
+ *     packages/cli/test/declared-config-parity.test.mjs.
+ *
+ * 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.
+ *
+ * Plain JS on purpose (same reason as declared-tenant-config.mjs): plain-`node`
+ * tooling and the CLI's parity test read it alongside the TypeScript runtime.
+ */
+
+/** The evidence checks this module grades, in report order. */
+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
+ */
+export function isRegulatedCompliance(compliance) {
+  const minAge = compliance?.minAge;
+  return (typeof minAge === "number" && minAge > 0) || !!compliance?.nicotineWarning;
+}
+
+/**
+ * True when the declared block renders a shipping/jurisdiction notice: the platform's
+ * fixed-wording PACT Act notice (`pactAct: true`) or the tenant's own restriction
+ * text (`shippingRestriction`). Both render in the site footer.
+ *
+ * @param {Record<string, unknown> | null | undefined} compliance
+ */
+export function declaresJurisdictionNotice(compliance) {
+  const text = compliance?.shippingRestriction;
+  return compliance?.pactAct === true || (typeof text === "string" && text.trim().length > 0);
+}
+
+/**
+ * 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.
+ *
+ * @param {Record<string, unknown> | 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;
+}

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 = "siteType" | "compliance" | "capabilities" | "features" | "embeds";
+export type DeclaredTenantConfigField = "displayName" | "siteType" | "compliance" | "capabilities" | "features" | "embeds";
 export type DeclaredTenantConfig = Partial<Pick<TenantConfig, DeclaredTenantConfigField>>;
 
 export const DECLARED_TENANT_CONFIG_FIELDS: readonly DeclaredTenantConfigField[];

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

@@ -19,6 +19,7 @@
 
 /** `.tot/config.json` keys that become TenantConfig fields. */
 export const DECLARED_TENANT_CONFIG_FIELDS = Object.freeze([
+  "displayName",
   "siteType",
   "compliance",
   "capabilities",
@@ -87,7 +88,10 @@ export function declaredTenantConfig(config) {
   /** @type {Record<string, unknown>} */
   const out = {};
   if (!isPlainObject(config)) return out;
-  const { siteType, compliance, capabilities, features, embeds } = /** @type {Record<string, unknown>} */ (config);
+  const { displayName, siteType, compliance, capabilities, features, embeds } = /** @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();
   if (typeof siteType === "string" && SITE_TYPES.has(siteType)) out.siteType = siteType;
   if (isPlainObject(compliance)) out.compliance = compliance;
   if (isPlainObject(capabilities)) out.capabilities = capabilities;
@@ -102,7 +106,7 @@ export function isEmptyDeclaredTenantConfig(declared) {
 }
 
 /**
- * Overlay a declaration onto a resolved tenant. `siteType` is replaced; the object
+ * Overlay a declaration onto a resolved tenant. `displayName` and `siteType` are replaced; the object
  * fields merge key by key, and `embeds` (catalog slugs) is unioned, so a declaration
  * adds to — and can set individual keys of — what the platform record already
  * carries, but never erases what it omits.

package/packages/public-runtime/src/extension-contract-values.d.mts

@@ -1,4 +1,4 @@
-export declare const BLOCK_PALETTE_CURRENT_CONTRACT: "block-palette@6";
+export declare const BLOCK_PALETTE_CURRENT_CONTRACT: "block-palette@7";
 export declare const BLOCK_PALETTE_SUPPORTED_CONTRACTS: readonly [
   "block-palette@1",
   "block-palette@2",
@@ -6,6 +6,7 @@ export declare const BLOCK_PALETTE_SUPPORTED_CONTRACTS: readonly [
   "block-palette@4",
   "block-palette@5",
   "block-palette@6",
+  "block-palette@7",
 ];
 export declare const FEATURED_PRODUCT_PRESENTATIONS: readonly ["grid", "carousel"];
 export declare const PROMO_TILE_PRESENTATIONS: readonly [
@@ -14,6 +15,8 @@ export declare const PROMO_TILE_PRESENTATIONS: readonly [
   "editorial-cards",
   "logo-strip",
 ];
+export declare const THEME_HEADING_LEVELS: readonly ["hero", "h1", "h2", "h3"];
+export declare function isThemeCssSize(value: unknown): value is string;
 export declare function isSafeRehostedAssetPath(value: unknown): value is string;
 export declare function isSafeRehostedAssetPathForTenant(value: unknown, tenantId: unknown): value is string;
 export declare function isSafeStorefrontHref(value: unknown): value is string;

package/packages/public-runtime/src/extension-contract-values.mjs

@@ -5,7 +5,7 @@
  * runtime and repository Node tooling. The separately published CLI mirrors
  * these values and pins that mirror with a parity test.
  */
-export const BLOCK_PALETTE_CURRENT_CONTRACT = "block-palette@6";
+export const BLOCK_PALETTE_CURRENT_CONTRACT = "block-palette@7";
 
 export const BLOCK_PALETTE_SUPPORTED_CONTRACTS = Object.freeze([
   "block-palette@1",
@@ -13,6 +13,7 @@ export const BLOCK_PALETTE_SUPPORTED_CONTRACTS = Object.freeze([
   "block-palette@3",
   "block-palette@4",
   "block-palette@5",
+  "block-palette@6",
   BLOCK_PALETTE_CURRENT_CONTRACT,
 ]);
 
@@ -25,6 +26,18 @@ export const PROMO_TILE_PRESENTATIONS = Object.freeze([
   "logo-strip",
 ]);
 
+/** Heading levels a theme may size (theme.json `type.headings`). */
+export const THEME_HEADING_LEVELS = Object.freeze(["hero", "h1", "h2", "h3"]);
+
+/**
+ * A heading size a theme may emit: a CSS length or a math function over lengths
+ * ("28px", "1.75rem", "clamp(1.5rem, 4vw, 2rem)"). The character set cannot close
+ * the declaration or the injected `<style>` block.
+ */
+export function isThemeCssSize(value) {
+  return typeof value === "string" && value.length <= 120 && /^[0-9a-z.%(),+\-*/ ]*[0-9a-z%)]$/i.test(value.trim());
+}
+
 /** True only for static assets materialized into a governed serving namespace. */
 export function isSafeRehostedAssetPath(value) {
   if (typeof value !== "string" || !value.startsWith("/")) return false;

package/packages/public-runtime/src/extension-contract.ts

@@ -16,9 +16,11 @@ export {
   BLOCK_PALETTE_SUPPORTED_CONTRACTS,
   FEATURED_PRODUCT_PRESENTATIONS,
   PROMO_TILE_PRESENTATIONS,
+  THEME_HEADING_LEVELS,
   isSafeRehostedAssetPath,
   isSafeRehostedAssetPathForTenant,
   isSafeStorefrontHref,
+  isThemeCssSize,
 } from "./extension-contract-values.mjs";
 
 export type PromoTilePresentation =

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

@@ -61,9 +61,12 @@ export interface ThemeColorTokens {
   error?: string;
   /** Informational state (notices, help). */
   info?: string;
-  /** Accent tuned for SMALL text/links on light surfaces (AA). Default: a
-   *  derived darken of `accent`; set to hand-tune contrast. */
+  /** Accent tuned for SMALL text/links on light surfaces (AA). Default:
+   *  `accent` with its lightness capped; set to hand-tune contrast. */
   "accent-ink"?: string;
+  /** Readable text/icon color ON an `accent` fill. Default: black or white,
+   *  whichever the accent's lightness favours; set to hand-tune contrast. */
+  "accent-contrast"?: string;
   /** Hover/active shade of `primary`. Default: a derived darken of `primary`. */
   "primary-hover"?: string;
   /** Hover/active shade of `accent`. Default: a derived darken of `accent`. */
@@ -98,6 +101,9 @@ export interface ThemeColorTokens {
   /** Trust / reassurance accent — guarantee callouts, security and compliance
    *  badges, proof strips. Default: `success`. */
   trust?: string;
+  /** Home hero eyebrow text. Default: `muted` on a light hero, a translucent
+   *  `primary-contrast` on a bold hero. */
+  "hero-eyebrow"?: string;
 }
 
 export interface ThemeFontFamily {
@@ -112,8 +118,24 @@ export interface ThemeTypeTokens {
   /** Type scale ratio, e.g. 1.25 (major third). */
   scale: number;
   tracking?: string;
+  /**
+   * Fixed heading sizes (any CSS length: "28px", "1.75rem", "clamp(…)"). Each
+   * replaces the fluid display-scale size for its level: `hero` sizes the home
+   * hero headline; `h1`–`h3` size every other heading of that level (page and
+   * listing titles, block titles, rich-text headings). Unset levels keep the
+   * fluid scale derived from `scale`.
+   */
+  headings?: ThemeHeadingSizes;
+}
+
+export interface ThemeHeadingSizes {
+  hero?: string;
+  h1?: string;
+  h2?: string;
+  h3?: string;
 }
 
+
 export interface ThemeSpaceTokens {
   /** Base spacing unit in px. */
   base: number;
@@ -259,6 +281,24 @@ export interface ExciseTaxConfig {
  */
 export type ComplianceRuleProfile = "vape-nicotine-us";
 
+/**
+ * The FDA nicotine warning's presentation: a validated `preset` ("dark" by default,
+ * "light"), optionally adjusted by `style`. Any `style` that leaves the preset is a
+ * custom presentation the owner approves before it goes live. Validated and resolved
+ * by packages/cli/src/declared-config.mjs; the wording is never configurable.
+ */
+export interface NicotineWarningDeclaration {
+  preset?: string;
+  style?: {
+    background?: string;
+    text?: string;
+    border?: string;
+    textTransform?: "uppercase" | "none";
+    fontWeight?: number;
+    fontSizePx?: number;
+  };
+}
+
 export interface ComplianceConfig {
   /**
    * The reviewed rule PROFILE whose ruleset the enforcement gate evaluates for
@@ -272,8 +312,12 @@ export interface ComplianceConfig {
   ruleProfile?: ComplianceRuleProfile;
   /** Minimum age to enter. Drives the soft affirmation gate (e.g. 21). */
   minAge?: number;
-  /** Render the FDA nicotine warning sitewide + reinforced on PDP. */
-  nicotineWarning?: boolean;
+  /**
+   * Render the FDA nicotine warning sitewide + reinforced on PDP. `true` renders the
+   * default preset; an object picks a validated preset and, optionally, a custom style
+   * the owner reviews at go-live (packages/cli/src/declared-config.mjs).
+   */
+  nicotineWarning?: boolean | NicotineWarningDeclaration;
   /** Short PACT-Act / no-ship-states / adult-signature notice (plain text). */
   shippingRestriction?: string;
   /**