ompchamber 1.2.1 → 2.0.1

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 the chamber 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 the chamber 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
+    // the chamber'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 the chamber 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 { CHAMBER_PALETTES } from '@/shared/lib/theme/palettes/chamber';
+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 CHAMBER_PALETTES)[number]['id']
+  | (typeof LIGHT_PALETTES)[number]['id']
+  | (typeof DARK_PALETTES)[number]['id'];
+
+const ALL_PALETTES = [...CHAMBER_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 = CHAMBER_PALETTES[0];
+
+/**
+ * Every palette, in appearance-grid order: the chamber'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 [...CHAMBER_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/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;
+}

package/src/shared/lib/theme/palettes/chamber.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The chamber's own palettes, carried over from the hand-written
+ * `[data-theme]` blocks in `tailwind.css` with their values unchanged.
+ *
+ * They stay in the catalog rather than becoming OpenChamber ports so an
+ * existing install keeps the exact colors it was using: `paper` is the shipped
+ * default and `one-dark-pro-soft` is what every dark-theme user has selected
+ * until now.
+ */
+
+import type { ThemePalette } from '@/shared/types/theme';
+
+export const CHAMBER_PALETTES = [
+  {
+    id: 'paper',
+    name: 'E-Ink Paper',
+    family: 'paper',
+    variant: 'light',
+    canvas: '#f4f1ea',
+    paper: '#faf8f3',
+    ink: '#141310',
+    error: '#c8321e',
+    success: '#047857',
+    info: '#0284c7',
+    warning: '#c2410c',
+    meta: '#4f46e5',
+  },
+  {
+    id: 'contrast',
+    name: 'High Contrast',
+    family: 'contrast',
+    variant: 'light',
+    canvas: '#f4f4f4',
+    paper: '#ffffff',
+    ink: '#111111',
+    error: '#b42318',
+    success: '#067647',
+    info: '#0369a1',
+    warning: '#b54708',
+    meta: '#4338ca',
+  },
+  {
+    id: 'one-dark-pro-soft',
+    name: 'One Dark Pro Soft',
+    family: 'one-dark-pro-soft',
+    variant: 'dark',
+    canvas: '#21252b',
+    paper: '#282c34',
+    ink: '#abb2bf',
+    error: '#e06c75',
+    success: '#34d399',
+    info: '#61afef',
+    warning: '#fb923c',
+    meta: '#818cf8',
+  },
+] as const satisfies readonly ThemePalette[];