@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/client/components/common/code-surface/shiki.ts

@@ -0,0 +1,234 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shiki colours for the CodeMirror surface, as a decoration plugin.
+ *
+ * The app has ONE tokenizer. The chat timeline, the diff views, the wiki reader
+ * and the markdown preview all render through `highlightCode`, and the editor
+ * must not disagree with them about what a keyword looks like — which is why
+ * this is Shiki over CM6's viewport rather than a lezer grammar. A lezer build
+ * would cover 48 of the 59 ids `shiki-langs` knows and paint a second palette.
+ *
+ * Two rules make it affordable on a large file:
+ *
+ * - **Only the viewport is tokenized**, plus `CONTEXT_LINES` above it so a
+ *   window that opens inside a block comment or a template literal still
+ *   tokenizes as one. Measured: 2.1 ms per keystroke at 20 000 lines, flat,
+ *   because the window is ~100 lines whatever the document is.
+ * - **A line at or past `MAX_LINE_CHARS` is left plain.** A minified bundle is
+ *   one line of hundreds of KB, and tokenizing it on every scroll is what makes
+ *   an editor feel dead.
+ *
+ * The colours are NOT inline. Every token carries Shiki's two custom properties
+ * (`--shiki-light` / `--shiki-dark`) and `theme.ts` picks one through
+ * `[data-theme-variant]`, so a theme switch repaints with zero re-tokenizing —
+ * the same property every other surface relies on.
+ */
+
+import { RangeSetBuilder, type Extension } from '@codemirror/state';
+import { Decoration, ViewPlugin, type DecorationSet, type EditorView, type ViewUpdate } from '@codemirror/view';
+
+import { getHighlighterSync, onLanguageReady, onSyntaxReady, requestLanguage } from '@/shared/lib/code/highlighter';
+import { loadEditorTheme, onEditorThemeReady } from '@/shared/lib/code/editor/theme-loader';
+import { SHIKI_THEMES } from '@/shared/lib/code/shiki-themes';
+
+/** Lines tokenized above the viewport, to seed the grammar's own state. */
+const CONTEXT_LINES = 40;
+
+/** Lines at or above this length render as plain text (see the module note). */
+const MAX_LINE_CHARS = 12_000;
+
+/** Marks are shared by their style string: a file has a few dozen distinct ones. */
+const markCache = new Map<string, Decoration>();
+
+/** Ceiling on cached marks; a pathological file cannot grow the map forever. */
+const MARK_CACHE_LIMIT = 2_000;
+
+function markFor(style: string): Decoration {
+  const cached = markCache.get(style);
+  if (cached) return cached;
+  const mark = Decoration.mark({ class: 'shiki-tok', attributes: { style } });
+  if (markCache.size >= MARK_CACHE_LIMIT) markCache.clear();
+  markCache.set(style, mark);
+  return mark;
+}
+
+/** `{ '--shiki-light': '#…', '--shiki-dark': '#…' }` as a declaration list. */
+function styleOf(htmlStyle: Record<string, string> | undefined): string | null {
+  if (!htmlStyle) return null;
+  let style = '';
+  for (const key of Object.keys(htmlStyle)) {
+    const value = htmlStyle[key];
+    if (!value) continue;
+    style += `${style ? ';' : ''}${key}:${value}`;
+  }
+  return style || null;
+}
+
+/** The two theme names a surface tokenizes with. */
+export interface ShikiThemeNames {
+  light: string;
+  dark: string;
+}
+
+/** The app's dual pair, used when a caller names none. */
+const APP_THEMES: ShikiThemeNames = SHIKI_THEMES;
+
+/**
+ * Tokenize the viewport and emit one mark per coloured token.
+ *
+ * `RangeSetBuilder` requires ascending ranges, which the line walk gives for
+ * free: tokens arrive in document order because they are read line by line.
+ */
+function buildDecorations(
+  view: EditorView,
+  language: string,
+  themes: ShikiThemeNames,
+): DecorationSet {
+  const highlighter = getHighlighterSync();
+  // Not booted yet, or the grammar is still in flight: plain text for this
+  // pass, and `subscribe` re-runs the moment either lands.
+  if (!highlighter || language === 'text' || !requestLanguage(language)) return Decoration.none;
+
+  const doc = view.state.doc;
+  const firstLine = doc.lineAt(view.viewport.from).number;
+  const lastLine = doc.lineAt(view.viewport.to).number;
+  const contextStart = Math.max(1, firstLine - CONTEXT_LINES);
+
+  const lines: string[] = [];
+  for (let number = contextStart; number <= lastLine; number++) lines.push(doc.line(number).text);
+  const source = lines.join('\n');
+
+  let tokenized: { content: string; htmlStyle?: Record<string, string> }[][];
+  try {
+    tokenized = highlighter.codeToTokens(source, {
+      lang: language,
+      // Shiki's own type is `Partial<Record<string, ThemeRegistrationAny|string>>`;
+      // the pair is a plain string map, which is what it accepts at runtime.
+      themes: themes as unknown as Record<string, string>,
+      defaultColor: false,
+      tokenizeMaxLineLength: MAX_LINE_CHARS,
+    }).tokens as typeof tokenized;
+  } catch {
+    // A grammar the engine refuses (or a Shiki internal): plain text is the
+    // honest fallback, never a crash that takes the editor down.
+    return Decoration.none;
+  }
+
+  const builder = new RangeSetBuilder<Decoration>();
+  for (let index = 0; index < tokenized.length && index < lines.length; index++) {
+    const line = doc.line(contextStart + index);
+    if (line.length >= MAX_LINE_CHARS) continue;
+    let offset = 0;
+    for (const token of tokenized[index]) {
+      const length = token.content.length;
+      const style = styleOf(token.htmlStyle);
+      if (style && length > 0) {
+        const from = line.from + offset;
+        const to = Math.min(line.to, from + length);
+        if (to > from) builder.add(from, to, markFor(style));
+      }
+      offset += length;
+    }
+  }
+  return builder.finish();
+}
+
+/**
+ * Re-run when the highlighter boots, a grammar lands, or the theme's module
+ * arrives.
+ *
+ * The theme is the third case and it is not optional: an explicit editor theme
+ * is a module that is fetched on selection, and `codeToTokens` throws for a
+ * theme Shiki has not been given — which the catch below turns into plain text.
+ * Without this subscription a freshly picked theme would leave the surface
+ * uncoloured until something else forced a rebuild.
+ */
+function subscribe(themes: ShikiThemeNames, onReady: () => void): () => void {
+  const offBoot = onSyntaxReady(onReady);
+  const offLanguage = onLanguageReady(onReady);
+  const wanted = new Set([themes.light, themes.dark]);
+  const offTheme = onEditorThemeReady((id) => {
+    if (wanted.has(id)) onReady();
+  });
+  // A theme the app has never loaded: ask now, and the subscription above
+  // rebuilds once it lands.
+  for (const id of wanted) void loadEditorTheme(id);
+  return () => {
+    offBoot();
+    offLanguage();
+    offTheme();
+  };
+}
+
+/**
+ * The decoration plugin for one language and theme.
+ *
+ * Both are baked in because neither changes under a live state: `documentKey`
+ * carries the language (a `.ts` tab and a `.py` tab are two cached states, and
+ * two states cannot share decorations built from different grammars), and a
+ * theme switch is a CSS repaint — the marks carry both palettes as custom
+ * properties, so the values are identical when one theme names both slots.
+ *
+ * `themes` is optional so a caller that has no editor-theme opinion (a diff
+ * card inside a chat message) keeps the app's dual pair.
+ */
+export function shikiHighlight(language: string, themes: ShikiThemeNames = APP_THEMES): Extension {
+  return ViewPlugin.fromClass(
+    class {
+      decorations: DecorationSet;
+      private readonly view: EditorView;
+      private dirty = false;
+      private destroyed = false;
+      private readonly unsubscribe: () => void;
+
+      constructor(view: EditorView) {
+        this.view = view;
+        this.decorations = buildDecorations(view, language, themes);
+        this.unsubscribe = subscribe(themes, () => this.invalidate());
+      }
+
+      update(update: ViewUpdate): void {
+        // A composition is a document in flux: tokenizing mid-IME paints
+        // decorations over text the browser is still composing, and Chrome
+        // reacts by moving the caret out from under the user. The rebuild lands
+        // on the first update after it ends.
+        if (update.view.composing) {
+          this.dirty = true;
+          return;
+        }
+        if (!update.docChanged && !update.viewportChanged && !this.dirty) return;
+        this.dirty = false;
+        this.decorations = buildDecorations(update.view, language, themes);
+      }
+
+      destroy(): void {
+        this.destroyed = true;
+        this.unsubscribe();
+      }
+
+      /**
+       * A grammar landed: force one rebuild.
+       *
+       * The empty transaction is the only way a plugin can ask for an update it
+       * did not get from a document change — and the `dirty` flag is what makes
+       * the rebuild happen even though neither `docChanged` nor
+       * `viewportChanged` is set. Guarded, because a chunk can land while the
+       * view is being torn down.
+       */
+      private invalidate(): void {
+        if (this.destroyed) return;
+        this.dirty = true;
+        try {
+          this.view.dispatch({});
+        } catch {
+          // The view went away between the check and the dispatch.
+        }
+      }
+    },
+    { decorations: (plugin) => plugin.decorations },
+  );
+}

package/src/client/components/common/code-surface/sync.test.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The external-sync guard, which is the difference between a large file being
+ * usable and not.
+ *
+ * `syncExternal` runs on EVERY render, and the parent re-renders on every
+ * keystroke, so its fast path has to be a reference comparison: the old version
+ * compared against `view.state.doc.toString()` unconditionally, which is 7.2 ms
+ * at 20 MB and 13.7 ms at 30 MB (measured in Bun) — twice per character, since
+ * the write and the read each cost one.
+ *
+ * The cases below pin both halves: the echo must be free, and a REAL external
+ * replacement must still land. A guard that skipped both would look correct in
+ * the fast-path test and silently stop a file re-read from reaching the editor.
+ *
+ * Driven through a real `EditorView` in happy-dom, because the thing under test
+ * dispatches transactions — a stub view would test the stub.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+import { syncExternal, type MutableRef } from '@/client/components/common/code-surface/sync';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+let observer: unknown;
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  installDomGlobals(win);
+  // `installDomGlobals` covers what a COMPONENT reads; mounting a real
+  // `EditorView` additionally needs `MutationObserver` and
+  // `requestAnimationFrame`, which CM6's DOM observer and its measure cycle
+  // call directly on `globalThis`.
+  const target = globalThis as unknown as Record<string, unknown>;
+  observer = target.MutationObserver;
+  target.MutationObserver = (win as unknown as Record<string, unknown>).MutationObserver;
+  target.requestAnimationFrame = (win as unknown as Record<string, unknown>).requestAnimationFrame;
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  if (observer === undefined) delete target.MutationObserver;
+  else target.MutationObserver = observer;
+  restoreDomGlobals();
+});
+
+interface Harness {
+  view: EditorView;
+  writingRef: MutableRef<boolean>;
+  lastValueRef: MutableRef<string>;
+  /** Every string the sync was asked to write, in order. */
+  writes: string[];
+  destroy(): void;
+}
+
+/**
+ * A view over `doc`, wired the way the component wires it: the update listener
+ * keeps `lastValueRef` in step and records the writes it observes.
+ */
+function mount(doc: string): Harness {
+  const writingRef: MutableRef<boolean> = { current: false };
+  const lastValueRef: MutableRef<string> = { current: doc };
+  const writes: string[] = [];
+
+  const view = new EditorView({
+    state: EditorState.create({
+      doc,
+      extensions: [
+        EditorView.updateListener.of((update) => {
+          if (!update.docChanged) return;
+          // Mirrors `documents.ts`'s `onDocChange`: recorded BEFORE the writing
+          // guard, because this is what the document holds either way.
+          lastValueRef.current = update.state.doc.toString();
+          if (writingRef.current) return;
+          writes.push(update.state.doc.toString());
+        }),
+      ],
+    }),
+    parent: document.body,
+  });
+
+  return { view, writingRef, lastValueRef, writes, destroy: () => view.destroy() };
+}
+
+describe('syncExternal', () => {
+  test('the echo of the document costs one comparison and dispatches nothing', () => {
+    const harness = mount('const a = 1;');
+    try {
+      // What the parent hands back after a keystroke.
+      syncExternal(harness.view, 'const a = 1;', harness.writingRef, harness.lastValueRef);
+
+      expect(harness.view.state.doc.toString()).toBe('const a = 1;');
+      expect(harness.writes).toEqual([]);
+    } finally {
+      harness.destroy();
+    }
+  });
+
+  test('the fast path does not stringify: a same-reference value is accepted', () => {
+    const harness = mount('x');
+    try {
+      // The document and `lastValueRef` agree, so the guard returns before the
+      // `doc.toString()` that used to run on every render. A spy is not needed:
+      // `lastValueRef` being the identity the caller passes is the contract, and
+      // an unchanged document proves nothing was dispatched.
+      const before = harness.view.state.doc;
+      syncExternal(harness.view, 'x', harness.writingRef, harness.lastValueRef);
+
+      expect(harness.view.state.doc).toBe(before);
+    } finally {
+      harness.destroy();
+    }
+  });
+
+  test('a real external replacement lands, once, and is not reported as a user edit', () => {
+    const harness = mount('old text');
+    try {
+      syncExternal(harness.view, 'new text', harness.writingRef, harness.lastValueRef);
+
+      expect(harness.view.state.doc.toString()).toBe('new text');
+      // `writingRef` suppresses the report: a re-read is not something the user
+      // typed, and reporting it would arm an autosave for an unchanged file.
+      expect(harness.writes).toEqual([]);
+      expect(harness.lastValueRef.current).toBe('new text');
+      expect(harness.writingRef.current).toBe(false);
+    } finally {
+      harness.destroy();
+    }
+  });
+
+  test('a value that differs from the ref but EQUALS the document is adopted without a dispatch', () => {
+    const harness = mount('same');
+    try {
+      // The parent re-serialized the same text: a new string, same content.
+      const fresh = ['same'].join('');
+      harness.lastValueRef.current = 'stale';
+      syncExternal(harness.view, fresh, harness.writingRef, harness.lastValueRef);
+
+      expect(harness.view.state.doc.toString()).toBe('same');
+      expect(harness.writes).toEqual([]);
+      // The ref is corrected, so the NEXT render takes the fast path again.
+      expect(harness.lastValueRef.current).toBe('same');
+    } finally {
+      harness.destroy();
+    }
+  });
+
+  test('an empty document is a real value, not "nothing to do"', () => {
+    const harness = mount('was here');
+    try {
+      syncExternal(harness.view, '', harness.writingRef, harness.lastValueRef);
+
+      expect(harness.view.state.doc.length).toBe(0);
+      expect(harness.lastValueRef.current).toBe('');
+    } finally {
+      harness.destroy();
+    }
+  });
+
+  test('the writing flag is released even when the dispatch throws', () => {
+    const harness = mount('text');
+    try {
+      const broken = {
+        state: harness.view.state,
+        dispatch: () => {
+          throw new Error('dispatch failed');
+        },
+      } as unknown as EditorView;
+
+      expect(() => syncExternal(broken, 'other', harness.writingRef, harness.lastValueRef)).toThrow(
+        'dispatch failed',
+      );
+      // A stuck flag would silently swallow every later user edit.
+      expect(harness.writingRef.current).toBe(false);
+    } finally {
+      harness.destroy();
+    }
+  });
+});

package/src/client/components/common/code-surface/sync.ts

@@ -0,0 +1,58 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Writing the parent's `value` into the view — and, more importantly, NOT
+ * writing it.
+ *
+ * The parent re-renders on every keystroke, so an unguarded write would dispatch
+ * a full-document replace on each one: a second edit and a fresh undo entry per
+ * character.
+ *
+ * The guard used to be a single comparison against `view.state.doc.toString()`,
+ * which is a full stringify of the document — and since the parent re-renders on
+ * every keystroke, a large file paid it twice per character. Measured in Bun:
+ * 7.2 ms at 20 MB and 13.7 ms at 30 MB; in the browser the knee was visible as
+ * 67 ms per keystroke at 30 MB and 83 ms at 40 MB. Both drop by roughly a third
+ * once the common case is a reference check.
+ *
+ * `lastValueRef` is what makes that possible, and its definition is the whole
+ * correctness argument: it describes what the DOCUMENT holds — written by the
+ * update listener for every change (user or programmatic) and by this function
+ * when it writes — never what the parent last asked for. So an external
+ * replacement still falls through to the real comparison, while the echo of the
+ * parent's own value is rejected in one string comparison.
+ */
+
+import type { EditorView } from '@codemirror/view';
+
+export interface MutableRef<T> {
+  current: T;
+}
+
+export function syncExternal(
+  view: EditorView,
+  value: string,
+  writingRef: MutableRef<boolean>,
+  lastValueRef: MutableRef<string>,
+): void {
+  // The common case: `value` is the string the update listener reported a
+  // moment ago, so this costs nothing whatever the document's size.
+  if (value === lastValueRef.current) return;
+  // A genuinely different string. It may still equal the document (a parent that
+  // re-serialized the same text), in which case nothing needs dispatching — and
+  // the stringify is affordable here precisely because it is the rare path.
+  if (value === view.state.doc.toString()) {
+    lastValueRef.current = value;
+    return;
+  }
+  writingRef.current = true;
+  try {
+    view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: value } });
+    lastValueRef.current = value;
+  } finally {
+    writingRef.current = false;
+  }
+}

package/src/client/components/common/code-surface/theme.test.ts

@@ -0,0 +1,202 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The code surface's colours, and the two mechanisms that carry them.
+ *
+ * An editor theme is applied in TWO places, and confusing them is the bug this
+ * file exists to catch:
+ *
+ * - **The chrome** (surface, gutter, caret, selection, find, diff bands) is a
+ *   set of `--editor-*` custom properties on the surface's own host. Writing
+ *   them repaints the editor with no transaction at all, which is what makes a
+ *   theme switch a colour change rather than a rebuild.
+ * - **The tokens** are baked into the Shiki decoration plugin, because Shiki is
+ *   handed theme NAMES at tokenize time. That one needs a compartment
+ *   reconfigure — and the reconfigure must keep the document, the selection and
+ *   the undo history, which is why it is a compartment and not a re-mount.
+ *
+ * Both are asserted through a real `EditorView` in happy-dom: the theme
+ * extension emits real CSS, and a stub would test the stub.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { Compartment, EditorState } from '@codemirror/state';
+import { EditorView } from '@codemirror/view';
+
+import { createDocumentCache } from '@/client/components/common/code-surface/documents';
+import { surfaceTheme } from '@/client/components/common/code-surface/theme';
+import { editorThemeVars, resolveEditorTheme } from '@/shared/lib/code/editor/themes';
+import { SHIKI_THEMES } from '@/shared/lib/code/shiki-themes';
+import { installDomGlobals, restoreDomGlobals } from '@/test-support/pristine-globals';
+
+const EXTRA_GLOBALS = ['MutationObserver', 'requestAnimationFrame', 'cancelAnimationFrame'] as const;
+const native: Partial<Record<(typeof EXTRA_GLOBALS)[number], unknown>> = {};
+
+let host: HTMLElement;
+
+beforeAll(() => {
+  const win = new Window({ url: 'http://localhost' });
+  installDomGlobals(win);
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of EXTRA_GLOBALS) {
+    native[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  host = document.body.appendChild(document.createElement('div'));
+});
+
+afterAll(() => {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of EXTRA_GLOBALS) {
+    if (native[key] === undefined) delete target[key];
+    else target[key] = native[key];
+  }
+  restoreDomGlobals();
+});
+
+/** The stylesheet CM6 generated for the theme extension. */
+function themeCss(): string {
+  return Array.from(document.head.querySelectorAll('style'))
+    .map((node) => node.textContent ?? '')
+    .join('\n');
+}
+
+describe('surface theme', () => {
+  /** CM6 injects a theme's stylesheet when a VIEW mounts, not when the
+   *  extension is built — so one view is mounted for the CSS cases below. */
+  beforeAll(() => {
+    const view = new EditorView({
+      parent: host,
+      state: EditorState.create({ doc: 'x', extensions: [surfaceTheme()] }),
+    });
+    view.destroy();
+  });
+
+  test('every chrome colour is a variable with the app palette as its fallback', () => {
+    const css = themeCss();
+    // The editor's own variable first, the app's palette behind it — which is
+    // what makes `auto` a no-op and an explicit theme a pure repaint.
+    expect(css).toContain('background-color: var(--editor-bg, transparent)');
+    expect(css).toContain('color: var(--editor-fg, var(--theme-ink))');
+    expect(css).toContain('var(--editor-gutter-fg,');
+    expect(css).toContain('var(--editor-selection,');
+    expect(css).toContain('var(--editor-cursor, var(--theme-ink))');
+    expect(css).toContain('var(--editor-find,');
+    expect(css).toContain('var(--editor-border,');
+  });
+
+  test('a token paints from the app variant when the editor theme is auto', () => {
+    const css = themeCss();
+    expect(css).toContain('.cm-content .shiki-tok {color: var(--shiki-light)');
+    // The dark rule is scoped to the app's variant attribute, so an app theme
+    // flip recolours tokens with no re-tokenize.
+    expect(css).toContain('html[data-theme-variant="dark"]');
+    expect(css).toContain('var(--shiki-dark)');
+  });
+
+  test('writing the theme variables on the host repaints without a transaction', () => {
+    const view = new EditorView({ parent: host, state: EditorState.create({ doc: 'const a = 1;', extensions: [surfaceTheme()] }) });
+    try {
+      const theme = resolveEditorTheme('dracula');
+      expect(theme).not.toBeNull();
+      const before = view.state.doc.length;
+      for (const [key, value] of Object.entries(editorThemeVars(theme))) {
+        host.style.setProperty(key, value);
+      }
+      // The document and its history are untouched: a colour change is CSS.
+      expect(view.state.doc.length).toBe(before);
+      expect(host.style.getPropertyValue('--editor-bg')).toBe(theme!.bg);
+      expect(host.style.getPropertyValue('--editor-gutter-fg')).toBe(theme!.gutterFg);
+    } finally {
+      view.destroy();
+    }
+  });
+});
+
+describe('document cache theme reconfigure', () => {
+  function cache() {
+    return createDocumentCache({
+      wordWrap: false,
+      readOnly: false,
+      themes: SHIKI_THEMES,
+      onDocChange: () => {},
+      onState: () => {},
+    });
+  }
+
+  test('a theme change is reported for the document it applies to', () => {
+    const documents = cache();
+    documents.stateFor('a', 'typescript', 'const a = 1;');
+
+    // Nothing moved: no effects, which is what keeps a re-render free.
+    expect(documents.optionsEffects({ wordWrap: false, readOnly: false, themes: SHIKI_THEMES }, 'a')).toEqual([]);
+
+    const effects = documents.optionsEffects(
+      { wordWrap: false, readOnly: false, themes: { light: 'dracula', dark: 'dracula' } },
+      'a',
+    );
+    expect(effects).toHaveLength(1);
+  });
+
+  test('a wrap toggle and a theme change are independent effects', () => {
+    const documents = cache();
+    documents.stateFor('a', 'typescript', 'x');
+    const effects = documents.optionsEffects(
+      { wordWrap: true, readOnly: false, themes: { light: 'nord', dark: 'nord' } },
+      'a',
+    );
+    // Two compartments: one for the wrap, one for the tokenizer.
+    expect(effects).toHaveLength(2);
+  });
+
+  test('a reconfigure keeps the document, the caret and the history', () => {
+    const documents = cache();
+    const first = documents.stateFor('a', 'typescript', 'const a = 1;');
+    const edited = first.update({ changes: { from: 0, to: 5, insert: 'let' } }).state;
+    documents.remember('a', edited);
+
+    const themeCompartment = new Compartment();
+    const view = new EditorView({ parent: host, state: edited });
+    try {
+      // A reconfigure of a live view is what a theme switch does.
+      view.dispatch({ effects: themeCompartment.reconfigure([]) });
+      expect(view.state.doc.toString()).toBe('let a = 1;');
+      expect(view.state.selection.main.head).toBe(edited.selection.main.head);
+    } finally {
+      view.destroy();
+    }
+  });
+
+  test('a document switched back gets the CURRENT theme, not the one it was created with', () => {
+    const documents = cache();
+    documents.stateFor('a', 'typescript', 'a');
+    documents.optionsEffects(
+      { wordWrap: false, readOnly: false, themes: { light: 'dracula', dark: 'dracula' } },
+      'a',
+    );
+    // `currentEffects` is the re-apply `view.setState` owes: a cached state
+    // carries the configuration it was CREATED with.
+    const effects = documents.currentEffects('a');
+    expect(effects.length).toBeGreaterThan(0);
+  });
+
+  test('a switch back to a document that already holds the theme does not re-tokenize', () => {
+    const documents = cache();
+    documents.stateFor('a', 'typescript', 'a');
+    documents.stateFor('b', 'typescript', 'b');
+    const dracula = { light: 'dracula', dark: 'dracula' };
+
+    // Pick the theme while `a` is the live document, then switch to `b` — the
+    // apply path reconfigures BOTH, which is what makes them agree.
+    documents.optionsEffects({ wordWrap: false, readOnly: false, themes: dracula }, 'a');
+    documents.currentEffects('b');
+    // ... and back: `a` already holds the theme, so there is nothing to rebuild.
+    const effects = documents.currentEffects('a');
+    // Wrap + read-only only; the tokenizer's reconfigure is absent.
+    expect(effects).toHaveLength(2);
+  });
+});