ompchamber 1.2.1 → 2.0.0

package/src/shared/lib/markdown/marked.ts

@@ -8,17 +8,19 @@
  *
  * Stack (run in order, all server/client safe — parsed synchronously):
  *   1. remend  — heal incomplete markdown while streaming (before parse)
- *   2. marked  — GFM true, breaks true, autolink via marked-linkify-it (CJK
- *      punctuation is not swallowed into URLs), plus a KaTeX extension for
- *      \(...\) inline, \[...\] block, and $$...$$ display math
+ *   2. marked  — GFM true, breaks true, autolink via linkify-it (CJK
+ *      punctuation is not swallowed into URLs, and a match carrying a backtick
+ *      is left to the code-span rule — see autolink.ts), plus a KaTeX
+ *      extension for \(...\) inline, \[...\] block, and $$...$$ display math
  *
  * The resulting HTML is NOT sanitized here — run the output through
- * DOMPurify (see sanitize.ts) before injecting, so raw HTML from the
- * assistant is escaped rather than executed.
+ * DOMPurify (see sanitize.ts) before injecting. What the source's own HTML
+ * means is the caller's call: `renderMarkdown` escapes it (assistant output,
+ * where markup is data) unless `allowHtml` says the source is a document.
  */
 
 import { Marked } from 'marked';
-import markedLinkifyIt from 'marked-linkify-it';
+import { codeSafeAutolink } from '@/shared/lib/markdown/autolink';
 import remend from 'remend';
 import { highlightCode } from '@/shared/lib/code/syntax-highlight';
 import { MATH_PENDING_CLASS } from '@/shared/lib/markdown/katex';
@@ -64,7 +66,7 @@ const marked = new Marked({
   breaks: true,
 });
 
-marked.use(markedLinkifyIt());
+marked.use(codeSafeAutolink());
 
 interface CodeToken {
   type: string;
@@ -217,19 +219,29 @@ function escapeHtmlOutsideCode(source: string): string {
  * parsing so the placeholder URL never leaks into the DOM as an href. */
 const INCOMPLETE_LINK_RE = /\[([^\]]*)\]\(streamdown:incomplete-link\)/g;
 
+export interface RenderMarkdownOptions {
+  /**
+   * Leave the source's own HTML markup intact so marked parses it as markup.
+   *
+   * OFF (default) is the agent-output contract: assistant HTML is data, never
+   * markup, so `<div align="center">` and `<br>` arrive as visible text and
+   * DOMPurify is only the second line of defence. ON is the file-preview
+   * contract, where the source IS the document — a README's `<p align="center">`
+   * block, badge `<img>` and inline `<br>` are the layout its author wrote, and
+   * escaping them shows the tags instead of the page. DOMPurify still sanitizes
+   * the result, so scripts and event handlers never survive either way.
+   */
+  allowHtml?: boolean;
+}
+
 /**
  * Heal streaming markdown (remend) then parse to HTML via marked.
  * Synchronous and side-effect free — safe in both server loaders and the
  * browser. The output must be sanitized with DOMPurify before injection.
- *
- * Raw HTML in the source is escaped (instruksi: assistant HTML is escaped,
- * never rendered) — `<script>`/`<img onerror>` come through as literal text
- * while backtick code is preserved. DOMPurify remains the second line of
- * defence.
  */
-export function renderMarkdown(markdown: string): string {
-  const escaped = escapeHtmlOutsideCode(markdown);
-  const healed = remend(escaped, { katex: true, inlineKatex: true })
+export function renderMarkdown(markdown: string, options: RenderMarkdownOptions = {}): string {
+  const source = options.allowHtml ? markdown : escapeHtmlOutsideCode(markdown);
+  const healed = remend(source, { katex: true, inlineKatex: true })
     .replace(INCOMPLETE_LINK_RE, (_, text: string) => `<span class="md-incomplete-link">${text}</span>`);
   return (marked.parse(healed) as string).trim();
 }

package/src/shared/lib/markdown/mermaid.ts

@@ -18,6 +18,7 @@
  */
 
 import { sanitizeMermaidSvg } from '@/shared/lib/markdown/sanitize';
+import { isDarkTheme } from '@/shared/lib/theme/catalog';
 
 export interface MermaidRenderResult {
   rendered: number;
@@ -34,8 +35,7 @@ let mermaidPromise: Promise<MermaidModule['default']> | null = null;
 let lastThemeKey: ThemeKey | null = null;
 
 function resolveThemeKey(): ThemeKey {
-  const theme = document.documentElement.dataset.theme || document.documentElement.getAttribute('data-theme');
-  return theme === 'one-dark-pro-soft' || theme === 'noir' || theme === 'dark' ? 'dark' : 'default';
+  return isDarkTheme(document.documentElement.dataset.theme || document.documentElement.getAttribute('data-theme')) ? 'dark' : 'default';
 }
 
 function cacheKey(themeKey: ThemeKey, source: string): string {

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

@@ -17,7 +17,7 @@ export interface CatalogModelInfo {
   reasoning?: boolean;
   tool_call?: boolean;
   limit?: { context?: number; output?: number };
-  cost?: { input?: number; output?: number; cache_read?: number };
+  cost?: { input?: number; output?: number; cache_read?: number; cache_write?: number };
 }
 
 type ModelsDevCatalog = Record<string, { models?: Record<string, CatalogModelInfo> }>;

package/src/shared/lib/omp/session/schema-migrations.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Additive migrations for `session_stream_state`. `CREATE TABLE IF NOT EXISTS`
+ * leaves an existing table alone, so a database created before `owner_pid`
+ * existed would miss the column and every status read would fail on it.
+ *
+ * Split out of `@/server/lib/db/schema` for the same reason
+ * `@/shared/lib/workspace/schema-migrations` is: the DDL block there owns table
+ * creation, and each later column arrives in the module that explains it.
+ */
+
+import type { DbClient } from '@/server/lib/db/client';
+
+async function addColumn(db: DbClient, statement: string): Promise<void> {
+  try {
+    await db.exec(statement);
+  } catch {
+    // Already present — a fresh install gets the column from the DDL.
+  }
+}
+
+export async function migrateSessionStreamStateColumns(db: DbClient): Promise<void> {
+  // Which chamber process is running the session, so any instance reading this
+  // table can judge a `stream` row it does not own (see stream-state.server.ts).
+  await addColumn(db, 'ALTER TABLE session_stream_state ADD COLUMN owner_pid INTEGER;');
+}

package/src/shared/lib/omp/session/stream-state.server.test.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The staleness rule behind the sidebar's self-heal. Getting it wrong is
+ * user-visible in both directions: too eager clears the spinner of a run that
+ * is still working, too lazy leaves a spinner turning forever for a run whose
+ * process is gone.
+ *
+ * The rule is deliberately a pure function of the ROW plus OS liveness, with no
+ * caller context. That is what makes several chamber instances agree: they all
+ * read the same row and ask the same question about the same pid.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { isStaleStreamRow } from '@/shared/lib/omp/session/stream-state.server';
+
+const OWNER = 4242;
+const otherInstance = 9999;
+/** OWNER and the other instance are alive; anything else, including 999999, is not. */
+const alive = (pid: number) => pid === OWNER || pid === otherInstance;
+
+describe('isStaleStreamRow', () => {
+  test('a row whose owner is alive is live, whoever is asking', () => {
+    expect(isStaleStreamRow({ session_id: 's1', owner_pid: OWNER }, alive)).toBe(false);
+  });
+
+  test('a row whose owner is gone is stale', () => {
+    expect(isStaleStreamRow({ session_id: 's1', owner_pid: 999999 }, alive)).toBe(true);
+  });
+
+  test('the verdict does not depend on which instance is asking', () => {
+    // The regression this shape exists for: several instances read ONE row and
+    // must report the same status. Judging by the reader's own runtime registry
+    // made a second instance call another instance's live run stale — the row
+    // is live here, and every asker must say so.
+    const row = { session_id: 's1', owner_pid: otherInstance };
+    const verdicts = [otherInstance, OWNER, 12345].map(() => isStaleStreamRow(row, alive));
+    expect(verdicts).toEqual([false, false, false]);
+  });
+
+  test('an ownerless row is stale, because nothing can vouch for its run', () => {
+    expect(isStaleStreamRow({ session_id: 's1', owner_pid: null }, alive)).toBe(true);
+  });
+
+  test('a row owned by the reader is judged by liveness like any other', () => {
+    // Self-ownership is not special-cased: the reader's own pid is alive while
+    // it runs, so its live rows survive.
+    expect(isStaleStreamRow({ session_id: 's1', owner_pid: OWNER }, (pid) => pid === OWNER)).toBe(false);
+  });
+});

package/src/shared/lib/omp/session/stream-state.server.ts

@@ -5,35 +5,49 @@
 
 /**
  * Server-authoritative per-session stream status, persisted in SQLite so the
- * sidebar can render spinner/check from the SAME loader that already refresh
+ * sidebar can render spinner/check from the SAME loader that already refreshes
  * on stream events (`omp:session-updated` → revalidator). Statuses:
  *
- *   stream  — a run is in flight (prompt dispatch → agent_start)
+ *   stream  — a run is in flight (prompt dispatch → agent_end)
  *   finish  — the run ended normally (agent_end), not yet seen
  *   abort   — the user stopped it, not yet seen
  *
  * A terminal status is a one-shot badge: opening the session acknowledges it
  * (`markStreamSeen` deletes the row), which is exactly the "check appears
- * once, disappears when the session is opened" contract. Rows marked
- * `stream` whose session is no longer running when the sidebar loads are
- * stale (chamber restart mid-run) and self-heal to `finish`.
+ * once, disappears when the session is opened" contract.
+ *
+ * `stream` rows record the pid of the chamber process running that session, so
+ * a `stream` row whose owner is gone self-heals to `finish` — see
+ * `healStaleStreamStatuses`. Ownership travels in the row because the database
+ * is SHARED by every chamber instance on the machine (~/.ompchamber/db.sqlite)
+ * while the runtime session registry is per process: without the column, a
+ * second instance opening its sidebar judged the first instance's live run by
+ * its own empty registry and cleared a spinner that was still working.
  *
  * All writes are fire-and-forget: a status write must never fail a prompt,
  * and the sidebar re-reads on the next revalidate anyway.
  */
 
 import { getDb } from '@/server/db.server';
+import { isProcessAlive } from '@/server/lib/lifecycle/identity';
 
 export type SessionStreamStatus = 'stream' | 'finish' | 'abort';
 
 export async function markStreamStatus(sessionId: string, status: SessionStreamStatus): Promise<void> {
   try {
     const db = await getDb();
+    // The owner describes the process running a live row; a terminal badge
+    // belongs to no process, and leaving a pid on it would invite a later read
+    // to judge the badge by the liveness of a process it never concerned.
+    const ownerPid = status === 'stream' ? process.pid : null;
     await db.run(
-      `INSERT INTO session_stream_state (session_id, status, updated_at)
-       VALUES (?, ?, CURRENT_TIMESTAMP)
-       ON CONFLICT(session_id) DO UPDATE SET status = excluded.status, updated_at = excluded.updated_at`,
-      [sessionId, status],
+      `INSERT INTO session_stream_state (session_id, status, owner_pid, updated_at)
+       VALUES (?, ?, ?, CURRENT_TIMESTAMP)
+       ON CONFLICT(session_id) DO UPDATE SET
+         status = excluded.status,
+         owner_pid = excluded.owner_pid,
+         updated_at = excluded.updated_at`,
+      [sessionId, status, ownerPid],
     );
   } catch {
     // Status tracking is best-effort by design.
@@ -97,23 +111,58 @@ export async function loadStreamStatuses(): Promise<Record<string, SessionStream
 }
 
 /**
- * Self-heal: `stream` rows belong to a live chamber process. After a restart
- * mid-run nothing will ever write the terminal status, so at read time a
- * `stream` row with no running session flips to `finish`.
+ * Whether a `stream` row has no live run behind it and must heal to `finish`.
+ *
+ * The owner pid is the only input: a row is live exactly while the process that
+ * wrote it is still running. EVERY chamber instance therefore reaches the same
+ * verdict from the same row — which is the point. Judging a row by the reader's
+ * own runtime registry instead made instances disagree about one run: a second
+ * instance opening its sidebar saw an empty registry, called the first
+ * instance's working run stale, and cleared a spinner that was still turning.
+ *
+ * A row with no owner predates the column and heals: new code always records a
+ * pid for `stream`, so an ownerless `stream` row can only come from an older
+ * process, whose run nothing can vouch for.
+ */
+export function isStaleStreamRow(
+  row: { session_id: string; owner_pid: number | null },
+  isOwnerAlive: (ownerPid: number) => boolean,
+): boolean {
+  if (row.owner_pid === null) return true;
+  return !isOwnerAlive(row.owner_pid);
+}
+
+/**
+ * Self-heal: a `stream` row outlives its owner when a chamber process exits
+ * mid-run (crash, restart, SIGKILL) — nothing will ever write the terminal
+ * status for it. At read time every such row flips to `finish`, which is the
+ * honest outcome: the run is not going to finish.
+ *
+ * Deliberately takes no caller context. Liveness is the same question for every
+ * instance, so it is answered once, here, from the OS — the database is shared
+ * by all of them and they must all read the same status out of it.
+ *
+ * Runs on the sidebar loader's path, so the authoritative status travels with
+ * the same fetch that refreshes the list.
  */
-export async function healStaleStreamStatuses(runningIds: Set<string>): Promise<void> {
+export async function healStaleStreamStatuses(): Promise<void> {
   try {
     const db = await getDb();
-    const rows = (await db.all("SELECT session_id FROM session_stream_state WHERE status = 'stream'")) as {
+    const rows = (await db.all("SELECT session_id, owner_pid FROM session_stream_state WHERE status = 'stream'")) as {
       session_id: string;
+      owner_pid: number | null;
     }[];
-    for (const row of rows) {
-      if (!runningIds.has(row.session_id)) {
-        await db.run("UPDATE session_stream_state SET status = 'finish', updated_at = CURRENT_TIMESTAMP WHERE session_id = ?", [
-          row.session_id,
-        ]);
-      }
-    }
+    const stale = rows.filter((row) => isStaleStreamRow(row, isProcessAlive)).map((row) => row.session_id);
+    if (stale.length === 0) return;
+    // `status = 'stream'` is re-checked in the WHERE clause: a run that started
+    // between the read above and this write owns its row now, and healing it
+    // would clear the spinner of a session that is demonstrably working.
+    const placeholders = stale.map(() => '?').join(', ');
+    await db.run(
+      `UPDATE session_stream_state SET status = 'finish', updated_at = CURRENT_TIMESTAMP
+       WHERE status = 'stream' AND session_id IN (${placeholders})`,
+      stale,
+    );
   } catch {
     // Best-effort.
   }

package/src/shared/lib/settings/client.ts

@@ -76,14 +76,20 @@ export function writeSetting(key: string, value: unknown): void {
 }
 
 /**
- * Write a patch of chamber-blob keys (`theme`, `streamTransport`, …). The blob
- * is kept whole so the durable copy stays one round-trippable object, while the
- * snapshot exposes its keys flat.
+ * Write a patch of chamber-blob keys (`theme`, `streamTransport`, …). The
+ * snapshot exposes the blob's keys flat, so an edit applies to the next read
+ * without a round-trip.
+ *
+ * Only the patch travels, and the server merges it into the stored blob. The
+ * whole local blob must not be republished: this page's copy was taken when it
+ * booted, so a tab left open across an external change (a second tab, a direct
+ * API call) would overwrite the newer keys with its own stale ones on the next
+ * unrelated write — which is exactly how a theme chosen elsewhere reverted.
  */
 export function writeChamberSettings(patch: Record<string, any>): void {
   chamberBlob = { ...chamberBlob, ...patch };
   snapshot = { ...current(), ...patch };
-  sendSettings({ [CHAMBER_SETTINGS_KEY]: chamberBlob });
+  sendSettings({ [CHAMBER_SETTINGS_KEY]: patch });
 }
 
 /** POST a settings patch to SQLite. Fire-and-forget; failures are non-fatal. */

package/src/shared/lib/settings/diff.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from 'bun:test';
+
+import { diffSettings } from '@/shared/lib/settings/diff';
+
+describe('diffSettings', () => {
+  test('an object patch persists only the keys it actually changed', () => {
+    const prev = { theme: 'paper', soundAlerts: true, binaryPath: '/bin/omp' };
+    const next = { ...prev, theme: 'nord-dark' };
+    expect(diffSettings(prev, next, { theme: 'nord-dark' })).toEqual({ theme: 'nord-dark' });
+  });
+
+  test('a no-op patch persists nothing', () => {
+    const prev = { theme: 'paper', soundAlerts: true };
+    expect(diffSettings(prev, { ...prev }, { theme: 'paper' })).toEqual({});
+  });
+
+  test('an updater function persists every key whose value it moved', () => {
+    const prev = { keybindingSend: 'Enter', keybindingNewLine: 'Shift + Enter' };
+    const next = { keybindingSend: 'Ctrl / Cmd + Enter', keybindingNewLine: 'Enter' };
+    expect(diffSettings(prev, next, (state) => ({ ...state, ...next }))).toEqual(next);
+  });
+
+  test('an unrelated update never republishes the theme it read', () => {
+    // The regression this exists for: a tab that booted on `paper` toggling an
+    // unrelated switch in a settings modal whose snapshot predates an external
+    // theme change must not write `theme` back.
+    const prev = { theme: 'paper', chatCompletionSound: true };
+    const patch = { chatCompletionSound: false };
+    expect(diffSettings(prev, { ...prev, ...patch }, patch)).toEqual({ chatCompletionSound: false });
+  });
+});

package/src/shared/lib/settings/diff.ts

@@ -0,0 +1,37 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The subset of a settings update that should be persisted.
+ *
+ * The settings modal keeps a full `SettingsState` snapshot from the moment it
+ * opened and hands every edit to one writer. Writing the whole object back
+ * republishes values the user never touched, from a snapshot that may be older
+ * than what another writer (a second tab, an API call) has since stored — the
+ * stale copy wins purely because it was written last.
+ *
+ * A key is persisted only when the update changed it:
+ *
+ * - **Object patch** — the keys it names, but only those whose value actually
+ *   differs, so a no-op re-render does not touch the row.
+ * - **Updater function** — every key whose value differs between `prev` and
+ *   `next`; the function's own intent is not inspectable, so the diff is.
+ *
+ * Values are compared by identity, which is what `SettingsState` holds: strings,
+ * numbers and booleans. A nested object would compare by reference and be
+ * reported as changed — acceptable here, and better than dropping a real edit.
+ */
+export function diffSettings<T extends Record<string, any>>(
+  prev: T,
+  next: T,
+  update: Partial<T> | ((prev: T) => T),
+): Partial<T> {
+  const patch: Partial<T> = {};
+  const keys = typeof update === 'function' ? (Object.keys(next) as (keyof T)[]) : (Object.keys(update) as (keyof T)[]);
+  for (const key of keys) {
+    if (next[key] !== prev[key]) patch[key] = next[key];
+  }
+  return patch;
+}

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');
+  });
+});