From c661d4185ff3320803fad1e7dd543d2f385620ff Mon Sep 17 00:00:00 2001
From: Parsa <91623162+parsakhaz@users.noreply.github.com>
Date: Mon, 14 Sep 2026 00:38:18 -0700
Subject: [PATCH] Use browser theme validation and an offline appearance
 bootstrap

Closes #625
Closes #626
Closes #631
Closes #635
---
 .github/workflows/quality.yml              |   3 +
 AGENTS.md                                  |   2 +-
 frontend/index.html                        |  32 +--
 frontend/src/contexts/themeClasses.test.ts |  47 ----
 frontend/src/index.css                     |   2 +-
 frontend/src/styles/themeContrast.test.ts  | 260 ---------------------
 frontend/src/styles/tokens/colors.css      |  16 +-
 frontend/src/styles/tokens/effects.css     |   4 +-
 frontend/src/styles/tokens/typography.css  |   3 +-
 frontend/vite.config.ts                    |  16 +-
 playwright.ci.minimal.config.ts            |   2 +-
 scripts/README.md                          |  44 ++--
 scripts/check-theme-contrast.mjs           | 229 +++++++-----------
 shared/types/appearance.ts                 |   2 +-
 tests/appearance-bootstrap.spec.ts         |  54 ++++-
 15 files changed, 205 insertions(+), 511 deletions(-)
 delete mode 100644 frontend/src/contexts/themeClasses.test.ts
 delete mode 100644 frontend/src/styles/themeContrast.test.ts

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index 18b511e3c..3d086fefc 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -84,6 +84,9 @@ jobs:
     - name: Install Playwright browser dependencies
       run: pnpm exec playwright install --with-deps chromium
 
+    - name: Verify browser-computed theme contrast
+      run: pnpm theme:contrast
+
     - name: Rebuild native modules for Electron smoke tests
       run: pnpm run electron:rebuild
 
diff --git a/AGENTS.md b/AGENTS.md
index f6e5551a9..4050cbeac 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,7 +14,7 @@
 - Lint: `pnpm lint`; Type-check: `pnpm typecheck` (runs per package). The root lint command is the single entry point for blocking Oxlint and Knip checks, residual ESLint, and advisory anti-slop checks.
 - Detailed advisory output: `pnpm lint:ox:extra:details`; accessibility scan: `pnpm a11y:scan` (install Chromium once with `pnpm exec playwright install chromium`); opt-in render evidence: `pnpm perf:scan`.
 - Tests (E2E): `pnpm test`, `pnpm test:ui`, CI configs in `playwright.ci*.config.ts`.
-- Themes: `pnpm theme:contrast` gates the 15 batch themes' token pairs in `frontend/src/styles/tokens/colors.css` (text/UI/terminal contrast, high-contrast overlay, CVD separation; `--all` reports the original twelve, `--themes a,b` picks themes, `--markdown --cvd` prints PR tables — see `scripts/README.md`); `pnpm theme:screenshots` regenerates `screenshots/themes/batch/`.
+- Themes: `pnpm theme:contrast` gates every theme's muted text plus the 15 batch themes' token pairs in `frontend/src/styles/tokens/colors.css` (text/UI/terminal contrast, high-contrast overlay, CVD separation; `--all` reports all themes without enforcing thresholds, `--themes a,b` picks themes, `--markdown --cvd` prints PR tables — see `scripts/README.md`); `pnpm theme:screenshots` regenerates `screenshots/themes/batch/`.
 - Main unit tests (if added): `pnpm --filter main test`, coverage: `pnpm --filter main run test:coverage`.
 - Releases must follow `docs/RELEASE_INSTRUCTIONS.md` and run from a clean `main` checkout whose `HEAD` matches `origin/main`.
 
diff --git a/frontend/index.html b/frontend/index.html
index b751f9a80..2855a9a3c 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -9,37 +9,9 @@
     <link rel="preload" href="/fonts/SymbolsNerdFontMono-Regular.woff2" as="font" type="font/woff2" crossorigin />
     <title>Pane</title>
     <script>
-      const themeClasses = {
-        'light': ['light'],
-        'light-rounded': ['light', 'light-rounded'],
-        'dark': ['dark'],
-        'oled': ['dark', 'oled'],
-        'dusk': ['dark', 'dusk'],
-        'dusk-oled': ['dark', 'dusk', 'dusk-oled'],
-        'forge': ['dark', 'forge'],
-        'ember': ['dark', 'ember'],
-        'aurora': ['dark', 'aurora'],
-        'night-owl': ['dark', 'night-owl'],
-        'night-owl-oled': ['dark', 'night-owl', 'night-owl-oled'],
-        'terracotta': ['dark', 'terracotta'],
-        'synthwave': ['dark', 'synthwave'],
-        'acid': ['dark', 'acid'],
-        'tokyo-rain': ['dark', 'tokyo-rain'],
-        'folio': ['light', 'folio'],
-        'newsprint': ['light', 'newsprint'],
-        'walnut': ['dark', 'walnut'],
-        'amber-crt': ['dark', 'amber-crt'],
-        'teletype': ['light', 'teletype'],
-        'dot-matrix': ['dark', 'dot-matrix'],
-        'haar': ['light', 'haar'],
-        'abyss': ['dark', 'abyss'],
-        'understory': ['dark', 'understory'],
-        'colorblind-safe': ['dark', 'colorblind-safe'],
-        'low-fatigue': ['dark', 'low-fatigue'],
-        'high-legibility': ['light', 'high-legibility'],
-      };
+      const themeClasses = __PANE_THEME_CLASSES__;
       try {
-        const defaults = { appearanceMode: 'system', theme: 'light-rounded', systemLightTheme: 'light-rounded', systemDarkTheme: 'dark' };
+        const defaults = __PANE_DEFAULT_APPEARANCE__;
         const snapshot = window.electronAPI?.appearanceSnapshot;
         let cached;
         try {
diff --git a/frontend/src/contexts/themeClasses.test.ts b/frontend/src/contexts/themeClasses.test.ts
deleted file mode 100644
index aac5c82f8..000000000
--- a/frontend/src/contexts/themeClasses.test.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-import { THEME_CLASSES } from './themeContextValue';
-
-/**
- * frontend/index.html stamps the theme classes before React loads (to avoid a
- * flash) and therefore mirrors the shared THEME_CLASSES map once.
- * PR #362 found that copy had silently drifted; this keeps it honest.
- */
-const INDEX_HTML = readFileSync(
-  resolve(dirname(fileURLToPath(import.meta.url)), '../../index.html'),
-  'utf8',
-);
-
-/** Parse a `{ 'id': ['a', 'b'], ... }` object literal from the bootstrap script into id → class list entries. */
-function parseClassMap(source: string) {
-  return Object.fromEntries(
-    [...source.matchAll(/'([\w-]+)':\s*\[([^\]]*)\]/g)].map((entry) => [
-      entry[1],
-      [...entry[2].matchAll(/'([\w-]+)'/g)].map((m) => m[1]),
-    ]),
-  );
-}
-
-describe('index.html theme bootstrap', () => {
-  const classMaps = [...INDEX_HTML.matchAll(/const themeClasses = \{([\s\S]*?)\};/g)].map((m) => parseClassMap(m[1]));
-
-  it('has one complete class map and the expected precedence inputs', () => {
-    expect(classMaps).toHaveLength(1);
-    expect(Object.keys(classMaps[0]).sort()).toEqual(Object.keys(THEME_CLASSES).sort());
-    expect(INDEX_HTML).toContain('appearanceSnapshot');
-    expect(INDEX_HTML).toContain('pane.appearance.v1');
-    expect(INDEX_HTML).toContain('prefers-color-scheme');
-  });
-
-  it('keeps the bootstrap copy identical to THEME_CLASSES', () => {
-    for (const map of classMaps) expect(map).toEqual(THEME_CLASSES);
-  });
-
-  it('every theme composes on the light or dark base', () => {
-    for (const [theme, classes] of Object.entries(THEME_CLASSES)) {
-      expect(['light', 'dark'], `${theme} must start with a base class`).toContain(classes[0]);
-    }
-  });
-});
diff --git a/frontend/src/index.css b/frontend/src/index.css
index 5f158fa73..dd54d40d6 100644
--- a/frontend/src/index.css
+++ b/frontend/src/index.css
@@ -685,7 +685,7 @@ body.understory {
 
 .thinking-content blockquote {
   color: inherit;
-  border-color: rgba(var(--color-interactive-rgb), 0.2);
+  border-color: rgb(var(--color-interactive-rgb) / 0.2);
   @apply pl-3 py-1;
 }
 
diff --git a/frontend/src/styles/themeContrast.test.ts b/frontend/src/styles/themeContrast.test.ts
deleted file mode 100644
index 1dc6bd594..000000000
--- a/frontend/src/styles/themeContrast.test.ts
+++ /dev/null
@@ -1,260 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-import { THEME_CLASSES } from '../contexts/themeContextValue';
-
-/**
- * Static WCAG contrast gate over the theme tokens in tokens/colors.css.
- *
- * Resolves each theme's cascade the same way the browser does (`:root` dark
- * base → `:root.light` → `:root.<theme>` → OLED child → `.high-contrast`),
- * composites alpha colours over the surface they sit on, and checks the
- * ratios that PR #362 measured by hand. New themes register in FULL_THEMES
- * so text, buttons, focus rings and the 16 ANSI colours are all gated.
- */
-
-const COLORS_CSS = readFileSync(
-  resolve(dirname(fileURLToPath(import.meta.url)), 'tokens/colors.css'),
-  'utf8',
-).replace(/\/\*[\s\S]*?\*\//g, '');
-
-type Rgb = [number, number, number];
-type Rgba = [number, number, number, number];
-type TokenMap = Map<string, string>;
-
-const AA_TEXT = 4.5;
-const AA_UI = 3;
-const AAA_TEXT = 7;
-
-type ThemeId = keyof typeof THEME_CLASSES;
-// SAFETY: THEME_CLASSES is a closed object literal, so its keys are exactly ThemeId.
-const ALL_THEMES = Object.keys(THEME_CLASSES) as ThemeId[];
-
-// Themes that ship with the full contrast matrix (add new themes here).
-const FULL_THEMES: ThemeId[] = ['folio', 'newsprint', 'walnut'];
-
-const MUTED_FAMILY = [
-  '--color-text-muted',
-  '--color-text-interactive-muted',
-  '--color-text-navigation-muted',
-  '--color-text-navigation-section',
-];
-
-const ANSI = [
-  'red', 'green', 'yellow', 'blue', 'magenta', 'cyan',
-  'bright-black', 'bright-red', 'bright-green', 'bright-yellow', 'bright-blue', 'bright-magenta', 'bright-cyan',
-];
-
-// --- CSS parsing -----------------------------------------------------------
-
-/** All `{ ... }` bodies whose selector list matches `selector` exactly, in source order. */
-function blocksFor(selector: string): string[] {
-  const bodies: string[] = [];
-  for (const match of COLORS_CSS.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
-    const selectors = match[1].split(',').map((s) => s.trim());
-    if (selectors.includes(selector)) bodies.push(match[2]);
-  }
-  return bodies;
-}
-
-function collectDeclarations(body: string, into: TokenMap): void {
-  for (const decl of body.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
-    into.set(decl[1], decl[2].trim());
-  }
-}
-
-/** Resolve the token map a browser would see for the given class list. */
-function tokensFor(classes: string[], highContrast = false): TokenMap {
-  const tokens: TokenMap = new Map();
-  for (const body of blocksFor(':root')) collectDeclarations(body, tokens);
-  // Same specificity, so source order decides — mirror it by walking the classes
-  // in the order colors.css declares them (light before the print themes, dark
-  // parents before their OLED children), which THEME_CLASSES already encodes.
-  for (const cls of classes) for (const body of blocksFor(`:root.${cls}`)) collectDeclarations(body, tokens);
-  if (highContrast) {
-    for (const cls of classes) for (const body of blocksFor(`:root.high-contrast.${cls}`)) collectDeclarations(body, tokens);
-  }
-  return tokens;
-}
-
-// --- Colour maths ----------------------------------------------------------
-
-function substituteVars(value: string, tokens: TokenMap, depth = 0): string {
-  if (depth > 16) throw new Error(`var() recursion too deep in ${value}`);
-  const next = value.replace(/var\((--[\w-]+)(?:\s*,\s*([^)]+))?\)/g, (_m, name: string, fallback?: string) => {
-    const resolved = tokens.get(name) ?? fallback;
-    if (resolved === undefined) throw new Error(`Unresolved token ${name}`);
-    return resolved;
-  });
-  return next.includes('var(') ? substituteVars(next, tokens, depth + 1) : next;
-}
-
-function parseColor(raw: string): Rgba {
-  const value = raw.trim();
-  const hex = value.match(/^#([0-9a-f]{3,8})$/i);
-  if (hex) {
-    let h = hex[1];
-    if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('');
-    const n = (i: number) => parseInt(h.slice(i, i + 2), 16);
-    return [n(0), n(2), n(4), h.length === 8 ? n(6) / 255 : 1];
-  }
-  const fn = value.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/i);
-  if (fn) {
-    const alpha = fn[4] === undefined ? 1 : fn[4].endsWith('%') ? parseFloat(fn[4]) / 100 : parseFloat(fn[4]);
-    return [Number(fn[1]), Number(fn[2]), Number(fn[3]), alpha];
-  }
-  if (value === 'transparent') return [0, 0, 0, 0];
-  throw new Error(`Cannot parse colour "${raw}"`);
-}
-
-function resolveColor(name: string, tokens: TokenMap): Rgba {
-  const raw = tokens.get(name);
-  if (raw === undefined) throw new Error(`Token ${name} is not defined`);
-  return parseColor(substituteVars(raw, tokens));
-}
-
-function composite([r, g, b, a]: Rgba, [br, bg, bb]: Rgb): Rgb {
-  return [r * a + br * (1 - a), g * a + bg * (1 - a), b * a + bb * (1 - a)];
-}
-
-function luminance([r, g, b]: Rgb): number {
-  const channel = (c: number) => {
-    const s = c / 255;
-    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
-  };
-  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
-}
-
-function contrast(fg: Rgba, bg: Rgba): number {
-  // Backgrounds with alpha are assumed to sit on an opaque page; that is close
-  // enough for the surfaces gated here (all opaque in practice).
-  const solidBg: Rgb = [bg[0], bg[1], bg[2]];
-  const solidFg = composite(fg, solidBg);
-  const [hi, lo] = [luminance(solidFg), luminance(solidBg)].sort((a, b) => b - a);
-  return (hi + 0.05) / (lo + 0.05);
-}
-
-function ratioOf(tokens: TokenMap, fg: string, bg: string): number {
-  return contrast(resolveColor(fg, tokens), resolveColor(bg, tokens));
-}
-
-function expectRatio(tokens: TokenMap, fg: string, bg: string, min: number, label: string): void {
-  const ratio = ratioOf(tokens, fg, bg);
-  expect(ratio, `${label}: ${fg} on ${bg} = ${ratio.toFixed(2)}:1, need ≥ ${min}:1`).toBeGreaterThanOrEqual(min);
-}
-
-// --- Tests -----------------------------------------------------------------
-
-describe('theme contrast (tokens/colors.css)', () => {
-  it('declares theme blocks in THEME_CLASSES order so the cascade model matches the browser', () => {
-    // Same specificity everywhere, so source order decides. The resolver
-    // above walks THEME_CLASSES in order; that is only faithful if colors.css
-    // lists each class's block (and its high-contrast block) in that order.
-    for (const theme of ALL_THEMES) {
-      const classes = THEME_CLASSES[theme];
-      for (const prefix of [':root.', ':root.high-contrast.']) {
-        // Not every class owns a block (the dark base is bare `:root`, light-rounded
-        // inherits `.light`'s high-contrast block) — only the blocks that exist must be ordered.
-        const offsets = classes
-          .map((cls) => ({ cls, offset: COLORS_CSS.indexOf(`${prefix}${cls} {`) }))
-          .filter(({ offset }) => offset >= 0);
-        for (let i = 1; i < offsets.length; i += 1) {
-          expect(offsets[i].offset, `${prefix}${offsets[i].cls} must come after ${prefix}${offsets[i - 1].cls}`)
-            .toBeGreaterThan(offsets[i - 1].offset);
-        }
-      }
-    }
-  });
-
-  describe.each(ALL_THEMES)('%s', (theme) => {
-    const tokens = tokensFor(THEME_CLASSES[theme]);
-    const hcTokens = tokensFor(THEME_CLASSES[theme], true);
-
-    it('keeps the muted text family at AA against --color-bg-primary', () => {
-      for (const token of MUTED_FAMILY) expectRatio(tokens, token, '--color-bg-primary', AA_TEXT, theme);
-    });
-
-    it('lifts the muted text family to AAA in high-contrast mode', () => {
-      for (const token of MUTED_FAMILY) expectRatio(hcTokens, token, '--color-bg-primary', AAA_TEXT, `${theme} (high-contrast)`);
-    });
-  });
-
-  describe.each(FULL_THEMES)('%s (full matrix)', (theme) => {
-    const tokens = tokensFor(THEME_CLASSES[theme]);
-
-    it('body text reads on every surface it can land on', () => {
-      const surfaces = [
-        '--color-bg-primary', '--color-bg-secondary', '--color-bg-tertiary', '--color-bg-hover', '--color-bg-active',
-        '--color-bg-chrome', '--color-bg-editor',
-        '--color-surface-primary', '--color-surface-secondary', '--color-surface-tertiary',
-        '--color-card-bg', '--color-card-nested-bg', '--color-modal-bg', '--color-input-bg',
-        '--color-surface-navigation', '--color-surface-navigation-hover',
-      ];
-      for (const bg of surfaces) {
-        for (const fg of ['--color-text-primary', '--color-text-secondary', '--color-text-tertiary', '--color-text-muted']) {
-          expectRatio(tokens, fg, bg, AA_TEXT, theme);
-        }
-      }
-      // Navigation text on the sidebar surfaces
-      for (const bg of ['--color-surface-navigation', '--color-surface-navigation-hover', '--color-surface-navigation-active']) {
-        for (const fg of ['--color-text-navigation-primary', '--color-text-navigation-secondary', '--color-text-navigation-muted', '--color-text-navigation-selected', '--color-text-navigation-section']) {
-          expectRatio(tokens, fg, bg, AA_TEXT, theme);
-        }
-      }
-      expectRatio(tokens, '--color-input-text', '--color-input-bg', AA_TEXT, theme);
-      expectRatio(tokens, '--color-input-placeholder', '--color-input-bg', AA_TEXT, theme);
-    });
-
-    it('links, accents, status and focus meet AA text / 3:1 UI on the page', () => {
-      for (const bg of ['--color-bg-primary', '--color-bg-editor', '--color-bg-chrome', '--color-surface-primary']) {
-        expectRatio(tokens, '--color-interactive-text', bg, AA_TEXT, theme);
-        expectRatio(tokens, '--color-text-interactive-on-dark', bg, AA_TEXT, theme);
-        expectRatio(tokens, '--color-status-neutral', bg, AA_UI, theme);
-        for (const ui of ['--color-interactive-primary', '--color-focus-ring', '--color-border-focus', '--color-status-success', '--color-status-warning', '--color-status-error', '--color-status-info']) {
-          expectRatio(tokens, ui, bg, AA_UI, theme);
-        }
-      }
-    });
-
-    it('buttons keep their label readable in every state', () => {
-      expectRatio(tokens, '--color-button-primary-text', '--color-button-primary-bg', AA_TEXT, theme);
-      expectRatio(tokens, '--color-button-primary-text', '--color-button-primary-hover', AA_TEXT, theme);
-      expectRatio(tokens, '--color-text-on-interactive', '--color-interactive-primary', AA_TEXT, theme);
-      expectRatio(tokens, '--color-text-on-interactive', '--color-interactive-hover', AA_TEXT, theme);
-      expectRatio(tokens, '--color-text-on-interactive', '--color-interactive-active', AA_TEXT, theme);
-      expectRatio(tokens, '--color-button-secondary-text', '--color-button-secondary-bg', AA_TEXT, theme);
-      expectRatio(tokens, '--color-button-secondary-text', '--color-button-secondary-hover', AA_TEXT, theme);
-      expectRatio(tokens, '--color-button-ghost-text', '--color-bg-primary', AA_TEXT, theme);
-      expectRatio(tokens, '--color-button-ghost-text', '--color-button-ghost-hover', AA_TEXT, theme);
-      for (const status of ['success', 'warning', 'error', 'info']) {
-        expectRatio(tokens, `--color-text-on-status-${status}`, `--color-status-${status}`, AA_TEXT, theme);
-      }
-    });
-
-    it('terminal palette reads on the terminal background', () => {
-      expectRatio(tokens, '--color-terminal-fg', '--color-terminal-bg', AA_TEXT, theme);
-      expectRatio(tokens, '--color-terminal-white', '--color-terminal-bg', AA_TEXT, theme);
-      expectRatio(tokens, '--color-terminal-bright-white', '--color-terminal-bg', AA_TEXT, theme);
-      expectRatio(tokens, '--color-terminal-cursor', '--color-terminal-bg', AA_UI, theme);
-      for (const name of ANSI) expectRatio(tokens, `--color-terminal-${name}`, '--color-terminal-bg', AA_UI, theme);
-      // The terminal background must be one of the theme's own surfaces, not a fallback.
-      const termBg = resolveColor('--color-terminal-bg', tokens);
-      const editorBg = resolveColor('--color-bg-editor', tokens);
-      expect(termBg.slice(0, 3)).toEqual(editorBg.slice(0, 3));
-    });
-
-    it('overrides every token the base light and dark themes define (no half-theme fallbacks)', () => {
-      const own: TokenMap = new Map();
-      for (const body of blocksFor(`:root.${theme}`)) collectDeclarations(body, own);
-      const expected = new Set<string>();
-      for (const selector of [':root.light', ':root.terracotta']) {
-        const block: TokenMap = new Map();
-        for (const body of blocksFor(selector)) collectDeclarations(body, block);
-        for (const name of block.keys()) expected.add(name);
-      }
-      const missing = [...expected].filter((name) => !own.has(name));
-      expect(missing, `${theme} is missing: ${missing.join(', ')}`).toEqual([]);
-    });
-  });
-});
diff --git a/frontend/src/styles/tokens/colors.css b/frontend/src/styles/tokens/colors.css
index d325635e0..c1cfbe9b3 100644
--- a/frontend/src/styles/tokens/colors.css
+++ b/frontend/src/styles/tokens/colors.css
@@ -525,20 +525,20 @@
   /* Interactive surface tokens */
   --color-surface-interactive: var(--gh-800);
   --color-surface-interactive-hover: var(--gh-700);
-  --color-interactive-surface: rgba(var(--color-interactive-rgb), 0.15);
-  --color-interactive-surface-hover: rgba(var(--color-interactive-rgb), 0.25);
+  --color-interactive-surface: rgb(var(--color-interactive-rgb) / 0.15);
+  --color-interactive-surface-hover: rgb(var(--color-interactive-rgb) / 0.25);
 
   /* Interactive border tokens */
   --color-border-interactive-subtle: rgba(255, 255, 255, 0.05);
   --color-border-interactive: rgba(255, 255, 255, 0.08);
-  --color-interactive-border: rgba(var(--color-interactive-rgb), 0.5);
-  --color-interactive-border-hover: rgba(var(--color-interactive-rgb), 0.7);
+  --color-interactive-border: rgb(var(--color-interactive-rgb) / 0.5);
+  --color-interactive-border-hover: rgb(var(--color-interactive-rgb) / 0.7);
 
   /* Interactive text tokens */
   --color-text-interactive-muted: rgb(114 122 133);  /* #727a85 — 4.7:1 on bg-primary (AA) */
 
   /* Focus ring variations */
-  --color-focus-ring-subtle: rgba(var(--color-interactive-rgb), 0.4);
+  --color-focus-ring-subtle: rgb(var(--color-interactive-rgb) / 0.4);
 
   /* Semantic Tokens - Status */
   --color-status-success: rgb(63 185 80);        /* GitHub #3fb950 */
@@ -594,8 +594,8 @@
   --color-surface-navigation: var(--gh-black);
   --color-surface-navigation-hover: var(--gh-800);
   --color-surface-navigation-active: var(--gh-700);
-  --color-surface-navigation-selected: rgba(var(--color-interactive-rgb), 0.15);
-  --color-surface-navigation-selected-hover: rgba(var(--color-interactive-rgb), 0.2);
+  --color-surface-navigation-selected: rgb(var(--color-interactive-rgb) / 0.15);
+  --color-surface-navigation-selected-hover: rgb(var(--color-interactive-rgb) / 0.2);
 
   --color-text-navigation-primary: rgb(200 208 217);
   --color-text-navigation-secondary: rgb(125 133 144);
@@ -697,7 +697,7 @@
   --color-interactive-border: var(--blue-500);      /* 3.7:1 — passes 3:1 UI threshold */
   --color-interactive-border-hover: var(--blue-600);
   --color-text-interactive-muted: var(--gray-500);
-  --color-focus-ring-subtle: rgba(var(--color-interactive-rgb), 0.4);
+  --color-focus-ring-subtle: rgb(var(--color-interactive-rgb) / 0.4);
 
   /* Context-Aware Text Tokens - Light Mode */
   --color-text-on-primary: rgb(31 35 40);
diff --git a/frontend/src/styles/tokens/effects.css b/frontend/src/styles/tokens/effects.css
index 6b255bc59..8c94fc8e9 100644
--- a/frontend/src/styles/tokens/effects.css
+++ b/frontend/src/styles/tokens/effects.css
@@ -66,8 +66,8 @@
   --shadow-dropdown-pointer: 0 2px 4px rgba(0, 0, 0, 0.1);
   
   /* Glow effects for interactive elements */
-  --glow-interactive: 0 0 0 2px rgba(var(--color-interactive-rgb), 0.1);
-  --glow-interactive-hover: 0 0 0 3px rgba(var(--color-interactive-rgb), 0.15);
+  --glow-interactive: 0 0 0 2px rgb(var(--color-interactive-rgb) / 0.1);
+  --glow-interactive-hover: 0 0 0 3px rgb(var(--color-interactive-rgb) / 0.15);
   
   /* Toggle zone shadows for subtle depth */
   --shadow-toggle-zone: 0 1px 2px rgba(0, 0, 0, 0.03), 0 1px 3px rgba(0, 0, 0, 0.04);
diff --git a/frontend/src/styles/tokens/typography.css b/frontend/src/styles/tokens/typography.css
index 7b2856da8..592e84da7 100644
--- a/frontend/src/styles/tokens/typography.css
+++ b/frontend/src/styles/tokens/typography.css
@@ -1,6 +1,7 @@
 /* Typography Design Tokens for Pane */
 
-@import url('https://fonts.googleapis.com/css2?family=Geist+Mono:wght@100;200;300;400;500;600;700;800;900&display=block');
+/* Use locally installed fonts and the system fallback stack. A remote @import
+ * makes Vite's renderer CSS preload depend on an external font service. */
 
 /*
  * Symbols Nerd Font Mono — SIL Open Font License 1.1 (Ryan L McIntyre / Nerd Fonts)
diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts
index 15a273f46..e55b6aae3 100644
--- a/frontend/vite.config.ts
+++ b/frontend/vite.config.ts
@@ -1,9 +1,23 @@
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import { resolve } from 'node:path';
+import { DEFAULT_APPEARANCE, THEME_CLASSES } from '../shared/types/appearance';
 
 export default defineConfig(({ command }) => ({
-  plugins: [react()],
+  plugins: [
+    react(),
+    {
+      name: 'pane-appearance-bootstrap',
+      // Inline before the browser parses the head in both dev and packaged builds.
+      // The preload snapshot stays authoritative; this only generates its theme map.
+      transformIndexHtml: {
+        order: 'pre',
+        handler: (html) => html
+          .replace('__PANE_THEME_CLASSES__', JSON.stringify(THEME_CLASSES))
+          .replace('__PANE_DEFAULT_APPEARANCE__', JSON.stringify(DEFAULT_APPEARANCE)),
+      },
+    },
+  ],
   define: {
     __PANE_REACT_SCAN_ENABLED__: JSON.stringify(
       command === 'serve' && process.env.PANE_REACT_SCAN === '1'
diff --git a/playwright.ci.minimal.config.ts b/playwright.ci.minimal.config.ts
index fea2cf5ec..92d1109b7 100644
--- a/playwright.ci.minimal.config.ts
+++ b/playwright.ci.minimal.config.ts
@@ -6,7 +6,7 @@ const devServerPort = getPlaywrightPort();
 export default defineConfig({
   testDir: './tests',
   // Keep the fast startup checks and the maintained accessibility journeys in CI.
-  testMatch: ['smoke.spec.ts', 'health-check.spec.ts', 'accessibility.spec.ts'],
+  testMatch: ['smoke.spec.ts', 'health-check.spec.ts', 'accessibility.spec.ts', 'appearance-bootstrap.spec.ts'],
   // Allow enough time for cold CI startup while keeping failures bounded.
   timeout: 30 * 1000,
   expect: {
diff --git a/scripts/README.md b/scripts/README.md
index 6bde904ec..f48a0a1cd 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -52,23 +52,37 @@ The script helps ensure Pane complies with open source license requirements by:
 
 ## check-theme-contrast.mjs
 
-Contrast and colour-vision-deficiency gate for Pane themes. Parses
-`frontend/src/styles/tokens/colors.css`, composes each theme's tokens the way
-`ThemeProvider` composes classes, and measures WCAG 2.x contrast for text,
-UI (3:1) and terminal ANSI pairs. Simulates protanopia, deuteranopia and
-tritanopia (Machado 2009 matrices) for the status, diff and ANSI palettes.
+Contrast and colour-vision-deficiency gate for Pane themes. Chromium loads
+`frontend/src/styles/tokens/colors.css` and resolves the real cascade, variables,
+and colours with computed styles. One engine measures WCAG 2.x contrast for
+text, UI and terminal ANSI pairs, and simulates protanopia, deuteranopia and
+tritanopia (Machado 2009) for status, diff and ANSI palettes. It runs without
+starting Pane, Vite, or any network requests.
 
 ```bash
-pnpm theme:contrast                    # gate every theme in GATED_THEMES (the 15 batch themes)
-pnpm theme:contrast -- --all --verbose # report every theme (report only, always exit 0)
+pnpm exec playwright install chromium # once locally; CI already installs Chromium
+pnpm theme:contrast                    # enforce the complete contrast contract
+pnpm theme:contrast -- --themes folio,colorblind-safe
+pnpm theme:contrast -- --all --verbose # report every theme without failing thresholds
 pnpm theme:contrast -- --markdown --cvd
 ```
 
-Only the themes in `GATED_THEMES` fail the exit code; every other theme is
-report-only so existing debt does not block CI. Each gated theme carries the
-profile its family was designed to (`body` / `ui` / `terminal` / `status`
-minimums; `strictUi` adds the hairline pairs — 1px input border, scrollbar
-thumb, subtle focus ring — that only the accessibility family commits to;
-`cvd` gates the colour-vision simulation). Add a theme to `THEME_CLASSES` (and
-to `GATED_THEMES` when it should be enforced) when adding one to
-`themeContextValue.ts`.
+All themes enforce AA muted text and AAA muted text in high-contrast mode.
+The fifteen themes in `GATED_THEMES` also enforce their designed text, UI,
+terminal and status profiles, including high-contrast variants. `strictUi`
+adds the accessibility family's hairline pairs; `cvd` enforces CVD separation.
+Folio, Newsprint and Walnut additionally check every editorial text surface,
+button state and terminal/editor background equality, and require explicit
+overrides for the base theme tokens. Other pairs remain informational for the
+original twelve themes. `--all` reports all thresholds without failing them;
+missing Chromium, invalid themes and other execution errors still fail.
+
+Add themes to the canonical `THEME_CLASSES` in `shared/types/appearance.ts` and
+add their full profile to `GATED_THEMES`. Vite also embeds that canonical map
+and the default appearance directly into the synchronous HTML bootstrap in
+dev and production; no second map or runtime fetch is needed. CI runs the
+contrast gate and the appearance bootstrap browser journeys.
+
+Typography uses locally installed fonts and the existing system monospace
+fallbacks. The renderer stylesheet must not import runtime font CDNs: a failed
+nested stylesheet request can reject Vite's CSS preload and prevent startup.
diff --git a/scripts/check-theme-contrast.mjs b/scripts/check-theme-contrast.mjs
index 2ee8f663f..5ee55e1df 100644
--- a/scripts/check-theme-contrast.mjs
+++ b/scripts/check-theme-contrast.mjs
@@ -1,66 +1,17 @@
 #!/usr/bin/env node
 /**
- * Theme contrast + color-vision-deficiency (CVD) gate for Pane themes.
- *
- * Reads frontend/src/styles/tokens/colors.css, resolves each theme's semantic
- * tokens (following the same class composition ThemeProvider applies), and
- * measures WCAG 2.x contrast for the text/UI/terminal pairs listed below.
- *
- *   node scripts/check-theme-contrast.mjs                 # gate every theme in GATED_THEMES
- *   node scripts/check-theme-contrast.mjs --themes dusk    # report any theme(s)
- *   node scripts/check-theme-contrast.mjs --all            # report every theme (report only, exit 0)
- *   node scripts/check-theme-contrast.mjs --markdown       # PR-ready tables
- *   node scripts/check-theme-contrast.mjs --cvd            # add CVD simulation tables
- *   node scripts/check-theme-contrast.mjs --verbose        # print passing rows too
- *
- * Exit code is 1 when a gated theme fails a threshold. Themes not listed in
- * GATED_THEMES (the twelve original themes) are report-only so existing debt
- * does not block CI. Each gated theme carries its own profile — see
- * GATED_THEMES: `strictUi` additionally gates the hairline pairs (1px input
- * border, scrollbar thumb, the subtle focus ring) and the "on-dark" link text
- * on the page background, which only the accessibility family commits to.
- *
- * CVD simulation uses the Machado, Oliveira & Fernandes (2009) severity-1.0
- * matrices applied in linear sRGB — the same matrices as the SVG filters used
- * for the simulated screenshots in tests/theme-screenshots.spec.ts.
+ * One browser-computed contrast gate for every theme's muted family, the full
+ * editorial matrix, and the batch themes' text/UI/terminal/CVD profiles.
+ * Chromium resolves the real CSS cascade and var() expressions; the remaining
+ * code measures WCAG contrast, CVD separation, and prints CLI/PR reports.
  */
 import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import path from 'node:path';
+import { chromium } from 'playwright';
+import { THEME_CLASSES } from '../shared/types/appearance.ts';
 
-const here = path.dirname(fileURLToPath(import.meta.url));
-const COLORS_CSS = path.join(here, '..', 'frontend', 'src', 'styles', 'tokens', 'colors.css');
-
-// Mirrors THEME_CLASSES in frontend/src/contexts/ThemeProvider.tsx.
-const THEME_CLASSES = {
-  'light': ['light'],
-  'light-rounded': ['light', 'light-rounded'],
-  'dark': ['dark'],
-  'oled': ['dark', 'oled'],
-  'dusk': ['dark', 'dusk'],
-  'dusk-oled': ['dark', 'dusk', 'dusk-oled'],
-  'forge': ['dark', 'forge'],
-  'ember': ['dark', 'ember'],
-  'aurora': ['dark', 'aurora'],
-  'night-owl': ['dark', 'night-owl'],
-  'night-owl-oled': ['dark', 'night-owl', 'night-owl-oled'],
-  'terracotta': ['dark', 'terracotta'],
-  'synthwave': ['dark', 'synthwave'],
-  'acid': ['dark', 'acid'],
-  'tokyo-rain': ['dark', 'tokyo-rain'],
-  'folio': ['light', 'folio'],
-  'newsprint': ['light', 'newsprint'],
-  'walnut': ['dark', 'walnut'],
-  'amber-crt': ['dark', 'amber-crt'],
-  'teletype': ['light', 'teletype'],
-  'dot-matrix': ['dark', 'dot-matrix'],
-  'haar': ['light', 'haar'],
-  'abyss': ['dark', 'abyss'],
-  'understory': ['dark', 'understory'],
-  'colorblind-safe': ['dark', 'colorblind-safe'],
-  'low-fatigue': ['dark', 'low-fatigue'],
-  'high-legibility': ['light', 'high-legibility'],
-};
+const COLORS_CSS = new URL('../frontend/src/styles/tokens/colors.css', import.meta.url);
+const EDITORIAL_THEMES = ['folio', 'newsprint', 'walnut'];
+const MUTED_FAMILY = ['--color-text-muted', '--color-text-interactive-muted', '--color-text-navigation-muted', '--color-text-navigation-section'];
 
 // Themes that must pass, each with the bar its family was designed to.
 //   body      minimum for text pairs (4.5 = AA; high-legibility promises AAA)
@@ -96,60 +47,44 @@ const GATED_THEMES = {
   'high-legibility': { body: 7, ui: 3, terminal: 4.5, strictUi: true },
 };
 
-// ---------- CSS parsing ----------
-
-function parseBlocks(rawCss) {
-  const css = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-  const blocks = new Map(); // selector -> Map(var, value) (later blocks with the same selector are merged)
-  const re = /([^{}]+)\{([^{}]*)\}/g;
-  let match;
-  while ((match = re.exec(css)) !== null) {
-    const selector = match[1].trim();
-    const body = match[2];
-    const vars = blocks.get(selector) ?? new Map();
-    for (const decl of body.split(';')) {
-      const idx = decl.indexOf(':');
-      if (idx === -1) continue;
-      const name = decl.slice(0, idx).trim();
-      if (!name.startsWith('--')) continue;
-      const value = decl.slice(idx + 1).trim();
-      vars.set(name, value);
+// The browser owns CSS parsing, specificity, source order, variable resolution,
+// and color syntax. No app/server/network access is needed for this measurement.
+async function readThemeStyles(page, theme) {
+  return page.evaluate(({ classes, theme }) => {
+    const root = document.documentElement;
+    const probe = document.createElement('span');
+    root.append(probe);
+    const snapshots = [];
+    for (const highContrast of [false, true]) {
+      root.className = [...classes, ...(highContrast ? ['high-contrast'] : [])].join(' ');
+      const styles = getComputedStyle(root);
+      const tokens = [];
+      for (const name of styles) {
+        if (!name.startsWith('--color-') || name.endsWith('-rgb')) continue;
+        if (!CSS.supports('color', styles.getPropertyValue(name))) throw new Error(`Invalid color token ${name}`);
+        probe.style.color = `var(${name})`;
+        tokens.push([name, getComputedStyle(probe).color]);
+      }
+      snapshots.push(tokens);
     }
-    blocks.set(selector, vars);
-  }
-  return blocks;
-}
-
-function tokensFor(blocks, theme, highContrast = false) {
-  const classes = THEME_CLASSES[theme];
-  if (!classes) throw new Error(`Unknown theme "${theme}"`);
-  const merged = new Map(blocks.get(':root') ?? []);
-  const apply = (selector) => {
-    for (const [name, value] of blocks.get(selector) ?? []) merged.set(name, value);
-  };
-  for (const cls of classes) apply(`:root.${cls}`);
-  if (highContrast) for (const cls of classes) apply(`:root.high-contrast.${cls}`);
-  return merged;
+    probe.remove();
+    // Full editorial themes promise explicit overrides. Use CSSOM declarations
+    // for that contract; inherited values alone cannot demonstrate ownership.
+    const declared = (selector) => [...document.styleSheets].flatMap((sheet) =>
+      [...sheet.cssRules].flatMap((rule) =>
+        rule instanceof CSSStyleRule && rule.selectorText.split(',').map((part) => part.trim()).includes(selector)
+          ? [...rule.style].filter((name) => name.startsWith('--')) : []));
+    const expected = new Set([...declared(':root.light'), ...declared(':root.terracotta')]);
+    const own = new Set(declared(`:root.${theme}`));
+    return { snapshots, missing: [...expected].filter((name) => !own.has(name)) };
+  }, { classes: THEME_CLASSES[theme], theme });
 }
 
 // ---------- color math ----------
 
 function parseColor(raw) {
   const value = raw.trim();
-  let m = value.match(/^#([0-9a-f]{3,8})$/i);
-  if (m) {
-    const hex = m[1];
-    if (hex.length === 3 || hex.length === 4) {
-      const [r, g, b, a] = hex.split('').map((c) => parseInt(c + c, 16));
-      return { r, g, b, a: hex.length === 4 ? a / 255 : 1 };
-    }
-    const r = parseInt(hex.slice(0, 2), 16);
-    const g = parseInt(hex.slice(2, 4), 16);
-    const b = parseInt(hex.slice(4, 6), 16);
-    const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1;
-    return { r, g, b, a };
-  }
-  m = value.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/i);
+  const m = value.match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:[\s,/]+([\d.]+%?))?\s*\)$/i);
   if (m) {
     let a = 1;
     if (m[4] !== undefined) a = m[4].endsWith('%') ? parseFloat(m[4]) / 100 : parseFloat(m[4]);
@@ -159,21 +94,8 @@ function parseColor(raw) {
   return null;
 }
 
-function resolve(tokens, name, seen = new Set()) {
-  const raw = tokens.get(name);
-  if (raw === undefined) return undefined;
-  if (seen.has(name)) return undefined;
-  seen.add(name);
-  // rgba(var(--x-rgb), 0.5) → expand the triplet
-  const value = raw.replace(/var\((--[\w-]+)\)/g, (_, ref) => {
-    const inner = resolve(tokens, ref, new Set(seen));
-    return inner === undefined ? _ : inner;
-  });
-  return value;
-}
-
 function color(tokens, name) {
-  const value = resolve(tokens, name);
+  const value = tokens.get(name);
   return value === undefined ? null : parseColor(value);
 }
 
@@ -335,7 +257,7 @@ function measure(tokens, fgName, bgName) {
   return { fg, bg, ratio: contrast(fg, bg) };
 }
 
-function runTheme(theme, blocks, opts) {
+function runTheme(theme, styles, opts) {
   const gate = GATED_THEMES[theme] ?? null;
   const bodyMin = gate?.body ?? 4.5;
   const uiMin = gate?.ui ?? 3;
@@ -347,9 +269,9 @@ function runTheme(theme, blocks, opts) {
   const results = [];
   const variants = [['', false], [' + high-contrast', true]];
   for (const [suffix, hc] of variants) {
-    const tokens = tokensFor(blocks, theme, hc);
+    const tokens = new Map(styles.snapshots[hc ? 1 : 0]);
     const push = (kind, fgName, bgName, min, tag) => {
-      const info = tag === 'strict' && !strictUi;
+      const info = (tag === 'strict' && !strictUi) || (!gate && tag !== 'global');
       const m = measure(tokens, fgName, bgName);
       if (!m) {
         results.push({ variant: suffix, kind, fg: fgName, bg: bgName, ratio: null, min, pass: info, missing: true, info });
@@ -360,11 +282,23 @@ function runTheme(theme, blocks, opts) {
     };
     for (const [fg, bg, tag] of TEXT_ON_SURFACES) push('text', fg, bg, tag === 'status' ? statusMin : bodyMin, tag);
     for (const [fg, bg, tag] of UI_ON_SURFACES) push('ui', fg, bg, uiMin, tag);
-    if (hc) {
-      // The High contrast toggle promises AAA (7:1) for the muted family (PR #362).
-      for (const fg of ['--color-text-muted', '--color-text-interactive-muted', '--color-text-navigation-muted', '--color-text-navigation-section']) {
-        push('text-aaa', fg, '--color-bg-primary', Math.max(7, bodyMin));
+    // This baseline applies to all 27 themes, including the original twelve.
+    for (const fg of MUTED_FAMILY) {
+      push(hc ? 'text-aaa' : 'text-aa', fg, '--color-bg-primary', hc ? 7 : 4.5, 'global');
+    }
+    if (!hc && EDITORIAL_THEMES.includes(theme)) {
+      // Preserve the broader surface/button matrix previously gated by Vitest.
+      for (const bg of ['bg-primary', 'bg-secondary', 'bg-tertiary', 'bg-hover', 'bg-active', 'bg-chrome', 'bg-editor', 'surface-primary', 'surface-secondary', 'surface-tertiary', 'card-bg', 'card-nested-bg', 'modal-bg', 'input-bg', 'surface-navigation', 'surface-navigation-hover']) {
+        for (const fg of ['primary', 'secondary', 'tertiary', 'muted']) push('text', `--color-text-${fg}`, `--color-${bg}`, 4.5);
+      }
+      for (const bg of ['surface-navigation', 'surface-navigation-hover', 'surface-navigation-active']) {
+        for (const fg of ['primary', 'secondary', 'muted', 'selected', 'section']) push('text', `--color-text-navigation-${fg}`, `--color-${bg}`, 4.5);
       }
+      for (const bg of ['bg-primary', 'bg-editor', 'bg-chrome', 'surface-primary']) {
+        for (const fg of ['interactive-text', 'text-interactive-on-dark']) push('text', `--color-${fg}`, `--color-${bg}`, 4.5);
+        for (const fg of ['status-neutral', 'interactive-primary', 'focus-ring', 'border-focus', 'status-success', 'status-warning', 'status-error', 'status-info']) push('ui', `--color-${fg}`, `--color-${bg}`, 3);
+      }
+      for (const bg of ['interactive-hover', 'interactive-active']) push('text', '--color-text-on-interactive', `--color-${bg}`, 4.5);
     }
     for (const fg of TERMINAL_FG) push('terminal', fg, '--color-terminal-bg', terminalMin);
     if (!hc) {
@@ -375,8 +309,16 @@ function runTheme(theme, blocks, opts) {
   }
 
   let cvd = null;
-  if (opts.cvd || gate?.cvd) cvd = runCvd(tokensFor(blocks, theme, false));
-  return { theme, gate, bodyMin, uiMin, terminalMin, statusMin, results, cvd };
+  if (opts.cvd || gate?.cvd) cvd = runCvd(new Map(styles.snapshots[0]));
+  const contractErrors = [];
+  if (EDITORIAL_THEMES.includes(theme)) {
+    if (styles.missing.length) contractErrors.push(`Missing own token overrides: ${styles.missing.join(', ')}`);
+    const tokens = new Map(styles.snapshots[0]);
+    if (tokens.get('--color-terminal-bg') !== tokens.get('--color-bg-editor')) {
+      contractErrors.push('Terminal background must match the editor surface');
+    }
+  }
+  return { theme, gate, bodyMin, uiMin, terminalMin, statusMin, results, cvd, contractErrors };
 }
 
 // Semantic pairs that must stay distinguishable for every CVD type.
@@ -424,7 +366,7 @@ function printText(report, showAll) {
   const { theme, gate, results, cvd } = report;
   const failures = results.filter((r) => !r.pass);
   const statusNote = gate && report.statusMin !== report.bodyMin ? `, status ≥ ${report.statusMin}:1` : '';
-  console.log(`\n== ${theme}${gate ? ` (gated: text ≥ ${report.bodyMin}:1, UI ≥ ${report.uiMin}:1, terminal ≥ ${report.terminalMin}:1${statusNote}${gate.strictUi ? ', hairlines gated' : ''})` : ' (report only)'} ==`);
+  console.log(`\n== ${theme}${gate ? ` (gated: text ≥ ${report.bodyMin}:1, UI ≥ ${report.uiMin}:1, terminal ≥ ${report.terminalMin}:1${statusNote}${gate.strictUi ? ', hairlines gated' : ''})` : ' (muted family gated; other pairs report only)'} ==`);
   for (const r of results) {
     if (!showAll && r.pass && !r.below) continue;
     const status = r.missing ? (r.info ? 'n/a ' : 'MISSING') : r.info ? (r.below ? 'low ' : 'ok  ') : r.pass ? 'ok  ' : 'FAIL';
@@ -433,6 +375,7 @@ function printText(report, showAll) {
   }
   const gated = results.filter((r) => !r.info);
   console.log(`  ${gated.length - failures.length}/${gated.length} checks pass`);
+  for (const error of report.contractErrors) console.log(`  FAIL ${error}`);
   if (cvd) {
     console.log('  CVD simulation (Machado 2009, severity 1.0) — worst pair ΔE (CIE76), min contrast on bg:');
     const cvdGated = Boolean(gate?.cvd);
@@ -487,6 +430,7 @@ function printMarkdown(report) {
   const hc = results.filter((r) => r.variant !== '');
   const hcPassing = hc.filter((r) => r.pass).length;
   console.log(`\n${passing}/${total} token pairs pass at this theme's thresholds; ${hcPassing}/${hc.length} with High contrast on.`);
+  for (const error of report.contractErrors) console.log(`\n❌ ${error}`);
   if (cvd) {
     console.log(`\n#### ${theme} — CVD simulation (Machado 2009, severity 1.0; worst pairwise ΔE, CIE76)\n`);
     console.log('| Set | Normal | Protanopia | Deuteranopia | Tritanopia |');
@@ -513,12 +457,11 @@ const markdown = flag('--markdown');
 const cvd = flag('--cvd');
 
 const css = readFileSync(COLORS_CSS, 'utf8');
-const blocks = parseBlocks(css);
 const themes = flag('--all')
   ? Object.keys(THEME_CLASSES)
   : themesArg
     ? themesArg.split(',').map((t) => t.trim()).filter(Boolean)
-    : Object.keys(GATED_THEMES);
+    : Object.keys(THEME_CLASSES);
 const unknown = themes.filter((t) => !THEME_CLASSES[t]);
 if (unknown.length) {
   console.error(`Unknown theme(s): ${unknown.join(', ')}. Known: ${Object.keys(THEME_CLASSES).join(', ')}`);
@@ -527,16 +470,24 @@ if (unknown.length) {
 
 let failed = false;
 const reportOnly = flag('--all');
-for (const theme of themes) {
-  const report = runTheme(theme, blocks, { cvd });
-  if (markdown) printMarkdown(report);
-  else printText(report, showAll);
-  if (report.gate && !reportOnly) {
-    if (report.results.some((r) => !r.pass)) failed = true;
-    if (report.gate.cvd && report.cvd?.some((r) => !r.pass)) failed = true;
+const browser = await chromium.launch();
+try {
+  const page = await browser.newPage();
+  await page.setContent('<!doctype html><html><head></head><body></body></html>');
+  await page.addStyleTag({ content: css });
+  for (const theme of themes) {
+    const report = runTheme(theme, await readThemeStyles(page, theme), { cvd });
+    if (markdown) printMarkdown(report);
+    else printText(report, showAll);
+    if (!reportOnly) {
+      if (report.results.some((r) => !r.pass) || report.contractErrors.length) failed = true;
+      if (report.gate?.cvd && report.cvd?.some((r) => !r.pass)) failed = true;
+    }
   }
+} finally {
+  await browser.close();
 }
 if (failed) {
   console.error('\nTheme contrast gate FAILED.');
-  process.exit(1);
+  process.exitCode = 1;
 }
diff --git a/shared/types/appearance.ts b/shared/types/appearance.ts
index 0265cc9e9..b55918dd5 100644
--- a/shared/types/appearance.ts
+++ b/shared/types/appearance.ts
@@ -6,7 +6,7 @@ export type Theme =
   | 'haar' | 'abyss' | 'understory' | 'colorblind-safe' | 'low-fatigue'
   | 'high-legibility';
 
-/** Kept in sync with the pre-React bootstrap in frontend/index.html by themeClasses.test.ts. */
+/** Canonical map, also inlined into the pre-React bootstrap by the Vite HTML transform. */
 export const THEME_CLASSES = {
   light: ['light'],
   'light-rounded': ['light', 'light-rounded'],
diff --git a/tests/appearance-bootstrap.spec.ts b/tests/appearance-bootstrap.spec.ts
index 88abfbbdf..23736ecbd 100644
--- a/tests/appearance-bootstrap.spec.ts
+++ b/tests/appearance-bootstrap.spec.ts
@@ -1,7 +1,7 @@
 import { expect, test } from '@playwright/test';
 import { installElectronApiMock } from './electronApiMock';
 import { readTerminalTheme } from './terminalXterm';
-import type { AppearanceConfig } from '../shared/types/appearance';
+import { THEME_CLASSES, type AppearanceConfig } from '../shared/types/appearance';
 
 type AppearanceMock = {
   getBackgroundColorWrites: () => Array<{ theme: string; color: string }>;
@@ -15,8 +15,35 @@ const readBootstrapThemeClasses = (page: import('@playwright/test').Page) => pag
   return (window as typeof window & { __paneBootstrapThemeClasses?: string[] }).__paneBootstrapThemeClasses;
 });
 
+test('every canonical theme is applied before the React entry point can load', async ({ page }) => {
+  test.setTimeout(60_000); // One navigation per supported theme, also under the minimal CI config.
+  // No renderer can repair missing bootstrap classes in this test.
+  await page.route('**/*', (route) => route.request().resourceType() === 'script' ? route.abort() : route.continue());
+  await page.addInitScript(() => {
+    const fixedTheme = new URL(location.href).searchParams.get('bootstrap-theme');
+    localStorage.setItem('pane.appearance.v1', JSON.stringify({
+      v: 1, appearanceMode: 'fixed', theme: fixedTheme,
+      systemLightTheme: 'light-rounded', systemDarkTheme: 'dark',
+    }));
+  });
+  for (const [theme, classes] of Object.entries(THEME_CLASSES)) {
+    await page.goto(`/?bootstrap-theme=${theme}`, { waitUntil: 'domcontentloaded' });
+    expect(await readBootstrapThemeClasses(page)).toEqual(classes);
+    expect(await page.locator('html').evaluate((element) => [...element.classList])).toEqual(classes);
+    expect(await page.locator('body').evaluate((element) => [...element.classList])).toEqual(classes);
+    await expect(page.locator('html')).toHaveCSS('color-scheme', classes[0]);
+  }
+});
+
 test('first paint resolves the authoritative snapshot against the synchronous system preference', async ({ page }) => {
   await page.emulateMedia({ colorScheme: 'dark' });
+  await page.addInitScript(() => {
+    localStorage.setItem('pane.appearance.v1', JSON.stringify({
+      v: 1, appearanceMode: 'fixed', theme: 'folio',
+      systemLightTheme: 'folio', systemDarkTheme: 'walnut',
+    }));
+    localStorage.setItem('theme', 'light');
+  });
   await installElectronApiMock(page, {
     initialConfig: {
       appearanceMode: 'system', theme: 'light-rounded', systemLightTheme: 'folio', systemDarkTheme: 'abyss',
@@ -69,7 +96,8 @@ test('legacy theme is fixed and an invalid legacy value falls back to defaults',
   await invalidContext.close();
 });
 
-test('System follows live changes and refreshes native window colors while Fixed is immune', async ({ page }) => {
+test('System refreshes native window colors without a Google Fonts connection', async ({ page }) => {
+  await page.route('https://fonts.googleapis.com/**', (route) => route.abort());
   await page.emulateMedia({ colorScheme: 'light' });
   await installElectronApiMock(page, {
     windowControlsOverlayEnabled: true,
@@ -78,6 +106,7 @@ test('System follows live changes and refreshes native window colors while Fixed
     },
   });
   await page.goto('/');
+  await expect(page.getByRole('button', { name: 'Settings', exact: true })).toBeVisible({ timeout: 15_000 });
   await expect(page.locator('html')).toHaveClass(/folio/);
   await expect.poll(() => page.evaluate(() => {
     // SAFETY: installElectronApiMock defines this test-only bridge before the page loads.
@@ -107,6 +136,7 @@ test('fulfilled background-colour failures are logged without interrupting Syste
     },
   });
   await page.goto('/');
+  await expect(page.getByRole('button', { name: 'Settings', exact: true })).toBeVisible({ timeout: 15_000 });
   await expect(page.locator('html')).toHaveClass(/folio/);
   await expect.poll(() => page.evaluate(() => {
     // SAFETY: installElectronApiMock defines this test-only bridge before the page loads.
@@ -139,6 +169,7 @@ test('Fixed appearance ignores live system preference changes', async ({ page })
     },
   });
   await page.goto('/');
+  await expect(page.getByRole('button', { name: 'Settings', exact: true })).toBeVisible({ timeout: 15_000 });
   await expect(page.locator('html')).toHaveClass(/walnut/);
   await page.emulateMedia({ colorScheme: 'dark' });
   await expect(page.locator('html')).toHaveClass(/walnut/);
@@ -169,7 +200,22 @@ test('terminal palette and rendered diff follow a System slot flip', async ({ pa
       id: 1, session_id: session.id, execution_sequence: 1, after_commit_hash: '2222222', commit_message: 'Change example',
       timestamp: now, stats_additions: 1, stats_deletions: 1, stats_files_changed: 1, author: 'Pane', comparison_branch: 'origin/main', history_source: 'branch',
     }],
-    initialCombinedDiff: { diff, stats: { additions: 1, deletions: 1, filesChanged: 1 }, changedFiles: ['example.ts'] },
+    diffManifests: {
+      session: {
+        scope: { kind: 'session' },
+        files: [{ path: 'example.ts', kind: 'modified', additions: 1, deletions: 1, isBinary: false }],
+        resolvedBase: { kind: 'comparison-base', ref: 'origin/main', hash: '1111111' },
+        resolvedTarget: { kind: 'working-tree' },
+        stats: { additions: 1, deletions: 1, filesChanged: 1 },
+      },
+    },
+    fileDiffs: {
+      'session:example.ts': {
+        file: { path: 'example.ts', kind: 'modified', additions: 1, deletions: 1, isBinary: false },
+        patch: diff,
+        status: 'changed',
+      },
+    },
     initialTerminalStates: { 'appearance-terminal': { scrollbackBuffer: 'ready\r\n' } },
   });
   await page.goto('/');
@@ -186,7 +232,7 @@ test('terminal palette and rendered diff follow a System slot flip', async ({ pa
   const terminalBackground = () => readTerminalTheme(terminalSurface).then((theme) => theme.background ?? '');
   await expect.poll(terminalBackground).not.toBe('');
   const lightBackground = await terminalBackground();
-  await page.getByRole('button', { name: /^Open diff for example\.ts$/ }).click();
+  await page.getByRole('treeitem', { name: /^Open diff for example\.ts,/ }).click();
   await expect(page.getByText('example.ts', { exact: true }).last()).toBeVisible();
   const lightDiffColor = await page.getByText('export const value = 2;', { exact: false }).last().evaluate((element) => getComputedStyle(element).color);