@kabmo-labs/kabmo 0.7.0 → 0.9.0

package/src/shared/lib/code/editor/find-replace.test.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Replacement expansion: what one match becomes, and how a template is read.
+ *
+ * Each rule is asserted against the engine's own `String.replace` where one
+ * exists, because the search panel's replace PREVIEW and the write that lands
+ * must agree — a preview that painted `$1` over a file that would receive the
+ * captured group is exactly the drift this covers.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  expandReplacement,
+  replaceAllMatches,
+  replaceMatch,
+} from '@/shared/lib/code/editor/find-replace';
+import type { FindOptions } from '@/shared/lib/code/editor/find-scan';
+import { findMatches } from '@/shared/lib/code/editor/find-scan';
+
+const PLAIN: FindOptions = { matchCase: false, wholeWord: false, isRegex: false };
+
+describe('replaceMatch', () => {
+  test('literal replacement inserts the field verbatim, dollar signs included', () => {
+    const text = 'const a = 1;';
+    const result = replaceMatch(text, { start: 6, end: 7 }, 'a', '$&x', PLAIN);
+    expect(result?.text).toBe('const $&x = 1;');
+    expect(result?.caret).toBe(6 + 3);
+  });
+
+  test('regex replacement expands capture groups like String.replace', () => {
+    const text = 'key = value';
+    const result = replaceMatch(text, { start: 6, end: 11 }, '(\\w+)', '[$1]', { ...PLAIN, isRegex: true });
+    expect(result?.text).toBe('key = [value]');
+    expect(result?.caret).toBe(13);
+  });
+
+  test('refuses a match that is no longer at its offset', () => {
+    expect(replaceMatch('abc', { start: 5, end: 7 }, 'a', 'z', PLAIN)).toBeNull();
+  });
+});
+
+describe('replaceAllMatches', () => {
+  test('literal replace-all rewrites every occurrence', () => {
+    expect(replaceAllMatches('a a a', 'a', 'b', PLAIN)).toBe('b b b');
+  });
+
+  test('regex replace-all agrees with the engine', () => {
+    const text = 'foo1 bar2';
+    const options: FindOptions = { ...PLAIN, isRegex: true };
+    expect(replaceAllMatches(text, '([a-z]+)(\\d)', '$2-$1', options)).toBe(text.replace(/([a-z]+)(\d)/g, '$2-$1'));
+  });
+
+  test('whole-word replace-all leaves substrings alone', () => {
+    expect(replaceAllMatches('cat category', 'cat', 'dog', { ...PLAIN, wholeWord: true })).toBe('dog category');
+  });
+
+  test('returns null for an unusable query', () => {
+    expect(replaceAllMatches('abc', '(', 'x', { ...PLAIN, isRegex: true })).toBeNull();
+    expect(replaceAllMatches('abc', '', 'x', PLAIN)).toBeNull();
+  });
+});
+
+/**
+ * The write path and the match list must be the SAME answer.
+ *
+ * They were not, and every case below was silent: the scan runs through
+ * CodeMirror's `RegExpCursor` (`gm` + `u`) while the replacement compiled the
+ * query itself (`g`/`gi`), so the count in the widget and the bytes written
+ * disagreed about anchors, unicode property escapes and which escapes are even
+ * legal. `find-scan.ts` now states the flags once (`BASE_FLAGS`), and these
+ * assert the two ends together rather than one engine in isolation.
+ */
+describe('the write path agrees with the scan', () => {
+  const REGEX: FindOptions = { ...PLAIN, isRegex: true };
+
+  test('an anchored pattern rewrites every line the scan counted', () => {
+    const text = 'foo\nbar\nfoo';
+    expect(findMatches(text, '^foo', REGEX).matches).toHaveLength(2);
+    expect(replaceAllMatches(text, '^foo', 'X', REGEX)).toBe('X\nbar\nX');
+
+    expect(findMatches(text, 'foo$', REGEX).matches).toHaveLength(2);
+    expect(replaceAllMatches(text, 'foo$', 'X', REGEX)).toBe('X\nbar\nX');
+  });
+
+  test('a unicode property escape finds AND replaces', () => {
+    const text = 'a1 b2';
+    expect(findMatches(text, '\\p{L}\\d', REGEX).matches).toHaveLength(2);
+    expect(replaceAllMatches(text, '\\p{L}\\d', 'X', REGEX)).toBe('X X');
+    expect(replaceMatch(text, { start: 0, end: 2 }, '\\p{L}\\d', 'X', REGEX)?.text).toBe('X b2');
+  });
+
+  test('an escape the scan calls invalid is refused by the write too', () => {
+    // `\-` is a legal identity escape without `u` and a syntax error with it.
+    expect(findMatches('a-b', '\\-', REGEX).invalid).toBe(true);
+    expect(replaceAllMatches('a-b', '\\-', 'X', REGEX)).toBeNull();
+  });
+
+  test('a zero-width match is replaced by nothing, exactly as it is uncounted', () => {
+    // The widget says "No results" for `^`; inserting at every line start under
+    // it was the write contradicting the count it was shown beside.
+    expect(findMatches('a\nb', '^', REGEX).matches).toEqual([]);
+    expect(replaceAllMatches('a\nb', '^', 'X', REGEX)).toBe('a\nb');
+    expect(replaceAllMatches('abc', 'x*', 'X', REGEX)).toBe('abc');
+  });
+});
+
+describe('expandReplacement', () => {
+  /** Indexed by group number, `[0]` unused — the shape `groupsOf` produces. */
+  const groups = { full: 'ab12', numbered: [undefined, 'a', 'b'] as const, named: { tail: '12' } };
+
+  test('expands $&, $1 and $<name>', () => {
+    expect(expandReplacement('$&|$1|$2|$<tail>', groups)).toBe('ab12|a|b|12');
+  });
+
+  test('$$ is a literal dollar and an unknown group is empty', () => {
+    expect(expandReplacement('$$$9', groups)).toBe('$');
+  });
+
+  test('a missing two-digit group falls back to the one-digit group plus the digit', () => {
+    // The engine's own reading of `$12` with two groups: `$1` then a literal `2`.
+    expect('x'.replace(/(x)/, '$12')).toBe('x2');
+    expect(expandReplacement('$12', groups)).toBe('a2');
+  });
+
+  test('a template without a dollar is returned as-is', () => {
+    expect(expandReplacement('plain', groups)).toBe('plain');
+  });
+});
+

package/src/shared/lib/code/editor/{find.ts → find-replace.ts}

@@ -3,117 +3,23 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { lineIndexAt, lineStartOffset, type TextRange } from '@/shared/lib/code/editor/lines';
-
-export { lineIndexAt, lineStartOffset };
-
 /**
- * Find and replace over one document buffer — the pure half of the editor's
- * find widget.
+ * Replacement expansion, split from the scan.
  *
- * Everything here is offset arithmetic on a string: what the query compiles
- * to, which ranges match, where the caret lands after a replacement, and how
- * `$1` is expanded. The widget, the hook that owns its state and the editor
- * surface that paints the matches all read these results, so none of them
- * re-implements a rule and the count in the widget cannot disagree with the
- * ranges on screen.
- */
-
-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 costs a Range in the highlight
- * registry, 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 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.
+ * The scan (`find-scan.ts`) answers "where does this query match"; this answers
+ * "what does one match become". They are separate because the search panel's
+ * replace PREVIEW and the write that actually lands must read ONE expansion
+ * rule — a row that painted `$1` literally over a file that would receive the
+ * captured group is the drift this module exists to prevent — while the scan has
+ * a different consumer (the find bar's match list and count).
  *
- * Whole-word is a `\b`-anchored non-capturing group rather than a bare wrap so
- * an alternation (`foo|bar`) keeps its own precedence.
+ * The template grammar is `String.prototype.replace`'s for a string replacement:
+ * `$$`, `$&`, `$1`–`$99` and `$<name>`. The prefix/suffix forms (`` $` `` /
+ * `$'`) are deliberately left literal — nothing in the UI offers them, and
+ * leaving the two characters alone is the honest reading.
  */
-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 ? 'g' : 'gi');
-  } catch {
-    return null;
-  }
-}
 
-/**
- * Every match of `query` in `text`, in document order.
- *
- * Zero-width matches (`^`, `\b`, `a*`) are skipped: they have nothing to
- * highlight and nothing to replace, and stepping past them is what keeps the
- * scan terminating.
- */
-export function findMatches(text: string, query: string, options: FindOptions): FindResult {
-  const regex = buildFindRegex(query, options);
-  if (!query) return { matches: [], truncated: false, invalid: false };
-  if (!regex) return { matches: [], truncated: false, invalid: true };
-
-  const matches: FindMatch[] = [];
-  let match: RegExpExecArray | null;
-  while ((match = regex.exec(text)) !== null) {
-    if (match[0].length === 0) {
-      regex.lastIndex += 1;
-      continue;
-    }
-    matches.push({ start: match.index, end: match.index + match[0].length });
-    if (matches.length >= MAX_FIND_MATCHES) return { matches, truncated: true, invalid: false };
-  }
-  return { matches, truncated: false, 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;
-}
+import { buildFindRegex, type FindMatch, type FindOptions } from '@/shared/lib/code/editor/find-scan';
 
 /** What a replacement template is expanded against. */
 export interface MatchGroups {
@@ -210,7 +116,16 @@ export function replaceMatch(
   };
 }
 
-/** Replace every match. Null when the query is empty or does not compile. */
+/**
+ * Replace every match. Null when the query is empty or does not compile.
+ *
+ * A ZERO-WIDTH match is left alone, exactly as the scan leaves it out of the
+ * list: `^`, `$`, `\b` and `a*` have nothing to highlight and nothing to
+ * replace, so a `^` query reads "No results" in the widget — and rewriting every
+ * line start under it was the write disagreeing with the count it was shown
+ * next to. (A non-empty literal query can never match zero characters, so this
+ * only ever applies to regex mode.)
+ */
 export function replaceAllMatches(
   text: string,
   query: string,
@@ -221,6 +136,7 @@ export function replaceAllMatches(
   if (!regex) return null;
   if (!options.isRegex) return text.replace(regex, () => replacement);
   return text.replace(regex, (...args: unknown[]) => {
+    if (String(args[0]).length === 0) return '';
     // A replacer's arguments are `(match, …groups, offset, string, groups?)`;
     // rebuilding an exec result from them keeps one expansion rule for both
     // the single and the bulk path.

package/src/shared/lib/code/editor/{find.test.ts → find-scan.test.ts}

@@ -4,28 +4,27 @@
  */
 
 /**
- * The find widget's arithmetic: what a query matches, where the caret lands
- * after a replacement, and how `$1` is expanded. These are the rules the widget
- * count, the on-screen highlights and the written buffer all read, so each is
- * asserted against the engine's own `String.replace` behaviour where one
- * exists.
+ * The find widget's scan: what a query matches and how the caret anchors to it.
+ *
+ * The scan runs on CodeMirror's `RegExpCursor`, so these cases are the CONTRACT
+ * that cursor has to keep — the same ordered list, the same case/whole-word/regex
+ * options, a broken pattern reported as `invalid` rather than as "no matches",
+ * and the cap. They are asserted here rather than through a live editor because
+ * the widget, the count and the painted marks all read this one function.
  */
 
 import { describe, expect, test } from 'bun:test';
 
 import {
   buildFindRegex,
-  expandReplacement,
   findMatches,
   lineIndexAt,
   lineStartOffset,
   matchIndexAtOrAfter,
   MAX_FIND_MATCHES,
-  replaceAllMatches,
-  replaceMatch,
   stepMatchIndex,
   type FindOptions,
-} from '@/shared/lib/code/editor/find';
+} from '@/shared/lib/code/editor/find-scan';
 
 const PLAIN: FindOptions = { matchCase: false, wholeWord: false, isRegex: false };
 
@@ -83,6 +82,17 @@ describe('findMatches', () => {
     expect(result.invalid).toBe(false);
   });
 
+  test('finds a match that begins at a line start, and one that spans lines', () => {
+    // The cursor searches line by line, so both edges are where it can lose a
+    // match: a pattern anchored at a line start, and one whose `\n` forces the
+    // whole-document path.
+    expect(findMatches('one\ntwo\ntwo', 'two', PLAIN).matches).toEqual([
+      { start: 4, end: 7 },
+      { start: 8, end: 11 },
+    ]);
+    expect(findMatches('one\ntwo', 'one\ntwo', { ...PLAIN, isRegex: true }).matches).toEqual([{ start: 0, end: 7 }]);
+  });
+
   test('caps the collected matches and says so', () => {
     const text = 'a'.repeat(MAX_FIND_MATCHES + 10);
     const result = findMatches(text, 'a', PLAIN);
@@ -104,70 +114,6 @@ describe('buildFindRegex', () => {
   });
 });
 
-describe('replaceMatch', () => {
-  test('literal replacement inserts the field verbatim, dollar signs included', () => {
-    const text = 'const a = 1;';
-    const result = replaceMatch(text, { start: 6, end: 7 }, 'a', '$&x', PLAIN);
-    expect(result?.text).toBe('const $&x = 1;');
-    expect(result?.caret).toBe(6 + 3);
-  });
-
-  test('regex replacement expands capture groups like String.replace', () => {
-    const text = 'key = value';
-    const result = replaceMatch(text, { start: 6, end: 11 }, '(\\w+)', '[$1]', { ...PLAIN, isRegex: true });
-    expect(result?.text).toBe('key = [value]');
-    expect(result?.caret).toBe(13);
-  });
-
-  test('refuses a match that is no longer at its offset', () => {
-    expect(replaceMatch('abc', { start: 5, end: 7 }, 'a', 'z', PLAIN)).toBeNull();
-  });
-});
-
-describe('replaceAllMatches', () => {
-  test('literal replace-all rewrites every occurrence', () => {
-    expect(replaceAllMatches('a a a', 'a', 'b', PLAIN)).toBe('b b b');
-  });
-
-  test('regex replace-all agrees with the engine', () => {
-    const text = 'foo1 bar2';
-    const options: FindOptions = { ...PLAIN, isRegex: true };
-    expect(replaceAllMatches(text, '([a-z]+)(\\d)', '$2-$1', options)).toBe(text.replace(/([a-z]+)(\d)/g, '$2-$1'));
-  });
-
-  test('whole-word replace-all leaves substrings alone', () => {
-    expect(replaceAllMatches('cat category', 'cat', 'dog', { ...PLAIN, wholeWord: true })).toBe('dog category');
-  });
-
-  test('returns null for an unusable query', () => {
-    expect(replaceAllMatches('abc', '(', 'x', { ...PLAIN, isRegex: true })).toBeNull();
-    expect(replaceAllMatches('abc', '', 'x', PLAIN)).toBeNull();
-  });
-});
-
-describe('expandReplacement', () => {
-  /** Indexed by group number, `[0]` unused — the shape `groupsOf` produces. */
-  const groups = { full: 'ab12', numbered: [undefined, 'a', 'b'] as const, named: { tail: '12' } };
-
-  test('expands $&, $1 and $<name>', () => {
-    expect(expandReplacement('$&|$1|$2|$<tail>', groups)).toBe('ab12|a|b|12');
-  });
-
-  test('$$ is a literal dollar and an unknown group is empty', () => {
-    expect(expandReplacement('$$$9', groups)).toBe('$');
-  });
-
-  test('a missing two-digit group falls back to the one-digit group plus the digit', () => {
-    // The engine's own reading of `$12` with two groups: `$1` then a literal `2`.
-    expect('x'.replace(/(x)/, '$12')).toBe('x2');
-    expect(expandReplacement('$12', groups)).toBe('a2');
-  });
-
-  test('a template without a dollar is returned as-is', () => {
-    expect(expandReplacement('plain', groups)).toBe('plain');
-  });
-});
-
 describe('caret anchoring', () => {
   test('lineIndexAt and lineStartOffset are inverses for every line start', () => {
     const text = 'one\ntwo\n\nfour';

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