@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/client/hooks/code/deferred-highlight.test.ts

@@ -0,0 +1,182 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The deferred-highlight hook, and the idle scheduler under it.
+ *
+ * The property that matters is the one the user feels: the FIRST render after a
+ * tap must not run the tokenizer. A card that appeared only after 220–300 ms of
+ * grammar work (measured at 4× CPU; 730–1484 ms at 20×) is the delay this
+ * exists to remove, and a hook that highlighted synchronously "sometimes" would
+ * pass a markup assertion and fail the point.
+ *
+ * So the scheduler is injectable here — the same seam the warm-up and the
+ * grammar loader use — and the assertions are about WHEN the compute ran, not
+ * only about what it produced. No wall-clock waits: the fallback path is driven
+ * by fake timers.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test, vi } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+
+import { useDeferredHighlight } from '@/client/hooks/code/deferred-highlight';
+import { scheduleIdle } from '@/shared/lib/code/idle';
+import { clearHighlightMemo, highlightMemoSize } from '@/shared/lib/code/highlight-memo';
+import { resetTokenizerWarmup, warmSyntaxTokenizers } from '@/shared/lib/code/highlighter-warmup';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event', 'MouseEvent'] as const;
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+let container: HTMLElement;
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    nativeGlobals[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (nativeGlobals[key] === undefined) delete target[key];
+    else target[key] = nativeGlobals[key];
+  }
+});
+
+afterEach(() => {
+  clearHighlightMemo();
+  resetTokenizerWarmup();
+});
+
+describe('scheduleIdle', () => {
+  test('a runtime without requestIdleCallback still runs the work', () => {
+    const host = globalThis as unknown as Record<string, unknown>;
+    const saved = host.requestIdleCallback;
+    delete host.requestIdleCallback;
+    vi.useFakeTimers();
+    try {
+      let runs = 0;
+      scheduleIdle(() => { runs += 1; });
+      vi.advanceTimersByTime(1);
+      expect(runs).toBe(1);
+    } finally {
+      vi.useRealTimers();
+      if (saved !== undefined) host.requestIdleCallback = saved;
+    }
+  });
+
+  test('cancelling before the slice fires skips the work', () => {
+    const host = globalThis as unknown as Record<string, unknown>;
+    const saved = host.requestIdleCallback;
+    delete host.requestIdleCallback;
+    vi.useFakeTimers();
+    try {
+      let runs = 0;
+      const cancel = scheduleIdle(() => { runs += 1; });
+      cancel();
+      vi.advanceTimersByTime(1);
+      expect(runs).toBe(0);
+    } finally {
+      vi.useRealTimers();
+      if (saved !== undefined) host.requestIdleCallback = saved;
+    }
+  });
+});
+
+describe('warmSyntaxTokenizers', () => {
+  test('tokenizes one sample per language, one slice at a time', () => {
+    const calls: Array<{ language: string; code: string }> = [];
+    const queue: Array<() => void> = [];
+    warmSyntaxTokenizers({
+      languages: ['typescript', 'bash'],
+      ready: () => true,
+      highlight: (code, language) => calls.push({ language, code }),
+      schedule: (run) => {
+        queue.push(run);
+        return () => {};
+      },
+    });
+
+    // One slice is armed, not the whole set: a slow grammar must not become the
+    // long task this exists to prevent.
+    expect(queue).toHaveLength(1);
+    act(() => queue.shift()!());
+    expect(calls.map((c) => c.language)).toEqual(['typescript']);
+    expect(queue).toHaveLength(1);
+    act(() => queue.shift()!());
+    expect(calls.map((c) => c.language)).toEqual(['typescript', 'bash']);
+  });
+
+  test('is a no-op the second time, so a re-evaluated entry cannot re-warm', () => {
+    let calls = 0;
+    const options = {
+      languages: ['typescript'],
+      ready: () => true,
+      highlight: () => { calls += 1; },
+      schedule: (run: () => void) => { run(); return () => {}; },
+    };
+    warmSyntaxTokenizers(options);
+    warmSyntaxTokenizers(options);
+    expect(calls).toBe(1);
+  });
+
+  test('a grammar that has not landed is retried rather than skipped', () => {
+    const calls: string[] = [];
+    let ready = false;
+    const queue: Array<() => void> = [];
+    warmSyntaxTokenizers({
+      languages: ['typescript'],
+      ready: () => ready,
+      highlight: (_code, language) => calls.push(language),
+      schedule: (run) => {
+        queue.push(run);
+        return () => {};
+      },
+    });
+
+    act(() => queue.shift()!());
+    expect(calls).toEqual([]);
+    ready = true;
+    act(() => queue.shift()!());
+    expect(calls).toEqual(['typescript']);
+  });
+});
+
+describe('the deferred render', () => {
+  test('draws the escaped source without tokenizing on the mounting tick', async () => {
+    let renders = 0;
+    function Card({ code }: { code: string }) {
+      const html = useDeferredHighlight(code, 'typescript');
+      renders += 1;
+      return h('pre', { dangerouslySetInnerHTML: { __html: html } });
+    }
+
+    await act(async () => {
+      render(h(Card, { code: 'const value = 1;' }), container);
+    });
+
+    // Nothing has been tokenized on this tick — the tap's own task is clean.
+    expect(highlightMemoSize()).toBe(0);
+    expect(renders).toBeGreaterThan(0);
+    // What it DID draw is the escaped source, not an empty box.
+    expect(container.textContent).toContain('const value = 1;');
+  });
+
+  test('empty input renders nothing and caches nothing', async () => {
+    function Card() {
+      return h('pre', { dangerouslySetInnerHTML: { __html: useDeferredHighlight('', 'typescript') } });
+    }
+    await act(async () => {
+      render(h(Card, {}), container);
+    });
+    expect(highlightMemoSize()).toBe(0);
+  });
+});

package/src/client/hooks/code/deferred-highlight.ts

@@ -0,0 +1,129 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Syntax-highlighted markup that never blocks the interaction that asked for it.
+ *
+ * A tool card renders its code the moment it is expanded, and the tokenizer used
+ * to run inside that render: measured on a throttled phone (4× CPU), a `read`
+ * card's expand was a 220–300 ms long task of which ~75% was the Shiki grammar
+ * engine, and at 20× the same card blocked for 730–1.484 ms. The card was on
+ * screen the whole time — it just could not paint until the last line had been
+ * tokenized.
+ *
+ * So the first render draws the text, escaped and correct, and the tokenized
+ * markup replaces it once the main thread is free (`scheduleIdle`). The two
+ * carry the same characters, so the swap costs colour and no layout.
+ *
+ * Three properties make that honest:
+ *
+ * - **A cached block renders highlighted on the FIRST paint.** `highlight-memo`
+ *   is checked during render, so reopening a card the reader already opened —
+ *   the common case while paging a transcript — has no plain-text frame at all.
+ * - **A stale block is never shown.** The value is tagged with the input it was
+ *   computed from; a filter keystroke in the search panel therefore shows the
+ *   new text, never the previous query's markup.
+ * - **Nothing is computed for empty input.** Call sites that gate a branch pass
+ *   `''`, which is how `Edit` stops tokenizing the two panels it is not drawing.
+ */
+
+import { useEffect, useMemo, useState } from 'preact/hooks';
+import { escapeCode } from '@/shared/lib/code/highlighter';
+import {
+  cachedHighlightBlock,
+  cachedHighlightBlockLines,
+  highlightBlock,
+  highlightBlockLines,
+} from '@/shared/lib/code/highlight-memo';
+import { scheduleIdle } from '@/shared/lib/code/idle';
+import { useSyntaxReady } from '@/client/hooks/ui/syntax-ready';
+
+interface Deferred<T> {
+  /** Identity of the input; a value computed for another input is not shown. */
+  key: object;
+  hasContent: boolean;
+  cached: T | undefined;
+  plain: T;
+  compute: () => T;
+}
+
+function useDeferred<T>(spec: Deferred<T>): T {
+  // A grammar arriving is what turns a plain fallback into a real highlight, so
+  // the effect re-runs on it even though the input did not move.
+  const syntaxReady = useSyntaxReady();
+  const [state, setState] = useState<{ key: object; value: T }>(() => ({
+    key: spec.key,
+    value: spec.cached ?? spec.plain,
+  }));
+
+  /** Adopt a value only when it is a change, so a cached block does not cost an
+   *  extra render on every mount. */
+  const adopt = (key: object, value: T): void => {
+    setState((previous) => (previous.key === key && previous.value === value ? previous : { key, value }));
+  };
+
+  useEffect(() => {
+    if (!spec.hasContent) {
+      adopt(spec.key, spec.plain);
+      return;
+    }
+    if (spec.cached !== undefined) {
+      adopt(spec.key, spec.cached);
+      return;
+    }
+    let cancelled = false;
+    const cancel = scheduleIdle(() => {
+      if (cancelled) return;
+      let value: T;
+      try {
+        value = spec.compute();
+      } catch {
+        // A grammar that cannot tokenize this input leaves the escaped text,
+        // which is what the first paint already drew.
+        value = spec.plain;
+      }
+      if (!cancelled) adopt(spec.key, value);
+    });
+    return () => {
+      cancelled = true;
+      cancel();
+    };
+    // `spec` is rebuilt every render; its KEY (the input) and the grammar's
+    // readiness are what decide the work.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [spec.key, syntaxReady]);
+
+  if (state.key === spec.key) return state.value;
+  return spec.cached ?? spec.plain;
+}
+
+/** Tokenized markup for one block, deferred off the render that asked for it. */
+export function useDeferredHighlight(code: string, language: string): string {
+  const key = useMemo(() => ({ code, language }), [code, language]);
+  const plain = useMemo(() => escapeCode(code), [code]);
+  return useDeferred<string>({
+    key,
+    hasContent: Boolean(code),
+    cached: code ? cachedHighlightBlock(code, language) : undefined,
+    plain,
+    compute: () => highlightBlock(code, language),
+  });
+}
+
+/** Tokenized markup per line, deferred the same way. */
+export function useDeferredHighlightLines(code: string, language: string): string[] {
+  const key = useMemo(() => ({ code, language }), [code, language]);
+  const plain = useMemo(
+    () => (code ? code.split('\n').map(escapeCode) : []),
+    [code],
+  );
+  return useDeferred<string[]>({
+    key,
+    hasContent: Boolean(code),
+    cached: code ? cachedHighlightBlockLines(code, language) : undefined,
+    plain,
+    compute: () => highlightBlockLines(code, language),
+  });
+}

package/src/client/hooks/editor/find-state.ts

@@ -14,7 +14,7 @@
  */
 
 import type { EditorCommand } from '@/shared/lib/code/editor/keymap';
-import type { FindOptions } from '@/shared/lib/code/editor/find';
+import type { FindOptions } from '@/shared/lib/code/editor/find-scan';
 
 export interface UseEditorFindOptions {
   /** The buffer on screen. */

package/src/client/hooks/editor/theme.test.ts

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor-theme setting, and the two rules that make it safe to offer.
+ *
+ * A theme is a MODULE that is fetched on selection, so there are two failure
+ * modes a unit test can pin without a browser:
+ *
+ * 1. **The module has to be registered before Shiki can tokenize with it.**
+ *    `loadTheme` is idempotent, and a second surface selecting the same theme
+ *    must share the first fetch rather than start a second one.
+ * 2. **`auto` must not register anything**, and an id this build does not ship
+ *    must resolve to no theme rather than leave the editor half-painted.
+ *
+ * Driven through happy-dom because the hook subscribes to a window event — the
+ * same shape the editor FONT uses, and the reason an already-open editor hears
+ * about a change at all (`appSettings` is a boot-time prop).
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+
+import {
+  EDITOR_THEME_CHANGED_EVENT,
+  currentEditorThemeId,
+  useEditorTheme,
+} from '@/client/hooks/editor/theme';
+import {
+  isEditorThemeReady,
+  loadEditorTheme,
+  onEditorThemeReady,
+  resetEditorThemeLoader,
+} from '@/shared/lib/code/editor/theme-loader';
+import { EDITOR_AUTO_THEME_ID, resolveEditorTheme } from '@/shared/lib/code/editor/themes';
+import { bootSyntax, onLanguageReady, requestLanguage } from '@/shared/lib/code/highlighter';
+import { primeKabmoSettings } from '@/shared/lib/settings/client';
+
+const DOM_GLOBALS = [
+  'window', 'document', 'navigator', 'HTMLElement', 'Element', 'Node', 'Event', 'CustomEvent',
+  'getComputedStyle', 'MutationObserver', 'requestAnimationFrame', 'cancelAnimationFrame',
+] as const;
+
+/** The runner's own globals, put back once this file's DOM work is done. */
+const native: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+/** happy-dom's `CustomEvent`, so a dispatch is an instance its EventTarget accepts. */
+let Custom: typeof CustomEvent;
+
+async function bootTokenizer(): Promise<void> {
+  // The highlighter only boots where `window` exists, and the Bun runner has
+  // none. Stub it for the boot alone, then hand the global to happy-dom — a
+  // `window` left pointing at `globalThis` would make the hook's
+  // `dispatchEvent` the runner's, which rejects a happy-dom CustomEvent.
+  const target = globalThis as unknown as Record<string, unknown>;
+  const had = 'window' in target ? target.window : undefined;
+  target.window = globalThis;
+  await bootSyntax();
+  if (had === undefined) delete target.window;
+  else target.window = had;
+  const { promise, resolve } = Promise.withResolvers<void>();
+  const settle = () => {
+    if (requestLanguage('typescript')) {
+      off();
+      resolve();
+    }
+  };
+  const off = onLanguageReady(settle);
+  settle();
+  await promise;
+}
+
+beforeAll(async () => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in native)) native[key] = target[key];
+    const value = (win as unknown as Record<string, unknown>)[key];
+    if (value !== undefined) target[key] = value;
+  }
+  Custom = win.CustomEvent as unknown as typeof CustomEvent;
+  await bootTokenizer();
+  resetEditorThemeLoader();
+});
+
+afterEach(() => {
+  primeKabmoSettings({});
+  document.body.innerHTML = '';
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (native[key] === undefined) delete target[key];
+    else target[key] = native[key];
+  }
+});
+
+/** A probe that renders exactly what the hook says the surface should paint. */
+function ThemeProbe() {
+  const theme = useEditorTheme();
+  return h(
+    'div',
+    { id: 'probe' },
+    `${theme.theme?.id ?? 'auto'}|${theme.vars['--editor-bg'] ?? 'none'}|${theme.themes.light}`,
+  );
+}
+
+async function mountProbe(): Promise<HTMLElement> {
+  const host = document.createElement('div');
+  document.body.appendChild(host);
+  await act(async () => {
+    render(h(ThemeProbe, {}), host);
+  });
+  return host.querySelector('#probe') as HTMLElement;
+}
+
+describe('currentEditorThemeId', () => {
+  test('reads the stored value and falls back to auto', () => {
+    primeKabmoSettings({});
+    expect(currentEditorThemeId()).toBe(EDITOR_AUTO_THEME_ID);
+
+    primeKabmoSettings({ kabmo_settings: { editorTheme: 'nord' } });
+    expect(currentEditorThemeId()).toBe('nord');
+  });
+});
+
+describe('theme module loading', () => {
+  test('auto needs no module, and an unknown id is a no-op', async () => {
+    resetEditorThemeLoader();
+    await loadEditorTheme(EDITOR_AUTO_THEME_ID);
+    expect(isEditorThemeReady(EDITOR_AUTO_THEME_ID)).toBe(true);
+
+    await loadEditorTheme('no-such-theme');
+    expect(isEditorThemeReady('no-such-theme')).toBe(false);
+  });
+
+  test('a shipped theme registers with the highlighter and announces itself', async () => {
+    resetEditorThemeLoader();
+    const seen: string[] = [];
+    const off = onEditorThemeReady((id) => seen.push(id));
+    try {
+      expect(isEditorThemeReady('nord')).toBe(false);
+      await loadEditorTheme('nord');
+      expect(isEditorThemeReady('nord')).toBe(true);
+      expect(seen).toEqual(['nord']);
+    } finally {
+      off();
+    }
+  });
+
+  test('two requests for one theme share a single registration', async () => {
+    resetEditorThemeLoader();
+    let announcements = 0;
+    const off = onEditorThemeReady(() => announcements++);
+    try {
+      await Promise.all([loadEditorTheme('dracula'), loadEditorTheme('dracula')]);
+      expect(announcements).toBe(1);
+      // Already registered: a third call resolves without announcing again.
+      await loadEditorTheme('dracula');
+      expect(announcements).toBe(1);
+    } finally {
+      off();
+    }
+  });
+});
+
+describe('useEditorTheme', () => {
+  test('auto renders no variables and the app’s dual pair', async () => {
+    primeKabmoSettings({});
+    const probe = await mountProbe();
+    expect(probe.textContent).toBe('auto|none|one-light');
+  });
+
+  test('an explicit theme renders its own surface and names itself in both slots', async () => {
+    primeKabmoSettings({ kabmo_settings: { editorTheme: 'dracula' } });
+    const probe = await mountProbe();
+    const theme = resolveEditorTheme('dracula');
+    expect(theme).not.toBeNull();
+    expect(probe.textContent).toBe(`dracula|${theme!.bg}|dracula`);
+  });
+
+  test('a write reaches an ALREADY-MOUNTED editor without a reload', async () => {
+    primeKabmoSettings({});
+    const probe = await mountProbe();
+    expect(probe.textContent).toBe('auto|none|one-light');
+
+    // Exactly what the settings modal dispatches on a change.
+    await act(async () => {
+      window.dispatchEvent(new Custom(EDITOR_THEME_CHANGED_EVENT, { detail: 'nord' }));
+    });
+    const nord = resolveEditorTheme('nord');
+    expect(probe.textContent).toBe(`nord|${nord!.bg}|nord`);
+
+    // And back to auto, which must clear the variables again rather than leave
+    // the previous theme's surface behind.
+    await act(async () => {
+      window.dispatchEvent(new Custom(EDITOR_THEME_CHANGED_EVENT, { detail: EDITOR_AUTO_THEME_ID }));
+    });
+    expect(probe.textContent).toBe('auto|none|one-light');
+  });
+});

package/src/client/hooks/editor/theme.ts

@@ -0,0 +1,82 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Which editor theme is live, and how a change reaches an open editor.
+ *
+ * The setting is visual, so it has to apply to the editor on screen — not on the
+ * next reload. `appSettings` is a prop captured at boot, so reading it once
+ * would leave an already-mounted editor on the previous palette; this follows
+ * the editor FONT's shape (`hooks/editor/font.ts`): the picker writes the
+ * setting and announces it, and every editor subscribes.
+ *
+ * A theme's module is fetched the first time it is SELECTED (`theme-loader.ts`),
+ * so an install that never opens the picker downloads none of them.
+ */
+
+import { useEffect, useState } from 'preact/hooks';
+import { readKabmoSetting } from '@/shared/lib/settings/client';
+import {
+  EDITOR_AUTO_THEME_ID,
+  EDITOR_DEFAULT_THEME_ID,
+  editorShikiThemes,
+  editorThemeVars,
+  resolveEditorTheme,
+  type EditorTheme,
+} from '@/shared/lib/code/editor/themes';
+import { loadEditorTheme } from '@/shared/lib/code/editor/theme-loader';
+
+/** Broadcast on every editor-theme write. Detail is the new theme id. */
+export const EDITOR_THEME_CHANGED_EVENT = 'omp:editor-theme-changed';
+
+/** The theme id currently stored, falling back to `auto`. */
+export function currentEditorThemeId(): string {
+  if (typeof window === 'undefined') return EDITOR_DEFAULT_THEME_ID;
+  return readKabmoSetting<string>('editorTheme') ?? EDITOR_DEFAULT_THEME_ID;
+}
+
+/** Everything a code surface needs to paint with the live editor theme. */
+export interface EditorThemeState {
+  /** The theme itself, or `null` for `auto` (the app palette). */
+  theme: EditorTheme | null;
+  /** CSS custom properties for the surface host; empty for `auto`. */
+  vars: Record<string, string>;
+  /** The two Shiki theme names to tokenize with. */
+  themes: { light: string; dark: string };
+}
+
+const AUTO_STATE: EditorThemeState = { theme: null, vars: {}, themes: editorShikiThemes(null) };
+
+/**
+ * The live editor theme, kept in step with writes.
+ *
+ * One hook rather than three, because a surface needs all three values and
+ * three subscriptions to one event would be three re-render paths that can
+ * disagree for a frame.
+ */
+export function useEditorTheme(): EditorThemeState {
+  const [id, setId] = useState<string>(currentEditorThemeId);
+
+  useEffect(() => {
+    const onChange = (event: Event) => {
+      const detail = (event as CustomEvent<string>).detail;
+      setId(detail || currentEditorThemeId());
+    };
+    window.addEventListener(EDITOR_THEME_CHANGED_EVENT, onChange);
+    return () => window.removeEventListener(EDITOR_THEME_CHANGED_EVENT, onChange);
+  }, []);
+
+  // Fetch the module the first time this theme is live, so the tokenizer can
+  // colour with it. A no-op for `auto` and for an id already registered.
+  useEffect(() => {
+    void loadEditorTheme(id);
+  }, [id]);
+
+  // `auto` is the shipped state, and it allocates nothing new per render.
+  if (id === EDITOR_AUTO_THEME_ID) return AUTO_STATE;
+
+  const theme = resolveEditorTheme(id);
+  return { theme, vars: editorThemeVars(theme), themes: editorShikiThemes(id) };
+}