@kabmo-labs/kabmo 0.8.0 → 0.9.0

package/src/shared/lib/code/editor/find-scan.ts

@@ -0,0 +1,177 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Find scanning over one document buffer.
+ *
+ * The SCAN is CodeMirror's: `RegExpCursor` walks the document and hands back the
+ * same ordered match list the surface paints, so the matcher and the editor
+ * cannot disagree about where a match is. That replaced a hand-written
+ * `RegExp.exec` loop, which had to re-implement the two things a cursor gets
+ * right for free — never returning a zero-width match (nothing to highlight,
+ * nothing to replace, and stepping past it is what keeps the scan terminating)
+ * and starting the next search after the previous match rather than at its own
+ * index.
+ *
+ * Everything around the scan is still Kabmo's, deliberately: the options shape,
+ * the cap and the `truncated`/`invalid` distinction are the find widget's
+ * contract. Replacement expansion lives in `find-replace.ts`, because a caller
+ * that only paints matches should not carry the template grammar.
+ *
+ * A regex that does not compile is a DIFFERENT answer from "no matches", which
+ * is why `invalid` exists: a user typing `(` must be told their pattern is
+ * broken, not that the file does not contain it.
+ */
+
+import { Text } from '@codemirror/state';
+import { RegExpCursor } from '@codemirror/search';
+
+import { lineIndexAt, lineStartOffset, type TextRange } from '@/shared/lib/code/editor/lines';
+
+export { lineIndexAt, lineStartOffset };
+
+export interface FindOptions {
+  matchCase: boolean;
+  wholeWord: boolean;
+  isRegex: boolean;
+}
+
+/** Half-open `[start, end)` offset range in the document. */
+export type FindMatch = TextRange;
+
+export interface FindResult {
+  matches: FindMatch[];
+  /** The document holds more matches than the cap; the list stops at it. */
+  truncated: boolean;
+  /** A regex query that does not compile — a different answer from "no matches". */
+  invalid: boolean;
+}
+
+/**
+ * Ceiling on collected matches. A one-character query over a large file matches
+ * tens of thousands of times and every match is a decoration, so past this the
+ * list stops and the widget reports `N+`.
+ */
+export const MAX_FIND_MATCHES = 5_000;
+
+export const DEFAULT_FIND_OPTIONS: FindOptions = {
+  matchCase: false,
+  wholeWord: false,
+  isRegex: false,
+};
+
+/**
+ * The flags `RegExpCursor` compiles with, stated once.
+ *
+ * This is not a preference: the cursor builds its own `RegExp` from the pattern
+ * SOURCE with `gm` (plus `u` where the engine has unicode property escapes), and
+ * a write path that compiled the same source with different flags would answer
+ * differently from the list on screen. Measured before this was aligned:
+ *
+ * - `^foo` / `foo$` — the cursor's `m` makes the anchor per LINE, so the widget
+ *   counted 2 matches on a three-line file while Replace All rewrote only the
+ *   first (no `m` = start/end of the whole document).
+ * - `\p{L}\d` — matched three times in the scan and zero in the replacement,
+ *   because a property escape is only a property escape with `u`; without it
+ *   `\p` is a literal `p`, so Replace All and Replace One did nothing at all.
+ * - `\-`, `\A` — invalid escapes under `u`, so the scan called the pattern
+ *   broken while Replace All still edited the file with the non-unicode reading.
+ *
+ * So the flags live here, `buildFindRegex` is the only compiler, and the scan,
+ * the replace preview and both write paths read it.
+ */
+const BASE_FLAGS = 'gm' + ('unicode' in RegExp.prototype ? 'u' : '');
+
+/**
+ * The pattern a query compiles to, or null when the query is empty or does not
+ * compile. A literal query is escaped here rather than at the call site so the
+ * match scan and the replacement splice can never disagree about what the
+ * pattern was.
+ *
+ * Whole-word is a `\b`-anchored non-capturing group rather than a bare wrap so
+ * an alternation (`foo|bar`) keeps its own precedence.
+ */
+export function buildFindRegex(query: string, options: FindOptions): RegExp | null {
+  if (!query) return null;
+  const source = options.isRegex ? query : query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const wrapped = options.wholeWord ? `\\b(?:${source})\\b` : source;
+  try {
+    return new RegExp(wrapped, options.matchCase ? BASE_FLAGS : `${BASE_FLAGS}i`);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The last string converted to a `Text`, kept for one call.
+ *
+ * A cursor needs a `Text`, and `Text.of(text.split('\n'))` builds a rope over
+ * the whole file. The find widget asks for matches on every keystroke in its
+ * query and on every edit, always for the same document, so keeping the last
+ * conversion is the difference between one split per render and one per call.
+ */
+let lastTextSource: string | null = null;
+let lastText: Text | null = null;
+
+function asText(source: string): Text {
+  if (lastTextSource === source && lastText) return lastText;
+  lastText = Text.of(source.split('\n'));
+  lastTextSource = source;
+  return lastText;
+}
+
+/**
+ * Every match of `query` in `text`, in document order.
+ *
+ * `RegExpCursor` searches LINE by line for a pattern that cannot span one, and
+ * falls back to a whole-document cursor when the pattern mentions `\n`, `\r`,
+ * `\s`, `\W`, `\D`, `\b`-free character classes or `[^`. Both return document
+ * offsets, so the caller never learns which one ran.
+ */
+export function findMatches(text: string, query: string, options: FindOptions): FindResult {
+  if (!query) return { matches: [], truncated: false, invalid: false };
+  const pattern = buildFindRegex(query, options);
+  if (!pattern) return { matches: [], truncated: false, invalid: true };
+
+  const matches: FindMatch[] = [];
+  let cursor: RegExpCursor;
+  try {
+    cursor = new RegExpCursor(asText(text), pattern.source, { ignoreCase: !options.matchCase });
+  } catch {
+    // A pattern `new RegExp` accepts but the cursor's own construction refuses
+    // (an unsupported flag combination) is still a broken pattern to the user.
+    return { matches: [], truncated: false, invalid: true };
+  }
+
+  while (matches.length < MAX_FIND_MATCHES && !cursor.next().done) {
+    const { from, to } = cursor.value;
+    if (from === to) continue;
+    matches.push({ start: from, end: to });
+  }
+
+  return { matches, truncated: matches.length >= MAX_FIND_MATCHES, invalid: false };
+}
+
+/**
+ * The match to call "current" for a caret/anchor at `offset`: the first one
+ * that ends after it, so a caret sitting inside a match still counts as being
+ * on that match. Wraps to the first match when the anchor is past the last one,
+ * and reports -1 for an empty list.
+ */
+export function matchIndexAtOrAfter(matches: readonly FindMatch[], offset: number): number {
+  if (matches.length === 0) return -1;
+  for (let index = 0; index < matches.length; index++) {
+    if (matches[index].end > offset) return index;
+  }
+  return 0;
+}
+
+/** Step one match forward (`1`) or back (`-1`), wrapping at either end. */
+export function stepMatchIndex(index: number, count: number, direction: 1 | -1): number {
+  if (count <= 0) return -1;
+  if (index < 0) return direction === 1 ? 0 : count - 1;
+  return (index + direction + count) % count;
+}
+

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

@@ -8,9 +8,9 @@
  *
  * One table is the whole truth about an editor shortcut: what it does, which
  * chords reach it on each platform, and what the palette calls it. The
- * textarea's handler, the find bar's buttons, the tooltips and the command
- * palette all read this table, so a shortcut cannot be listed in the palette
- * and unbound in the editor.
+ * generated CodeMirror keymap, the find bar's buttons, the tooltips and the
+ * command palette all read this table, so a shortcut cannot be listed in the
+ * palette and unbound in the editor.
  *
  * VS Code's defaults are followed wherever this editor has an equivalent. Where
  * it has none — folding, go-to-definition, the `⌘K` prefix chords — the command

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

@@ -4,21 +4,17 @@
  */
 
 /**
- * Line arithmetic, which every line command and the gutter depend on agreeing
- * about. The interesting cases are the two the arithmetic gets wrong by
- * accident: a caret on the empty line a trailing newline opens, and a selection
- * that ends exactly at a line start (which does not touch that line).
+ * Line arithmetic, which the highlighter's per-line walk and the find widget's
+ * "jump to line N" both read.
+ *
+ * The interesting cases are the two the arithmetic gets wrong by accident: the
+ * empty line a trailing newline opens, and an offset past the end of the
+ * document.
  */
 
 import { describe, expect, test } from 'bun:test';
 
-import {
-  countLines,
-  lineIndexAt,
-  lineRangeAt,
-  lineRangesInSelection,
-  lineStartOffset,
-} from '@/shared/lib/code/editor/lines';
+import { lineIndexAt, lineStartOffset } from '@/shared/lib/code/editor/lines';
 
 describe('lineIndexAt and lineStartOffset', () => {
   test('are inverses for every line start', () => {
@@ -34,48 +30,4 @@ describe('lineIndexAt and lineStartOffset', () => {
     expect(lineIndexAt('one\ntwo', 999)).toBe(1);
     expect(lineStartOffset('one\ntwo', 99)).toBe(7);
   });
-
-  test('count a trailing newline as opening one more, empty line', () => {
-    expect(countLines('one\ntwo')).toBe(2);
-    expect(countLines('one\ntwo\n')).toBe(3);
-    expect(countLines('')).toBe(1);
-  });
-});
-
-describe('lineRangeAt', () => {
-  test('includes the trailing newline, so the range can delete or move the line', () => {
-    expect(lineRangeAt('one\ntwo\nthree', 5)).toEqual({ start: 4, end: 8 });
-  });
-
-  test('the last line has no newline to include', () => {
-    expect(lineRangeAt('one\ntwo', 5)).toEqual({ start: 4, end: 7 });
-  });
-
-  test('a caret on the empty line a trailing newline opens yields an empty range there', () => {
-    // `a\n` has an empty second line at offset 2; the honest reading of that
-    // position is "no characters of its own", not the previous line.
-    expect(lineRangeAt('a\n', 2)).toEqual({ start: 2, end: 2 });
-  });
-});
-
-describe('lineRangesInSelection', () => {
-  test('covers every line the selection touches', () => {
-    const text = 'one\ntwo\nthree';
-    expect(lineRangesInSelection(text, { start: 4, end: 7 })).toEqual([{ start: 4, end: 8 }]);
-    expect(lineRangesInSelection(text, { start: 0, end: 7 })).toEqual([
-      { start: 0, end: 4 },
-      { start: 4, end: 8 },
-    ]);
-  });
-
-  test('a selection ending exactly at a line start does not touch that line', () => {
-    // The rule VS Code applies, and the one that keeps a whole-line selection
-    // from splitting off an empty trailing entry.
-    const text = 'one\ntwo';
-    expect(lineRangesInSelection(text, { start: 0, end: 4 })).toEqual([{ start: 0, end: 4 }]);
-  });
-
-  test('an empty selection still names the line the caret is on', () => {
-    expect(lineRangesInSelection('one\ntwo', { start: 5, end: 5 })).toEqual([{ start: 4, end: 7 }]);
-  });
 });

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

@@ -4,13 +4,15 @@
  */
 
 /**
- * Line arithmetic over a buffer.
+ * Line arithmetic over a buffer: which line an offset is on, and where that
+ * line begins.
  *
- * Extracted from the find module because the editor's line commands (delete,
- * move, duplicate, comment) and the highlighter need the same two facts — which
- * line an offset is on, and where that line begins — and neither of them is a
- * find concern. Keeping one implementation is what stops a line command from
- * disagreeing with the gutter about where line 12 starts.
+ * Two consumers, and they must agree — the highlighter's per-line walk and the
+ * find widget's "jump to line N" both turn a line number into an offset. The
+ * editor's own line COMMANDS no longer come through here: every one of them
+ * (delete, move, duplicate, comment, indent) is a CodeMirror command now, and
+ * `state.doc.line*` is what they read. `lineRangeAt`/`lineRangesInSelection`
+ * went with them.
  */
 
 /** Half-open `[start, end)` offset range in a document. */
@@ -39,45 +41,3 @@ export function lineStartOffset(text: string, lineIndex: number): number {
   }
   return offset;
 }
-
-/** How many lines `text` holds; a trailing newline opens one more (empty) line. */
-export function countLines(text: string): number {
-  let count = 1;
-  for (let index = text.indexOf('\n'); index !== -1; index = text.indexOf('\n', index + 1)) count++;
-  return count;
-}
-
-/**
- * The whole line containing `offset`, INCLUDING its trailing newline.
- *
- * Including the newline is what makes the range directly usable by the line
- * commands: deleting it removes the line rather than blanking it, and moving it
- * carries the line's own separator with it. A caret on the empty line a
- * trailing newline opens (`"a\n"` at offset 2) yields an empty range there,
- * which the commands treat as "the newline above" — the honest reading of a
- * position that has no characters of its own.
- */
-export function lineRangeAt(text: string, offset: number): TextRange {
-  const lineStart = lineStartOffset(text, lineIndexAt(text, offset));
-  const lineEnd = text.indexOf('\n', lineStart);
-  if (lineEnd === -1) return { start: lineStart, end: text.length };
-  return { start: lineStart, end: lineEnd + 1 };
-}
-
-/**
- * The ranges of every line a selection touches, in document order.
- *
- * A selection ending exactly at a line start does not touch that line — the
- * same rule VS Code applies, and the one that keeps ⌘⇧L on a whole-line
- * selection from splitting off an empty trailing entry.
- */
-export function lineRangesInSelection(text: string, selection: TextRange): TextRange[] {
-  const startLine = lineIndexAt(text, selection.start);
-  const lastOffset = selection.end > selection.start && text[selection.end - 1] === '\n' ? selection.end - 1 : selection.end;
-  const endLine = lineIndexAt(text, lastOffset);
-  const ranges: TextRange[] = [];
-  for (let line = startLine; line <= endLine; line++) {
-    ranges.push(lineRangeAt(text, lineStartOffset(text, line)));
-  }
-  return ranges;
-}

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

@@ -57,12 +57,11 @@ describe('tokenMarkup', () => {
     expect(tokenMarkup('<', 0, [{ start: 0, end: 1 }], -1)).toContain('&lt;');
   });
 
-  test('the current match and an extra selection are painted differently', () => {
-    // The caret can only be in the primary range, so the two must not look
-    // alike — the user has to see where their keystrokes will land.
+  test('the current match is painted differently from the others', () => {
+    // The caret is aimed at exactly one match, so the reader has to be able to
+    // see which — and the others must not claim that mark.
     expect(tokenMarkup('a', 0, [{ start: 0, end: 1 }], 0)).toContain('data-find-current');
-    expect(tokenMarkup('a', 0, [{ start: 0, end: 1 }], -1, 0)).toContain('data-occurrence');
-    expect(tokenMarkup('a', 0, [{ start: 0, end: 1 }], -1, 0)).not.toContain('data-find-current');
+    expect(tokenMarkup('a', 0, [{ start: 0, end: 1 }], -1)).not.toContain('data-find-current');
   });
 
   test('a plain match is neither current nor an occurrence', () => {

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

@@ -12,11 +12,16 @@
  * match routinely spans several tokens (`const alpha` is three) and a token
  * routinely holds several matches.
  *
- * `<mark>` is not decoration: it is an INLINE element with a background and no
- * padding or border, which is what keeps the transparent `<textarea>` above the
- * layer aligned with the glyphs underneath. Anything that changes the box —
- * a block display, a border, an outline with an offset — moves the text under
- * the caret and breaks editing.
+ * This is the markup path for the surfaces that render highlighted HTML (the
+ * chat's excerpt cards, the search panel's rows, the wiki reader). The EDITOR no
+ * longer uses it: CodeMirror draws its own decorations from a state field
+ * (`code-surface/marks.ts`), which is what stopped every find result from
+ * forcing a re-tokenize.
+ *
+ * `<mark>` is an INLINE element with a background and no padding or border, so
+ * it paints without moving the glyphs it sits between — anything that changes
+ * the box (a block display, a border, an outline with an offset) shifts the text
+ * and breaks the alignment a caller's own layout depends on.
  *
  * Kept out of `syntax-highlight.ts` so the tokenizer module stays under the
  * repository's line ceiling and because this is the find feature's concern
@@ -24,7 +29,7 @@
  */
 
 import { escapeCode } from '@/shared/lib/code/highlighter';
-import type { FindMatch } from '@/shared/lib/code/editor/find';
+import type { FindMatch } from '@/shared/lib/code/editor/find-scan';
 
 /**
  * How `highlightLines` paints its marks. Declared here rather than in the
@@ -41,32 +46,16 @@ export interface HighlightLinesOptions {
    * Match ranges (absolute offsets in `code`) to wrap in `<mark class="find-match">`.
    * The find widget's highlights ride on the same markup the tokens do, so a
    * match cannot drift from the text it belongs to — and an inline `<mark>`
-   * paints a background without moving the glyphs, which is what keeps the
-   * transparent `<textarea>` above aligned with this layer.
+   * paints a background without moving the glyphs it sits between.
    */
   marks?: readonly FindMatch[];
   /** Index into `marks` of the current match, marked `data-find-current`. */
   currentMark?: number;
-  /**
-   * Marks from this index on are extra ⌘D SELECTIONS rather than find matches,
-   * and are painted as such. The caller appends them after the matches, so one
-   * index is all the split needs.
-   */
-  occurrenceFrom?: number;
 }
 
 export const MARK_OPEN = '<mark class="find-match">';
 /** The current match is the one the caret/next-step is aimed at; the CSS paints it darker. */
 export const MARK_CURRENT_OPEN = '<mark class="find-match" data-find-current="">';
-/**
- * An extra ⌘D range. It is not a find match — it is a second SELECTION, and it
- * has to read as one: the caret can only be in the primary range, so painting
- * them alike would leave the user unable to tell which one their keystrokes go
- * to. The two differ only in colour; the geometry is shared, which is what
- * keeps the layers aligned.
- */
-export const MARK_OCCURRENCE_OPEN = '<mark class="find-match" data-occurrence="">';
-
 /**
  * `content` with every intersecting mark spliced in, HTML-escaped.
  *
@@ -79,7 +68,6 @@ export function tokenMarkup(
   tokenStart: number,
   marks: readonly FindMatch[] | undefined,
   currentMark: number,
-  occurrenceFrom = -1,
 ): string {
   const tokenEnd = tokenStart + content.length;
   if (!marks || marks.length === 0) return escapeCode(content);
@@ -98,7 +86,7 @@ export function tokenMarkup(
     const to = Math.min(mark.end, tokenEnd) - tokenStart;
     if (to <= cursor) continue;
     html += escapeCode(content.slice(cursor, from));
-    const open = index === currentMark ? MARK_CURRENT_OPEN : index >= occurrenceFrom && occurrenceFrom >= 0 ? MARK_OCCURRENCE_OPEN : MARK_OPEN;
+    const open = index === currentMark ? MARK_CURRENT_OPEN : MARK_OPEN;
     html += open + escapeCode(content.slice(from, to)) + '</mark>';
     cursor = to;
   }

package/src/shared/lib/code/editor/theme-loader.ts

@@ -0,0 +1,97 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Registering an editor theme with the shared Shiki highlighter, on demand.
+ *
+ * Shiki throws for a theme it has not been given, and `@shikijs/themes` ships 65
+ * of them (1.3 MB of TextMate JSON). So a theme is loaded the first time it is
+ * SELECTED — the picker's grid draws from the generated colour rows and fetches
+ * nothing — and a surface that asks for one before it lands keeps the plain
+ * fallback and re-runs on `onEditorThemeReady`.
+ *
+ * This lives beside the tokenizer rather than in a client hook because the
+ * decoration plugin is what needs the notification, and it must not import a
+ * Preact module to get it.
+ */
+
+import { getHighlighterSync } from '@/shared/lib/code/highlighter';
+import {
+  EDITOR_AUTO_THEME_ID,
+  EDITOR_THEME_LOADERS,
+} from '@/shared/lib/code/editor/themes';
+
+/** Ids registered with the highlighter. */
+const loaded = new Set<string>();
+/** In-flight loads, so two surfaces selecting one theme share a fetch. */
+const pending = new Map<string, Promise<void>>();
+const listeners = new Set<(id: string) => void>();
+
+function notifyReady(id: string): void {
+  for (const listener of [...listeners]) {
+    try {
+      listener(id);
+    } catch {
+      // A listener must never break the others.
+    }
+  }
+}
+
+/** Fires when a theme module lands, so a pending tokenize can retry. */
+export function onEditorThemeReady(listener: (id: string) => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Whether Shiki can tokenize with `id` synchronously right now. */
+export function isEditorThemeReady(id: string): boolean {
+  if (id === EDITOR_AUTO_THEME_ID) return true;
+  return loaded.has(id);
+}
+
+/**
+ * Register `id`'s theme with the shared highlighter.
+ *
+ * Resolves immediately for `auto`, for an id this build does not ship, and for
+ * a highlighter that has not booted yet (the caller keeps the fallback and is
+ * retried by `onSyntaxReady`). Never rejects: a theme that fails to load leaves
+ * the surface on the app palette, which is a wrong palette rather than a blank
+ * editor.
+ */
+export function loadEditorTheme(id: string): Promise<void> {
+  if (id === EDITOR_AUTO_THEME_ID || loaded.has(id)) return Promise.resolve();
+  const loader = EDITOR_THEME_LOADERS[id];
+  if (!loader) return Promise.resolve();
+  const inFlight = pending.get(id);
+  if (inFlight) return inFlight;
+
+  const highlighter = getHighlighterSync();
+  if (!highlighter) return Promise.resolve();
+
+  const load = highlighter
+    .loadTheme(loader as never)
+    .then(() => {
+      loaded.add(id);
+      notifyReady(id);
+    })
+    .catch(() => {
+      // Left out of `loaded` so a later attempt can still succeed.
+    })
+    .finally(() => {
+      pending.delete(id);
+    });
+
+  pending.set(id, load);
+  return load;
+}
+
+/** Test seam: forget every registration (a highlighter restart). */
+export function resetEditorThemeLoader(): void {
+  loaded.clear();
+  pending.clear();
+  listeners.clear();
+}