ompchamber 3.0.0 → 3.1.0

package/src/client/components/workspace/file-explorer/TreeItem.tsx

@@ -1,14 +1,11 @@
-import { useEffect, useRef, useState } from 'preact/hooks';
-import type { FormEvent } from 'preact/compat';
+import { useEffect, useState } from 'preact/hooks';
 import { ChevronDown, ChevronRight } from 'lucide-preact';
-import { useFetcher } from '@/client/lib/router/fetcher';
 import { FileIcon } from '@/client/components/common/file-icon';
-import { FileContextMenu, FileDeleteModal, FileHistoryModal, FileRenameModal } from '@/client/components/workspace/file-explorer/Modals';
+import { FileContextMenu, FileCreateModal, FileDeleteModal, FileHistoryModal, FileRenameModal } from '@/client/components/workspace/file-explorer/Modals';
 import { getGitStatusInfo, type FolderGitStatusInfo } from '@/shared/lib/fs/git-status';
-import { toAbsolutePath } from '@/shared/lib/fs/paths';
-import { copyToClipboard } from '@/client/hooks/ui/clipboard';
-import type { GitChange } from '@/shared/types/git';
+import { useFileActions } from '@/client/hooks/workspace/file-tree-actions';
 import { useOnClickOutside } from '@/client/hooks/ui/on-click-outside';
+import type { GitChange } from '@/shared/types/git';
 
 interface FileTreeItemProps {
   file: any;
@@ -41,16 +38,8 @@ export function FileTreeItem({
   const isFolder = file.type === 'folder';
   const [isOpen, setIsOpen] = useState(false);
   const [isLoadingChildren, setIsLoadingChildren] = useState(false);
-  const actionFetcher = useFetcher<any>();
+  /** Portals need a real document; the first client render is the gate. */
   const [mounted, setMounted] = useState(false);
-
-  const [contextMenu, setContextMenu] = useState<{ x: number, y: number } | null>(null);
-  const contextMenuRef = useRef<HTMLDivElement>(null);
-  const [showRenameModal, setShowRenameModal] = useState(false);
-  const [showDeleteModal, setShowDeleteModal] = useState(false);
-  const [showHistoryModal, setShowHistoryModal] = useState(false);
-  const [renameValue, setRenameValue] = useState(file.path);
-
   const children = Array.isArray(file.children) ? file.children : [];
 
   const normalizedPath = (file.path || '').replace(/^\/+/, '');
@@ -80,19 +69,13 @@ export function FileTreeItem({
     }
   }, [isFolder, actualIsOpen, file.children, file.path, onLoadChildren]);
 
-  useOnClickOutside(contextMenuRef, () => setContextMenu(null));
-
-  useEffect(() => {
-    if (actionFetcher.state === 'idle' && actionFetcher.data) {
-      if (actionFetcher.data.success) {
-        if (!actionFetcher.data.type) {
-          setShowRenameModal(false);
-          setShowDeleteModal(false);
-          onActionComplete();
-        }
-      }
-    }
-  }, [actionFetcher.state, actionFetcher.data]);
+  const actions = useFileActions({
+    file: { path: file.path, name: file.name, basePath, rootPath, repo },
+    diff: { staged: gitChange?.staged || (gitChange?.status ? gitChange.status[0] !== ' ' && gitChange.status[0] !== '?' : false), status: gitStatusInfo?.charStatus },
+    onOpenFile,
+    onActionComplete,
+  });
+  useOnClickOutside(actions.contextMenuRef, actions.closeContextMenu);
 
   const handleToggle = (e: globalThis.MouseEvent) => {
     e.stopPropagation();
@@ -121,72 +104,7 @@ export function FileTreeItem({
   const handleContextMenu = (e: globalThis.MouseEvent) => {
     e.preventDefault();
     e.stopPropagation();
-    setContextMenu({ x: e.clientX, y: e.clientY });
-  };
-
-  const submitAction = (formData: FormData) => {
-    if (repo && repo !== '.') formData.append('repo', repo);
-    if (rootPath) formData.append('root', rootPath);
-    actionFetcher.submit(formData, { method: 'post', action: '/api/fs/action' });
-  };
-
-  const handleAction = (actionType: string) => {
-    setContextMenu(null);
-    if (actionType === 'view') {
-      if (onOpenFile) {
-        onOpenFile({
-          ...file,
-          root: rootPath,
-          repo: repo || '.',
-        });
-      }
-    } else if (actionType === 'diff') {
-      window.dispatchEvent(new CustomEvent('omp:open-diff', {
-        detail: {
-          file: file.path,
-          staged: gitChange?.staged || (gitChange?.status && gitChange.status[0] !== ' ' && gitChange.status[0] !== '?'),
-          status: gitStatusInfo?.charStatus || 'M',
-          repo: repo || '.',
-          root: rootPath,
-        }
-      }));
-    } else if (actionType === 'explorer') {
-      const fd = new FormData();
-      fd.append('actionType', 'open_explorer');
-      fd.append('path', file.path);
-      submitAction(fd);
-    } else if (actionType === 'copy_path') {
-      void copyToClipboard(toAbsolutePath(basePath, file.path));
-    } else if (actionType === 'copy_relative') {
-      void copyToClipboard(file.path);
-    } else if (actionType === 'history') {
-      setShowHistoryModal(true);
-      const fd = new FormData();
-      fd.append('actionType', 'git_history');
-      fd.append('path', file.path);
-      submitAction(fd);
-    } else if (actionType === 'rename') {
-      setRenameValue(file.path);
-      setShowRenameModal(true);
-    } else if (actionType === 'delete') {
-      setShowDeleteModal(true);
-    }
-  };
-
-  const submitRename = (e: FormEvent) => {
-    e.preventDefault();
-    const fd = new FormData();
-    fd.append('actionType', 'rename');
-    fd.append('path', file.path);
-    fd.append('newPath', renameValue);
-    submitAction(fd);
-  };
-
-  const submitDelete = () => {
-    const fd = new FormData();
-    fd.append('actionType', 'delete');
-    fd.append('path', file.path);
-    submitAction(fd);
+    actions.openContextMenu(e.clientX, e.clientY);
   };
 
   return (
@@ -255,44 +173,56 @@ export function FileTreeItem({
         </div>
       )}
 
-      {mounted && contextMenu && (
+      {mounted && actions.contextMenu && (
         <FileContextMenu
-          x={contextMenu.x}
-          y={contextMenu.y}
+          x={actions.contextMenu.x}
+          y={actions.contextMenu.y}
           isFolder={isFolder}
           hasGitStatus={hasGitStatus}
-          onAction={handleAction}
+          onAction={actions.handleAction}
+        />
+      )}
+
+      {mounted && actions.showCreateModal && (
+        <FileCreateModal
+          folderPath={file.path}
+          value={actions.createName}
+          error={actions.createError}
+          isLoading={actions.busy}
+          onChange={actions.setCreateName}
+          onCancel={actions.closeCreate}
+          onSubmit={actions.submitCreate}
         />
       )}
 
-      {mounted && showDeleteModal && (
+      {mounted && actions.showDeleteModal && (
         <FileDeleteModal
           fileName={file.name}
           isFolder={isFolder}
-          isLoading={actionFetcher.state !== 'idle'}
-          onCancel={() => setShowDeleteModal(false)}
-          onConfirm={submitDelete}
+          isLoading={actions.busy}
+          onCancel={actions.closeDelete}
+          onConfirm={actions.submitDelete}
         />
       )}
 
-      {mounted && showRenameModal && (
+      {mounted && actions.showRenameModal && (
         <FileRenameModal
           isFolder={isFolder}
-          renameValue={renameValue}
+          renameValue={actions.renameValue}
           originalPath={file.path}
-          isLoading={actionFetcher.state !== 'idle'}
-          onChange={setRenameValue}
-          onCancel={() => setShowRenameModal(false)}
-          onSubmit={submitRename}
+          isLoading={actions.busy}
+          onChange={actions.setRenameValue}
+          onCancel={actions.closeRename}
+          onSubmit={actions.submitRename}
         />
       )}
 
-      {mounted && showHistoryModal && (
+      {mounted && actions.showHistoryModal && (
         <FileHistoryModal
           filePath={file.path}
-          fetcherState={actionFetcher.state}
-          fetcherData={actionFetcher.data}
-          onClose={() => setShowHistoryModal(false)}
+          fetcherState={actions.fetcherState}
+          fetcherData={actions.fetcherData}
+          onClose={actions.closeHistory}
         />
       )}
     </div>

package/src/client/components/workspace/todo-panel/PhaseGroup.tsx

@@ -0,0 +1,76 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One phase group of the todo panel: a header with the phase's own `closed/total`
+ * badge, then its task rows.
+ *
+ * The collapse state is the panel's (persisted per session), not local: a list
+ * the operator collapsed should stay collapsed across a reload, and the panel
+ * owns every phase's flag in one map so "collapse all" is one write.
+ */
+
+import { ChevronDown, ChevronRight } from 'lucide-preact';
+import type { TodoPhase } from '@/shared/types/todo';
+import { closedTaskCount } from '@/shared/lib/chat/todo/progress';
+import { TodoRow } from '@/client/components/workspace/todo-panel/Row';
+
+interface TodoPhaseGroupProps {
+  phase: TodoPhase;
+  index: number;
+  collapsed: boolean;
+  /** `phase:task` of the row to highlight as current, or null. */
+  currentKey: string | null;
+  onToggle: () => void;
+}
+
+export function TodoPhaseGroup({ phase, index, collapsed, currentKey, onToggle }: TodoPhaseGroupProps) {
+  const closed = closedTaskCount(phase);
+  const isComplete = phase.tasks.length > 0 && closed === phase.tasks.length;
+
+  return (
+    <div className="overflow-hidden rounded-lg border border-ink/10 bg-paper">
+      <button
+        type="button"
+        onClick={onToggle}
+        aria-expanded={!collapsed}
+        className="flex w-full items-center gap-1.5 border-b border-ink/8 bg-canvas/40 px-2.5 py-1.5 text-left hover:bg-ink/5"
+      >
+        {collapsed ? (
+          <ChevronRight size={12} className="shrink-0 text-ink/40" />
+        ) : (
+          <ChevronDown size={12} className="shrink-0 text-ink/40" />
+        )}
+        <span
+          className={`min-w-0 flex-1 truncate text-[10px] font-semibold uppercase tracking-wider ${
+            isComplete ? 'text-ink/35' : 'text-ink/60'
+          }`}
+          title={phase.name}
+        >
+          {index + 1}. {phase.name}
+        </span>
+        <span className="shrink-0 font-mono text-[9.5px] text-ink/40">
+          {closed}/{phase.tasks.length}
+        </span>
+      </button>
+
+      {!collapsed && (
+        <div className="divide-y divide-ink/[0.05] p-0.5">
+          {phase.tasks.length === 0 ? (
+            <div className="px-2.5 py-1.5 text-[11px] text-ink/40">No tasks in this phase</div>
+          ) : (
+            phase.tasks.map((task, taskIndex) => (
+              <TodoRow
+                key={`${taskIndex}-${task.content}`}
+                task={task}
+                current={currentKey === `${index}:${taskIndex}`}
+              />
+            ))
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/client/components/workspace/todo-panel/Row.tsx

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * One task row of the todo panel.
+ *
+ * The five statuses render through one component because they are one axis of
+ * the same row — icon, tone, and whether the text is struck through — and
+ * splitting them across branches is how a `blocked` task ends up drawn as an
+ * ordinary pending one. A blocked task also carries its own note (`blocker`),
+ * which is the only place omp records WHY it is waiting.
+ */
+
+import { Ban, CheckCircle2, Circle, Loader2, OctagonAlert } from 'lucide-preact';
+import type { TodoItem } from '@/shared/types/todo';
+import { taskNote, todoStatusVisual } from '@/shared/lib/chat/todo/progress';
+
+function StatusIcon({ status, className }: { status: TodoItem['status']; className: string }) {
+  switch (status) {
+    case 'completed':
+      return <CheckCircle2 size={13} className={className} />;
+    case 'in_progress':
+      return <Loader2 size={13} className={`${className} animate-spin`} />;
+    case 'abandoned':
+      return <Ban size={13} className={className} />;
+    case 'blocked':
+      return <OctagonAlert size={13} className={className} />;
+    default:
+      return <Circle size={13} className={className} />;
+  }
+}
+
+export function TodoRow({ task, current }: { task: TodoItem; current: boolean }) {
+  const visual = todoStatusVisual(task.status);
+  const note = taskNote(task);
+
+  return (
+    <div
+      className={`flex items-start gap-2.5 px-2.5 py-1.5 transition-colors ${
+        current ? 'bg-ink/[0.04]' : ''
+      }`}
+    >
+      <StatusIcon status={task.status} className={`mt-[2px] shrink-0 ${visual.tone}`} />
+      <div className="min-w-0 flex-1">
+        <div
+          className={`text-[11.5px] leading-snug ${
+            visual.closed
+              ? 'text-ink/40 line-through'
+              : visual.active
+                ? 'font-medium text-ink'
+                : 'text-ink/75'
+          }`}
+        >
+          {task.content}
+        </div>
+        {note && (
+          <div className="mt-0.5 text-[10.5px] leading-snug text-warning/90 break-words">{note}</div>
+        )}
+      </div>
+      {visual.active && (
+        <span className="shrink-0 rounded bg-ink/8 px-1.5 py-0.5 font-mono text-[9px] uppercase tracking-wider text-ink/70">
+          Now
+        </span>
+      )}
+    </div>
+  );
+}

package/src/client/components/workspace/todo-panel/index.tsx

@@ -0,0 +1,161 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Right-panel Todo view: the session's live todo list, as oh-my-pi itself
+ * would resume with it.
+ *
+ * The list is omp's, read from the session transcript (see
+ * `@/server/lib/omp/session/todos`), so this panel adds presentation only —
+ * phase groups, a progress bar, and the current task called out. It deliberately
+ * does NOT recompute or cache a list of its own: a chamber-side copy would drift
+ * from the one the agent rehydrates, and a plan panel that disagrees with the
+ * agent is worse than no panel.
+ *
+ * Empty states are distinguished, because they mean different things: no
+ * session selected, a session whose transcript has no todo snapshot at all
+ * (the agent never used the tool here), and a snapshot whose every task is
+ * closed.
+ */
+
+import { useMemo } from 'preact/hooks';
+import { AlertCircle, ListTodo, RefreshCw } from 'lucide-preact';
+import { useSearchParams } from '@/client/lib/router/search-params';
+import { useSessionState } from '@/client/hooks/workspace/session-state';
+import { useSessionTodos } from '@/client/hooks/workspace/session-todos';
+import { TodoPhaseGroup } from '@/client/components/workspace/todo-panel/PhaseGroup';
+import { currentTaskLocation, todoProgressLabel, todoProgressPercent } from '@/shared/lib/chat/todo/progress';
+
+interface TodoPanelProps {
+  className?: string;
+  /**
+   * False while the view is not the one on screen: pauses the poll and the
+   * event-driven re-read.
+   *
+   * Deliberately NOT the `enabled` gate the workspace-scoped panels take. That
+   * flag means "the active session's cwd resolves to a registered workspace
+   * folder", which files/search/git/terminal genuinely need. A todo list does
+   * not: it lives in the session's own transcript, so a session running outside
+   * every registered workspace still has one — gating on the workspace showed
+   * "No session selected" for a session that was open and had a full list.
+   */
+  active?: boolean;
+}
+
+export function TodoPanel({ className = '', active = true }: TodoPanelProps) {
+  const [searchParams] = useSearchParams();
+  const sessionId = searchParams.get('sessionId');
+  const [collapsedPhases, setCollapsedPhases] = useSessionState<Record<string, boolean>>(
+    'todo.collapsedPhases',
+    {},
+  );
+  const { data, isLoading, error, reload } = useSessionTodos(sessionId, active);
+
+  const snapshot = data?.snapshot ?? null;
+  const progress = data?.progress ?? null;
+
+  // `phase:task` of the row to highlight. Derived from the snapshot rather than
+  // stored, so it follows the list as it moves.
+  const currentKey = useMemo(() => {
+    const location = currentTaskLocation(snapshot?.phases ?? []);
+    return location ? `${location.phase}:${location.task}` : null;
+  }, [snapshot]);
+
+  if (!sessionId) {
+    return (
+      <div className={`flex h-full flex-col items-center justify-center bg-paper text-ink/40 ${className}`}>
+        <span className="text-xs font-mono">No session selected</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`flex h-full w-full min-w-0 flex-col overflow-hidden bg-paper text-ink ${className}`}>
+      <div className="flex flex-shrink-0 items-center justify-between gap-3 border-b border-ink/10 px-3.5 py-2.5">
+        <div className="flex min-w-0 items-center gap-2">
+          <h2 className="text-xs font-semibold uppercase tracking-wider text-ink">Todos</h2>
+          {snapshot && (
+            <span className="truncate font-mono text-[10.5px] text-ink/50" title={todoProgressLabel(progress!)}>
+              {todoProgressLabel(progress!)}
+            </span>
+          )}
+          {data?.isMock && (
+            <span className="flex-shrink-0 rounded border border-ink/15 bg-ink/5 px-1.5 py-0.5 font-mono text-[10px] uppercase tracking-wider text-ink/60">
+              Mock
+            </span>
+          )}
+        </div>
+        <button
+          type="button"
+          onClick={reload}
+          disabled={isLoading}
+          title="Refresh todos"
+          aria-label="Refresh todos"
+          className="flex-shrink-0 rounded-md border border-ink/15 bg-paper p-1.5 text-ink/80 transition-colors hover:bg-ink/5 disabled:opacity-50"
+        >
+          <RefreshCw size={12} className={isLoading ? 'animate-spin text-ink' : ''} />
+        </button>
+      </div>
+
+      {progress && progress.total > 0 && (
+        <div className="flex-shrink-0 border-b border-ink/10 px-3.5 py-2.5">
+          <div className="h-1.5 overflow-hidden rounded-full bg-ink/8">
+            <div
+              className="h-full rounded-full bg-success transition-all duration-300"
+              style={{ width: `${todoProgressPercent(progress)}%` }}
+            />
+          </div>
+        </div>
+      )}
+
+      <div className="min-h-0 flex-1 space-y-2 overflow-y-auto scrollbar-overlay-container scrollbar-overlay-static p-3.5">
+        {error && (
+          <div className="flex items-start gap-2 rounded-lg border border-error/30 bg-error/5 px-3 py-2 text-[11px] text-error">
+            <AlertCircle size={13} className="mt-[1px] shrink-0" />
+            <span className="min-w-0 break-words">{error}</span>
+          </div>
+        )}
+
+        {!snapshot ? (
+          <div className="flex flex-col items-center justify-center gap-2 py-12 text-center text-ink/40">
+            <ListTodo size={20} />
+            <p className="max-w-[240px] text-[11.5px] leading-relaxed">
+              No todo list in this session. The agent writes one with the <span className="font-mono">todo</span> tool
+              when a task is worth planning.
+            </p>
+          </div>
+        ) : (
+          <>
+            {snapshot.phases.map((phase, index) => (
+              <TodoPhaseGroup
+                key={`${index}-${phase.name}`}
+                phase={phase}
+                index={index}
+                collapsed={Boolean(collapsedPhases[String(index)])}
+                currentKey={currentKey}
+                onToggle={() =>
+                  setCollapsedPhases((prev) => ({ ...prev, [String(index)]: !prev[String(index)] }))
+                }
+              />
+            ))}
+
+            <p className="pt-1 text-[10.5px] leading-relaxed text-ink/35">
+              Read from this session&apos;s transcript
+              {snapshot.updatedAt ? ` · updated ${formatStamp(snapshot.updatedAt)}` : ''}
+              {snapshot.source === 'custom' ? ' · edited by hand' : ''}.
+            </p>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** Local time of a snapshot stamp; the raw ISO string when it cannot be read. */
+function formatStamp(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+}

package/src/client/hooks/editor/find-harness.test-util.ts

@@ -0,0 +1,170 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The harness `use-editor-find` is exercised through.
+ *
+ * Split out because the find hook has two test files (opening and stepping /
+ * writing and options) and both must render it the same way — the session
+ * provider it needs, the surface calls it makes, and a fresh session id per test
+ * so the PERSISTED query does not leak between them.
+ *
+ * The hook's modules are imported dynamically, after the DOM globals exist:
+ * Preact binds its environment at evaluation time, and a static import would
+ * capture the DOM-less one.
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach } from 'bun:test';
+import { Window } from 'happy-dom';
+import type { ComponentChildren, h as PreactH, render as PreactRender } from 'preact';
+import type { act as PreactAct } from 'preact/test-utils';
+import type { EditorFindState, useEditorFind as UseEditorFindHook } from '@/client/hooks/editor/use-editor-find';
+
+export interface FindHarness {
+  /** The latest render's state; re-read after every settle, never held across one. */
+  readonly find: EditorFindState | null;
+  /** What the hook under test is handed — mutated per test, then re-rendered. */
+  readonly input: {
+    text: string;
+    documentKey: string;
+    selection: { start: number; end: number } | null;
+  };
+  /** Surface calls, so "did it select / reveal / write" is observable. */
+  readonly selections: Array<[number, number, boolean]>;
+  readonly reveals: number[];
+  readonly writes: Array<{ value: string; caretStart: number }>;
+  /** Re-render with the current `input` and settle. */
+  rerender: () => Promise<void>;
+  /** Flush pending effects and renders. */
+  flush: () => Promise<void>;
+  /**
+   * Preact's `act`, exposed because every interaction in these tests is a hook
+   * call the DOM never sees: it has to be wrapped to be flushed.
+   */
+  act: typeof PreactAct;
+  /** Register the before/after hooks this harness needs. */
+  install: () => void;
+}
+
+export async function createFindHarness(): Promise<FindHarness> {
+  let useEditorFind: typeof UseEditorFindHook;
+  let SessionStateContext: { Provider: (props: { value: { sessionId: string; ready: boolean }; children: ComponentChildren }) => ComponentChildren };
+  let h: typeof PreactH;
+  let render: typeof PreactRender;
+  let act: typeof PreactAct;
+
+  let find: EditorFindState | null = null;
+  let container: HTMLElement;
+  let sessionId = 'test-session';
+  let sessionCounter = 0;
+
+  const input: FindHarness['input'] = { text: 'alpha beta alpha', documentKey: 'file-1', selection: { start: 0, end: 5 } };
+  const selections: FindHarness['selections'] = [];
+  const reveals: number[] = [];
+  const writes: FindHarness['writes'] = [];
+
+  function Inner() {
+    find = useEditorFind({
+      text: input.text,
+      documentKey: input.documentKey,
+      readSelection: () => input.selection,
+      select: (start, end, focus = true) => selections.push([start, end, focus]),
+      reveal: (offset) => reveals.push(offset),
+      applyDocument: (value, caretStart) => writes.push({ value, caretStart }),
+    });
+    return null;
+  }
+
+  function Harness() {
+    // The hook persists the query and the toggles per session, so it needs the
+    // provider the panel supplies. A test session id is all it reads.
+    return h(SessionStateContext.Provider, { value: { sessionId, ready: true }, children: h(Inner, {}) });
+  }
+
+  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();
+  }
+
+  const domGlobals = (win: Window): Record<string, unknown> => ({
+    window: win,
+    document: win.document,
+    navigator: win.navigator,
+    Node: win.Node,
+    Element: win.Element,
+    HTMLElement: win.HTMLElement,
+  });
+
+  const installed: Record<string, unknown> = {};
+  const displaced: Record<string, unknown> = {};
+
+  return {
+    get find() {
+      return find;
+    },
+    input,
+    selections,
+    reveals,
+    writes,
+    rerender,
+    flush,
+    get act() {
+      return act;
+    },
+    install() {
+      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;
+        }
+        ({ useEditorFind } = await import('@/client/hooks/editor/use-editor-find'));
+        ({ SessionStateContext } = await import('@/client/hooks/workspace/session-state/context'));
+        ({ 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 () => {
+        find = null;
+        // The query and the toggles are persisted per session — that is the
+        // feature — so each test gets its OWN session id rather than sharing a
+        // blob with the test before it.
+        sessionId = `test-session-${++sessionCounter}`;
+        input.text = 'alpha beta alpha';
+        input.documentKey = 'file-1';
+        input.selection = { start: 0, end: 5 };
+        selections.length = 0;
+        reveals.length = 0;
+        writes.length = 0;
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        await rerender();
+      });
+
+      afterEach(() => {
+        render(null, container);
+        container.remove();
+      });
+    },
+  };
+}