ompchamber 2.0.2 → 3.1.0

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;
+    },
+  };
+}

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

@@ -19,10 +19,6 @@ export interface FileEditorTarget {
 }
 
 export interface UseFileEditorOptions {
-  /** Content substituted when a read fails (desktop). Omit to report the failure (mobile). */
-  fallback?: (name: string) => string;
-  /** Surface read failures through `loadError` instead of silently substituting `fallback`. */
-  reportLoadError?: boolean;
   /** Flush a pending debounced write on unmount so closing the editor cannot drop an edit. */
   flushOnUnmount?: boolean;
   /** Mark a failed write as `'error'`; otherwise the status returns to `'idle'`. */
@@ -74,8 +70,6 @@ export function useFileEditor(
   options: UseFileEditorOptions = {},
 ): UseFileEditorResult {
   const {
-    fallback,
-    reportLoadError = false,
     flushOnUnmount = false,
     reportSaveError = false,
     downloadMimeType = 'text/plain',
@@ -184,11 +178,9 @@ export function useFileEditor(
     }
 
     if (!target.path) {
-      if (reportLoadError) {
-        setLoadError('No file path supplied for this attachment.');
-        return;
-      }
-      remember(fileKey, fallback ? fallback(target.name) : '');
+      // An attachment chip with no path has nothing to read and nothing to
+      // save; the message is the honest outcome.
+      setLoadError('No file path supplied for this attachment.');
       return;
     }
 
@@ -203,14 +195,11 @@ export function useFileEditor(
     if (target.repo && target.repo !== '.') params.set('repo', target.repo);
     fetch(`/api/fs/read?${params.toString()}`)
       .then(async (res) => {
-        const data = await res.json().catch(() => null);
-        if (reportLoadError) {
-          if (!res.ok || !data || typeof data.content !== 'string') {
-            throw new Error((data as { error?: string } | null)?.error || `HTTP ${res.status}`);
-          }
-          return data.content as string;
+        const data = (await res.json().catch(() => null)) as { content?: unknown; error?: string } | null;
+        if (!res.ok || !data || typeof data.content !== 'string') {
+          throw new Error(data?.error || `HTTP ${res.status}`);
         }
-        return typeof data?.content === 'string' ? (data.content as string) : null;
+        return data.content;
       })
       .then((text) => {
         if (cancelled) return;
@@ -222,18 +211,16 @@ export function useFileEditor(
         if (typed !== undefined && typed !== baselinesRef.current[fileKey]) return;
         const queued = pendingRef.current;
         if (queued && targetKey(queued.file) === fileKey) return;
-        remember(fileKey, text ?? (fallback ? fallback(target.name) : ''));
+        remember(fileKey, text);
       })
       .catch((err: unknown) => {
         if (cancelled) return;
         // A failed re-read keeps what is on screen; only a first load reports.
         if (!firstLoad) return;
-        if (reportLoadError) {
-          remember(fileKey, '');
-          setLoadError(err instanceof Error ? err.message : 'Failed to read file');
-        } else {
-          remember(fileKey, fallback ? fallback(target.name) : '');
-        }
+        // An empty buffer, never a substitute: the next save would write the
+        // substitute over the real file.
+        remember(fileKey, '');
+        setLoadError(err instanceof Error ? err.message : 'Failed to read file');
       })
       .finally(() => {
         if (!cancelled) setIsLoading(false);
@@ -242,7 +229,7 @@ export function useFileEditor(
     return () => {
       cancelled = true;
     };
-  }, [key, target, fallback, reportLoadError, remember, revision, isImage]);
+  }, [key, target, remember, revision, isImage]);
 
   useEffect(() => {
     if (saveStatus !== 'saved') return;
@@ -250,6 +237,13 @@ export function useFileEditor(
     return () => window.clearTimeout(timer);
   }, [saveStatus]);
 
+  // The save status describes the file that was written, so it must not outlive
+  // that tab: opening another file used to keep showing the previous file's
+  // "Save failed" (and its error icon) against a file that was never saved.
+  useEffect(() => {
+    setSaveStatus('idle');
+  }, [key]);
+
   const onChange = useCallback(
     (next: string) => {
       if (!target || isImage) return;
@@ -268,6 +262,9 @@ export function useFileEditor(
 
   const saveNow = useCallback(() => {
     if (!target || isImage) return;
+    // A file whose read failed has no trustworthy buffer: saving it would write
+    // the empty placeholder over the real file. The user must reopen it first.
+    if (loadError) return;
     const text = contents[targetKey(target)];
     if (text === undefined) return;
     if (pendingRef.current) {
@@ -275,7 +272,7 @@ export function useFileEditor(
       pendingRef.current = null;
     }
     void persistRef.current(target, text);
-  }, [target, contents, isImage]);
+  }, [target, contents, isImage, loadError]);
 
   const { copied, copy, download } = useFileTransfer({
     target,

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

@@ -0,0 +1,236 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `useOccurrences` — the ranges behind ⌘D, ⌘⇧L and ⌘⇧D.
+ *
+ * The rules live in `shared/lib/code/editor/occurrences` and are tested there;
+ * what this file covers is the hook's own contract: the caller's copy wins
+ * (clearing the ranges in the panel must clear them here), every change is
+ * announced so the surface repaints, and the textarea is read rather than
+ * assumed.
+ *
+ * Runs against a real DOM (happy-dom) because it is a Preact hook; the modules
+ * below are imported dynamically, after those globals exist.
+ */
+
+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 { OccurrencesApi, useOccurrences as UseOccurrencesHook } from '@/client/hooks/editor/use-occurrences';
+import type { TextRange } from '@/shared/lib/code/editor/commands';
+
+let useOccurrences: typeof UseOccurrencesHook;
+let h: typeof PreactH;
+let render: typeof PreactRender;
+let act: typeof PreactAct;
+
+let api: OccurrencesApi | null = null;
+let container: HTMLElement;
+let textarea: HTMLTextAreaElement;
+/** What the caller passes in as its own copy, changed per test. */
+let controlled: TextRange[] | undefined;
+const announced: Array<readonly TextRange[]> = [];
+const selections: Array<[number, number]> = [];
+
+function Harness() {
+  api = useOccurrences({
+    controlled,
+    onChange: (ranges) => announced.push(ranges),
+  });
+  return null;
+}
+
+async function flush() {
+  for (let i = 0; i < 3; i++) {
+    await act(async () => {
+      for (let turn = 0; turn < 4; turn++) await Promise.resolve();
+    });
+  }
+}
+
+async function rerender() {
+  await act(async () => {
+    render(h(Harness, {}), container);
+  });
+  await flush();
+}
+
+function select(start: number, end = start) {
+  textarea.selectionStart = start;
+  textarea.selectionEnd = end;
+}
+
+/**
+ * Stands in for the editor's own `select`: it MOVES the textarea's selection and
+ * records it. The hook reads the textarea, so a callback that only recorded the
+ * range would leave every later press looking at the original caret.
+ */
+function selectingSurface() {
+  return (start: number, end: number) => {
+    selections.push([start, end]);
+    select(start, end);
+  };
+}
+
+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;
+  }
+  ({ useOccurrences } = await import('@/client/hooks/editor/use-occurrences'));
+  ({ 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;
+  controlled = undefined;
+  announced.length = 0;
+  selections.length = 0;
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  textarea = document.createElement('textarea');
+  textarea.value = 'alpha beta alpha gamma alpha';
+  container.appendChild(textarea);
+  await rerender();
+});
+
+afterEach(() => {
+  render(null, container);
+  container.remove();
+});
+
+describe('useOccurrences', () => {
+  test('starts with no extra ranges', () => {
+    expect(api?.ranges).toEqual([]);
+  });
+
+  test('⌘D selects the word first, then grows one occurrence per press', async () => {
+    select(2);
+    await act(async () => {
+      api?.selectNext(textarea, selectingSurface());
+    });
+    expect(selections.at(-1)).toEqual([0, 5]);
+    expect(api?.ranges).toEqual([]);
+
+    await act(async () => {
+      api?.selectNext(textarea, selectingSurface());
+    });
+    expect(api?.ranges).toEqual([{ start: 11, end: 16 }]);
+  });
+
+  test('⌘⇧L takes every occurrence, primary first', async () => {
+    select(0, 5);
+    await act(async () => {
+      api?.selectAll(textarea, selectingSurface());
+    });
+
+    expect(selections.at(-1)).toEqual([0, 5]);
+    expect(api?.ranges).toEqual([
+      { start: 11, end: 16 },
+      { start: 23, end: 28 },
+    ]);
+  });
+
+  test('every change is announced so the surface can repaint', async () => {
+    select(0, 5);
+    await act(async () => {
+      api?.selectAll(textarea, () => {});
+    });
+
+    expect(announced.at(-1)?.length).toBe(2);
+  });
+
+  test('clear drops every range and says so', async () => {
+    select(0, 5);
+    await act(async () => {
+      api?.selectAll(textarea, () => {});
+    });
+    await act(async () => {
+      api?.clear();
+    });
+
+    expect(api?.ranges).toEqual([]);
+    expect(announced.at(-1)).toEqual([]);
+  });
+
+  test('the caller’s copy is authoritative', async () => {
+    // The panel can clear the ranges without the editor asking (a file switch,
+    // a save); the hook has to follow, not keep its own stale list.
+    controlled = [{ start: 1, end: 3 }];
+    await rerender();
+
+    expect(api?.ranges).toEqual([{ start: 1, end: 3 }]);
+
+    controlled = [];
+    await rerender();
+
+    expect(api?.ranges).toEqual([]);
+  });
+
+  test('⌘⇧D adds a caret below on the same column', async () => {
+    textarea.value = 'one\ntwo\nthree';
+    select(1);
+    await act(async () => {
+      api?.insertCursorBelow(textarea);
+    });
+
+    expect(api?.ranges).toEqual([{ start: 5, end: 5 }]);
+  });
+
+  test('⌘⇧D on the last line adds nothing', async () => {
+    textarea.value = 'one\ntwo';
+    select(5);
+    await act(async () => {
+      api?.insertCursorBelow(textarea);
+    });
+
+    expect(api?.ranges).toEqual([]);
+  });
+
+  test('replicate reports nothing without extra ranges', () => {
+    expect(api?.replicate('abc', 'abXc', { start: 2, end: 2 })).toBeNull();
+  });
+
+  test('replicate replays the browser’s edit at every extra range', async () => {
+    select(0, 5);
+    await act(async () => {
+      api?.selectAll(textarea, () => {});
+    });
+
+    // The browser replaced `alpha` at 0..5 with `Z`; the other two follow.
+    const applied = api?.replicate('alpha beta alpha gamma alpha', 'Z beta alpha gamma alpha', { start: 0, end: 5 });
+
+    expect(applied?.value).toBe('Z beta Z gamma Z');
+    expect(applied?.caret).toBe(1);
+    expect(applied?.rest.length).toBe(2);
+  });
+});