@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

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

@@ -0,0 +1,777 @@
+/**
+ * Chrome model — the ONE schema for a tenant's site chrome (header + footer),
+ * plus its fail-closed validator.
+ *
+ * Consolidates what used to be two competing, undocumented shapes:
+ *   - a lean `SiteChrome` (lib/storyblok/content-model.ts), consumed by the
+ *     token-styled <SiteHeader>/<SiteFooter> components via
+ *     Astro.locals.content.getChrome();
+ *   - a superset `TenantChrome`, consumed by the raw `chrome.html` splice
+ *     wrapper (lib/rawChrome.ts) via lib/chrome/parseConfig.ts, gated on an
+ *     explicit `sharedChrome: true` flag.
+ * Both read the same `tenants/<id>/content/chrome.json` file; neither was the
+ * complete picture. This file is now the single source of truth for that
+ * file's shape — both consumers map from `ChromeConfig`.
+ *
+ * `header` and `footer` are separate, independently-evolvable sub-shapes: a
+ * change to one's fields never forces a change to the other's.
+ *
+ * Lives in `@tot/public-runtime` (not the storefront renderer's `lib/chrome/`)
+ * so `@tot/private-controlplane`'s write-side `ArtifactValidator` for
+ * `tenants/<id>/content/chrome.json`
+ * (packages/private-controlplane/src/customization-chrome.ts) can call
+ * {@link validateChromeConfig} without the renderer importing the
+ * control-plane package — the `renderer-no-controlplane` fence
+ * (apps/storefront/.dependency-cruiser.cjs) runs the other way: packages may
+ * depend on `@tot/public-runtime`, but the renderer must never import
+ * `@tot/private-controlplane`. `apps/storefront/src/lib/chrome/model.ts` and
+ * `parseConfig.ts` re-export from here so every existing renderer import
+ * keeps resolving unchanged.
+ */
+
+/**
+ * A navigation/footer/CTA link. `id` is a STABLE identifier, independent of
+ * the visible `label` copy — the resolved substitute for a governed action
+ * registry (spec: no runtime registry, no DOM observer; just a schema-
+ * validated identifier + a real `href` fallback, always present on every
+ * actionable item). `external` opens off-site; `badge` shows e.g. "NEW".
+ */
+export interface ChromeLink {
+  id: string;
+  label: string;
+  href: string;
+  external?: boolean;
+  badge?: string;
+}
+
+/** One column of a mega-menu panel. */
+export interface MegaColumn {
+  title?: string;
+  links: ChromeLink[];
+}
+
+/**
+ * A primary-nav item. A plain link (no children/columns), a single-column
+ * dropdown (`children`), or a multi-column mega-menu (`columns`). `badge`
+ * marks it (e.g. "NEW"); `flag` gives it the emphasized/highlighted
+ * treatment. See {@link ChromeLink} for `id`.
+ */
+export interface ChromeNavItem {
+  id: string;
+  label: string;
+  href: string;
+  badge?: string;
+  flag?: boolean;
+  children?: ChromeLink[];
+  columns?: MegaColumn[];
+}
+
+export interface SocialLink {
+  label: string;
+  href: string;
+  /** Optional inline-SVG path data (single <path d="…">) — no external images. */
+  iconPath?: string;
+}
+
+export interface ChromeLogo {
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+}
+
+/** A marketing conversion CTA (header-actions / footer, non-commerce tenants). */
+export interface ChromeCta {
+  id: string;
+  label: string;
+  href: string;
+  variant?: "primary" | "secondary" | "ghost";
+}
+
+/** A stable link-with-a-name-and-href, minus badge/external — used for the
+ * small number of single-purpose action links (e.g. a member-price cue). */
+export type ChromeActionLink = Pick<ChromeLink, "id" | "label" | "href">;
+
+export interface FooterColumn {
+  title: string;
+  links: ChromeLink[];
+}
+
+export interface FooterNewsletter {
+  title?: string;
+  body?: string;
+  /** Form action (defaults to /api/newsletter). */
+  action?: string;
+  placeholder?: string;
+  /** Hidden `source` field value (e.g. "footer"). */
+  source?: string;
+  /** When true, render the "I confirm I am 21+" age-attestation checkbox (regulated tenants). */
+  ageAttestation?: boolean;
+}
+
+/** A brand identity: an image wordmark/logo, OR a text wordmark of styled spans. */
+export interface ChromeBrand {
+  /** Link target (defaults to "/"). */
+  href?: string;
+  /** Accessible name (aria-label / img alt), e.g. "Prime Vapor Club". */
+  label: string;
+  /** Image wordmark. Preferred when present and a valid src. */
+  logo?: ChromeLogo;
+  /**
+   * Text wordmark rendered as inline spans (e.g. PVC's `Prime`/`Vapor`/`Club`),
+   * each span optionally given a class the theme styles. Used when there's no
+   * logo image (placeholder brand).
+   */
+  wordmark?: { text: string; className?: string }[];
+  /** Marks the brand as a stand-in for a pending real logo (adds data-placeholder). */
+  placeholder?: boolean;
+}
+
+/** Header search affordance (progressive GET form). Omit to hide search. */
+export interface ChromeSearch {
+  /** Form action (defaults to "/search"). */
+  action?: string;
+  placeholder?: string;
+  /** sr-only label (defaults to "Search"). */
+  label?: string;
+}
+
+/** The thin utility bar above the header: minor links, locale chips, social, cue. */
+export interface ChromeUtilityNav {
+  links?: ChromeLink[];
+  /** Locale/currency chips shown on the right (e.g. "English", "United States (USD $)"). */
+  locale?: string[];
+  social?: SocialLink[];
+  /** Optional right-aligned member-price cue link. */
+  memberCue?: ChromeActionLink;
+}
+
+/**
+ * Announcement banner. Three variants map to the shared stylesheet's classes:
+ *   - "marquee": infinite horizontal scroll;
+ *   - "bar": dismissible + optionally message-rotating promo bar;
+ *   - "solid": a static single-line solid bar.
+ */
+export interface ChromeAnnouncement {
+  variant: "marquee" | "bar" | "solid";
+  /** One or more messages. "bar" rotates through them when >1 and rotateMs set. */
+  messages: string[];
+  /** aria-label for the region (defaults to the first message). */
+  label?: string;
+  /** "bar" only — show a dismiss button (remembered via storageKey). */
+  dismissible?: boolean;
+  /** "bar" only — rotate messages every N ms (needs messages.length > 1). */
+  rotateMs?: number;
+  /** localStorage key remembering a dismissal (defaults to a stable derived key). */
+  storageKey?: string;
+}
+
+/**
+ * 21+ age-gate interstitial config (regulated tenants). The raw-chrome renderer
+ * (rawChrome.ts) embeds this as JSON; the shared behavior JS mounts the gate inside
+ * a closed shadow root — the same tamper-resistance pattern
+ * components/islands/IsolatedAgeGate.tsx uses for component pages — so tenant
+ * CSS/JS can't reach the dialog.
+ */
+export interface ChromeAgeGate {
+  minAge: number;
+  /** localStorage key remembering a pass (defaults to a stable derived key). */
+  storageKey?: string;
+  title?: string;
+  lede?: string;
+  yesLabel?: string;
+  noLabel?: string;
+  denyText?: string;
+  /** Fine-print warning under the actions (e.g. the FDA nicotine line). */
+  fineText?: string;
+  /** Optional styled wordmark above the title (spans, like ChromeBrand.wordmark). */
+  mark?: { text: string; className?: string }[];
+}
+
+/** Footer brand block: identity + tagline/contact + optional inline newsletter. */
+export interface ChromeFooterBrand {
+  logo?: ChromeLogo;
+  wordmark?: { text: string; className?: string }[];
+  /** Tagline / contact HTML-free text (rendered with <br> on newlines). */
+  text?: string;
+}
+
+/** A footer trust mark: a small inline-SVG cue + label (e.g. "Secure checkout"). */
+export interface ChromeTrustMark {
+  /** Inner SVG markup (paths/rects/circles), viewBox 0 0 24 24. */
+  icon: string;
+  label: string;
+}
+
+/** Per-tenant <head> extras the wrapper links (the shared css is ALWAYS linked). */
+export interface ChromeHead {
+  /** Favicon href (image/png). */
+  favicon?: string;
+  /** Tenant theme stylesheet hrefs (token definitions), e.g. the *-navy.css theme. */
+  themeStylesheets?: string[];
+  /** <meta name="theme-color"> — a deliberately brand-fixed surface color. */
+  themeColor?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Header / footer variants — explicit, schema-validated content shapes. A
+// page declares which it wants (see Layout.astro's headerVariant/footerVariant
+// props); NEVER inferred from route/CSS/title. Extend the union to add a
+// variant — additive, non-breaking for content already authored against the
+// existing members.
+// ---------------------------------------------------------------------------
+
+/** The only two header content shapes: a full header, or a minimal one
+ * (e.g. checkout/policy pages — brand + a reduced action set, no full nav). */
+export const HEADER_VARIANTS = ["primary", "minimal"] as const;
+export type HeaderVariant = (typeof HEADER_VARIANTS)[number];
+
+/** Footer content shapes. One member today; the type is an extensible string
+ * union (not a boolean) so a future variant is an additive change. */
+export const FOOTER_VARIANTS = ["default"] as const;
+export type FooterVariant = (typeof FOOTER_VARIANTS)[number];
+
+export function isHeaderVariant(v: unknown): v is HeaderVariant {
+  return typeof v === "string" && (HEADER_VARIANTS as readonly string[]).includes(v);
+}
+
+export function isFooterVariant(v: unknown): v is FooterVariant {
+  return typeof v === "string" && (FOOTER_VARIANTS as readonly string[]).includes(v);
+}
+
+/**
+ * Thrown by the renderer's `assertHeaderVariant` / `assertFooterVariant`
+ * (apps/storefront/src/lib/chrome/variant.ts) when a page passes an unknown
+ * variant. Fails closed
+ * at validation time with an actionable message rather than silently falling
+ * back to a default — an unrecognized variant is a bug in the caller, not a
+ * degraded-but-safe state.
+ */
+export class InvalidChromeVariantError extends Error {
+  constructor(kind: "header" | "footer", got: unknown, allowed: readonly string[]) {
+    super(
+      `Invalid ${kind}Variant ${JSON.stringify(got)} — must be one of: ${allowed.join(", ")}. ` +
+        `${kind === "header" ? "headerVariant" : "footerVariant"} is assigned explicitly per page (Layout.astro props); it is never inferred from the URL, a CSS class, or the page title.`,
+    );
+    this.name = "InvalidChromeVariantError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Header / footer — independently-evolvable sub-shapes.
+// ---------------------------------------------------------------------------
+
+export interface ChromeHeader {
+  variant: HeaderVariant;
+  brand: ChromeBrand;
+  /** Primary nav — flat links and/or mega panels (ChromeNavItem.columns). */
+  nav: ChromeNavItem[];
+  search?: ChromeSearch;
+  utilityNav?: ChromeUtilityNav;
+  announcement?: ChromeAnnouncement;
+  /** Header-actions member-price cue (in addition to any utility-nav cue). */
+  memberCue?: ChromeActionLink;
+  accountHref?: string;
+  cartHref?: string;
+  /** Marketing conversion CTAs (non-commerce tenants), shown in the header's
+   * actions cluster in place of the commerce search/saved controls. */
+  ctas?: ChromeCta[];
+}
+
+export interface ChromeFooter {
+  variant: FooterVariant;
+  brand?: ChromeFooterBrand;
+  columns: FooterColumn[];
+  newsletter?: FooterNewsletter;
+  trustMarks?: ChromeTrustMark[];
+  /** Accepted-payment marks (text tokens, e.g. "VISA"). */
+  payments?: string[];
+  social?: SocialLink[];
+  /** The bold compliance/nicotine warning block. */
+  warning?: string;
+  /** Bottom bar: copyright + a legal note line. */
+  bottom?: { copyright?: string; note?: string };
+}
+
+/**
+ * The full tenant chrome config (content only) authored as `chrome.json`.
+ * CONTENT ONLY — every color/space/type comes from theme tokens via the
+ * platform-shipped stylesheet; this config carries no styling.
+ */
+export interface ChromeConfig {
+  /** <html lang> (defaults to "en"). */
+  lang?: string;
+  head?: ChromeHead;
+  /** Skip-link target/label overrides (defaults to "#main" / "Skip to main content"). */
+  skipLink?: { href?: string; label?: string };
+  /** FDA/compliance warning strip at the very top (e.g. the nicotine line). */
+  warningBar?: string;
+  /**
+   * OPT-IN: also link the shared commerce-MARKETING stylesheet
+   * (/shared/commerce-marketing.css) into this tenant's wrapper — the
+   * raw-page BODY layer (page-hero / prose / callouts / value & tier cards /
+   * contact form / FAQ / CTA band) its content fragments repeat. Linked AFTER
+   * the chrome sheet so its page-level variants win.
+   */
+  sharedMarketingCss?: boolean;
+  header: ChromeHeader;
+  footer: ChromeFooter;
+  ageGate?: ChromeAgeGate;
+  /** The compliance strip below the page body (e.g. the nicotine warning). */
+  complianceStrip?: string;
+  /** Default legal/safety disclaimer HTML (fallback for unknown categories). */
+  disclaimer?: string;
+  /** Per-product-category disclaimer HTML, keyed by product_type (or
+   * compliance.product_category) — the source store renders a different legal
+   * block per type (sub-ohm on salts, battery on devices). */
+  disclaimers?: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Validation — fail-closed schema validation for a tenant's `chrome.json`.
+// ---------------------------------------------------------------------------
+
+export interface ChromeConfigValidationResult {
+  ok: boolean;
+  config: ChromeConfig | null;
+  /** Actionable, path-prefixed messages, e.g. "header.nav[2].id: required, non-empty string". */
+  errors: string[];
+}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === "string" && v.trim().length > 0;
+}
+
+function checkOptionalString(v: unknown, path: string, errors: string[]): void {
+  if (v !== undefined && typeof v !== "string") errors.push(`${path}: must be a string`);
+}
+
+function checkOptionalBoolean(v: unknown, path: string, errors: string[]): void {
+  if (v !== undefined && typeof v !== "boolean") errors.push(`${path}: must be a boolean`);
+}
+
+/** `ChromeLink` — the base actionable-item shape: a stable `id` + `label` + `href`. */
+function validateLink(v: unknown, path: string, errors: string[]): v is ChromeLink {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isNonEmptyString(v.id)) {
+    errors.push(
+      `${path}.id: required, non-empty string — a stable identifier independent of ` +
+        `\`label\` copy (the governed-action-registry substitute; every nav/link/CTA needs one)`,
+    );
+  }
+  if (!isNonEmptyString(v.label)) errors.push(`${path}.label: required, non-empty string`);
+  if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
+  checkOptionalBoolean(v.external, `${path}.external`, errors);
+  checkOptionalString(v.badge, `${path}.badge`, errors);
+  return errors.length === before;
+}
+
+/** An action-link (member-price cue etc.): `id` + `label` + `href`, no badge/external. */
+function validateActionLink(v: unknown, path: string, errors: string[]): boolean {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isNonEmptyString(v.id)) errors.push(`${path}.id: required, non-empty string`);
+  if (!isNonEmptyString(v.label)) errors.push(`${path}.label: required, non-empty string`);
+  if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
+  return errors.length === before;
+}
+
+function validateMegaColumn(v: unknown, path: string, errors: string[]): v is MegaColumn {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  checkOptionalString(v.title, `${path}.title`, errors);
+  if (!Array.isArray(v.links)) {
+    errors.push(`${path}.links: required array`);
+  } else {
+    v.links.forEach((l, i) => validateLink(l, `${path}.links[${i}]`, errors));
+  }
+  return errors.length === before;
+}
+
+function validateNavItem(v: unknown, path: string, errors: string[]): v is ChromeNavItem {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isNonEmptyString(v.id)) {
+    errors.push(`${path}.id: required, non-empty string — a stable identifier independent of \`label\` copy`);
+  }
+  if (!isNonEmptyString(v.label)) errors.push(`${path}.label: required, non-empty string`);
+  if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
+  checkOptionalString(v.badge, `${path}.badge`, errors);
+  checkOptionalBoolean(v.flag, `${path}.flag`, errors);
+  if (v.children !== undefined) {
+    if (!Array.isArray(v.children)) errors.push(`${path}.children: must be an array`);
+    else v.children.forEach((c, i) => validateLink(c, `${path}.children[${i}]`, errors));
+  }
+  if (v.columns !== undefined) {
+    if (!Array.isArray(v.columns)) errors.push(`${path}.columns: must be an array`);
+    else v.columns.forEach((c, i) => validateMegaColumn(c, `${path}.columns[${i}]`, errors));
+  }
+  return errors.length === before;
+}
+
+function validateCta(v: unknown, path: string, errors: string[]): v is ChromeCta {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isNonEmptyString(v.id)) errors.push(`${path}.id: required, non-empty string`);
+  if (!isNonEmptyString(v.label)) errors.push(`${path}.label: required, non-empty string`);
+  if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
+  if (v.variant !== undefined && !["primary", "secondary", "ghost"].includes(v.variant as string)) {
+    errors.push(`${path}.variant: must be one of primary, secondary, ghost`);
+  }
+  return errors.length === before;
+}
+
+function validateSocialLink(v: unknown, path: string, errors: string[]): v is SocialLink {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isNonEmptyString(v.label)) errors.push(`${path}.label: required, non-empty string`);
+  if (!isNonEmptyString(v.href)) errors.push(`${path}.href: required, non-empty string`);
+  checkOptionalString(v.iconPath, `${path}.iconPath`, errors);
+  return errors.length === before;
+}
+
+function validateFooterColumn(v: unknown, path: string, errors: string[]): v is FooterColumn {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isNonEmptyString(v.title)) errors.push(`${path}.title: required, non-empty string`);
+  if (!Array.isArray(v.links)) {
+    errors.push(`${path}.links: required array`);
+  } else {
+    v.links.forEach((l, i) => validateLink(l, `${path}.links[${i}]`, errors));
+  }
+  return errors.length === before;
+}
+
+function validateAnnouncement(v: unknown, path: string, errors: string[]): v is ChromeAnnouncement {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!["marquee", "bar", "solid"].includes(v.variant as string)) {
+    errors.push(`${path}.variant: must be one of marquee, bar, solid`);
+  }
+  if (!Array.isArray(v.messages) || !v.messages.every((m) => typeof m === "string")) {
+    errors.push(`${path}.messages: required array of strings`);
+  }
+  return errors.length === before;
+}
+
+function validateAgeGate(v: unknown, path: string, errors: string[]): v is ChromeAgeGate {
+  if (!isObject(v)) {
+    errors.push(`${path}: must be an object`);
+    return false;
+  }
+  const before = errors.length;
+  if (typeof v.minAge !== "number" || !Number.isFinite(v.minAge)) {
+    errors.push(`${path}.minAge: required number`);
+  }
+  return errors.length === before;
+}
+
+function validateHeader(v: unknown, path: string, errors: string[]): v is ChromeHeader {
+  if (!isObject(v)) {
+    errors.push(`${path}: required object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isHeaderVariant(v.variant)) {
+    errors.push(`${path}.variant: required, must be one of ${HEADER_VARIANTS.join(", ")} (got ${JSON.stringify(v.variant)})`);
+  }
+  if (!isObject(v.brand) || !isNonEmptyString((v.brand as Record<string, unknown>).label)) {
+    errors.push(`${path}.brand: required object with a non-empty \`label\``);
+  }
+  if (!Array.isArray(v.nav)) {
+    errors.push(`${path}.nav: required array`);
+  } 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.utilityNav !== undefined) {
+    const u = v.utilityNav;
+    if (!isObject(u)) {
+      errors.push(`${path}.utilityNav: must be an object`);
+    } else {
+      (u.links as unknown[] | undefined)?.forEach((l, i) => validateLink(l, `${path}.utilityNav.links[${i}]`, errors));
+      (u.social as unknown[] | undefined)?.forEach((s, i) => validateSocialLink(s, `${path}.utilityNav.social[${i}]`, errors));
+      if (u.memberCue !== undefined) validateActionLink(u.memberCue, `${path}.utilityNav.memberCue`, errors);
+    }
+  }
+  if (v.announcement !== undefined) validateAnnouncement(v.announcement, `${path}.announcement`, errors);
+  if (v.memberCue !== undefined) validateActionLink(v.memberCue, `${path}.memberCue`, errors);
+  checkOptionalString(v.accountHref, `${path}.accountHref`, errors);
+  checkOptionalString(v.cartHref, `${path}.cartHref`, errors);
+  if (v.ctas !== undefined) {
+    if (!Array.isArray(v.ctas)) errors.push(`${path}.ctas: must be an array`);
+    else v.ctas.forEach((c, i) => validateCta(c, `${path}.ctas[${i}]`, errors));
+  }
+  return errors.length === before;
+}
+
+function validateFooter(v: unknown, path: string, errors: string[]): v is ChromeFooter {
+  if (!isObject(v)) {
+    errors.push(`${path}: required object`);
+    return false;
+  }
+  const before = errors.length;
+  if (!isFooterVariant(v.variant)) {
+    errors.push(`${path}.variant: required, must be one of ${FOOTER_VARIANTS.join(", ")} (got ${JSON.stringify(v.variant)})`);
+  }
+  if (!Array.isArray(v.columns)) {
+    errors.push(`${path}.columns: required array`);
+  } else {
+    v.columns.forEach((c, i) => validateFooterColumn(c, `${path}.columns[${i}]`, errors));
+  }
+  if (v.social !== undefined) {
+    if (!Array.isArray(v.social)) errors.push(`${path}.social: must be an array`);
+    else v.social.forEach((s, i) => validateSocialLink(s, `${path}.social[${i}]`, errors));
+  }
+  if (v.payments !== undefined && (!Array.isArray(v.payments) || !v.payments.every((p) => typeof p === "string"))) {
+    errors.push(`${path}.payments: must be an array of strings`);
+  }
+  checkOptionalString(v.warning, `${path}.warning`, 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`);
+  return errors.length === before;
+}
+
+/**
+ * Validate `raw` (parsed JSON) as a `ChromeConfig`. Collects every violation
+ * (not just the first) so a caller gets one actionable report. Trusts the
+ * authored shape beyond these checks — the renderers are defensive (escape
+ * values, guard every optional section), so a missing optional degrades
+ * rather than breaks.
+ */
+export function validateChromeConfig(raw: unknown): ChromeConfigValidationResult {
+  const errors: string[] = [];
+  if (!isObject(raw)) {
+    return { ok: false, config: null, errors: ["chrome.json: must be a JSON object"] };
+  }
+  checkOptionalString(raw.lang, "lang", errors);
+  checkOptionalBoolean(raw.sharedMarketingCss, "sharedMarketingCss", errors);
+  validateHeader(raw.header, "header", errors);
+  validateFooter(raw.footer, "footer", errors);
+  if (raw.ageGate !== undefined) validateAgeGate(raw.ageGate, "ageGate", errors);
+  checkOptionalString(raw.complianceStrip, "complianceStrip", errors);
+  checkOptionalString(raw.disclaimer, "disclaimer", errors);
+  if (raw.disclaimers !== undefined && !isObject(raw.disclaimers)) {
+    errors.push("disclaimers: must be an object keyed by product_type");
+  }
+  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 (errors.length > 0) return { ok: false, config: null, errors };
+  return { ok: true, config: raw as unknown as ChromeConfig, errors: [] };
+}
+
+/**
+ * Parse `raw` into a `ChromeConfig`, or null if it fails validation. Drop-in
+ * replacement for the retired `parseChromeConfig` opt-in gate: callers that
+ * only need "is this adopted" keep their existing null-means-not-adopted
+ * contract; callers that want the actionable report call
+ * {@link validateChromeConfig} directly.
+ */
+export function parseChromeConfig(raw: unknown): ChromeConfig | null {
+  return validateChromeConfig(raw).config;
+}
+
+// ---------------------------------------------------------------------------
+// Page-assignment manifest — per-page header/footer variant overrides for the
+// raw-HTML rendering path (`content/<tenant>/pages-html/**.html`).
+//
+// Layout.astro's headerVariant/footerVariant props only reach pages rendered as
+// Astro components. A raw-HTML page renders via ContentProvider.getChromeHtml(),
+// which has no per-page variant argument and always used the tenant's single
+// chrome.json default. `content/<tenant>/chrome-assignments.json` is the
+// raw-HTML equivalent of that prop.
+// ---------------------------------------------------------------------------
+
+/** One page's variant override. At least one field must be set — an entry that
+ * overrides neither overrides nothing. */
+export interface ChromeAssignmentEntry {
+  headerVariant?: HeaderVariant;
+  footerVariant?: FooterVariant;
+}
+
+/**
+ * The manifest: a map keyed by page path, so a second, conflicting assignment
+ * for the same page is structurally unrepresentable rather than
+ * representable-and-then-rejected.
+ *
+ * Keys are FULL page paths with a leading slash ("/", "/contact/contact-sales")
+ * — the exact string form `getChromeHtml(currentPath)` already receives
+ * (`` `/${slug}` `` from [...slug].astro, "/" from index.astro), so the resolver
+ * does no format translation on the hot path.
+ */
+export interface ChromeAssignments {
+  assignments: Record<string, ChromeAssignmentEntry>;
+}
+
+export interface ChromeAssignmentsValidationResult {
+  ok: boolean;
+  assignments: ChromeAssignments | null;
+  /** Structural violations — fail closed. */
+  errors: string[];
+  /** Non-fatal notes, e.g. an assignment naming a page that doesn't exist yet. */
+  warnings: string[];
+}
+
+export interface ValidateChromeAssignmentsOptions {
+  /**
+   * Every page path that currently exists, in the same leading-slash form as
+   * the keys. When given, a key naming a page outside it is a WARNING, never an
+   * error: the assignment and the page it targets are naturally authored
+   * together, so erroring would make the manifest unauthorable until the page
+   * lands. Omit it entirely (rather than passing a guess) where the page set
+   * isn't known — the check is then skipped silently.
+   */
+  knownPagePaths?: readonly string[];
+}
+
+const CHROME_ASSIGNMENT_ENTRY_KEYS = ["headerVariant", "footerVariant"] as const;
+
+/** Trailing-slash-insensitive page-path form. "/" is preserved as-is. */
+export function normalizeChromePagePath(path: string): string {
+  return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+
+function validateAssignmentEntry(v: unknown, path: string, errors: string[]): void {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) {
+    errors.push(`${path}: must be an object with headerVariant and/or footerVariant`);
+    return;
+  }
+  const entry = v as Record<string, unknown>;
+  for (const key of Object.keys(entry)) {
+    if (!(CHROME_ASSIGNMENT_ENTRY_KEYS as readonly string[]).includes(key)) {
+      errors.push(
+        `${path}.${key}: unknown field — only ${CHROME_ASSIGNMENT_ENTRY_KEYS.join(" and ")} may be set`,
+      );
+    }
+  }
+  if (entry.headerVariant !== undefined && !isHeaderVariant(entry.headerVariant)) {
+    errors.push(
+      `${path}.headerVariant: must be one of ${HEADER_VARIANTS.join(", ")} (got ${JSON.stringify(entry.headerVariant)})`,
+    );
+  }
+  if (entry.footerVariant !== undefined && !isFooterVariant(entry.footerVariant)) {
+    errors.push(
+      `${path}.footerVariant: must be one of ${FOOTER_VARIANTS.join(", ")} (got ${JSON.stringify(entry.footerVariant)})`,
+    );
+  }
+  if (entry.headerVariant === undefined && entry.footerVariant === undefined) {
+    errors.push(`${path}: must set headerVariant and/or footerVariant — an entry that overrides neither overrides nothing`);
+  }
+}
+
+/**
+ * Validate `raw` as a page-assignment manifest. Collects every structural
+ * violation rather than stopping at the first, like {@link validateChromeConfig}.
+ */
+export function validateChromeAssignments(
+  raw: unknown,
+  options: ValidateChromeAssignmentsOptions = {},
+): ChromeAssignmentsValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return {
+      ok: false,
+      assignments: null,
+      errors: ['chrome-assignments.json: must be a JSON object of the form { "assignments": { "/page": { … } } }'],
+      warnings,
+    };
+  }
+  const doc = raw as Record<string, unknown>;
+  for (const key of Object.keys(doc)) {
+    if (key !== "assignments") {
+      errors.push(`${key}: unknown top-level field — the only field is "assignments"`);
+    }
+  }
+  const map = doc.assignments;
+  if (typeof map !== "object" || map === null || Array.isArray(map)) {
+    errors.push('assignments: required — an object keyed by page path (e.g. { "/contact/contact-sales": { "headerVariant": "minimal" } })');
+    return { ok: false, assignments: null, errors, warnings };
+  }
+
+  const entries = map as Record<string, unknown>;
+  for (const key of Object.keys(entries)) {
+    const at = `assignments[${JSON.stringify(key)}]`;
+    if (!key.startsWith("/")) {
+      errors.push(`${at}: page path must start with "/" (e.g. "/${key}")`);
+    } else if (key.length > 1 && key.endsWith("/")) {
+      errors.push(`${at}: page path must not end with "/" — author it as "${normalizeChromePagePath(key)}"`);
+    }
+    validateAssignmentEntry(entries[key], at, errors);
+  }
+  if (errors.length > 0) return { ok: false, assignments: null, errors, warnings };
+
+  if (options.knownPagePaths) {
+    const known = new Set(options.knownPagePaths.map(normalizeChromePagePath));
+    for (const key of Object.keys(entries)) {
+      if (!known.has(normalizeChromePagePath(key))) {
+        warnings.push(
+          `assignments[${JSON.stringify(key)}]: no page exists at this path yet — the assignment applies once the page lands`,
+        );
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    assignments: { assignments: entries as Record<string, ChromeAssignmentEntry> },
+    errors,
+    warnings,
+  };
+}
+
+/**
+ * Parse `raw` into `ChromeAssignments`, or null if absent or invalid — the same
+ * null-means-not-adopted contract as {@link parseChromeConfig}.
+ */
+export function parseChromeAssignments(raw: unknown): ChromeAssignments | null {
+  if (raw === null || raw === undefined) return null;
+  return validateChromeAssignments(raw).assignments;
+}
+
+/**
+ * The entry assigned to `currentPath`, if any. Exact match only (after
+ * trailing-slash normalization) — deliberately no prefix or glob matching:
+ * real tenant trees nest pages under a shared prefix ("/contact",
+ * "/contact/contact-sales", "/contact/startup-apply"), so a prefix rule would
+ * sweep in pages nobody assigned.
+ */
+export function resolveChromeAssignment(
+  assignments: ChromeAssignments | null | undefined,
+  currentPath: string | undefined,
+): ChromeAssignmentEntry | undefined {
+  if (!assignments || currentPath === undefined) return undefined;
+  return assignments.assignments[normalizeChromePagePath(currentPath)];
+}