@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/theme.ts

@@ -0,0 +1,628 @@
+/**
+ * Portal themes (ADR-033): how a Tenant's Customer Portal looks, as data. A
+ * closed vocabulary — a preset and overrides picked from fixed lists — so
+ * every choice is one the portal's stylesheet knows how to draw, and nothing
+ * a Tenant writes reaches a page as CSS. Pure and dependency-free: the Engine
+ * validates with these lists, the portal renders with them, the Admin UI
+ * edits and previews with them.
+ *
+ * Stored as `branding.theme` on the Tenant record; served on
+ * `GET /v0/portal/presentation` as `theme`.
+ */
+import { INLINE_IMAGE_PATTERN } from "./branding.js";
+
+export const THEME_PRESETS = ["asturiu", "porcelain", "midnight", "aurora", "sandstone", "evergreen", "graphite", "ember"] as const;
+/** `auto` follows the device, and the person may pick light or dark on the page. */
+export const THEME_SCHEMES = ["dark", "light", "auto"] as const;
+export const THEME_BACKGROUNDS = ["plain", "glow", "gradient", "mesh", "grid", "dots", "image"] as const;
+export const THEME_INTENSITIES = ["subtle", "medium", "bold"] as const;
+/** Corner radius scale: controls and cards together. */
+export const THEME_SHAPES = ["sharp", "soft", "rounded", "pill"] as const;
+export const THEME_DENSITIES = ["compact", "comfortable", "spacious"] as const;
+export const THEME_BUTTONS = ["solid", "gradient", "outline", "soft", "glow"] as const;
+/** How cards, lists and tiles sit on the page. */
+export const THEME_SURFACES = ["flat", "outlined", "raised", "glass"] as const;
+/** `bar`: a tab bar on a phone and a side rail on a wide screen; `floating`: a dock and a floating panel. */
+export const THEME_NAVIGATION = ["bar", "floating"] as const;
+export const THEME_FONTS = ["system", "humanist", "geometric", "grotesque", "rounded", "serif", "classic", "editorial", "industrial", "mono"] as const;
+export const THEME_WEIGHTS = ["regular", "medium", "semibold", "bold", "heavy"] as const;
+/** Section labels and eyebrows. */
+export const THEME_LABEL_CASES = ["upper", "normal"] as const;
+export const THEME_TONES = ["primary", "secondary", "neutral"] as const;
+export const THEME_ICON_STROKES = ["light", "regular", "bold"] as const;
+export const THEME_ICON_FRAMES = ["tile", "circle", "outline", "plain"] as const;
+/** The frame around the Tenant's logo (or its initial, when it has none). */
+export const THEME_MARK_FRAMES = ["tile", "circle", "plain"] as const;
+export const THEME_SIGN_IN_LAYOUTS = ["centered", "card", "split"] as const;
+export const THEME_MOTION = ["full", "subtle", "off"] as const;
+
+export type ThemePreset = (typeof THEME_PRESETS)[number];
+export type ThemeScheme = (typeof THEME_SCHEMES)[number];
+export type ThemeBackground = (typeof THEME_BACKGROUNDS)[number];
+export type ThemeIntensity = (typeof THEME_INTENSITIES)[number];
+export type ThemeShape = (typeof THEME_SHAPES)[number];
+export type ThemeDensity = (typeof THEME_DENSITIES)[number];
+export type ThemeButtons = (typeof THEME_BUTTONS)[number];
+export type ThemeSurfaces = (typeof THEME_SURFACES)[number];
+export type ThemeNavigation = (typeof THEME_NAVIGATION)[number];
+export type ThemeFont = (typeof THEME_FONTS)[number];
+export type ThemeWeight = (typeof THEME_WEIGHTS)[number];
+export type ThemeLabelCase = (typeof THEME_LABEL_CASES)[number];
+export type ThemeTone = (typeof THEME_TONES)[number];
+export type ThemeIconStroke = (typeof THEME_ICON_STROKES)[number];
+export type ThemeIconFrame = (typeof THEME_ICON_FRAMES)[number];
+export type ThemeMarkFrame = (typeof THEME_MARK_FRAMES)[number];
+export type ThemeSignInLayout = (typeof THEME_SIGN_IN_LAYOUTS)[number];
+export type ThemeMotion = (typeof THEME_MOTION)[number];
+
+/** Colours one scheme may override. Everything else in the scheme is derived from these. */
+export interface ThemeSchemeColors {
+  background?: string;
+  surface?: string;
+  text?: string;
+  primary?: string;
+  secondary?: string;
+}
+
+/** `branding.theme`: a preset and what the Tenant changes about it. Every key is optional. */
+export interface PortalThemeSpec {
+  preset?: ThemePreset;
+  scheme?: ThemeScheme;
+  colors?: { primary?: string; secondary?: string; light?: ThemeSchemeColors; dark?: ThemeSchemeColors };
+  background?: { style?: ThemeBackground; intensity?: ThemeIntensity; grain?: boolean; image_url?: string };
+  shape?: ThemeShape;
+  density?: ThemeDensity;
+  buttons?: ThemeButtons;
+  surfaces?: ThemeSurfaces;
+  navigation?: ThemeNavigation;
+  typography?: { body?: ThemeFont; display?: ThemeFont; weight?: ThemeWeight; labels?: ThemeLabelCase; label_tone?: ThemeTone };
+  icons?: { stroke?: ThemeIconStroke; frame?: ThemeIconFrame; tone?: ThemeTone };
+  mark?: ThemeMarkFrame;
+  sign_in?: { layout?: ThemeSignInLayout; headline?: string; tagline?: string; image_url?: string };
+  motion?: ThemeMotion;
+}
+
+/** Limits the Engine enforces on the free text and images of a theme. */
+export const THEME_LIMITS = { headline: 80, tagline: 200, imageUrl: 400_000 } as const;
+
+/** Every colour token of one scheme, as `#rrggbb`. */
+export interface ThemePalette {
+  background: string;
+  surface: string;
+  surface2: string;
+  line: string;
+  line2: string;
+  text: string;
+  text2: string;
+  text3: string;
+  primary: string;
+  onPrimary: string;
+  /** The primary as text or an icon on this scheme's background: adjusted until it reads (WCAG AA). */
+  primaryText: string;
+  primarySoft: string;
+  primaryHover: string;
+  secondary: string;
+  onSecondary: string;
+  secondaryText: string;
+  secondarySoft: string;
+}
+
+/** A theme with every choice made: what the portal draws. */
+export interface ResolvedPortalTheme {
+  preset: ThemePreset;
+  scheme: ThemeScheme;
+  light: ThemePalette;
+  dark: ThemePalette;
+  background: { style: ThemeBackground; intensity: ThemeIntensity; grain: boolean; imageUrl: string | null };
+  shape: ThemeShape;
+  density: ThemeDensity;
+  buttons: ThemeButtons;
+  surfaces: ThemeSurfaces;
+  navigation: ThemeNavigation;
+  typography: { body: ThemeFont; display: ThemeFont; weight: ThemeWeight; labels: ThemeLabelCase; labelTone: ThemeTone };
+  icons: { stroke: ThemeIconStroke; frame: ThemeIconFrame; tone: ThemeTone };
+  mark: ThemeMarkFrame;
+  signIn: { layout: ThemeSignInLayout; headline: string | null; tagline: string | null; imageUrl: string | null };
+  motion: ThemeMotion;
+  logoUrl: string | null;
+  /** A logo drawn for dark backgrounds; the dark scheme shows it instead of `logoUrl`. */
+  logoDarkUrl: string | null;
+  faviconUrl: string | null;
+}
+
+/** System font stacks only: nothing is downloaded, nothing reaches another origin, and each reads well where it falls back. */
+export const THEME_FONT_STACKS: Record<ThemeFont, { label: string; stack: string }> = {
+  system: { label: "System", stack: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, "Noto Sans", system-ui, sans-serif' },
+  humanist: { label: "Humanist", stack: 'Seravek, "Gill Sans Nova", Ubuntu, Calibri, "DejaVu Sans", source-sans-pro, sans-serif' },
+  geometric: { label: "Geometric", stack: 'Avenir, "Avenir Next LT Pro", Montserrat, Corbel, "URW Gothic", source-sans-pro, sans-serif' },
+  grotesque: { label: "Grotesque", stack: 'Inter, "Helvetica Neue", Helvetica, "Arial Nova", "Nimbus Sans", Arial, sans-serif' },
+  rounded: { label: "Rounded", stack: 'ui-rounded, "SF Pro Rounded", "Hiragino Maru Gothic ProN", Quicksand, Comfortaa, Manjari, "Arial Rounded MT", Calibri, sans-serif' },
+  serif: { label: "Serif", stack: 'Charter, "Bitstream Charter", "Sitka Text", Cambria, serif' },
+  classic: { label: "Classic", stack: '"Iowan Old Style", "Palatino Linotype", "URW Palladio L", P052, serif' },
+  editorial: { label: "Editorial", stack: 'Didot, "Bodoni MT", "Noto Serif Display", "URW Palladio L", P052, Sylfaen, serif' },
+  industrial: { label: "Industrial", stack: 'Bahnschrift, "DIN Alternate", "Franklin Gothic Medium", "Nimbus Sans Narrow", sans-serif-condensed, sans-serif' },
+  mono: { label: "Monospace", stack: 'ui-monospace, "SF Mono", "Cascadia Code", "Source Code Pro", Menlo, Consolas, "DejaVu Sans Mono", monospace' },
+};
+
+const WEIGHT: Record<ThemeWeight, string> = { regular: "400", medium: "500", semibold: "600", bold: "700", heavy: "800" };
+
+/** A preset's scheme: the neutrals, and optionally its own primary and secondary with their exact companions (used only while the Tenant keeps the preset's colour). */
+type SchemeBase = Pick<ThemePalette, "background" | "surface" | "surface2" | "line" | "line2" | "text" | "text2" | "text3"> & Partial<Pick<ThemePalette, "primary" | "secondary" | "onPrimary" | "primaryHover">>;
+
+interface PresetDefinition {
+  label: string;
+  description: string;
+  primary: string;
+  secondary: string;
+  light: SchemeBase;
+  dark: SchemeBase;
+  choices: Omit<ResolvedPortalTheme, "preset" | "light" | "dark" | "logoUrl" | "logoDarkUrl" | "faviconUrl" | "background" | "signIn"> & { background: Omit<ResolvedPortalTheme["background"], "imageUrl">; signIn: Pick<ResolvedPortalTheme["signIn"], "layout"> };
+}
+
+/**
+ * The presets. `asturiu` is the platform's own look — the Admin UI's tokens,
+ * one for one — and the default for a Tenant that sets no branding at all.
+ * Names describe a look, never a product.
+ */
+export const THEME_PRESET_DEFINITIONS: Record<ThemePreset, PresetDefinition> = {
+  asturiu: {
+    label: "Asturiu",
+    description: "Ink, gold and teal. The platform's own look, as in the Admin UI.",
+    primary: "#f2c230",
+    secondary: "#35a8a4",
+    dark: { background: "#0a0b0d", surface: "#111316", surface2: "#181b20", line: "#262a31", line2: "#343941", text: "#f4f4f1", text2: "#a5aab3", text3: "#6f7580", onPrimary: "#1a1400", primaryHover: "#ffd54a" },
+    light: { background: "#f4f4f1", surface: "#ffffff", surface2: "#ecebe6", line: "#e2e1db", line2: "#cfcec7", text: "#0a0b0d", text2: "#4a4f57", text3: "#6f7580", secondary: "#2b7f8b", onPrimary: "#1a1400", primaryHover: "#ffd54a" },
+    choices: {
+      scheme: "dark",
+      background: { style: "glow", intensity: "subtle", grain: false },
+      shape: "soft",
+      density: "comfortable",
+      buttons: "solid",
+      surfaces: "outlined",
+      navigation: "bar",
+      typography: { body: "system", display: "system", weight: "semibold", labels: "upper", labelTone: "primary" },
+      icons: { stroke: "regular", frame: "tile", tone: "secondary" },
+      mark: "plain",
+      signIn: { layout: "card" },
+      motion: "subtle",
+    },
+  },
+  porcelain: {
+    label: "Porcelain",
+    description: "Bright and calm, soft shadows, rounded corners. Follows the device's light or dark setting.",
+    primary: "#4f46e5",
+    secondary: "#0ea5e9",
+    light: { background: "#f5f6f8", surface: "#ffffff", surface2: "#f1f3f6", line: "#e4e7ec", line2: "#d0d5dd", text: "#101828", text2: "#475467", text3: "#667085" },
+    dark: { background: "#0c0e12", surface: "#15181e", surface2: "#1c2028", line: "#252a33", line2: "#323844", text: "#f2f4f7", text2: "#aab2bf", text3: "#7d8696" },
+    choices: {
+      scheme: "auto",
+      background: { style: "gradient", intensity: "subtle", grain: false },
+      shape: "rounded",
+      density: "comfortable",
+      buttons: "solid",
+      surfaces: "raised",
+      navigation: "bar",
+      typography: { body: "system", display: "system", weight: "bold", labels: "upper", labelTone: "neutral" },
+      icons: { stroke: "regular", frame: "tile", tone: "primary" },
+      mark: "tile",
+      signIn: { layout: "centered" },
+      motion: "full",
+    },
+  },
+  midnight: {
+    label: "Midnight",
+    description: "Deep navy, electric blue, frosted glass over a soft colour mesh.",
+    primary: "#5b8cff",
+    secondary: "#22d3ee",
+    dark: { background: "#060a14", surface: "#0d1424", surface2: "#131c31", line: "#1c2742", line2: "#283656", text: "#eaf0ff", text2: "#9fb0d0", text3: "#6b7ca0" },
+    light: { background: "#eef2fb", surface: "#ffffff", surface2: "#e8edf8", line: "#d8e0f0", line2: "#c3cee5", text: "#0a1228", text2: "#44506b", text3: "#66728d", primary: "#3563e9", secondary: "#0891b2" },
+    choices: {
+      scheme: "dark",
+      background: { style: "mesh", intensity: "medium", grain: false },
+      shape: "rounded",
+      density: "comfortable",
+      buttons: "gradient",
+      surfaces: "glass",
+      navigation: "floating",
+      typography: { body: "geometric", display: "geometric", weight: "bold", labels: "upper", labelTone: "secondary" },
+      icons: { stroke: "light", frame: "circle", tone: "secondary" },
+      mark: "circle",
+      signIn: { layout: "split" },
+      motion: "full",
+    },
+  },
+  aurora: {
+    label: "Aurora",
+    description: "Violet and pink light on a night sky, pill shapes, glowing buttons.",
+    primary: "#a78bfa",
+    secondary: "#f472b6",
+    dark: { background: "#0a0614", surface: "#130d22", surface2: "#1b1430", line: "#2a2040", line2: "#3b2e57", text: "#f5f0ff", text2: "#b8acd6", text3: "#8576a8" },
+    light: { background: "#f7f3ff", surface: "#ffffff", surface2: "#f1ebfd", line: "#e6dcfa", line2: "#d3c4f2", text: "#1c1030", text2: "#574a73", text3: "#7a6d96", primary: "#7c3aed", secondary: "#db2777" },
+    choices: {
+      scheme: "dark",
+      background: { style: "mesh", intensity: "bold", grain: true },
+      shape: "pill",
+      density: "comfortable",
+      buttons: "glow",
+      surfaces: "glass",
+      navigation: "floating",
+      typography: { body: "rounded", display: "rounded", weight: "heavy", labels: "normal", labelTone: "primary" },
+      icons: { stroke: "regular", frame: "circle", tone: "primary" },
+      mark: "circle",
+      signIn: { layout: "card" },
+      motion: "full",
+    },
+  },
+  sandstone: {
+    label: "Sandstone",
+    description: "Warm paper, terracotta and olive, editorial serif headings, square corners.",
+    primary: "#b4532a",
+    secondary: "#5f7a3a",
+    light: { background: "#f4efe6", surface: "#fffcf6", surface2: "#efe8db", line: "#e3d9c8", line2: "#d1c3ab", text: "#2a2118", text2: "#5e5143", text3: "#85776a" },
+    dark: { background: "#15110d", surface: "#1e1913", surface2: "#262019", line: "#332b22", line2: "#463b2e", text: "#f3ece1", text2: "#bfb2a0", text3: "#8f8373", primary: "#e07a4a", secondary: "#9bb26b" },
+    choices: {
+      scheme: "light",
+      background: { style: "dots", intensity: "subtle", grain: true },
+      shape: "sharp",
+      density: "spacious",
+      buttons: "solid",
+      surfaces: "outlined",
+      navigation: "bar",
+      typography: { body: "humanist", display: "editorial", weight: "regular", labels: "upper", labelTone: "neutral" },
+      icons: { stroke: "light", frame: "plain", tone: "primary" },
+      mark: "plain",
+      signIn: { layout: "split" },
+      motion: "subtle",
+    },
+  },
+  evergreen: {
+    label: "Evergreen",
+    description: "Forest green with a touch of brass, quiet and trustworthy.",
+    primary: "#1f7a52",
+    secondary: "#c8a24a",
+    light: { background: "#f2f5f1", surface: "#ffffff", surface2: "#ebf0ea", line: "#dde5db", line2: "#c7d3c4", text: "#10201a", text2: "#44574e", text3: "#687a71", secondary: "#9a7a2c" },
+    dark: { background: "#08110d", surface: "#0f1a15", surface2: "#15231c", line: "#1f3029", line2: "#2b4136", text: "#e9f3ee", text2: "#a3b8ad", text3: "#6f8579", primary: "#3fae7c" },
+    choices: {
+      scheme: "auto",
+      background: { style: "glow", intensity: "medium", grain: false },
+      shape: "soft",
+      density: "comfortable",
+      buttons: "solid",
+      surfaces: "raised",
+      navigation: "bar",
+      typography: { body: "humanist", display: "serif", weight: "semibold", labels: "normal", labelTone: "primary" },
+      icons: { stroke: "regular", frame: "tile", tone: "primary" },
+      mark: "tile",
+      signIn: { layout: "card" },
+      motion: "subtle",
+    },
+  },
+  graphite: {
+    label: "Graphite",
+    description: "Black and white, hairlines and a fine grid. Nothing but the content.",
+    primary: "#0a0a0a",
+    secondary: "#52525b",
+    light: { background: "#fafafa", surface: "#ffffff", surface2: "#f4f4f5", line: "#e7e7e9", line2: "#d4d4d8", text: "#0a0a0a", text2: "#52525b", text3: "#71717a" },
+    dark: { background: "#09090b", surface: "#111113", surface2: "#18181b", line: "#232326", line2: "#323236", text: "#fafafa", text2: "#a1a1aa", text3: "#71717a", primary: "#fafafa", secondary: "#a1a1aa" },
+    choices: {
+      scheme: "auto",
+      background: { style: "grid", intensity: "subtle", grain: false },
+      shape: "sharp",
+      density: "compact",
+      buttons: "solid",
+      surfaces: "outlined",
+      navigation: "bar",
+      typography: { body: "grotesque", display: "grotesque", weight: "semibold", labels: "upper", labelTone: "neutral" },
+      icons: { stroke: "light", frame: "outline", tone: "neutral" },
+      mark: "tile",
+      signIn: { layout: "centered" },
+      motion: "subtle",
+    },
+  },
+  ember: {
+    label: "Ember",
+    description: "Glowing orange and amber on charcoal, bold and energetic.",
+    primary: "#ff7a1a",
+    secondary: "#ffc247",
+    dark: { background: "#0f0a08", surface: "#1a120e", surface2: "#221813", line: "#33241c", line2: "#4a3529", text: "#fff3ea", text2: "#c9ab98", text3: "#93786a" },
+    light: { background: "#fff7f0", surface: "#ffffff", surface2: "#fdeee2", line: "#f6dfcd", line2: "#e9c5a9", text: "#2a140a", text2: "#6b4a39", text3: "#8f6e5d", primary: "#e8600a", secondary: "#c98a00" },
+    choices: {
+      scheme: "dark",
+      background: { style: "gradient", intensity: "bold", grain: true },
+      shape: "rounded",
+      density: "comfortable",
+      buttons: "gradient",
+      surfaces: "raised",
+      navigation: "floating",
+      typography: { body: "system", display: "industrial", weight: "bold", labels: "upper", labelTone: "primary" },
+      icons: { stroke: "bold", frame: "tile", tone: "primary" },
+      mark: "tile",
+      signIn: { layout: "split" },
+      motion: "full",
+    },
+  },
+};
+
+/** The preset for a Tenant that names no theme: the platform's look, or — for a Tenant that only ever set `primary_color` — Porcelain in that colour, close to the portal's look before themes. */
+export function defaultPresetFor(branding: Record<string, unknown> | null | undefined): ThemePreset {
+  return parseHex(branding?.primary_color) ? "porcelain" : "asturiu";
+}
+
+// ------------------------------------------------------------------ colour
+
+type Rgb = [number, number, number];
+
+function parseHex(c: unknown): Rgb | null {
+  if (typeof c !== "string") return null;
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(c.trim());
+  if (!m) return null;
+  const hex = m[1].length === 3 ? m[1].split("").map((x) => x + x).join("") : m[1];
+  return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16)) as Rgb;
+}
+
+/** A colour as the theme stores it: `#rrggbb`, lower case; null when it is not one. */
+export function themeColor(c: unknown): string | null {
+  const rgb = parseHex(c);
+  return rgb ? toHex(rgb) : null;
+}
+
+const toHex = (rgb: number[]) => `#${rgb.map((v) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, "0")).join("")}`;
+const mix = (a: Rgb, b: Rgb, t: number): Rgb => a.map((v, i) => v + (b[i] - v) * t) as Rgb;
+const WHITE: Rgb = [255, 255, 255];
+const BLACK: Rgb = [0, 0, 0];
+
+function luminance([r, g, b]: Rgb): number {
+  const lin = (v: number) => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** WCAG contrast ratio of two colours. */
+export function contrastRatio(a: string, b: string): number {
+  const x = parseHex(a);
+  const y = parseHex(b);
+  if (!x || !y) return 1;
+  return ratio(x, y);
+}
+
+function ratio(a: Rgb, b: Rgb): number {
+  const [hi, lo] = [luminance(a), luminance(b)].sort((p, q) => q - p);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Moved towards white on a dark ground, towards black on a light one, until it reads at `min` against `ground`. */
+function readable(c: Rgb, ground: Rgb, min: number): Rgb {
+  const toward = luminance(ground) < 0.2 ? WHITE : BLACK;
+  let out = c;
+  for (let i = 0; i < 24 && ratio(out, ground) < min; i++) out = mix(out, toward, 0.08);
+  return out;
+}
+
+/** Text on a fill: a deep shade of the fill itself when that reads, else white or black, whichever reads better. */
+function onColor(fill: Rgb): Rgb {
+  const deep = mix(fill, BLACK, 0.86);
+  if (ratio(deep, fill) >= 4.5) return deep;
+  return ratio(WHITE, fill) >= ratio(BLACK, fill) ? WHITE : BLACK;
+}
+
+function palette(base: SchemeBase, over: ThemeSchemeColors | undefined, primaryHex: string | null, secondaryHex: string | null, presetPrimary: string, presetSecondary: string, dark: boolean): ThemePalette {
+  const bg = parseHex(over?.background) ?? (parseHex(base.background) as Rgb);
+  const surface = parseHex(over?.surface) ?? (parseHex(base.surface) as Rgb);
+  const custom = !!(over?.background || over?.surface || over?.text);
+  let text = parseHex(over?.text) ?? (parseHex(base.text) as Rgb);
+  if (ratio(text, bg) < 7) text = luminance(bg) < 0.2 ? [244, 244, 241] : [12, 14, 18];
+  const keep = (k: keyof SchemeBase, derived: Rgb) => (custom ? derived : (parseHex(base[k]) as Rgb));
+  const ownPrimary = !over?.primary && !primaryHex;
+  const primary = parseHex(over?.primary) ?? parseHex(primaryHex) ?? (parseHex(base.primary ?? presetPrimary) as Rgb);
+  const secondary = parseHex(over?.secondary) ?? parseHex(secondaryHex) ?? (parseHex(base.secondary ?? presetSecondary) as Rgb);
+  return {
+    background: toHex(bg),
+    surface: toHex(surface),
+    surface2: toHex(keep("surface2", mix(surface, text, dark ? 0.05 : 0.035))),
+    line: toHex(keep("line", mix(surface, text, dark ? 0.12 : 0.1))),
+    line2: toHex(keep("line2", mix(surface, text, dark ? 0.19 : 0.17))),
+    text: toHex(text),
+    text2: toHex(keep("text2", readable(mix(text, bg, 0.32), bg, 4.5))),
+    text3: toHex(keep("text3", readable(mix(text, bg, 0.5), bg, 3))),
+    primary: toHex(primary),
+    onPrimary: ownPrimary && base.onPrimary ? base.onPrimary : toHex(onColor(primary)),
+    primaryText: toHex(readable(primary, bg, 4.5)),
+    primarySoft: toHex(mix(primary, surface, dark ? 0.84 : 0.88)),
+    primaryHover: ownPrimary && base.primaryHover ? base.primaryHover : toHex(mix(primary, dark ? WHITE : BLACK, dark ? 0.16 : 0.1)),
+    secondary: toHex(secondary),
+    onSecondary: toHex(onColor(secondary)),
+    secondaryText: toHex(readable(secondary, bg, 4.5)),
+    secondarySoft: toHex(mix(secondary, surface, dark ? 0.84 : 0.88)),
+  };
+}
+
+// ------------------------------------------------------------------ reading a spec
+
+const isObj = (v: unknown): v is Record<string, unknown> => !!v && typeof v === "object" && !Array.isArray(v);
+const pick = <T extends string>(list: readonly T[], v: unknown): T | undefined => (typeof v === "string" && (list as readonly string[]).includes(v) ? (v as T) : undefined);
+const text = (v: unknown, max: number): string | undefined => (typeof v === "string" && v.trim() ? v.trim().slice(0, max) : undefined);
+
+/**
+ * An image a theme may show: an inline base64 image, a path on this origin
+ * (how the Customer Portal names an image it serves, ADR-038) or an http(s)
+ * URL, and nothing that could leave a CSS `url("…")` — no quotes, brackets,
+ * backslashes or white space.
+ */
+export function themeImageUrl(v: unknown): string | null {
+  if (typeof v !== "string" || !v || v.length > THEME_LIMITS.imageUrl) return null;
+  if (INLINE_IMAGE_PATTERN.test(v)) return v;
+  return /^(https?:\/\/|\/(?!\/))[^\s"'()<>\\]*$/.test(v) ? v : null;
+}
+
+function schemeColors(v: unknown): ThemeSchemeColors | undefined {
+  if (!isObj(v)) return undefined;
+  const out: ThemeSchemeColors = {};
+  for (const k of ["background", "surface", "text", "primary", "secondary"] as const) {
+    const c = themeColor(v[k]);
+    if (c) out[k] = c;
+  }
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * The theme as far as it can be read: every known key with a valid value, the
+ * rest dropped. The Engine refuses a bad theme when it is written (the Tenant
+ * schema); this is for reading, so an odd stored value falls back to the
+ * preset's instead of breaking a page. Image paths are kept as they are — the
+ * Interface API resolves them against the Tenant's site, like `logo_url`.
+ */
+export function sanitizeThemeSpec(raw: unknown): PortalThemeSpec {
+  if (!isObj(raw)) return {};
+  const out: PortalThemeSpec = {};
+  const set = <K extends keyof PortalThemeSpec>(k: K, v: PortalThemeSpec[K] | undefined) => {
+    if (v !== undefined && !(isObj(v) && !Object.keys(v).length)) out[k] = v;
+  };
+  const strip = <T extends Record<string, unknown>>(o: T): T => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined)) as T;
+  const image = (v: unknown) => (typeof v === "string" && /^\/(?!\/)[^\s"'()<>\\]*$/.test(v) && v.length < 2048 ? v : (themeImageUrl(v) ?? undefined));
+  set("preset", pick(THEME_PRESETS, raw.preset));
+  set("scheme", pick(THEME_SCHEMES, raw.scheme));
+  if (isObj(raw.colors)) set("colors", strip({ primary: themeColor(raw.colors.primary) ?? undefined, secondary: themeColor(raw.colors.secondary) ?? undefined, light: schemeColors(raw.colors.light), dark: schemeColors(raw.colors.dark) }));
+  if (isObj(raw.background))
+    set("background", strip({ style: pick(THEME_BACKGROUNDS, raw.background.style), intensity: pick(THEME_INTENSITIES, raw.background.intensity), grain: typeof raw.background.grain === "boolean" ? raw.background.grain : undefined, image_url: image(raw.background.image_url) }));
+  set("shape", pick(THEME_SHAPES, raw.shape));
+  set("density", pick(THEME_DENSITIES, raw.density));
+  set("buttons", pick(THEME_BUTTONS, raw.buttons));
+  set("surfaces", pick(THEME_SURFACES, raw.surfaces));
+  set("navigation", pick(THEME_NAVIGATION, raw.navigation));
+  if (isObj(raw.typography))
+    set("typography", strip({ body: pick(THEME_FONTS, raw.typography.body), display: pick(THEME_FONTS, raw.typography.display), weight: pick(THEME_WEIGHTS, raw.typography.weight), labels: pick(THEME_LABEL_CASES, raw.typography.labels), label_tone: pick(THEME_TONES, raw.typography.label_tone) }));
+  if (isObj(raw.icons)) set("icons", strip({ stroke: pick(THEME_ICON_STROKES, raw.icons.stroke), frame: pick(THEME_ICON_FRAMES, raw.icons.frame), tone: pick(THEME_TONES, raw.icons.tone) }));
+  set("mark", pick(THEME_MARK_FRAMES, raw.mark));
+  if (isObj(raw.sign_in))
+    set("sign_in", strip({ layout: pick(THEME_SIGN_IN_LAYOUTS, raw.sign_in.layout), headline: text(raw.sign_in.headline, THEME_LIMITS.headline), tagline: text(raw.sign_in.tagline, THEME_LIMITS.tagline), image_url: image(raw.sign_in.image_url) }));
+  set("motion", pick(THEME_MOTION, raw.motion));
+  return out;
+}
+
+// ------------------------------------------------------------------ resolving
+
+/**
+ * Every choice made: the preset (named, or the default for this branding),
+ * then the Tenant's overrides. `branding` supplies the logo, the dark logo,
+ * the favicon and — when the theme names no primary — `primary_color`.
+ */
+export function resolvePortalTheme(input: { branding?: Record<string, unknown> | null; theme?: unknown } | null | undefined): ResolvedPortalTheme {
+  const branding = input?.branding ?? {};
+  const spec = sanitizeThemeSpec(input?.theme ?? branding.theme);
+  const name = spec.preset ?? defaultPresetFor(branding);
+  const p = THEME_PRESET_DEFINITIONS[name];
+  const c = p.choices;
+  // A theme is the whole truth once set; `primary_color` speaks only for a Tenant that has none.
+  const legacy = Object.keys(spec).length ? null : themeColor(branding.primary_color);
+  const primary = spec.colors?.primary ?? legacy;
+  const secondary = spec.colors?.secondary;
+  const url = (v: unknown) => themeImageUrl(v);
+  return {
+    preset: name,
+    scheme: spec.scheme ?? c.scheme,
+    light: palette(p.light, spec.colors?.light, primary ?? null, secondary ?? null, p.primary, p.secondary, false),
+    dark: palette(p.dark, spec.colors?.dark, primary ?? null, secondary ?? null, p.primary, p.secondary, true),
+    background: {
+      style: spec.background?.style ?? c.background.style,
+      intensity: spec.background?.intensity ?? c.background.intensity,
+      grain: spec.background?.grain ?? c.background.grain,
+      imageUrl: url(spec.background?.image_url),
+    },
+    shape: spec.shape ?? c.shape,
+    density: spec.density ?? c.density,
+    buttons: spec.buttons ?? c.buttons,
+    surfaces: spec.surfaces ?? c.surfaces,
+    navigation: spec.navigation ?? c.navigation,
+    typography: {
+      body: spec.typography?.body ?? c.typography.body,
+      display: spec.typography?.display ?? c.typography.display,
+      weight: spec.typography?.weight ?? c.typography.weight,
+      labels: spec.typography?.labels ?? c.typography.labels,
+      labelTone: spec.typography?.label_tone ?? c.typography.labelTone,
+    },
+    icons: { stroke: spec.icons?.stroke ?? c.icons.stroke, frame: spec.icons?.frame ?? c.icons.frame, tone: spec.icons?.tone ?? c.icons.tone },
+    mark: spec.mark ?? c.mark,
+    signIn: { layout: spec.sign_in?.layout ?? c.signIn.layout, headline: spec.sign_in?.headline ?? null, tagline: spec.sign_in?.tagline ?? null, imageUrl: url(spec.sign_in?.image_url) },
+    motion: spec.motion ?? c.motion,
+    logoUrl: url(branding.logo_url),
+    logoDarkUrl: url(branding.logo_dark_url),
+    faviconUrl: url(branding.favicon_url),
+  };
+}
+
+const PALETTE_VARS: [keyof ThemePalette, string][] = [
+  ["background", "bg"],
+  ["surface", "surface"],
+  ["surface2", "surface-2"],
+  ["line", "line"],
+  ["line2", "line-2"],
+  ["text", "text"],
+  ["text2", "text-2"],
+  ["text3", "text-3"],
+  ["primary", "primary"],
+  ["onPrimary", "on-primary"],
+  ["primaryText", "primary-fg"],
+  ["primarySoft", "primary-soft"],
+  ["primaryHover", "primary-hover"],
+  ["secondary", "secondary"],
+  ["onSecondary", "on-secondary"],
+  ["secondaryText", "secondary-fg"],
+  ["secondarySoft", "secondary-soft"],
+];
+
+/** The CSS custom property names a palette is written to, per scheme prefix (`--l-*`, `--d-*`). */
+export const THEME_PALETTE_VARS = PALETTE_VARS.map(([, v]) => v);
+
+export interface PortalThemeStyle {
+  /** CSS custom properties for the root element: both schemes' palettes (`--l-*`, `--d-*`), the fonts, and the images as `url("…")`. */
+  vars: Record<string, string>;
+  /** `data-*` attributes for the root element, one per choice; the stylesheet draws each. */
+  attrs: Record<string, string>;
+}
+
+/**
+ * A resolved theme as the root element carries it. `scheme` overrides the
+ * theme's (a person's own light or dark choice on an `auto` theme).
+ */
+export function portalThemeStyle(t: ResolvedPortalTheme, scheme?: "light" | "dark" | null): PortalThemeStyle {
+  const vars: Record<string, string> = {};
+  for (const [k, v] of PALETTE_VARS) {
+    vars[`--l-${v}`] = t.light[k];
+    vars[`--d-${v}`] = t.dark[k];
+  }
+  vars["--font"] = THEME_FONT_STACKS[t.typography.body].stack;
+  vars["--font-display"] = THEME_FONT_STACKS[t.typography.display].stack;
+  vars["--display-weight"] = WEIGHT[t.typography.weight];
+  if (t.background.imageUrl) vars["--ground-image"] = `url("${t.background.imageUrl}")`;
+  if (t.signIn.imageUrl) vars["--signin-image"] = `url("${t.signIn.imageUrl}")`;
+  const attrs: Record<string, string> = {
+    "data-preset": t.preset,
+    "data-scheme": t.scheme === "auto" && scheme ? scheme : t.scheme,
+    "data-ground": t.background.style === "image" && !t.background.imageUrl ? "glow" : t.background.style,
+    "data-intensity": t.background.intensity,
+    "data-grain": String(t.background.grain),
+    "data-shape": t.shape,
+    "data-density": t.density,
+    "data-buttons": t.buttons,
+    "data-surfaces": t.surfaces,
+    "data-nav": t.navigation,
+    "data-font-body": t.typography.body,
+    "data-font-display": t.typography.display,
+    "data-labels": t.typography.labels,
+    "data-label-tone": t.typography.labelTone,
+    "data-icon-stroke": t.icons.stroke,
+    "data-icon-frame": t.icons.frame,
+    "data-icon-tone": t.icons.tone,
+    "data-mark": t.mark,
+    "data-signin": t.signIn.layout,
+    "data-motion": t.motion,
+  };
+  return { vars, attrs };
+}
+
+/** The ground colour a browser's own chrome (status bar, overscroll) should take for each scheme. */
+export function portalThemeColors(t: ResolvedPortalTheme): { light: string; dark: string; scheme: ThemeScheme } {
+  return { light: t.light.background, dark: t.dark.background, scheme: t.scheme };
+}