ompchamber 3.0.0 → 3.1.0

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

@@ -0,0 +1,321 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's find/replace state machine.
+ *
+ * Owns the query, the option toggles, which match is "current", and the two
+ * write paths (replace one, replace all). Every rule it applies lives in
+ * `shared/lib/code/editor/find`, so the count in the widget, the marks painted
+ * on the surface and the bytes written back are the same list — the failure
+ * this shape exists to prevent is a widget that says "3 of 7" over highlights
+ * that disagree.
+ *
+ * The query and the toggles persist per session; whether the bar is OPEN does
+ * not. A reload that reopened a find bar over the file would be noise the user
+ * never asked for, and the same reasoning keeps the btw panel unpersisted.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'preact/hooks';
+
+import { useSessionState } from '@/client/hooks/workspace/session-state';
+import {
+  DEFAULT_FIND_OPTIONS,
+  findMatches,
+  matchIndexAtOrAfter,
+  replaceAllMatches,
+  replaceMatch,
+  stepMatchIndex,
+  type FindOptions,
+} from '@/shared/lib/code/editor/find';
+import type { EditorCommand } from '@/shared/lib/code/editor/keymap';
+
+export interface UseEditorFindOptions {
+  /** The buffer on screen. */
+  text: string;
+  /** Identity of the open document — a switch re-seeds the current match. */
+  documentKey: string;
+  /** Current selection, used to seed the query the way VS Code does. */
+  readSelection: () => { start: number; end: number } | null;
+  select: (start: number, end: number, focus?: boolean) => void;
+  reveal: (offset: number) => void;
+  /** Replace the buffer as ONE undoable edit; focus stays where the caller wants it. */
+  applyDocument: (value: string, caretStart: number, caretEnd: number) => void;
+  /** ⌥Z / Alt+Z — word wrap belongs to the editor panel, not to this hook. */
+  toggleWordWrap?: () => void;
+}
+
+export interface EditorFindState {
+  open: boolean;
+  replaceOpen: boolean;
+  query: string;
+  replacement: string;
+  options: FindOptions;
+  matches: readonly { start: number; end: number }[];
+  /** The document holds more matches than the cap. */
+  truncated: boolean;
+  /** The query does not compile as a regex — a different answer from "no matches". */
+  invalid: boolean;
+  currentIndex: number;
+  setQuery: (value: string) => void;
+  setReplacement: (value: string) => void;
+  openFind: () => void;
+  openReplace: () => void;
+  /** Expand/collapse the replace row without changing which match is current. */
+  toggleReplace: () => void;
+  /** Bumped on every "open find" so the widget can refocus its field. */
+  focusRequest: number;
+  close: () => void;
+  /** Dispatch a keymap command (⌘F, F3, ⌥⌘C, …). */
+  runCommand: (command: EditorCommand) => void;
+  toggleOption: (key: keyof FindOptions) => void;
+  step: (direction: 1 | -1) => void;
+  replaceCurrent: () => void;
+  replaceAll: () => void;
+}
+
+/** A seeded query must be one line of real text, like VS Code's. */
+function seedQuery(text: string, selection: { start: number; end: number } | null): string | null {
+  if (!selection || selection.start === selection.end) return null;
+  const selected = text.slice(selection.start, selection.end);
+  if (!selected || selected.includes('\n') || selected.length > 200) return null;
+  return selected;
+}
+
+export function useEditorFind({
+  text,
+  documentKey,
+  readSelection,
+  select,
+  reveal,
+  applyDocument,
+  toggleWordWrap,
+}: UseEditorFindOptions): EditorFindState {
+  const [query, setQueryState] = useSessionState<string>('editor.findQuery', '');
+  const [replacement, setReplacement] = useSessionState<string>('editor.findReplace', '');
+  const [storedOptions, setOptions] = useSessionState<FindOptions>('editor.findOptions', DEFAULT_FIND_OPTIONS);
+  // A blob written before an option existed carries only the keys it had, so
+  // the read is merged over the defaults rather than trusted wholesale.
+  const options = useMemo<FindOptions>(() => ({ ...DEFAULT_FIND_OPTIONS, ...storedOptions }), [storedOptions]);
+  const [open, setOpen] = useState(false);
+  const [replaceOpen, setReplaceOpen] = useState(false);
+  const [currentIndex, setCurrentIndex] = useState(-1);
+  /** Bumped by every open request so the widget can refocus its field. */
+  const [focusRequest, setFocusRequest] = useState(0);
+  /**
+   * Bumped whenever the current match must be re-resolved even though the match
+   * LIST has not changed — opening the bar on an unchanged query, or switching
+   * documents (where the offsets mean something else entirely). Without it the
+   * resolve effect never ran and the bar kept pointing at the previous file's
+   * index.
+   */
+  const [resolveRequest, setResolveRequest] = useState(0);
+  /** Read outside the callbacks: "already open" must not re-seed the query. */
+  const openRef = useRef(false);
+  openRef.current = open;
+
+  const result = useMemo(() => findMatches(text, query, options), [text, query, options]);
+
+  /**
+   * Where the current match is resolved FROM: the caret/anchor a reseed uses.
+   * A step and a replacement both move it, which is what keeps "next match"
+   * meaning the one after the one just replaced.
+   */
+  const anchorRef = useRef(0);
+  /** The next match-list change re-resolves the current match from the anchor. */
+  const reseedRef = useRef(true);
+
+  // Live mirrors: `reveal`/`select` close over the surface's own layout state,
+  // and the effects below must not re-run because a callback identity moved.
+  const revealRef = useRef(reveal);
+  revealRef.current = reveal;
+  const selectRef = useRef(select);
+  selectRef.current = select;
+
+  const reseed = useCallback((anchor: number) => {
+    anchorRef.current = anchor;
+    reseedRef.current = true;
+  }, []);
+
+  // A new document starts from the top: the offsets of the previous file's
+  // match say nothing about this one. The token is what makes the resolve below
+  // run when the match list itself is unchanged.
+  useEffect(() => {
+    reseed(0);
+    setResolveRequest((previous) => previous + 1);
+  }, [documentKey, reseed]);
+
+  // Resolve the current match whenever the match list moves under it — a
+  // keystroke in the query, a toggle, an edit, a replacement. Only a reseed
+  // scrolls: an edit in the document must not yank the view back to a match
+  // the user is no longer looking at.
+  useEffect(() => {
+    const matches = result.matches;
+    if (reseedRef.current) {
+      reseedRef.current = false;
+      const index = matchIndexAtOrAfter(matches, anchorRef.current);
+      setCurrentIndex(index);
+      if (index >= 0) {
+        selectRef.current(matches[index].start, matches[index].end, false);
+        revealRef.current(matches[index].start);
+      }
+      return;
+    }
+    setCurrentIndex((previous) => {
+      if (matches.length === 0) return -1;
+      if (previous < 0) return matchIndexAtOrAfter(matches, anchorRef.current);
+      return Math.min(previous, matches.length - 1);
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [result, resolveRequest]);
+
+  const setQuery = useCallback(
+    (value: string) => {
+      setQueryState(value);
+      // Typing in the field is an explicit re-aim: the first match at or after
+      // the caret the widget opened on is the one the user means.
+      reseed(anchorRef.current);
+    },
+    [setQueryState, reseed],
+  );
+
+  const openFind = useCallback(() => {
+    setFocusRequest((previous) => previous + 1);
+    // Already open: ⌘F is a request for the field, not a new search. Re-seeding
+    // here would overwrite what the user typed with the current match's text,
+    // since the widget keeps that match selected in the document.
+    if (openRef.current) return;
+    const selection = readSelection();
+    const seeded = seedQuery(text, selection);
+    if (seeded) setQueryState(seeded);
+    reseed(selection ? selection.start : 0);
+    setOpen(true);
+    // The replace row is NOT collapsed here: ⌥⌘F opens the bar with it already
+    // showing, and this function is the path it takes.
+    setResolveRequest((previous) => previous + 1);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [text, readSelection, reseed, setQueryState]);
+
+  const openReplace = useCallback(() => {
+    setReplaceOpen(true);
+    openFind();
+  }, [openFind]);
+
+  const toggleReplace = useCallback(() => setReplaceOpen((prev) => !prev), []);
+
+  const close = useCallback(() => {
+    setOpen(false);
+    setReplaceOpen(false);
+    // Focus returns to the match, which is where the user was looking.
+    const match = result.matches[currentIndex];
+    if (match) select(match.start, match.end, true);
+  }, [result.matches, currentIndex, select]);
+
+  const step = useCallback(
+    (direction: 1 | -1) => {
+      const matches = result.matches;
+      if (matches.length === 0) return;
+      const index = stepMatchIndex(currentIndex, matches.length, direction);
+      setCurrentIndex(index);
+      anchorRef.current = matches[index].end;
+      // Selection is set without stealing focus: the user may be typing in the
+      // find field, and the current-match mark is what shows where it landed.
+      select(matches[index].start, matches[index].end, false);
+      reveal(matches[index].start);
+    },
+    [result.matches, currentIndex, select, reveal],
+  );
+
+  const toggleOption = useCallback(
+    (key: keyof FindOptions) => {
+      setOptions({ ...options, [key]: !options[key] });
+      reseed(anchorRef.current);
+    },
+    [options, setOptions, reseed],
+  );
+
+  const replaceCurrent = useCallback(() => {
+    const match = result.matches[currentIndex];
+    if (!match) return;
+    const next = replaceMatch(text, match, query, replacement, options);
+    if (!next) return;
+    // Focus stays in the widget: "Replace" is a button the user is about to
+    // press again, and pulling focus into the document would eat the next ⌘⌥F.
+    applyDocument(next.text, next.caret, next.caret);
+    reseed(next.caret);
+  }, [result.matches, currentIndex, text, query, replacement, options, applyDocument, reseed]);
+
+  const replaceAll = useCallback(() => {
+    const next = replaceAllMatches(text, query, replacement, options);
+    if (next === null || next === text) return;
+    const caret = Math.min(anchorRef.current, next.length);
+    applyDocument(next, caret, caret);
+    reseed(caret);
+  }, [text, query, replacement, options, applyDocument, reseed]);
+
+  const runCommand = useCallback(
+    (command: EditorCommand) => {
+      switch (command) {
+        case 'find':
+          openFind();
+          return;
+        case 'replace':
+          openReplace();
+          return;
+        case 'nextMatch':
+          step(1);
+          return;
+        case 'previousMatch':
+          step(-1);
+          return;
+        case 'replaceOne':
+          replaceCurrent();
+          return;
+        case 'replaceAll':
+          replaceAll();
+          return;
+        case 'toggleCaseSensitive':
+          toggleOption('matchCase');
+          return;
+        case 'toggleWholeWord':
+          toggleOption('wholeWord');
+          return;
+        case 'toggleRegex':
+          toggleOption('isRegex');
+          return;
+        case 'toggleWordWrap':
+          toggleWordWrap?.();
+          return;
+        default:
+          return;
+      }
+    },
+    [openFind, openReplace, step, replaceCurrent, replaceAll, toggleOption, toggleWordWrap],
+  );
+
+  return {
+    open,
+    replaceOpen,
+    query,
+    replacement,
+    options,
+    matches: result.matches,
+    truncated: result.truncated,
+    invalid: result.invalid,
+    currentIndex,
+    setQuery,
+    setReplacement,
+    openFind,
+    openReplace,
+    toggleReplace,
+    focusRequest,
+    close,
+    runCommand,
+    toggleOption,
+    step,
+    replaceCurrent,
+    replaceAll,
+  };
+}

package/src/client/hooks/editor/use-editor-history.test.ts

@@ -0,0 +1,216 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's undo stack.
+ *
+ * The rule under test is the one that was wrong: the re-seed exists for a value
+ * replaced from the OUTSIDE (a file switch, a refresh), but it also fired for
+ * the component's own edits — every keystroke pushed a second, identical entry,
+ * so the first ⌘Z restored the buffer to the state it was already in and undo
+ * looked broken until the second press. `markApplied` is what separates the two,
+ * and these assertions are what keeps it separating them.
+ *
+ * Runs against a real DOM (happy-dom) because it is a Preact hook holding a
+ * `<textarea>`; the modules below are imported dynamically, after those globals
+ * exist (Preact binds its environment at evaluation time).
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { h as PreactH, render as PreactRender } from 'preact';
+import type { act as PreactAct } from 'preact/test-utils';
+import type { EditorHistory, useEditorHistory as UseEditorHistoryHook } from '@/client/hooks/editor/use-editor-history';
+
+let useEditorHistory: typeof UseEditorHistoryHook;
+let h: typeof PreactH;
+let render: typeof PreactRender;
+let act: typeof PreactAct;
+
+let api: EditorHistory | null = null;
+let container: HTMLElement;
+let textarea: HTMLTextAreaElement;
+
+/** The buffer the hook is told is on screen, changed from the outside by a test. */
+let externalValue = 'one';
+
+function Harness() {
+  api = useEditorHistory({
+    value: externalValue,
+    inputRef: { current: textarea },
+    onValueChange: (next) => {
+      textarea.value = next;
+    },
+  });
+  return null;
+}
+
+/** Flush the effect that watches `value`, with no timers: it resolves on a render. */
+async function flush() {
+  for (let i = 0; i < 3; i++) {
+    await act(async () => {
+      for (let turn = 0; turn < 4; turn++) await Promise.resolve();
+    });
+  }
+}
+
+function domGlobals(win: Window): Record<string, unknown> {
+  return {
+    window: win,
+    document: win.document,
+    navigator: win.navigator,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+    HTMLTextAreaElement: win.HTMLTextAreaElement,
+  };
+}
+
+const installed: Record<string, unknown> = {};
+const displaced: Record<string, unknown> = {};
+
+beforeAll(async () => {
+  const win = new Window({ url: 'http://localhost' });
+  for (const [key, value] of Object.entries(domGlobals(win))) {
+    displaced[key] = (globalThis as Record<string, unknown>)[key];
+    installed[key] = value;
+    (globalThis as Record<string, unknown>)[key] = value;
+  }
+  ({ useEditorHistory } = await import('@/client/hooks/editor/use-editor-history'));
+  ({ h, render } = await import('preact'));
+  ({ act } = await import('preact/test-utils'));
+});
+
+afterAll(() => {
+  for (const key of Object.keys(installed)) {
+    if (displaced[key] === undefined) delete (globalThis as Record<string, unknown>)[key];
+    else (globalThis as Record<string, unknown>)[key] = displaced[key];
+  }
+});
+
+beforeEach(async () => {
+  api = null;
+  externalValue = 'one';
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  textarea = document.createElement('textarea');
+  textarea.value = 'one';
+  container.appendChild(textarea);
+  await act(async () => {
+    render(h(Harness, {}), container);
+  });
+});
+
+afterEach(() => {
+  render(null, container);
+  container.remove();
+});
+
+describe('useEditorHistory', () => {
+  test('commit writes the buffer, the caret and the caller’s state', async () => {
+    await act(async () => {
+      api?.commit({ value: 'two', selectionStart: 2, selectionEnd: 2 });
+    });
+
+    expect(textarea.value).toBe('two');
+    expect(textarea.selectionStart).toBe(2);
+  });
+
+  test('an external value replacement is recorded, so undo reaches the old file', async () => {
+    // A file switch: the hook did not write this, so it becomes a history entry
+    // rather than silently replacing the stack.
+    externalValue = 'switched';
+    await act(async () => {
+      render(h(Harness, {}), container);
+    });
+    await flush();
+
+    await act(async () => {
+      api?.step('undo');
+    });
+
+    expect(textarea.value).toBe('one');
+  });
+
+  test('a value the hook itself wrote is NOT re-recorded', async () => {
+    // The bug this guards: an extra entry per keystroke made the first ⌘Z a
+    // no-op, because it restored the buffer to what was already on screen.
+    await act(async () => {
+      api?.commit({ value: 'two', selectionStart: 2, selectionEnd: 2 });
+    });
+    externalValue = 'two';
+    await act(async () => {
+      render(h(Harness, {}), container);
+    });
+    await flush();
+
+    await act(async () => {
+      api?.step('undo');
+    });
+
+    // One press reaches the ORIGINAL buffer; a duplicate entry would have
+    // restored 'two' again.
+    expect(textarea.value).toBe('one');
+  });
+
+  test('markApplied declares a browser edit as already recorded', async () => {
+    await act(async () => {
+      api?.markApplied('typed');
+    });
+    externalValue = 'typed';
+    await act(async () => {
+      render(h(Harness, {}), container);
+    });
+    await flush();
+
+    await act(async () => {
+      api?.step('undo');
+    });
+
+    // Nothing was pushed for `typed`, so there is nothing to step back to: the
+    // stack still holds only the initial record.
+    expect(textarea.value).toBe('one');
+  });
+
+  test('step at the ends of the stack is a no-op', async () => {
+    await act(async () => {
+      api?.step('undo');
+    });
+    const afterUndo = textarea.value;
+    await act(async () => {
+      api?.step('redo');
+    });
+
+    expect(afterUndo).toBe('one');
+    expect(textarea.value).toBe('one');
+  });
+
+  test('commitEdit supersedes the top entry, keeping its caret for the undo', async () => {
+    // A line command replaces a whole range at once; undo must return the caret
+    // to the selection the command replaced, not to where the edit ended.
+    textarea.selectionStart = 1;
+    textarea.selectionEnd = 3;
+    await act(async () => {
+      api?.commitEdit({ value: 'one-changed', selectionStart: 11, selectionEnd: 11 });
+    });
+    await act(async () => {
+      api?.step('undo');
+    });
+
+    expect(textarea.value).toBe('one');
+    expect(textarea.selectionStart).toBe(1);
+    expect(textarea.selectionEnd).toBe(3);
+  });
+
+  test('the exposed buffer is never a render behind', async () => {
+    // `handleChange` diffs against this; a value that lagged a keystroke read a
+    // one-character edit as a whole-word replacement.
+    await act(async () => {
+      api?.commit({ value: 'fresh', selectionStart: 5, selectionEnd: 5 });
+    });
+
+    expect(api?.buffer).toBe('fresh');
+  });
+});

package/src/client/hooks/editor/use-editor-history.ts

@@ -0,0 +1,134 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's undo stack, wired to the DOM node.
+ *
+ * `history.ts` is the pure bookkeeping (push, merge, step, cap); this is the
+ * part that has to touch the `<textarea>`: committing an edit as one entry,
+ * restoring a stepped record, and re-seeding the stack when the value is
+ * replaced from the OUTSIDE.
+ *
+ * The re-seed is the subtle one. It exists for a file switch or a refresh, but
+ * a naive `[value]` effect also fires for the component's own edits — every
+ * keystroke then pushed a second, identical entry, so the first ⌘Z restored the
+ * buffer to the state it was already in and undo looked broken until the second
+ * press (and the no-op `onValueChange` truncated the redo stack). The `applied`
+ * ref is what distinguishes "someone else replaced the value" from "we did".
+ */
+
+import { useEffect, useRef } from 'preact/hooks';
+
+import { createHistory, pushEdit, pushRecord, stepHistory, type History, type HistoryRecord } from '@/shared/lib/code/editor/history';
+
+/** The fields every write path needs: a buffer and where the caret goes. */
+export type HistoryEdit = Pick<HistoryRecord, 'value' | 'selectionStart' | 'selectionEnd'>;
+
+export interface EditorHistory {
+  /** The stack itself, for the typing-burst merge in the change handler. */
+  history: History;
+  /**
+   * The buffer as this component last knew it — its own writes included, and
+   * never a render behind. Diffing a browser edit has to start from here: the
+   * `value` prop lags a keystroke, and a stale `before` reads a one-character
+   * edit as a whole-word replacement.
+   */
+  readonly buffer: string;
+  /** Commit an edit as ONE undoable entry. */
+  commit: (edit: HistoryEdit) => void;
+  /**
+   * Commit an edit that SUPERSEDES the entry on top, keeping that entry's
+   * caret so undo returns to the selection the edit replaced.
+   */
+  commitEdit: (edit: HistoryEdit) => void;
+  /** Step the stack and restore the record; no-op at either end. */
+  step: (direction: 'undo' | 'redo') => void;
+  /**
+   * Declare a value the BROWSER produced as already applied, so the re-seed
+   * effect below does not record it a second time. The change handler calls
+   * this for every keystroke and every replicated multi-cursor edit.
+   */
+  markApplied: (value: string) => void;
+}
+
+export interface UseEditorHistoryOptions {
+  /** The controlled buffer, used to detect an external replacement. */
+  value: string;
+  /** The live `<textarea>`, so an external replacement records its own caret. */
+  inputRef: { current: HTMLTextAreaElement | null };
+  /** Push the committed buffer to the caller. */
+  onValueChange: (value: string) => void;
+}
+
+export function useEditorHistory({ value, inputRef, onValueChange }: UseEditorHistoryOptions): EditorHistory {
+  const historyRef = useRef<History>(createHistory());
+  /** The value this component itself last wrote — see the module note. */
+  const appliedRef = useRef<string | null>(null);
+
+  // Re-record when the controlled value is replaced from the outside
+  // (file switch, refresh) so undo does not jump between documents.
+  useEffect(() => {
+    const input = inputRef.current;
+    if (!input || appliedRef.current === value) return;
+    appliedRef.current = value;
+    pushRecord(historyRef.current, {
+      value: input.value,
+      selectionStart: input.selectionStart,
+      selectionEnd: input.selectionEnd,
+      timestamp: Date.now(),
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value]);
+
+  /** Put a buffer on screen without touching the stack. */
+  const write = (edit: HistoryEdit) => {
+    appliedRef.current = edit.value;
+    onValueChange(edit.value);
+    const input = inputRef.current;
+    if (!input) return;
+    input.value = edit.value;
+    input.selectionStart = edit.selectionStart;
+    input.selectionEnd = edit.selectionEnd;
+  };
+
+  return {
+    history: historyRef.current,
+
+    get buffer() {
+      return appliedRef.current ?? value;
+    },
+
+    commit: (edit) => {
+      pushEdit(historyRef.current, { ...edit, timestamp: Date.now() });
+      write(edit);
+    },
+
+    commitEdit: (edit) => {
+      const history = historyRef.current;
+      const last = history.stack[history.offset];
+      const input = inputRef.current;
+      if (last && input) {
+        // The entry on top is about to be superseded: keep where its caret was,
+        // so undo returns to the selection this edit replaced.
+        history.stack[history.offset] = {
+          ...last,
+          selectionStart: input.selectionStart,
+          selectionEnd: input.selectionEnd,
+        };
+      }
+      pushEdit(history, { ...edit, timestamp: Date.now() });
+      write(edit);
+    },
+
+    step: (direction) => {
+      const record = stepHistory(historyRef.current, direction);
+      if (record) write(record);
+    },
+
+    markApplied: (next) => {
+      appliedRef.current = next;
+    },
+  };
+}