@kabmo-labs/kabmo 0.8.0 → 0.9.0

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

@@ -0,0 +1,201 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One `EditorState` per open document, applied with `view.setState`.
+ *
+ * This is what the tab model actually needs and what the textarea surface could
+ * only fake: a tab's caret, its extra cursors and its UNDO HISTORY belong to the
+ * tab, not to the panel. Measured in CM6: switching states and coming back
+ * restores all three, and an undo in one tab cannot touch another — with the
+ * single buffer the panel used to hold, `⌘Z` after a tab switch undid an edit in
+ * the file the user was no longer looking at.
+ *
+ * The cache is bounded. A session can open a dozen files and each history holds
+ * whole-document snapshots, so the least recently used state is dropped past
+ * `MAX_CACHED`. Losing a closed tab's history is the intended cost; losing an
+ * OPEN tab's is not, which is why the drop is LRU rather than oldest-first.
+ *
+ * `wordWrap` and `readOnly` are per-VIEW settings, so they live in compartments
+ * this module owns. A cached state is NOT reconfigured in place: `setState`
+ * installs that state's own configuration, so the caller re-applies the current
+ * options after every swap (`optionsEffects`). Reconfiguring in the cache too
+ * would be a second place the same answer is stored.
+ */
+
+import { Compartment, EditorState, type Extension, type StateEffect } from '@codemirror/state';
+
+import type { EditorCommand } from '@/shared/lib/code/editor/keymap';
+import { readOnlyExtension, surfaceExtensions, wrapExtension } from '@/client/components/common/code-surface/extensions';
+import { shikiHighlight, type ShikiThemeNames } from '@/client/components/common/code-surface/shiki';
+
+/** States kept alive; past this the least recently used one is dropped. */
+const MAX_CACHED = 12;
+
+export interface SurfaceOptions {
+  wordWrap: boolean;
+  readOnly: boolean;
+  /**
+   * The tokenizer's two theme names.
+   *
+   * Part of the live options rather than of the document key: two tabs in
+   * different languages are two states (their decorations are built from
+   * different grammars), but a THEME is one setting for every tab — a new key
+   * per theme would throw away every open tab's undo history on a colour change.
+   */
+  themes: ShikiThemeNames;
+}
+
+export interface DocumentCacheDeps extends SurfaceOptions {
+  /** Panel-owned commands the editor delegates instead of running. */
+  onCommand?: (command: EditorCommand) => void;
+  /** Every user edit, with the whole new document. */
+  onDocChange: (value: string) => void;
+  /** Every state worth remembering (an edit or a selection move). */
+  onState: (state: EditorState) => void;
+}
+
+export interface DocumentCache {
+  /** The state for `key`, created (and cached) from `value` when absent. */
+  stateFor(key: string, language: string, value: string): EditorState;
+  /** Store the live state so a switch back finds it. */
+  remember(key: string, state: EditorState): void;
+  /** Drop a closed tab's history. */
+  drop(key: string): void;
+  /**
+   * Effects that bring a view to the current options; empty when nothing moved.
+   *
+   * `key` names the document the effects will be dispatched to, because the
+   * tokenizer is per-LANGUAGE: a theme reconfigure must rebuild it from that
+   * document's own grammar, not from whichever one the cache saw last.
+   */
+  optionsEffects(next: SurfaceOptions, key?: string): StateEffect<unknown>[];
+  /**
+   * Effects that install the CURRENT options unconditionally.
+   *
+   * A cached state carries the configuration it was created with, and
+   * `view.setState` installs that configuration wholesale — so a tab opened
+   * while wrap was off came back unwrapped after a toggle. This is the re-apply
+   * a document switch owes.
+   */
+  currentEffects(key?: string): StateEffect<unknown>[];
+}
+
+/** Whether two theme pairs name the same Shiki themes. */
+function sameThemes(a: ShikiThemeNames | undefined, b: ShikiThemeNames): boolean {
+  return a !== undefined && a.light === b.light && a.dark === b.dark;
+}
+
+export function createDocumentCache(deps: DocumentCacheDeps): DocumentCache {
+  const states = new Map<string, EditorState>();
+  const options: SurfaceOptions = {
+    wordWrap: deps.wordWrap,
+    readOnly: deps.readOnly,
+    themes: deps.themes,
+  };
+  const wordWrapCompartment = new Compartment();
+  const readOnlyCompartment = new Compartment();
+  const themeCompartment = new Compartment();
+  /** The language each cached state was built for, so a theme reconfigure can
+   *  rebuild its tokenizer with the SAME grammar. */
+  const languages = new Map<string, string>();
+  /**
+   * The theme pair each cached state's tokenizer currently holds.
+   *
+   * Tracked because a theme reconfigure REBUILDS the decoration plugin, which
+   * re-tokenizes the viewport. `currentEffects` runs on every tab switch, and
+   * paying that for a state that already has the right theme is work for
+   * nothing — 2.1 ms on a 20 000-line file, every switch.
+   */
+  const themesByKey = new Map<string, ShikiThemeNames>();
+
+  const extensionsFor = (language: string): Extension[] =>
+    surfaceExtensions({
+      language,
+      wordWrapCompartment,
+      readOnlyCompartment,
+      themeCompartment,
+      onCommand: deps.onCommand,
+      onDocChange: deps.onDocChange,
+      onState: deps.onState,
+      ...options,
+    });
+
+  /** Move `key` to the end of the map so the LRU drop takes the right one. */
+  const touch = (key: string, state: EditorState): void => {
+    states.delete(key);
+    states.set(key, state);
+  };
+
+  const evict = (): void => {
+    while (states.size > MAX_CACHED) {
+      const oldest = states.keys().next();
+      if (oldest.done) return;
+      states.delete(oldest.value);
+    }
+  };
+
+  return {
+    stateFor(key, language, value) {
+      const cached = states.get(key);
+      if (cached) {
+        touch(key, cached);
+        return cached;
+      }
+      const state = EditorState.create({ doc: value, extensions: extensionsFor(language) });
+      states.set(key, state);
+      languages.set(key, language);
+      themesByKey.set(key, options.themes);
+      evict();
+      return state;
+    },
+
+    remember(key, state) {
+      touch(key, state);
+    },
+
+    drop(key) {
+      states.delete(key);
+      languages.delete(key);
+      themesByKey.delete(key);
+    },
+
+    optionsEffects(next, key) {
+      const wrapChanged = next.wordWrap !== options.wordWrap;
+      const readOnlyChanged = next.readOnly !== options.readOnly;
+      const themeChanged = next.themes.light !== options.themes.light || next.themes.dark !== options.themes.dark;
+      options.wordWrap = next.wordWrap;
+      options.readOnly = next.readOnly;
+      options.themes = next.themes;
+      const effects: StateEffect<unknown>[] = [];
+      if (wrapChanged) effects.push(wordWrapCompartment.reconfigure(wrapExtension(options.wordWrap)));
+      if (readOnlyChanged) effects.push(readOnlyCompartment.reconfigure(readOnlyExtension(options.readOnly)));
+      // The plugin carries the language, so the tokenizer is rebuilt from THIS
+      // document's grammar. Other cached states are handled by `currentEffects`
+      // when they are applied, which is the moment they need it.
+      const language = key ? languages.get(key) : undefined;
+      if (themeChanged && language) {
+        effects.push(themeCompartment.reconfigure(shikiHighlight(language, options.themes)));
+        if (key) themesByKey.set(key, options.themes);
+      }
+      return effects;
+    },
+
+    currentEffects(key) {
+      const effects: StateEffect<unknown>[] = [
+        wordWrapCompartment.reconfigure(wrapExtension(options.wordWrap)),
+        readOnlyCompartment.reconfigure(readOnlyExtension(options.readOnly)),
+      ];
+      const language = key ? languages.get(key) : undefined;
+      // Only when this state's tokenizer still holds another theme: a switch
+      // back to a tab that already has it must not re-tokenize.
+      if (key && language && !sameThemes(themesByKey.get(key), options.themes)) {
+        effects.push(themeCompartment.reconfigure(shikiHighlight(language, options.themes)));
+        themesByKey.set(key, options.themes);
+      }
+      return effects;
+    },
+  };
+}

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

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's extension stack, and the one thing in it that fails SILENTLY.
+ *
+ * `toggleComment` reads its tokens out of the `languageData` facet, and
+ * `languageDataAt` looks the name up in each provider's RESULT — so a provider
+ * that returns the tokens bare (`() => [{ line: '//' }]`) yields an empty list,
+ * the command returns `false`, and ⌘/ does nothing at all. Measured: the line
+ * stayed uncommented in TypeScript and in YAML, with no error anywhere. These
+ * cases assert the command's own effect on a state built from the same stack the
+ * component mounts.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { Compartment, EditorSelection, EditorState } from '@codemirror/state';
+import { toggleComment } from '@codemirror/commands';
+
+import { readOnlyExtension, surfaceExtensions, wrapExtension } from '@/client/components/common/code-surface/extensions';
+import { SHIKI_THEMES } from '@/shared/lib/code/shiki-themes';
+
+/** A state from the component's own stack, with a bare caret on line 1. */
+function stateFor(language: string, doc = 'const alpha = 1;\n') {
+  return EditorState.create({
+    doc,
+    extensions: surfaceExtensions({
+      language,
+      wordWrapCompartment: new Compartment(),
+      readOnlyCompartment: new Compartment(),
+      themeCompartment: new Compartment(),
+      wordWrap: false,
+      readOnly: false,
+      themes: SHIKI_THEMES,
+      onDocChange: () => {},
+      onState: () => {},
+    }),
+  });
+}
+
+/** Apply `toggleComment` the way a `Command` would, returning the new text. */
+function toggled(state: EditorState): string {
+  let next = state;
+  toggleComment({ state, dispatch: (transaction) => { next = transaction.state; } });
+  return next.doc.toString();
+}
+
+describe('comment tokens', () => {
+  test('toggling comments a TypeScript line with //', () => {
+    expect(toggled(stateFor('typescript'))).toBe('// const alpha = 1;\n');
+  });
+
+  test('toggling uses the language’s own token, not a hard-coded //', () => {
+    // A `//` in YAML is a syntax error, which is what makes this the case worth
+    // pinning: the table has to reach the command.
+    expect(toggled(stateFor('yaml', 'key: value\n'))).toBe('# key: value\n');
+    expect(toggled(stateFor('sql', 'select 1;\n'))).toBe('-- select 1;\n');
+  });
+
+  test('a block-only language is wrapped instead of prefixed', () => {
+    expect(toggled(stateFor('css', 'a { color: red; }\n'))).toContain('/*');
+  });
+
+  test('a second toggle restores the line', () => {
+    const once = toggled(stateFor('typescript'));
+    const twice = toggled(stateFor('typescript', once));
+    expect(twice).toBe('const alpha = 1;\n');
+  });
+});
+
+describe('read-only', () => {
+  test('both halves are installed, so neither typing nor a dispatch can edit', () => {
+    const state = EditorState.create({
+      doc: 'x',
+      extensions: [readOnlyExtension(true)],
+    });
+    // `readOnly` is what stops the commands; `editable` is what stops the DOM.
+    expect(state.readOnly).toBe(true);
+  });
+
+  test('an editable surface installs neither', () => {
+    const state = EditorState.create({ doc: 'x', extensions: [readOnlyExtension(false)] });
+    expect(state.readOnly).toBe(false);
+  });
+});
+
+describe('wrap', () => {
+  test('wrapping is a compartment payload, so it can be swapped without a re-mount', () => {
+    const compartment = new Compartment();
+    const state = EditorState.create({ doc: 'x', extensions: [compartment.of(wrapExtension(true))] });
+    const unwrapped = state.update({ effects: compartment.reconfigure(wrapExtension(false)) }).state;
+    // Same document and selection: the reconfigure must not disturb either.
+    expect(unwrapped.doc.toString()).toBe('x');
+    expect(unwrapped.selection.main.head).toBe(state.selection.main.head);
+  });
+
+  test('the selection survives a wrap toggle', () => {
+    const compartment = new Compartment();
+    const state = EditorState.create({
+      doc: 'alpha beta',
+      selection: EditorSelection.range(0, 5),
+      extensions: [compartment.of(wrapExtension(false))],
+    });
+    const wrapped = state.update({ effects: compartment.reconfigure(wrapExtension(true)) }).state;
+    expect(wrapped.selection.main.from).toBe(0);
+    expect(wrapped.selection.main.to).toBe(5);
+  });
+});

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

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The code surface's extension stack, in one place.
+ *
+ * Split from the component because the mount and the configuration are two
+ * different concerns, and because this is the list a reader checks when asking
+ * "what does this editor do". Each entry is here for a reason worth stating:
+ *
+ * - `history()` replaces the hand-rolled undo stack. It is per `EditorState`,
+ *   and every document gets its own (see `documents.ts`), so history is already
+ *   isolated per tab.
+ * - `drawSelection()` paints the selection and the multi-cursor bands. Without
+ *   it a second cursor from `⌘D` is a state change with nothing on screen.
+ * - `rectangularSelection` / `crosshairCursor` are CM6's own answer to a column
+ *   selection; the textarea surface could not do one at all.
+ * - `languageData` carries the comment tokens, which is the whole of what
+ *   `toggleComment` needs — no lezer grammar, no syntax tree. It is read from
+ *   the same table the old text commands used, so `#` stays right in YAML and
+ *   `/* *\/` stays right in CSS.
+ * - Read-only is BOTH facets: `readOnly` stops the commands, `editable(false)`
+ *   sets `contenteditable=false`, and only the pair makes a viewer a viewer
+ *   (measured: `readOnly` alone let a programmatic `dispatch({changes})` through,
+ *   which a viewer has no business accepting).
+ *
+ * `wordWrap` and `readOnly` arrive as compartments because they are per-view
+ * settings that must reconfigure a live editor without re-creating it — a
+ * reconfigure keeps the document, the selection and the history, which is
+ * exactly what a wrap toggle must not disturb.
+ */
+
+import { type Compartment, EditorState, type Extension } from '@codemirror/state';
+import {
+  crosshairCursor,
+  drawSelection,
+  dropCursor,
+  EditorView,
+  lineNumbers,
+  rectangularSelection,
+} from '@codemirror/view';
+import { history } from '@codemirror/commands';
+import { indentUnit } from '@codemirror/language';
+
+import { commentSyntaxFor } from '@/shared/lib/code/editor/comment-syntax';
+import type { EditorCommand } from '@/shared/lib/code/editor/keymap';
+import { findMarksField } from '@/client/components/common/code-surface/marks';
+import { surfaceKeymap } from '@/client/components/common/code-surface/keymap';
+import { shikiHighlight, type ShikiThemeNames } from '@/client/components/common/code-surface/shiki';
+import { surfaceTheme } from '@/client/components/common/code-surface/theme';
+
+/** Indentation the surface inserts, in spaces. */
+const INDENT = '  ';
+
+/** Wrap on: CM6 wraps the content box; the panel no longer measures anything. */
+export function wrapExtension(wordWrap: boolean): Extension {
+  return wordWrap ? EditorView.lineWrapping : [];
+}
+
+/** Both halves of read-only, or nothing for an editable surface. */
+export function readOnlyExtension(readOnly: boolean): Extension {
+  return readOnly ? [EditorState.readOnly.of(true), EditorView.editable.of(false)] : [];
+}
+
+/** The comment tokens `toggleComment` reads out of `languageData`. */
+function commentTokens(language: string): { line?: string; block?: { open: string; close: string } } {
+  const syntax = commentSyntaxFor(language);
+  if ('line' in syntax) return { line: syntax.line };
+  return { block: { open: syntax.block[0], close: syntax.block[1] } };
+}
+
+export interface SurfaceExtensionsOptions {
+  language: string;
+  /** Compartment holding `wrapExtension`. */
+  wordWrapCompartment: Compartment;
+  /** Compartment holding `readOnlyExtension`. */
+  readOnlyCompartment: Compartment;
+  /**
+   * Compartment holding the tokenizer.
+   *
+   * The editor theme is baked into the decoration plugin (Shiki is handed the
+   * theme NAMES at tokenize time), so a theme change reconfigures this — which
+   * rebuilds the plugin while the document, the selection and the history stay
+   * exactly where they were.
+   */
+  themeCompartment: Compartment;
+  wordWrap: boolean;
+  readOnly: boolean;
+  /** The two Shiki theme names this surface tokenizes with. */
+  themes: ShikiThemeNames;
+  /** Panel-owned commands the editor delegates instead of running. */
+  onCommand?: (command: EditorCommand) => void;
+  /** Fired for every user edit, with the whole new document. */
+  onDocChange: (value: string) => void;
+  /** Fired on every state that must be remembered (an edit or a selection move). */
+  onState: (state: EditorState) => void;
+}
+
+/** Everything the editor needs, built once per document state. */
+export function surfaceExtensions({
+  language,
+  wordWrapCompartment,
+  readOnlyCompartment,
+  themeCompartment,
+  wordWrap,
+  readOnly,
+  themes,
+  onCommand,
+  onDocChange,
+  onState,
+}: SurfaceExtensionsOptions): Extension[] {
+  return [
+    lineNumbers(),
+    history(),
+    drawSelection(),
+    dropCursor(),
+    rectangularSelection(),
+    crosshairCursor(),
+    EditorState.allowMultipleSelections.of(true),
+    indentUnit.of(INDENT),
+    // `toggleComment` with no grammar: the tokens are the entire input it needs.
+    // The provider must return an object KEYED by the data name —
+    // `languageDataAt` looks the name up in each result, so returning the tokens
+    // bare yields an empty list and the command silently does nothing.
+    EditorState.languageData.of(() => [{ commentTokens: commentTokens(language) }]),
+    findMarksField,
+    themeCompartment.of(shikiHighlight(language, themes)),
+    surfaceTheme(),
+    wordWrapCompartment.of(wrapExtension(wordWrap)),
+    readOnlyCompartment.of(readOnlyExtension(readOnly)),
+    // The browser's own spellchecker underlines every identifier and offers to
+    // "correct" them; autocapitalise/autocorrect mangle code on a phone. CM6
+    // sets these itself, and stating them keeps a future default from silently
+    // regressing a mobile keyboard.
+    EditorView.contentAttributes.of({
+      spellcheck: 'false',
+      autocorrect: 'off',
+      autocapitalize: 'off',
+      translate: 'no',
+    }),
+    EditorView.updateListener.of((update) => {
+      // The per-tab cache stores the LIVE state so a switch back finds its
+      // caret: a selection move is as much of that state as an edit is.
+      if (update.docChanged || update.selectionSet) onState(update.state);
+      if (update.docChanged) onDocChange(update.state.doc.toString());
+      // The selection as a DOM fact, because a `contenteditable` exposes none.
+      // The old surface was a `<textarea>`, whose `selectionStart`/`selectionEnd`
+      // and line arithmetic were readable from the element; these two attributes
+      // are the same facts for the same readers (the e2e layer's outline and
+      // caret specs), and nothing in the app reads them.
+      if (update.docChanged || update.selectionSet) {
+        const range = update.state.selection.main;
+        const attrs = update.view.contentDOM.dataset;
+        attrs.selection = `${range.from},${range.to}`;
+        attrs.line = String(update.state.doc.lineAt(range.from).number);
+      }
+    }),
+    surfaceKeymap(onCommand, readOnly),
+  ];
+}

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

@@ -0,0 +1,102 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The imperative surface handle, built from the mount's refs.
+ *
+ * Split out of `index.tsx` because the component is at the repository's line
+ * ceiling and this half is dispatch, not rendering: every method here is "look
+ * up the live view, then hand CodeMirror a transaction". Keeping it a factory
+ * over the refs (rather than a hook) is what makes the identity stable — the
+ * handle is built once for the component's life, so a consumer holding it never
+ * re-subscribes.
+ *
+ * Two rules live here and nowhere else, both measured:
+ *
+ * - **`applyDocument` is a USER edit.** It is deliberately not silenced as an
+ *   external write: the find bar's replace has to reach `onValueChange` exactly
+ *   like typing does, or the parent keeps the pre-replace buffer and the next
+ *   render writes the OLD text back over it.
+ * - **A reveal cancels a pending scroll restore.** The restore's
+ *   `ResizeObserver` can run BEFORE the scroll event a reveal's dispatch causes,
+ *   so it would write the remembered offset back and the view would never move.
+ */
+
+import { EditorView } from '@codemirror/view';
+import type { MutableRef } from '@/client/components/common/code-surface/sync';
+import { cancelScrollRestore } from '@/client/hooks/editor/use-scroll-restore';
+import { runSurfaceCommand } from '@/client/components/common/code-surface/keymap';
+import type { EditorCommand } from '@/shared/lib/code/editor/keymap';
+
+/** The imperative surface every consumer of the editor holds. */
+export interface CodeSurfaceHandle {
+  /** Current selection offsets in the buffer, or null before the view mounts. */
+  getSelection(): { start: number; end: number } | null;
+  /** Select `[start, end)`; `focus` moves keyboard focus into the editor. */
+  select(start: number, end: number, focus?: boolean): void;
+  /** Replace the buffer as one undoable edit, caret at `[caretStart, caretEnd)`, focus unchanged. */
+  applyDocument(value: string, caretStart: number, caretEnd: number): void;
+  /** Run an editor command by name (the palette's path into the editor). */
+  runCommand(command: EditorCommand): void;
+  /**
+   * Bring the line holding `offset` into view WITHOUT moving the caret — what
+   * "step to the next match" needs: the user's focus stays in the find field
+   * while the match scrolls under it.
+   */
+  revealOffset(offset: number): void;
+}
+
+export interface SurfaceHandleRefs {
+  view: MutableRef<EditorView | null>;
+  /** The live `onCommand`, mirrored so the handle never captures a stale one. */
+  onCommand: MutableRef<((command: EditorCommand) => void) | undefined>;
+}
+
+/** The handle a `forwardRef` caller receives. Built once per mount. */
+export function createSurfaceHandle({ view: viewRef, onCommand: onCommandRef }: SurfaceHandleRefs): CodeSurfaceHandle {
+  return {
+    getSelection: () => {
+      const view = viewRef.current;
+      if (!view) return null;
+      const range = view.state.selection.main;
+      return { start: range.from, end: range.to };
+    },
+    select: (start, end, focus = true) => {
+      const view = viewRef.current;
+      if (!view) return;
+      view.dispatch({ selection: { anchor: start, head: end }, scrollIntoView: false });
+      // `focus()` is CM6's own `focusPreventScroll`, which is what stops the
+      // browser scrolling the caret into view a second time — the caller's
+      // `revealOffset` is the only thing that scrolls.
+      if (focus) view.focus();
+    },
+    applyDocument: (next, caretStart, caretEnd) => {
+      const view = viewRef.current;
+      if (!view) return;
+      // One transaction, so ⌘Z undoes the whole replacement: a replace-all that
+      // took one undo step per match is what the old surface had to hand-roll a
+      // history for.
+      view.dispatch({
+        changes: { from: 0, to: view.state.doc.length, insert: next },
+        selection: { anchor: caretStart, head: caretEnd },
+      });
+    },
+    runCommand: (command) => {
+      const view = viewRef.current;
+      if (!view) return;
+      runSurfaceCommand(command, view, onCommandRef.current);
+    },
+    revealOffset: (offset) => {
+      const view = viewRef.current;
+      if (!view) return;
+      const at = Math.max(0, Math.min(offset, view.state.doc.length));
+      cancelScrollRestore(view.scrollDOM);
+      // `y: 'nearest'` is the rule the old surface hand-rolled: a reveal only
+      // scrolls when the target is outside the visible band, so stepping
+      // through matches does not jump the whole view on every step.
+      view.dispatch({ effects: EditorView.scrollIntoView(at, { y: 'nearest', yMargin: 24 }) });
+    },
+  };
+}