@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/shared/lib/code/editor/themes.test.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor theme catalogue, and the one property that makes it trustworthy:
+ * every colour it ships is the INSTALLED package's own.
+ *
+ * The grid draws 65 cards without fetching a theme module, so its colours are
+ * data. Data generated from a dependency drifts the moment the dependency
+ * updates — silently, because the picker still renders, just with a palette the
+ * highlighter no longer has. These cases re-derive each row from
+ * `@shikijs/themes` itself, which is the only check that can fail on a version
+ * bump rather than on a typo.
+ *
+ * The remaining cases pin the two rules the surfaces depend on: `auto` resolves
+ * to no theme (so nothing changes for an install that never opens the picker),
+ * and an explicit theme names ITSELF in both Shiki slots — which is what makes
+ * the editor ignore the app's light/dark variant without a second CSS path.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import {
+  EDITOR_AUTO_THEME_ID,
+  EDITOR_DEFAULT_THEME_ID,
+  EDITOR_THEMES,
+  EDITOR_THEME_LOADERS,
+  editorShikiThemes,
+  editorThemeVars,
+  isEditorThemeId,
+  resolveEditorTheme,
+} from '@/shared/lib/code/editor/themes';
+import { SHIKI_THEMES } from '@/shared/lib/code/shiki-themes';
+
+/** The installed package's `dist`, resolved through the package itself so a
+ *  hoisted or linked install resolves the same way the app's own imports do. */
+const THEMES_DIR = join(dirname(Bun.resolveSync('@shikijs/themes/package.json', import.meta.dir)), 'dist');
+
+/** The ids the installed package actually ships, in the generator's order. */
+function installedIds(): string[] {
+  return readdirSync(THEMES_DIR)
+    .filter((file) => file.endsWith('.mjs') && file !== 'index.mjs')
+    .map((file) => file.slice(0, -'.mjs'.length))
+    .sort();
+}
+
+describe('catalogue', () => {
+  test('one row per theme the installed package ships, in id order', () => {
+    expect(EDITOR_THEMES.map((theme) => theme.id)).toEqual(installedIds());
+  });
+
+  test('every row has a loader, and every loader has a row', () => {
+    expect(Object.keys(EDITOR_THEME_LOADERS).sort()).toEqual(EDITOR_THEMES.map((theme) => theme.id));
+  });
+
+  test('a label is never empty and never the raw id with dashes', () => {
+    for (const theme of EDITOR_THEMES) {
+      expect(theme.label.length).toBeGreaterThan(0);
+      expect(theme.variant === 'light' || theme.variant === 'dark').toBe(true);
+    }
+  });
+});
+
+describe('generated colours', () => {
+  test('the surface and the ink are the theme’s own', async () => {
+    for (const theme of EDITOR_THEMES) {
+      // Dynamic on purpose: the specifier is the row's own id, read at runtime
+      // from a 65-entry catalogue — a static import cannot name it.
+      const module = (await import(`@shikijs/themes/${theme.id}`)).default as {
+        colors?: Record<string, string>;
+      };
+      const colors = module.colors ?? {};
+      expect(theme.bg).toBe(colors['editor.background'] as string);
+      // Five themes ship no `editor.foreground`; the generator falls back to the
+      // theme's own `foreground`, which is still ITS colour and not a borrow.
+      const own =
+        colors['editor.foreground'] ?? colors['foreground'] ?? colors['terminal.foreground'] ?? theme.fg;
+      expect(theme.fg).toBe(own);
+    }
+  });
+
+  test('a chrome colour the theme omits is a mix of its own ink and surface', () => {
+    for (const theme of EDITOR_THEMES) {
+      for (const value of [theme.gutterFg, theme.selection, theme.find, theme.border]) {
+        expect(value.length).toBeGreaterThan(0);
+        // Either the theme's own hex, or a `color-mix` over its own two colours
+        // — never a bare colour borrowed from another theme.
+        const isOwnHex = /^#[0-9a-f]{3,8}$/i.test(value);
+        const isOwnMix = value.startsWith('color-mix(') && value.includes(theme.bg);
+        expect(isOwnHex || isOwnMix).toBe(true);
+      }
+    }
+  });
+
+  test('the three accents differ enough to tell two themes apart', () => {
+    for (const theme of EDITOR_THEMES) {
+      expect(theme.keyword).toMatch(/^#[0-9a-f]{3,8}$/i);
+      expect(theme.string).toMatch(/^#[0-9a-f]{3,8}$/i);
+      expect(theme.comment).toMatch(/^#[0-9a-f]{3,8}$/i);
+    }
+  });
+});
+
+describe('resolution', () => {
+  test('auto is the default and resolves to no theme', () => {
+    expect(EDITOR_DEFAULT_THEME_ID).toBe(EDITOR_AUTO_THEME_ID);
+    expect(resolveEditorTheme(EDITOR_AUTO_THEME_ID)).toBeNull();
+    expect(resolveEditorTheme(undefined)).toBeNull();
+    expect(resolveEditorTheme(null)).toBeNull();
+  });
+
+  test('an id this build does not ship falls back to auto rather than half a theme', () => {
+    expect(resolveEditorTheme('no-such-theme')).toBeNull();
+    expect(isEditorThemeId('no-such-theme')).toBe(false);
+  });
+
+  test('a shipped id resolves to its own row', () => {
+    const dracula = resolveEditorTheme('dracula');
+    expect(dracula?.id).toBe('dracula');
+    expect(isEditorThemeId('dracula')).toBe(true);
+  });
+});
+
+describe('shiki themes', () => {
+  test('auto keeps the app’s dual pair, so an app theme flip repaints', () => {
+    expect(editorShikiThemes(null)).toEqual(SHIKI_THEMES);
+    expect(editorShikiThemes(EDITOR_AUTO_THEME_ID)).toEqual(SHIKI_THEMES);
+  });
+
+  test('an explicit theme names itself in BOTH slots', () => {
+    // Both slots carrying one theme is what makes the app's variant attribute
+    // harmless: `--shiki-light` and `--shiki-dark` hold the same value, so
+    // either selector paints the chosen theme.
+    expect(editorShikiThemes('dracula')).toEqual({ light: 'dracula', dark: 'dracula' });
+  });
+
+  test('an unknown id keeps the app pair', () => {
+    expect(editorShikiThemes('no-such-theme')).toEqual(SHIKI_THEMES);
+  });
+});
+
+describe('css variables', () => {
+  test('auto writes nothing, so every declaration keeps its palette fallback', () => {
+    expect(editorThemeVars(null)).toEqual({});
+  });
+
+  test('an explicit theme writes the surface, the gutter and the diff bands', () => {
+    const theme = resolveEditorTheme('nord');
+    expect(theme).not.toBeNull();
+    const vars = editorThemeVars(theme);
+    expect(vars['--editor-bg']).toBe(theme!.bg);
+    expect(vars['--editor-fg']).toBe(theme!.fg);
+    expect(vars['--editor-gutter-fg']).toBe(theme!.gutterFg);
+    expect(vars['--editor-selection']).toBe(theme!.selection);
+    expect(vars['--editor-find-current']).toBe(theme!.findCurrent);
+    expect(vars['--editor-added']).toBe(theme!.added);
+    expect(vars['--editor-removed-gutter']).toBe(theme!.removedGutter);
+    // Every key is a custom property, never a plain one.
+    for (const key of Object.keys(vars)) expect(key.startsWith('--editor-')).toBe(true);
+  });
+});

package/src/shared/lib/code/editor/themes.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The EDITOR's colour themes, independent of the app palette.
+ *
+ * CodeMirror can wear any of the 65 TextMate themes `@shikijs/themes` ships, and
+ * a reader who works in Dracula or Nord wants the code surface to say so while
+ * the console around it stays in the app's own palette. That separation is the
+ * whole feature: `SettingsState.editorTheme` is a second axis beside `theme`,
+ * and the editor paints its own surface, gutter, selection and tokens from it.
+ *
+ * Three rules keep it honest:
+ *
+ * - **`auto` is the default and means "the app's own palette".** Nothing changes
+ *   for an install that never opens the picker: the surface stays transparent
+ *   over the panel, the chrome reads `--theme-*`, and the tokenizer keeps the
+ *   dual `one-light`/`one-dark-pro` pair the app variant selects.
+ * - **The data is generated, never typed.** `themes.generated.ts` is written by
+ *   `scripts/editor-themes.mjs` from the installed package, so the picker's
+ *   swatches are the theme's OWN colours and a `@shikijs/themes` bump cannot
+ *   leave the grid showing a palette that no longer exists.
+ * - **A theme module is only fetched when it is selected.** The rows carry
+ *   enough colour to draw the grid; `EDITOR_THEME_LOADERS` is what the
+ *   highlighter calls, and 65 modules nobody picks are never downloaded.
+ *
+ * The picker's swatch shows the editor surface, the ink and three syntax
+ * accents — the five colours that actually tell two themes apart at 120px.
+ */
+
+import { EDITOR_THEME_LOADERS, EDITOR_THEME_ROWS } from '@/shared/lib/code/editor/themes.generated';
+import { SHIKI_THEMES } from '@/shared/lib/code/shiki-themes';
+
+/** The setting value meaning "follow the app palette". */
+export const EDITOR_AUTO_THEME_ID = 'auto';
+
+/** What a settings row that predates this option holds. */
+export const EDITOR_DEFAULT_THEME_ID = EDITOR_AUTO_THEME_ID;
+
+export type EditorThemeVariant = 'light' | 'dark';
+
+export interface EditorTheme {
+  /** Shiki's theme id, which is also the stored setting value. */
+  id: string;
+  label: string;
+  /** The theme's OWN light/dark verdict — never the app's. */
+  variant: EditorThemeVariant;
+  /** The editor surface and its ink. */
+  bg: string;
+  fg: string;
+  /** Line-number band. */
+  gutterFg: string;
+  /** Selection band, caret, and the two find-match bands. */
+  selection: string;
+  cursor: string;
+  find: string;
+  findCurrent: string;
+  /** Divider between the gutter and the text. */
+  border: string;
+  /** The two diff bands and their gutter markers. */
+  added: string;
+  removed: string;
+  addedGutter: string;
+  removedGutter: string;
+  /** Three syntax accents, for the picker's swatch only. */
+  keyword: string;
+  string: string;
+  comment: string;
+}
+
+/**
+ * The tuple's field order, stated once so the generated rows and this mapping
+ * cannot drift: a column added to the generator without a field here is a type
+ * error rather than a silently shifted colour.
+ */
+type EditorThemeRow = (typeof EDITOR_THEME_ROWS)[number];
+
+const FIELD_ORDER = [
+  'id',
+  'label',
+  'variant',
+  'bg',
+  'fg',
+  'gutterFg',
+  'selection',
+  'cursor',
+  'find',
+  'findCurrent',
+  'border',
+  'added',
+  'removed',
+  'addedGutter',
+  'removedGutter',
+  'keyword',
+  'string',
+  'comment',
+] as const satisfies ReadonlyArray<keyof EditorTheme>;
+
+function toTheme(row: EditorThemeRow): EditorTheme {
+  const theme = {} as EditorTheme;
+  FIELD_ORDER.forEach((field, index) => {
+    // The tuple and the field list are asserted equal by the types, so this
+    // cast is the only place the two meet.
+    (theme as unknown as Record<string, string>)[field] = row[index];
+  });
+  return theme;
+}
+
+/** Every theme the installed Shiki ships, in id order (the generator's order). */
+export const EDITOR_THEMES: readonly EditorTheme[] = EDITOR_THEME_ROWS.map(toTheme);
+
+const BY_ID = new Map(EDITOR_THEMES.map((theme) => [theme.id, theme]));
+
+/**
+ * The theme a stored setting names, or `null` for `auto` — and for an id this
+ * build no longer ships (a downgrade, a hand-edited row), which must render the
+ * app palette rather than a half-applied theme.
+ */
+export function resolveEditorTheme(id: string | null | undefined): EditorTheme | null {
+  if (!id || id === EDITOR_AUTO_THEME_ID) return null;
+  return BY_ID.get(id) ?? null;
+}
+
+/** True when `id` is a theme this build can paint. */
+export function isEditorThemeId(id: string): boolean {
+  return BY_ID.has(id);
+}
+
+/**
+ * The two theme names Shiki tokenizes with.
+ *
+ * `auto` keeps the app's dual pair, so the variant attribute picks the palette
+ * exactly as it does for every other surface. An explicit theme names ITSELF
+ * for both slots — one theme, both custom properties, identical values — which
+ * is what makes the editor ignore the app variant without a second CSS path.
+ */
+export function editorShikiThemes(id: string | null | undefined): { light: string; dark: string } {
+  const theme = resolveEditorTheme(id);
+  if (!theme) return SHIKI_THEMES;
+  return { light: theme.id, dark: theme.id };
+}
+
+/** The CSS custom properties an explicit theme writes, keyed by variable name. */
+export function editorThemeVars(theme: EditorTheme | null): Record<string, string> {
+  if (!theme) return {};
+  return {
+    '--editor-bg': theme.bg,
+    '--editor-fg': theme.fg,
+    '--editor-gutter-fg': theme.gutterFg,
+    '--editor-selection': theme.selection,
+    '--editor-cursor': theme.cursor,
+    '--editor-find': theme.find,
+    '--editor-find-current': theme.findCurrent,
+    '--editor-border': theme.border,
+    '--editor-added': theme.added,
+    '--editor-removed': theme.removed,
+    '--editor-added-gutter': theme.addedGutter,
+    '--editor-removed-gutter': theme.removedGutter,
+  };
+}
+
+/** The lazy module loaders, so the highlighter can fetch one theme on demand. */
+export { EDITOR_THEME_LOADERS };

package/src/shared/lib/code/highlight-memo.test.ts

@@ -0,0 +1,103 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The block memo in front of the tokenizer.
+ *
+ * Three properties matter and each was a decision:
+ *
+ * 1. **A repeat of the same `(language, code)` returns the same markup** — that
+ *    is the whole point (a card closed and reopened re-tokenized a 1000-line
+ *    read, measured as the dominant cost of its expand).
+ * 2. **A block whose grammar is not ready is NOT cached.** `highlightCode`
+ *    answers escaped text in that state, and caching it would pin the plain
+ *    fallback for the life of the entry.
+ * 3. **A find-in-progress bypasses the memo**, because its markup depends on the
+ *    match ranges rather than on the code alone.
+ */
+
+import { beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+
+import { bootSyntax, onLanguageReady, requestLanguage } from '@/shared/lib/code/highlighter';
+import {
+  clearHighlightMemo,
+  highlightBlock,
+  highlightBlockLines,
+  highlightMemoSize,
+} from '@/shared/lib/code/highlight-memo';
+
+const TOKEN = '--shiki-light:';
+
+beforeAll(async () => {
+  Object.assign(globalThis, { window: globalThis });
+  await bootSyntax();
+  Reflect.deleteProperty(globalThis, 'window');
+  const { promise, resolve } = Promise.withResolvers<void>();
+  const settle = () => {
+    if (requestLanguage('json') && requestLanguage('typescript')) {
+      off();
+      resolve();
+    }
+  };
+  const off = onLanguageReady(settle);
+  settle();
+  await promise;
+});
+
+beforeEach(() => clearHighlightMemo());
+
+describe('highlightBlock', () => {
+  test('a repeated block returns the same markup and is held once', () => {
+    const code = 'const value = 1;\n';
+    const first = highlightBlock(code, 'typescript');
+    const second = highlightBlock(code, 'typescript');
+
+    expect(first).toBe(second);
+    expect(first).toContain(TOKEN);
+    expect(highlightMemoSize()).toBe(1);
+  });
+
+  test('the same code in another language is a different entry', () => {
+    highlightBlock('{"a":1}', 'json');
+    highlightBlock('{"a":1}', 'typescript');
+    expect(highlightMemoSize()).toBe(2);
+  });
+
+  test('a grammar that is not ready is never cached', () => {
+    const html = highlightBlock('const a = 1;', 'not-a-real-grammar');
+    // It still renders something — escaped text, via the javascript fallback —
+    // but caching that would freeze the fallback for good.
+    expect(html).toContain('const');
+    expect(highlightMemoSize()).toBe(0);
+  });
+
+  test('a find-in-progress bypasses the memo', () => {
+    highlightBlock('const a = 1;', 'typescript', { marks: [{ start: 0, end: 5 }] });
+    expect(highlightMemoSize()).toBe(0);
+  });
+
+  test('empty input is not an entry', () => {
+    expect(highlightBlock('', 'typescript')).toBe('');
+    expect(highlightMemoSize()).toBe(0);
+  });
+
+  test('the per-language bound holds', () => {
+    for (let index = 0; index < 30; index += 1) {
+      highlightBlock(`const value${index} = ${index};`, 'typescript');
+    }
+    expect(highlightMemoSize()).toBeLessThanOrEqual(24);
+  });
+});
+
+describe('highlightBlockLines', () => {
+  test('lines are cached and round-trip through the same key', () => {
+    const lines = highlightBlockLines('const a = 1;\nconst b = 2;', 'typescript');
+    expect(lines).toHaveLength(2);
+    expect(highlightMemoSize()).toBe(1);
+
+    const again = highlightBlockLines('const a = 1;\nconst b = 2;', 'typescript');
+    expect(again).toEqual(lines);
+  });
+});

package/src/shared/lib/code/highlight-memo.ts

@@ -0,0 +1,149 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A bounded memo in front of the syntax highlighter, for BLOCK highlights — the
+ * code a tool card draws when it opens.
+ *
+ * Shiki tokenization is the expensive half of rendering a tool card: profiled on
+ * a throttled phone, a `read` expand spent 75% of its long task in
+ * `findNextMatchSync`/the grammar engine, and the same card re-expanded in 33 ms
+ * once its grammar was warm. Two consequences follow, and this module is the
+ * second half of both (the first is `idle.ts`, which moves the work off the tap):
+ *
+ * 1. A card that is closed and reopened is the same code and the same language,
+ *    so its markup is the same string. Tokenizing it again is pure waste, and a
+ *    reader paging through a transcript does exactly that repeatedly.
+ * 2. `Edit` asked for three highlights per render (old, new, preview) when at
+ *    most one of them is ever drawn. Caching per `(language, code)` makes the
+ *    duplicates free even before the call sites are gated.
+ *
+ * The key is a two-level map — language, then the code string itself — rather
+ * than one composite string, because the composite would COPY the whole file on
+ * every lookup, which is exactly the per-frame allocation this exists to remove.
+ * Insertion order is the LRU order.
+ *
+ * Nothing is cached while the language's grammar has not landed: `highlightCode`
+ * answers escaped text in that state, and caching it would pin the plain
+ * fallback for the life of the entry (the trap `highlight-cache.ts` documents
+ * for search rows). `useSyntaxReady` re-runs the caller when a grammar arrives,
+ * which is when the entry finally becomes cacheable.
+ */
+
+import { isLanguageReady } from '@/shared/lib/code/highlighter-lazy';
+import { highlightCode, highlightLines, type HighlightLinesOptions } from '@/shared/lib/code/syntax-highlight';
+
+/** Per language: a transcript page's worth of distinct blocks. */
+const MAX_BLOCKS_PER_LANGUAGE = 24;
+/** Across every language, so a long session cannot grow without bound. */
+const MAX_CACHED_CHARS = 512 * 1024;
+
+const blocks = new Map<string, Map<string, string>>();
+let cachedChars = 0;
+
+function bucket(language: string): Map<string, string> {
+  const existing = blocks.get(language);
+  if (existing) return existing;
+  const created = new Map<string, string>();
+  blocks.set(language, created);
+  return created;
+}
+
+/** Drop the oldest entry of the first language that has one. */
+function evictOne(): boolean {
+  for (const entries of blocks.values()) {
+    const oldest = entries.keys().next();
+    if (oldest.done) continue;
+    const value = entries.get(oldest.value) ?? '';
+    entries.delete(oldest.value);
+    cachedChars -= value.length;
+    return true;
+  }
+  return false;
+}
+
+function remember(language: string, code: string, html: string): void {
+  const entries = bucket(language);
+  const previous = entries.get(code);
+  if (previous !== undefined) {
+    entries.delete(code);
+    cachedChars -= previous.length;
+  }
+  entries.set(code, html);
+  cachedChars += html.length;
+  while (entries.size > MAX_BLOCKS_PER_LANGUAGE) {
+    const oldest = entries.keys().next();
+    if (oldest.done) break;
+    const value = entries.get(oldest.value) ?? '';
+    entries.delete(oldest.value);
+    cachedChars -= value.length;
+  }
+  while (cachedChars > MAX_CACHED_CHARS && evictOne()) {
+    // Keep dropping until the budget holds or nothing is left to drop.
+  }
+}
+
+/** The cached markup for `(language, code)`, or `undefined`. */
+export function cachedHighlightBlock(code: string, language: string): string | undefined {
+  const entries = blocks.get(language);
+  if (!entries) return undefined;
+  const hit = entries.get(code);
+  if (hit === undefined) return undefined;
+  // Reading is a use: move it to the most-recently-used end.
+  entries.delete(code);
+  entries.set(code, hit);
+  return hit;
+}
+
+/** The cached per-line markup, or `undefined`. */
+export function cachedHighlightBlockLines(code: string, language: string): string[] | undefined {
+  const hit = cachedHighlightBlock(code, language);
+  return hit === undefined ? undefined : hit.split('\n');
+}
+
+function cacheable(language: string, options: HighlightLinesOptions): boolean {
+  // A find-in-progress needs the match markup, which only the line path emits —
+  // and which changes per query, so those results are never shared.
+  if (options.marks && options.marks.length > 0) return false;
+  return isLanguageReady(language);
+}
+
+/** `highlightCode` for one block, memoized per `(language, code)`. */
+export function highlightBlock(code: string, language: string, options: HighlightLinesOptions = {}): string {
+  if (!code) return '';
+  const cached = options.marks?.length ? undefined : cachedHighlightBlock(code, language);
+  if (cached !== undefined) return cached;
+  const html = highlightCode(code, language, options);
+  if (cacheable(language, options)) remember(language, code, html);
+  return html;
+}
+
+/** `highlightLines` for one block, memoized per `(language, code)`. */
+export function highlightBlockLines(
+  code: string,
+  language: string,
+  options: HighlightLinesOptions = {},
+): string[] {
+  if (!code) return [''];
+  const cached = options.marks?.length ? undefined : cachedHighlightBlockLines(code, language);
+  if (cached !== undefined) return cached;
+  const lines = highlightLines(code, language, options);
+  if (cacheable(language, options)) remember(language, code, lines.join('\n'));
+  return lines;
+}
+
+/** Drop every entry. For tests and for a highlighter restart (grammar reload). */
+export function clearHighlightMemo(): void {
+  blocks.clear();
+  cachedChars = 0;
+}
+
+/** How many blocks are held — a hit and a recompute return equal strings, so
+ *  the map is the only observable. */
+export function highlightMemoSize(): number {
+  let total = 0;
+  for (const entries of blocks.values()) total += entries.size;
+  return total;
+}