@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/theme/catalog.test.ts

@@ -0,0 +1,168 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The catalog is the single source of truth for what Kabmo can paint, and
+ * every failure mode here is silent at runtime: an unknown id renders the
+ * default palette (a theme that "doesn't work"), a missing color renders as an
+ * empty declaration (an invisible swatch, a transparent panel), a wrong variant
+ * leaves a dark theme with light scrollbars and light-theme code blocks.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  DEFAULT_THEME_ID,
+  THEMES,
+  THEME_SWATCHES,
+  isDarkTheme,
+  resolveTheme,
+  resolveThemeId,
+} from '@/shared/lib/theme/catalog';
+import { themeStyleSheet } from '@/shared/lib/theme/css';
+import { mixHex, parseHexColor } from '@/shared/lib/theme/color';
+import { getXtermTheme } from '@/client/data/theme/terminal';
+
+const COLOR_KEYS = ['canvas', 'paper', 'ink', 'error', 'success', 'info', 'warning', 'meta'] as const;
+const COLOR_VALUE = /^(#[0-9a-f]{3}|#[0-9a-f]{6}|#[0-9a-f]{8})$/i;
+
+describe('theme catalog', () => {
+  test('ships Kabmo palettes plus every ported variant', () => {
+    expect(THEMES.length).toBe(45);
+    // 21 ported light + paper/contrast; 21 ported dark + one-dark-pro-soft.
+    expect(THEMES.filter((t) => t.variant === 'light').length).toBe(23);
+    expect(THEMES.filter((t) => t.variant === 'dark').length).toBe(22);
+  });
+
+  test('ids are unique and each palette carries a paintable color for every slot', () => {
+    const ids = new Set<string>();
+    for (const theme of THEMES) {
+      expect(ids.has(theme.id)).toBe(false);
+      ids.add(theme.id);
+      expect(theme.name.length).toBeGreaterThan(0);
+      expect(theme.family.length).toBeGreaterThan(0);
+      for (const key of COLOR_KEYS) {
+        expect(theme[key]).toMatch(COLOR_VALUE);
+      }
+    }
+  });
+
+  test('the default is the shipped E-Ink palette', () => {
+    expect(DEFAULT_THEME_ID).toBe('paper');
+    expect(resolveTheme(DEFAULT_THEME_ID).name).toBe('E-Ink Paper');
+  });
+
+  test('an id the catalog does not know resolves to the default, never to nothing', () => {
+    // `noir` shipped until this change as a byte-identical alias of
+    // `one-dark-pro-soft`; a settings row naming it must still render.
+    for (const unknown of ['noir', 'nonsense', '', undefined, null]) {
+      expect(resolveTheme(unknown).id).toBe(DEFAULT_THEME_ID);
+      expect(resolveThemeId(unknown)).toBe(DEFAULT_THEME_ID);
+    }
+  });
+
+  test('every ported family pairs a light entry with a dark one', () => {
+    const byFamily = new Map<string, Set<string>>();
+    for (const theme of THEMES) {
+      const variants = byFamily.get(theme.family) ?? new Set<string>();
+      variants.add(theme.variant);
+      byFamily.set(theme.family, variants);
+    }
+    // `paper`/`contrast` (light-only) and `one-dark-pro-soft` (dark-only) are
+    // Kabmo's own single-variant palettes; every ported family has both.
+    const singles = [...byFamily].filter(([, variants]) => variants.size === 1).map(([family]) => family);
+    expect(singles.sort()).toEqual(['contrast', 'one-dark-pro-soft', 'paper']);
+  });
+
+  test('swatches name every color the cards can show', () => {
+    expect(THEME_SWATCHES.map((s) => s.key)).toEqual([...COLOR_KEYS]);
+  });
+});
+
+describe('generated stylesheet', () => {
+  const css = themeStyleSheet();
+
+  test('defines every palette under a selector that beats :root', () => {
+    for (const theme of THEMES) {
+      // `html[...]` (0,1,1) outranks the stylesheet's `:root` (0,1,0); a bare
+      // `[data-theme]` would tie and lose on document order.
+      expect(css).toContain(`html[data-theme="${theme.id}"]`);
+    }
+    expect(css.match(/html\[data-theme="/g)?.length).toBe(THEMES.length);
+  });
+
+  test('carries each palette\'s colors and its color-scheme', () => {
+    expect(css).toContain('--theme-canvas: #1F2430;');
+    expect(css).toContain('color-scheme: dark;');
+    expect(css).toContain('color-scheme: light;');
+  });
+
+  test('derives the hover shades instead of pinning a hex that fits one palette', () => {
+    expect(css).toContain('--theme-info-hover: color-mix(in srgb, var(--theme-info) 85%, var(--theme-ink));');
+  });
+});
+
+describe('theme variant verdict', () => {
+  test('follows the palette, not a hand-kept id list', () => {
+    expect(isDarkTheme('paper')).toBe(false);
+    expect(isDarkTheme('one-dark-pro-soft')).toBe(true);
+    expect(isDarkTheme('nord-dark')).toBe(true);
+    expect(isDarkTheme('nord-light')).toBe(false);
+    expect(isDarkTheme('tokyonight-light')).toBe(false);
+    expect(isDarkTheme('tokyonight-dark')).toBe(true);
+  });
+
+  test('every dark palette is dark and every light palette is not', () => {
+    for (const theme of THEMES) {
+      expect(isDarkTheme(theme.id)).toBe(theme.variant === 'dark');
+    }
+  });
+});
+
+describe('color math', () => {
+  test('parses the notations the ported palettes actually use', () => {
+    expect(parseHexColor('#FFF')).toEqual({ r: 255, g: 255, b: 255, a: 1 });
+    expect(parseHexColor('#f4f1ea')).toEqual({ r: 244, g: 241, b: 234, a: 1 });
+    expect(parseHexColor('#dbd7caee')?.a).toBeCloseTo(0.933, 3);
+    expect(parseHexColor('rebeccapurple')).toBeNull();
+  });
+
+  test('mixes toward the blend color and composites its alpha', () => {
+    expect(mixHex('#000000', '#ffffff', 0.5)).toBe('#808080');
+    expect(mixHex('#000000', '#ffffff', 0)).toBe('#000000');
+    expect(mixHex('#000000', '#ffffff', 1)).toBe('#ffffff');
+    // A fully transparent blend leaves the base untouched rather than
+    // producing a black hole.
+    expect(mixHex('#123456', '#ffffff00', 1)).toBe('#123456');
+    expect(mixHex('nonsense', '#ffffff', 1)).toBe('nonsense');
+  });
+});
+
+describe('terminal palette', () => {
+  test('follows the active theme rather than a fixed light/dark pair', () => {
+    const nord = getXtermTheme('nord-dark');
+    const paper = getXtermTheme('paper');
+    expect(nord.background).toBe('#1F2430');
+    expect(nord.foreground).toBe('#E5E9F0');
+    expect(paper.background).toBe('#f4f1ea');
+    expect(paper.foreground).toBe('#141310');
+  });
+
+  test('emits literal colors — xterm cannot parse color-mix()', () => {
+    for (const theme of THEMES) {
+      for (const value of Object.values(getXtermTheme(theme.id))) {
+        expect(value).toMatch(COLOR_VALUE);
+      }
+    }
+  });
+
+  test('takes its signal colors from the palette', () => {
+    const dracula = getXtermTheme('dracula-dark');
+    expect(dracula.red).toBe('#FF5555');
+    expect(dracula.green).toBe('#50FA7B');
+    expect(dracula.yellow).toBe('#FFB86C');
+    expect(dracula.cursor).toBe('#BD93F9');
+  });
+});

package/src/shared/lib/theme/catalog.ts

@@ -0,0 +1,98 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The theme catalog: every palette Kabmo can paint, the lookups the whole
+ * app resolves a stored theme id through, and the light/dark verdict that used
+ * to be re-derived by hand in four places (`hooks/ui/theme.ts`,
+ * `code/shiki-themes.ts`, `markdown/mermaid.ts`, `server/plugins/ssr.ts`) — each
+ * with its own hardcoded id list that a new theme would have silently missed.
+ *
+ * Pure data plus pure functions: no DOM, no CSS, no server imports, so the
+ * client, the SSR shell and the tests all read the same catalog.
+ */
+
+import type { ThemePalette, ThemeSwatch } from '@/shared/types/theme';
+import { KABMO_PALETTES } from '@/shared/lib/theme/palettes/kabmo';
+import { DARK_PALETTES } from '@/shared/lib/theme/palettes/dark';
+import { LIGHT_PALETTES } from '@/shared/lib/theme/palettes/light';
+
+/** The shipped default, and the fallback for any id the catalog does not know. */
+export const DEFAULT_THEME_ID = 'paper';
+
+/**
+ * Every id in the catalog, as a literal union. `SettingsState.theme` is typed
+ * with it, so a typo — or a theme dropped from the catalog — is a compile error
+ * at the writer instead of an unstyled page at runtime.
+ */
+export type ThemeId =
+  | (typeof KABMO_PALETTES)[number]['id']
+  | (typeof LIGHT_PALETTES)[number]['id']
+  | (typeof DARK_PALETTES)[number]['id'];
+
+const ALL_PALETTES = [...KABMO_PALETTES, ...LIGHT_PALETTES, ...DARK_PALETTES];
+
+const BY_ID: Record<string, ThemePalette | undefined> = Object.fromEntries(
+  ALL_PALETTES.map((theme) => [theme.id, theme]),
+);
+
+const DEFAULT_PALETTE: ThemePalette = KABMO_PALETTES[0];
+
+/**
+ * Every palette, in appearance-grid order: Kabmo's own three first (the
+ * ones an existing install is already using), then each ported family with its
+ * light and dark entry adjacent.
+ *
+ * Pairing is by family key rather than by array index, so a re-port that
+ * updates one variant of a family cannot silently shift every pair after it.
+ */
+export const THEMES: readonly ThemePalette[] = (() => {
+  const families = new Map<string, ThemePalette[]>();
+  for (const palette of [...LIGHT_PALETTES, ...DARK_PALETTES]) {
+    const group = families.get(palette.family);
+    if (group) group.push(palette);
+    else families.set(palette.family, [palette]);
+  }
+  return [...KABMO_PALETTES, ...[...families.values()].flat()];
+})();
+
+/**
+ * Resolve a stored theme id to a palette the catalog can actually paint.
+ *
+ * A settings row can name a theme this build no longer ships — a downgrade, or
+ * the `noir` alias that was byte-identical to `one-dark-pro-soft` and is gone.
+ * Every reader goes through here, so an unknown id renders the default instead
+ * of an unstyled page.
+ */
+export function resolveTheme(id: string | undefined | null): ThemePalette {
+  return (id ? BY_ID[id] : undefined) ?? DEFAULT_PALETTE;
+}
+
+export function isDarkTheme(id: string | undefined | null): boolean {
+  return resolveTheme(id).variant === 'dark';
+}
+
+/**
+ * The catalog's own id for `id`, falling back to the default.
+ *
+ * The single narrowing point between a runtime string (a stored setting, a
+ * button's payload) and `ThemeId`: every palette's `id` is one of the union's
+ * members by construction, which is the fact the cast asserts.
+ */
+export function resolveThemeId(id: string | undefined | null): ThemeId {
+  return resolveTheme(id).id as ThemeId;
+}
+
+/** The eight slots a palette card shows, in paint order. */
+export const THEME_SWATCHES: readonly ThemeSwatch[] = [
+  { key: 'canvas', label: 'Canvas' },
+  { key: 'paper', label: 'Surface' },
+  { key: 'ink', label: 'Ink' },
+  { key: 'error', label: 'Error' },
+  { key: 'success', label: 'Success' },
+  { key: 'info', label: 'Info' },
+  { key: 'warning', label: 'Warning' },
+  { key: 'meta', label: 'Accent' },
+];

package/src/shared/lib/theme/chrome.test.ts

@@ -0,0 +1,53 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The window-chrome rule, pinned because it has TWO writers (the SSR shell and
+ * the client theme writer) and no single call site makes it obvious: the meta
+ * tag has to match the surface at the TOP of the window, and that surface is
+ * `--theme-paper` on the desktop layout and `--theme-canvas` on the phone and
+ * the login screen.
+ *
+ * The regression this pins: writing `palette.canvas` unconditionally put a
+ * strip one step darker than the header beneath it on every desktop install
+ * (`#f4f1ea` over `#faf8f3` on the default palette, `#21252b` over `#282c34` on
+ * `one-dark-pro-soft`).
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { windowChromeColor } from '@/shared/lib/theme/chrome';
+import { KABMO_PALETTES } from '@/shared/lib/theme/palettes/kabmo';
+
+const paper = KABMO_PALETTES[0];
+const oneDark = KABMO_PALETTES[2];
+
+describe('windowChromeColor', () => {
+  test('matches the desktop top bar (paper) for an authenticated desktop', () => {
+    expect(windowChromeColor(paper, { isMobile: false, authRequired: false })).toBe(paper.paper);
+    expect(windowChromeColor(oneDark, { isMobile: false, authRequired: false })).toBe(oneDark.paper);
+  });
+
+  test('matches the phone header (canvas) in the mobile layout', () => {
+    expect(windowChromeColor(paper, { isMobile: true, authRequired: false })).toBe(paper.canvas);
+    expect(windowChromeColor(oneDark, { isMobile: true, authRequired: false })).toBe(oneDark.canvas);
+  });
+
+  test('matches the login screen (canvas) in either layout', () => {
+    expect(windowChromeColor(paper, { isMobile: false, authRequired: true })).toBe(paper.canvas);
+    expect(windowChromeColor(paper, { isMobile: true, authRequired: true })).toBe(paper.canvas);
+  });
+
+  test('never returns the ink slot, which is what the manifest carries', () => {
+    for (const palette of KABMO_PALETTES) {
+      for (const isMobile of [true, false]) {
+        for (const authRequired of [true, false]) {
+          const chrome = windowChromeColor(palette, { isMobile, authRequired });
+          expect([palette.paper, palette.canvas] as string[]).toContain(chrome);
+        }
+      }
+    }
+  });
+});

package/src/shared/lib/theme/chrome.ts

@@ -0,0 +1,41 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The color Chrome paints behind an installed app's title bar.
+ *
+ * `<meta name="theme-color">` styles the window chrome of an installed PWA (and
+ * the status bar on a phone), and it has to be the color the layout paints
+ * across the TOP of the window or the two meet in a visible seam. That color is
+ * not one palette slot: the desktop layout's top strip is `bg-paper`
+ * (`desktop-layout/TopNavbar.tsx`, with the sidebar's own `bg-paper` beside
+ * it), while the phone's header is `bg-canvas`
+ * (`mobile/mobile-main-view/Header.tsx`) and the login screen is `bg-canvas`
+ * too (`auth/login-screen`).
+ *
+ * The rule lives here, in one function, because it has two writers — the SSR
+ * shell (which knows the user agent and whether the request was authenticated)
+ * and the client theme writer (which knows the layout the user ended up in) —
+ * and a rule restated at a call site is a rule that drifts. Writing
+ * `palette.canvas` unconditionally is what shipped: every desktop install drew
+ * a chrome strip one step darker than the header beneath it (`#f4f1ea` over
+ * `#faf8f3` on the default palette, `#21252b` over `#282c34` on
+ * `one-dark-pro-soft`).
+ */
+
+import type { ThemePalette } from '@/shared/types/theme';
+
+/** The two facts the chrome color depends on, as each writer knows them. */
+export interface WindowChromeMode {
+  /** The phone layout is on screen, whose header is `--theme-canvas`. */
+  isMobile: boolean;
+  /** The login screen is on screen — `--theme-canvas` in both layouts. */
+  authRequired: boolean;
+}
+
+/** The palette slot the window chrome is painted with. */
+export function windowChromeColor(palette: ThemePalette, mode: WindowChromeMode): string {
+  return mode.authRequired || mode.isMobile ? palette.canvas : palette.paper;
+}

package/src/shared/lib/theme/color.test.ts

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Hex color arithmetic for the terminal palette.
+ *
+ * xterm cannot parse `color-mix()`, so blends are computed here and handed over
+ * as literal hex — a wrong blend is a wrong-looking terminal, and a wrong
+ * fallback (returning a broken string instead of the base color) would blank a
+ * palette entry. The parser must handle all three spellings the ported palettes
+ * use (`#rgb`, `#rrggbb`, and 8-digit `#rrggbbaa`, including OpenChamber's
+ * `#FFF`), and `mixHex` must composite the blend's own alpha rather than treat
+ * it as opaque. `relativeLuminance` orders palette colors light-to-dark.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { mixHex, parseHexColor, relativeLuminance, rgbaToHex } from '@/shared/lib/theme/color';
+
+describe('parseHexColor', () => {
+  test('parses the short form, with or without the hash', () => {
+    expect(parseHexColor('#fff')).toEqual({ r: 255, g: 255, b: 255, a: 1 });
+    expect(parseHexColor('fff')).toEqual({ r: 255, g: 255, b: 255, a: 1 });
+    expect(parseHexColor('#abc')).toEqual({ r: 170, g: 187, b: 204, a: 1 });
+  });
+
+  test('parses the long form, case-insensitively and trimmed', () => {
+    expect(parseHexColor('#1A2b3C')).toEqual({ r: 26, g: 43, b: 60, a: 1 });
+    expect(parseHexColor('  #1a2b3c  ')).toEqual({ r: 26, g: 43, b: 60, a: 1 });
+  });
+
+  test('parses 8-digit values as r/g/b plus an alpha fraction', () => {
+    expect(parseHexColor('#11223344')).toEqual({ r: 0x11, g: 0x22, b: 0x33, a: 0x44 / 255 });
+    expect(parseHexColor('#aabbccff')).toEqual({ r: 170, g: 187, b: 204, a: 1 });
+  });
+
+  test('returns null for anything that is not 3, 6 or 8 hex digits', () => {
+    expect(parseHexColor('')).toBeNull();
+    expect(parseHexColor('red')).toBeNull();
+    expect(parseHexColor('#ffff')).toBeNull();
+    expect(parseHexColor('#fffff')).toBeNull();
+    expect(parseHexColor('#1234567')).toBeNull();
+    expect(parseHexColor('#gggggg')).toBeNull();
+    expect(parseHexColor('rgb(1,2,3)')).toBeNull();
+  });
+});
+
+describe('rgbaToHex', () => {
+  test('renders six lowercase hex digits, ignoring alpha', () => {
+    expect(rgbaToHex({ r: 255, g: 255, b: 255, a: 1 })).toBe('#ffffff');
+    expect(rgbaToHex({ r: 0, g: 0, b: 0, a: 0.2 })).toBe('#000000');
+  });
+
+  test('rounds and clamps each channel', () => {
+    expect(rgbaToHex({ r: 300, g: -5, b: 127.6, a: 1 })).toBe('#ff0080');
+    expect(rgbaToHex({ r: 127.4, g: 0, b: 0, a: 1 })).toBe('#7f0000');
+  });
+});
+
+describe('mixHex', () => {
+  test('ratio 0 is the base and ratio 1 the opaque blend', () => {
+    expect(mixHex('#ffffff', '#000000', 0)).toBe('#ffffff');
+    expect(mixHex('#ffffff', '#000000', 1)).toBe('#000000');
+    expect(mixHex('#000000', '#ffffff', 0.5)).toBe('#808080');
+  });
+
+  test('composites the blend alpha into the weight', () => {
+    expect(mixHex('#ffffff', '#00000080', 1)).toBe('#7f7f7f');
+    expect(mixHex('#ffffff', '#00000080', 0.5)).toBe('#bfbfbf');
+  });
+
+  test('falls back to the base when either side cannot be parsed', () => {
+    expect(mixHex('nope', '#fff', 0.5)).toBe('nope');
+    expect(mixHex('#000', 'nope', 0.5)).toBe('#000');
+  });
+});
+
+describe('relativeLuminance', () => {
+  test('is 0 for black and 1 for white', () => {
+    expect(relativeLuminance('#000000')).toBe(0);
+    expect(relativeLuminance('#ffffff')).toBe(1);
+  });
+
+  test('weights green above red above blue', () => {
+    expect(relativeLuminance('#ff0000')).toBeCloseTo(0.2126, 6);
+    expect(relativeLuminance('#00ff00')).toBeCloseTo(0.7152, 6);
+    expect(relativeLuminance('#0000ff')).toBeCloseTo(0.0722, 6);
+  });
+
+  test('uses the linear segment for very dark colors', () => {
+    expect(relativeLuminance('#0a0a0a')).toBeCloseTo(0.0030353, 5);
+    expect(relativeLuminance('#0a0a0a')).toBeLessThan(relativeLuminance('#808080'));
+  });
+
+  test('orders colors light-to-dark and treats unparseable input as black', () => {
+    expect(relativeLuminance('#ffffff')).toBeGreaterThan(relativeLuminance('#808080'));
+    expect(relativeLuminance('#808080')).toBeGreaterThan(relativeLuminance('#000000'));
+    expect(relativeLuminance('nope')).toBe(0);
+  });
+});

package/src/shared/lib/theme/color.ts

@@ -0,0 +1,88 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Hex color arithmetic for the places that cannot use CSS.
+ *
+ * `color-mix()` covers every blend inside the document, but xterm parses theme
+ * colors itself (it accepts `#rgb`, `#rrggbb`, `rgb()`, `hsl()` and named
+ * colors — not `color-mix()`, in either the DOM or the WebGL renderer), so the
+ * terminal palette has to be computed here and handed over as literal hex.
+ *
+ * The palette values are ported verbatim from OpenChamber and are therefore not
+ * uniform: `#FFF` (jetbrains-light) and 8-digit alpha (`#dbd7caee`,
+ * vitesse-dark) both appear, and a blend has to composite the alpha rather than
+ * pretend it is opaque.
+ */
+
+export interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  /** 0–1. */
+  a: number;
+}
+
+const HEX_SHORT = /^#?([0-9a-f]{3})$/i;
+const HEX_LONG = /^#?([0-9a-f]{6})$/i;
+const HEX_ALPHA = /^#?([0-9a-f]{8})$/i;
+
+/** Parse `#rgb`, `#rrggbb` or `#rrggbbaa`. `null` for anything else. */
+export function parseHexColor(value: string): Rgba | null {
+  const trimmed = value.trim();
+  const short = HEX_SHORT.exec(trimmed);
+  if (short) {
+    const [r, g, b] = short[1].split('');
+    return { r: parseInt(r + r, 16), g: parseInt(g + g, 16), b: parseInt(b + b, 16), a: 1 };
+  }
+  const long = HEX_LONG.exec(trimmed);
+  if (long) {
+    const n = parseInt(long[1], 16);
+    return { r: (n >> 16) & 0xff, g: (n >> 8) & 0xff, b: n & 0xff, a: 1 };
+  }
+  const alpha = HEX_ALPHA.exec(trimmed);
+  if (alpha) {
+    const n = parseInt(alpha[1], 16);
+    return { r: (n >>> 24) & 0xff, g: (n >> 16) & 0xff, b: (n >> 8) & 0xff, a: (n & 0xff) / 255 };
+  }
+  return null;
+}
+
+function toHex2(value: number): string {
+  return Math.max(0, Math.min(255, Math.round(value))).toString(16).padStart(2, '0');
+}
+
+export function rgbaToHex({ r, g, b }: Rgba): string {
+  return `#${toHex2(r)}${toHex2(g)}${toHex2(b)}`;
+}
+
+/**
+ * `ratio` of `blend` laid over `base` (0 = base, 1 = blend), compositing
+ * `blend`'s own alpha. Falls back to `base` when either value cannot be parsed,
+ * so a palette with an unexpected notation still yields a paintable color.
+ */
+export function mixHex(base: string, blend: string, ratio: number): string {
+  const under = parseHexColor(base);
+  const over = parseHexColor(blend);
+  if (!under || !over) return base;
+  const weight = over.a * ratio;
+  return rgbaToHex({
+    r: under.r * (1 - weight) + over.r * weight,
+    g: under.g * (1 - weight) + over.g * weight,
+    b: under.b * (1 - weight) + over.b * weight,
+    a: 1,
+  });
+}
+
+/** WCAG relative luminance, used to order two palette colors light-to-dark. */
+export function relativeLuminance(value: string): number {
+  const color = parseHexColor(value);
+  if (!color) return 0;
+  const channel = (raw: number) => {
+    const c = raw / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(color.r) + 0.7152 * channel(color.g) + 0.0722 * channel(color.b);
+}

package/src/shared/lib/theme/css.ts

@@ -0,0 +1,70 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The `[data-theme]` CSS for every palette in the catalog, as one string.
+ *
+ * Generated rather than hand-written because the palette values already exist
+ * in TypeScript — the appearance cards render the same eight colors as chips —
+ * so a second hand-maintained copy in `tailwind.css` would be 45 blocks that
+ * drift from the cards the moment either side is edited.
+ *
+ * Two details are load-bearing:
+ *
+ * - **Selector specificity is `html[data-theme=…]`, not `[data-theme=…]`.**
+ *   `tailwind.css` carries the default palette on `:root`, which is also
+ *   (0,1,0); at equal specificity the later declaration wins by document order,
+ *   so a bare attribute selector injected before the stylesheet would lose and
+ *   every theme would render as `paper`.
+ * - **`color-scheme` is set per variant.** Scrollbars, form controls and the
+ *   browser's own canvas background are painted by the UA from it; without it a
+ *   dark theme keeps white scrollbars and a white overscroll area.
+ *
+ * No DOM here — the SSR shell inlines this, and the client injects the same
+ * string only when a served document predates it.
+ */
+
+import type { ThemePalette } from '@/shared/types/theme';
+import { THEMES } from '@/shared/lib/theme/catalog';
+
+/** The `<style>` element's id: the SSR shell writes it, the client checks it. */
+export const THEME_STYLE_ELEMENT_ID = 'omp-theme-palettes';
+
+/**
+ * A hover shade of a signal color, mixed toward the theme's own ink so the
+ * direction follows the palette: darker on a light theme, lighter on a dark one.
+ * `--theme-info-hover` / `--theme-warning-hover` used to be fixed hex values in
+ * `tailwind.css` and could only be right for one palette.
+ */
+const HOVER_MIXES: ReadonlyArray<readonly [string, string]> = [
+  ['--theme-info-hover', '--theme-info'],
+  ['--theme-warning-hover', '--theme-warning'],
+];
+
+function paletteBlock(theme: ThemePalette): string {
+  const lines = [
+    `  --theme-paper: ${theme.paper};`,
+    `  --theme-canvas: ${theme.canvas};`,
+    `  --theme-ink: ${theme.ink};`,
+    `  --theme-error: ${theme.error};`,
+    `  --theme-success: ${theme.success};`,
+    `  --theme-info: ${theme.info};`,
+    `  --theme-warning: ${theme.warning};`,
+    `  --theme-meta: ${theme.meta};`,
+  ];
+  for (const [name, source] of HOVER_MIXES) {
+    lines.push(`  ${name}: color-mix(in srgb, var(${source}) 85%, var(--theme-ink));`);
+  }
+  lines.push(`  color-scheme: ${theme.variant};`);
+  return `html[data-theme="${theme.id}"] {\n${lines.join('\n')}\n}`;
+}
+
+/** Cached: the palette set is fixed for the life of the process. */
+let cached: string | null = null;
+
+export function themeStyleSheet(): string {
+  cached ??= `/* Generated from src/shared/lib/theme/palettes — do not edit by hand. */\n${THEMES.map(paletteBlock).join('\n')}\n`;
+  return cached;
+}