@stigmer/react 3.1.1 → 3.1.2

package/src/workspace/findChangeForSelection.ts

@@ -0,0 +1,61 @@
+// Correlate an open workspace-file selection with the session file change that
+// touched it, so the read-only Viewer can default a changed file to its diff
+// (Slice 4). This is the change-side peer of `resolveWorkspaceFileSelection`.
+//
+// The hard part is again PATH FORM, and — critically — ENTRY IDENTITY. A
+// `FileChange` carries a capture-side path (`path` is workspace-root-relative,
+// falling back to `absolutePath`), while the selection is the reader's
+// `{ entryId, path }`. Matching by a bare `/`-boundary suffix (as the
+// presentation-only `changeForRowPath` does) is deliberately NOT used here: in
+// a multi-repo session it would happily match `repoA/src/a.ts` to a change in
+// `repoB/src/a.ts` and render the wrong file's diff.
+//
+// Instead we route each change's path through the SAME correlation-grade
+// resolver (`resolveWorkspaceFileSelection`) the tree and transcript use to
+// open files, with the SAME `entries` and `sandboxWorkspaceRoot`. A change is
+// the open file's change iff it resolves to the exact `{ entryId, path }`
+// currently selected. Single-entry sessions match exactly; ambiguous
+// multi-entry / absolute paths degrade to "no match" (never a wrong match),
+// inheriting DD-08's honesty. One resolver, one truth.
+
+import type { FileChange } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
+import { resolveWorkspaceFileSelection } from "./resolveWorkspaceFileSelection.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+
+/**
+ * The session {@link FileChange} that touched the currently-open file, or
+ * `null` when the open file was not changed this session (or cannot be
+ * correlated with certainty).
+ *
+ * @param selection - The open file, keyed by `entryId` + repo/root-relative `path`.
+ * @param fileChanges - Net-per-file session changes (from `useSessionFileChanges`).
+ * @param entries - The client workspace entries — the SAME list the tree and
+ *   transcript resolve against (`flow.workspace.entries`), so the returned
+ *   `entryId` is directly comparable. Do not pass the proto `workspaceEntries`.
+ * @param sandboxWorkspaceRoot - The sandbox root for git sessions (strips
+ *   cloud-absolute change paths), identical to the transcript resolver's input.
+ * @returns The matching change, or `null`.
+ */
+export function findChangeForSelection(
+  selection: SelectedWorkspaceFile,
+  fileChanges: readonly FileChange[],
+  entries: readonly WorkspaceEntry[],
+  sandboxWorkspaceRoot?: string,
+): FileChange | null {
+  for (const change of fileChanges) {
+    const resolved = resolveWorkspaceFileSelection(
+      change.path || change.absolutePath,
+      entries,
+      sandboxWorkspaceRoot,
+    );
+    if (
+      resolved !== null &&
+      resolved.entryId === selection.entryId &&
+      resolved.path === selection.path
+    ) {
+      return change;
+    }
+  }
+  return null;
+}

package/src/workspace/index.ts

@@ -7,13 +7,67 @@ export type {
   WorkspaceFileEntry,
   WorkspaceFileLister,
 } from "./WorkspaceFileLister.js";
+export { MAX_WORKSPACE_FILE_READ_BYTES } from "./WorkspaceFileReader.js";
+export type {
+  WorkspaceFileContent,
+  WorkspaceFileReader,
+} from "./WorkspaceFileReader.js";
 export { useWorkspaceFiles } from "./useWorkspaceFiles.js";
 export type {
   UseWorkspaceFilesOptions,
   UseWorkspaceFilesReturn,
 } from "./useWorkspaceFiles.js";
-export { WorkspaceEntryFiles } from "./WorkspaceEntryFiles.js";
-export type { WorkspaceEntryFilesProps } from "./WorkspaceEntryFiles.js";
+export { useWorkspaceFileContent } from "./useWorkspaceFileContent.js";
+export type {
+  UseWorkspaceFileContentOptions,
+  UseWorkspaceFileContentReturn,
+} from "./useWorkspaceFileContent.js";
+export { useWorkspaceFileSearch } from "./useWorkspaceFileSearch.js";
+export type {
+  UseWorkspaceFileSearchOptions,
+  UseWorkspaceFileSearchReturn,
+  WorkspaceFileSearchGroup,
+} from "./useWorkspaceFileSearch.js";
+// The match type is part of the public search return; the matcher itself stays @internal.
+export type { WorkspaceFileMatch } from "./matchWorkspaceFiles.js";
+export { WorkspaceFileSearch } from "./WorkspaceFileSearch.js";
+export type { WorkspaceFileSearchProps } from "./WorkspaceFileSearch.js";
+export type {
+  WorkspaceContentMatch,
+  WorkspaceContentSearchResult,
+  WorkspaceContentSearcher,
+} from "./WorkspaceContentSearcher.js";
+export { useWorkspaceContentSearch } from "./useWorkspaceContentSearch.js";
+export type {
+  UseWorkspaceContentSearchOptions,
+  UseWorkspaceContentSearchReturn,
+  WorkspaceContentSearchGroup,
+} from "./useWorkspaceContentSearch.js";
+export { WorkspaceContentSearch } from "./WorkspaceContentSearch.js";
+export type { WorkspaceContentSearchProps } from "./WorkspaceContentSearch.js";
+// The highlight helper (findHighlightRanges) stays @internal, like matchWorkspaceFiles.
+export { FileViewer } from "./FileViewer.js";
+export type { FileViewerProps, FileViewerHandle } from "./FileViewer.js";
+export { WorkspaceSurface } from "./WorkspaceSurface.js";
+export type {
+  WorkspaceSurfaceProps,
+  SurfaceRailView,
+  SurfaceVirtualDocument,
+} from "./WorkspaceSurface.js";
+// Virtual-document identity helpers: hosts mint collision-proof entry ids for
+// SurfaceVirtualDocument tabs and detect them in file-only code paths.
+export { virtualEntryId, isVirtualEntryId } from "../internal/store/index.js";
+export { ExplorerTree } from "./ExplorerTree.js";
+export type { ExplorerTreeProps } from "./ExplorerTree.js";
+// The open-editor tab shape + open-file options are part of the public
+// WorkspaceSurface API.
+export type { OpenEditor, OpenFileOptions } from "../internal/store/index.js";
+// The jump-to-line reveal target rides on FileViewer / WorkspaceSurface /
+// ArtifactContentRenderer props; export the shape (the hook stays @internal).
+export type { RevealTarget } from "../internal/useRevealLine.js";
+// The viewer's selection shape is part of the public FileViewer API; re-export
+// the type (not the store) so consumers can construct/inspect a selection.
+export type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
 export { WorkspaceEditor } from "./WorkspaceEditor.js";
 export type { WorkspaceEditorProps } from "./WorkspaceEditor.js";
 export { WorkspaceSummary } from "./WorkspaceSummary.js";

package/src/workspace/matchContentPreview.ts

@@ -0,0 +1,51 @@
+// Pure highlight helper behind content search. Kept separate from the hook and
+// component so the offset math is exhaustively unit-testable in isolation (no
+// React, no async).
+//
+// The backend returns each hit's `preview` line but no column offset (a
+// cross-language byte/UTF-16 offset would be brittle — see WorkspaceContentMatch).
+// Since matching is case-insensitive substring, the client re-derives the
+// highlight span(s) from the preview text itself, identically to how
+// `matchWorkspaceFiles` derives the filename highlight range. `@internal`.
+
+/**
+ * A half-open `[start, end)` range of code-unit offsets into a preview string,
+ * marking one occurrence of the query to emphasize.
+ */
+export interface HighlightRange {
+  /** Inclusive start offset within the preview. */
+  readonly start: number;
+  /** Exclusive end offset within the preview. */
+  readonly end: number;
+}
+
+/**
+ * Finds every case-insensitive occurrence of `query` within `preview`,
+ * best-effort for rendering emphasis.
+ *
+ * - Empty/whitespace query → `[]` (nothing to highlight).
+ * - Overlapping matches cannot occur (search advances past each match end).
+ * - Offsets are JS string code units, so a consumer highlights with
+ *   `preview.slice(start, end)`.
+ */
+export function findHighlightRanges(
+  preview: string,
+  query: string,
+): HighlightRange[] {
+  const needle = query.trim().toLowerCase();
+  if (needle.length === 0) return [];
+
+  const haystack = preview.toLowerCase();
+  const ranges: HighlightRange[] = [];
+
+  let from = 0;
+  for (;;) {
+    const start = haystack.indexOf(needle, from);
+    if (start === -1) break;
+    const end = start + needle.length;
+    ranges.push({ start, end });
+    from = end;
+  }
+
+  return ranges;
+}

package/src/workspace/matchWorkspaceFiles.ts

@@ -0,0 +1,86 @@
+// Pure ranking function behind workspace search. Kept separate from the hook and
+// component so the matching/ranking rules are exhaustively unit-testable in
+// isolation (no React, no async).
+//
+// Match semantics intentionally mirror `internal/file-tree/filterFileTree` —
+// case-insensitive substring — but widened from a node's basename to the full
+// relative path, so `foo/bar` is findable and directory context is searchable
+// (DD-10). The trivial predicate is not extracted into a shared micro-module; a
+// cross-reference comment is the lower-coupling, honest choice.
+
+import type { WorkspaceFileEntry } from "./WorkspaceFileLister.js";
+
+/**
+ * A workspace file that matched a search query.
+ *
+ * `matchStart`/`matchEnd` are code-unit offsets into `path` (a half-open
+ * `[start, end)` range) for the single contiguous substring hit, so a consumer
+ * can highlight exactly the matched span with `path.slice(...)`.
+ */
+export interface WorkspaceFileMatch {
+  /** Repo-relative (git) or root-relative (local) path of the matched file. */
+  readonly path: string;
+  /** Inclusive start offset of the matched substring within `path`. */
+  readonly matchStart: number;
+  /** Exclusive end offset of the matched substring within `path`. */
+  readonly matchEnd: number;
+}
+
+/** A match plus the ranking signal used only for sorting. */
+interface RankedMatch extends WorkspaceFileMatch {
+  /** `true` when the hit falls within the basename (after the last `/`). */
+  readonly isBasenameHit: boolean;
+}
+
+/**
+ * Ranks a flat listing against a query, returning matched files best-first.
+ *
+ * - Case-insensitive substring on the full relative path.
+ * - Directories and advisory `notice` entries are never matched (a defensive
+ *   guard even though the shared cache already strips notices — DD-11).
+ * - Empty/whitespace query returns `[]` (search shows a hint, not everything).
+ *
+ * Ranking, in order: a basename hit outranks a path-only hit; then an earlier
+ * match offset; then a shorter path; then lexicographic path for a stable,
+ * deterministic order.
+ */
+export function matchWorkspaceFiles(
+  files: readonly WorkspaceFileEntry[],
+  query: string,
+): WorkspaceFileMatch[] {
+  const trimmed = query.trim();
+  if (trimmed.length === 0) return [];
+
+  const needle = trimmed.toLowerCase();
+  const ranked: RankedMatch[] = [];
+
+  for (const file of files) {
+    if (file.isDirectory || file.notice) continue;
+
+    const matchStart = file.path.toLowerCase().indexOf(needle);
+    if (matchStart === -1) continue;
+
+    const lastSlash = file.path.lastIndexOf("/");
+    ranked.push({
+      path: file.path,
+      matchStart,
+      matchEnd: matchStart + needle.length,
+      isBasenameHit: matchStart >= lastSlash + 1,
+    });
+  }
+
+  ranked.sort(compareMatches);
+
+  return ranked.map(({ path, matchStart, matchEnd }) => ({
+    path,
+    matchStart,
+    matchEnd,
+  }));
+}
+
+function compareMatches(a: RankedMatch, b: RankedMatch): number {
+  if (a.isBasenameHit !== b.isBasenameHit) return a.isBasenameHit ? -1 : 1;
+  if (a.matchStart !== b.matchStart) return a.matchStart - b.matchStart;
+  if (a.path.length !== b.path.length) return a.path.length - b.path.length;
+  return a.path.localeCompare(b.path);
+}

package/src/workspace/resolveWorkspaceFileSelection.ts

@@ -0,0 +1,119 @@
+// Resolve a transcript tool-call file path to an openable workspace-file
+// selection. This is the seam that lets a click on a path in the message thread
+// route to the same read-only Viewer a file-tree click drives (Slice 3).
+//
+// The hard part is NOT identity ("which entry") but PATH FORM. The reader and
+// lister contracts are strict: `WorkspaceFileReader` / the GitHub Trees lister
+// speak repo-root-relative (git) or root-relative (local) paths — the exact
+// strings a file-tree node carries. Transcript tool-call paths are not
+// guaranteed to be in that form: depending on harness and workspace layout they
+// arrive workspace-relative, subdir-prefixed, or absolute (see
+// `execution/file-review-status.ts` `changeForRowPath`, which documents the
+// same variance and treats path matching as presentation-only).
+//
+// Rather than fuzzy-match, this resolver normalizes deterministically using only
+// anchors the client already holds, grounded in how the runner provisions the
+// workspace (`backend/.../workspace/provisioner.ts`):
+//   - Single entry  -> cloned at the workspace root, so a (humanized) tool-call
+//                      path is already repo/root-relative. Identity transform.
+//   - Multiple git  -> each cloned into `<root>/<entry.name>/`, so the path is
+//                      prefixed by the subdir name; strip it.
+//   - Local (desktop) -> the native reader joins `entry.localPath` + a
+//                      root-relative path; local tool paths may be absolute, so
+//                      strip the known `entry.localPath` prefix.
+//   - Cloud absolute -> strip the known `sandboxWorkspaceRoot` first.
+// Anything that does not resolve to a definite relative path returns `null` so
+// the caller keeps its existing copy/GitHub-link behavior — a wrong file can
+// never open. Extending this to arbitrary/absolute paths belongs to a later
+// slice that resolves against the authoritative file-tree index.
+
+import { classifyPath } from "../execution/file-path-resolver.js";
+import type { SelectedWorkspaceFile } from "../internal/store/workspace-file-selection-store.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+
+/** Forward-slash-normalize and drop any leading slashes for prefix comparison. */
+function normalize(path: string): string {
+  return path.replace(/\\/g, "/").replace(/^\/+/, "");
+}
+
+/**
+ * Returns the portion of `path` beneath `anchor`, or `null` when `path` does
+ * not sit under `anchor`. An exact match (the anchor itself, a directory) yields
+ * `""` — the caller rejects it, since a directory is not a viewable file.
+ */
+function relativeTo(path: string, anchor: string): string | null {
+  if (!anchor) return null;
+  if (path === anchor) return "";
+  if (path.startsWith(anchor + "/")) return path.slice(anchor.length + 1);
+  return null;
+}
+
+/**
+ * Resolves a transcript tool-call file path to the {@link SelectedWorkspaceFile}
+ * that opens it in the read-only Viewer, or `null` when it cannot be resolved to
+ * a definite repo/root-relative file (caller keeps copy/GitHub-link fallback).
+ *
+ * `entries` are the client-side workspace entries (`useWorkspaceEntries`), the
+ * same list the Viewer resolves against, so the returned `entryId` is directly
+ * usable. `sandboxWorkspaceRoot` (when the session has git-repo entries, e.g.
+ * `/home/daytona/workspace`) is stripped first so cloud-absolute paths reduce to
+ * workspace-relative before per-entry anchoring.
+ *
+ * The result `path` is guaranteed to match what the file tree / lister emits for
+ * the same file, so opening from the transcript and from the tree produce an
+ * identical selection (and hit the same content fetch/cache).
+ */
+export function resolveWorkspaceFileSelection(
+  path: string,
+  entries: readonly WorkspaceEntry[],
+  sandboxWorkspaceRoot?: string,
+): SelectedWorkspaceFile | null {
+  if (!path || entries.length === 0) return null;
+
+  // 1. Reduce a cloud-absolute path to workspace-relative using the known root.
+  let work = normalize(path);
+  if (sandboxWorkspaceRoot) {
+    const root = normalize(sandboxWorkspaceRoot);
+    const relToRoot = relativeTo(work, root);
+    if (relToRoot !== null) work = relToRoot;
+  }
+  // The bare workspace root ("" after stripping, or the humanized ".") is not a
+  // file.
+  if (!work || work === ".") return null;
+
+  // 2. The platform mount (`.stigmer/…`) is a virtual namespace, not a workspace
+  //    file — checked after the root strip so an absolute `<root>/.stigmer/…`
+  //    is caught too. Keep copy behavior for it.
+  if (classifyPath(work).kind === "platform") return null;
+
+  // 3. Anchor on the exact per-entry roots the client holds. Local entries
+  //    anchor on their absolute `localPath`; multi-entry git repos anchor on the
+  //    provisioning subdir (`entry.name`). A single git entry is cloned at the
+  //    root, so it falls through to step 4.
+  const isMulti = entries.length > 1;
+  for (const entry of entries) {
+    let anchor: string | null = null;
+    if (entry.type === "local" && entry.localPath) {
+      anchor = normalize(entry.localPath);
+    } else if (entry.type === "git" && isMulti) {
+      anchor = normalize(entry.name);
+    }
+    if (anchor === null) continue;
+
+    const rel = relativeTo(work, anchor);
+    // Exact match is the entry's own root directory, not a viewable file — stop
+    // rather than fall through to the single-entry fallback (which would return
+    // the raw root path).
+    if (rel === "") return null;
+    if (rel) return { entryId: entry.id, path: rel };
+  }
+
+  // 4. A single entry whose anchor did not apply (e.g. a git repo at the root, or
+  //    a local path already root-relative): the path is already repo/root-relative.
+  if (entries.length === 1) {
+    return { entryId: entries[0].id, path: work };
+  }
+
+  // 5. Multi-entry with no anchor match: refuse to guess which entry owns it.
+  return null;
+}

package/src/workspace/useWorkspaceContentSearch.ts

@@ -0,0 +1,228 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { toError } from "../internal/toError.js";
+import type { WorkspaceEntry } from "./useWorkspaceEntries.js";
+import type {
+  WorkspaceContentMatch,
+  WorkspaceContentSearcher,
+} from "./WorkspaceContentSearcher.js";
+
+/** Default debounce for content-search query changes — matches `useResourceSearch`. */
+const DEFAULT_DEBOUNCE_MS = 300;
+
+/**
+ * Minimum query length before a disk search fires. Content search hits the
+ * filesystem on every query (unlike the cached filename search), so a
+ * single-character query would scan the whole tree for a near-useless result.
+ * Two characters is a gentle, documented floor — not an arbitrary limit.
+ */
+const DEFAULT_MIN_LENGTH = 2;
+
+/** Options for {@link useWorkspaceContentSearch}. */
+export interface UseWorkspaceContentSearchOptions {
+  /** All workspace entries to search across. */
+  readonly entries: readonly WorkspaceEntry[];
+  /** Platform-injected content searcher. `undefined` → content search is unavailable. */
+  readonly searcher: WorkspaceContentSearcher | undefined;
+  /** Current search query. Trimmed; below {@link minLength} yields no search. */
+  readonly query: string;
+  /** Debounce delay for query changes in milliseconds. @default 300 */
+  readonly debounceMs?: number;
+  /** Minimum trimmed query length before a search runs. @default 2 */
+  readonly minLength?: number;
+}
+
+/** Content-search hits (and per-entry status) for one workspace entry. */
+export interface WorkspaceContentSearchGroup {
+  /** The workspace entry these matches belong to. */
+  readonly entry: WorkspaceEntry;
+  /** Line-level matches within this entry, backend-ordered (path, then line). */
+  readonly matches: readonly WorkspaceContentMatch[];
+  /** `true` when this entry's search was capped (more matches exist than shown). */
+  readonly truncated: boolean;
+  /** Search error for this entry, if any (isolated — other entries still resolve). */
+  readonly error: Error | null;
+}
+
+/** Return value of {@link useWorkspaceContentSearch}. */
+export interface UseWorkspaceContentSearchReturn {
+  /** Entries with something to show (matches, an error, or a truncation notice). */
+  readonly groups: readonly WorkspaceContentSearchGroup[];
+  /** Total matches across all groups (for a "showing N of M" affordance). */
+  readonly totalMatches: number;
+  /** `true` during the first search of a query with no prior results to show. */
+  readonly isLoading: boolean;
+  /** `true` while a new query loads *over* previously-shown results (no blank flash). */
+  readonly isRefetching: boolean;
+  /** `true` when no substrate can be searched (no searcher, or every entry unsupported). */
+  readonly isUnsupported: boolean;
+  /** First per-entry error, for a top-level fallback message. `null` when none. */
+  readonly error: Error | null;
+}
+
+/** Settled per-entry result held between query changes (never a "loading" state). */
+type EntryResult =
+  | { readonly status: "ready"; readonly matches: readonly WorkspaceContentMatch[]; readonly truncated: boolean }
+  | { readonly status: "error"; readonly error: Error }
+  | { readonly status: "unsupported" };
+
+const EMPTY_GROUPS: readonly WorkspaceContentSearchGroup[] = [];
+
+/**
+ * Behavior hook powering workspace-wide content (text) search.
+ *
+ * The text-grep sibling of
+ * {@link useWorkspaceFileSearch}: it keeps
+ * that hook's per-entry aggregation, error isolation, and generation guard, and
+ * adds the platform's canonical debounce idiom from `useResourceSearch`
+ * (`query`/`debouncedQuery` + `setTimeout`). The key difference is that the
+ * debounced query is part of the *fetch* — each keystroke hits disk via the
+ * injected {@link WorkspaceContentSearcher}, uncached — so a `minLength` guard
+ * and a debounce protect the filesystem.
+ *
+ * Prior results stay visible while a new debounced query loads (`isRefetching`
+ * true, results unchanged); only the very first search with nothing to show
+ * flips `isLoading`. This avoids a per-keystroke blank flash the cached filename
+ * search never had.
+ *
+ * @example
+ * ```tsx
+ * const { groups, totalMatches, isRefetching } = useWorkspaceContentSearch({
+ *   entries: workspace.entries,
+ *   searcher: workspaceContentSearcher,
+ *   query,
+ * });
+ * ```
+ */
+export function useWorkspaceContentSearch({
+  entries,
+  searcher,
+  query,
+  debounceMs = DEFAULT_DEBOUNCE_MS,
+  minLength = DEFAULT_MIN_LENGTH,
+}: UseWorkspaceContentSearchOptions): UseWorkspaceContentSearchReturn {
+  // Settled results per entry, keyed by entry id. Retained across query changes
+  // and only swapped wholesale when a new generation fully resolves — so a
+  // reload never blanks what the user is already reading.
+  const [results, setResults] = useState<Record<string, EntryResult>>({});
+  const [pending, setPending] = useState(false);
+
+  // Debounce the query into the fetch key (the `useResourceSearch` idiom).
+  const [debouncedQuery, setDebouncedQuery] = useState(query);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedQuery(query), debounceMs);
+    return () => clearTimeout(timer);
+  }, [query, debounceMs]);
+
+  // Latest entries read inside the effect without widening its dependency to the
+  // (possibly per-render) array identity — the effect keys on the id set instead.
+  const entriesRef = useRef(entries);
+  entriesRef.current = entries;
+  const entriesKey = entries.map((entry) => entry.id).join("\u0000");
+
+  // Ignore resolutions from a superseded run (id set, searcher, or query changed).
+  const generationRef = useRef(0);
+
+  const effectiveQuery = debouncedQuery.trim();
+  const belowMinLength = effectiveQuery.length < minLength;
+
+  useEffect(() => {
+    // No searcher or a too-short query: clear results, nothing in flight. (An
+    // in-flight generation is abandoned via the bumped ref.)
+    if (!searcher || belowMinLength) {
+      generationRef.current += 1;
+      setResults({});
+      setPending(false);
+      return;
+    }
+
+    const currentEntries = entriesRef.current;
+    const generation = ++generationRef.current;
+    setPending(true);
+
+    Promise.all(
+      currentEntries.map(async (entry): Promise<[string, EntryResult]> => {
+        try {
+          const result = await searcher(entry, effectiveQuery);
+          if (result === null) return [entry.id, { status: "unsupported" }];
+          return [
+            entry.id,
+            { status: "ready", matches: result.matches, truncated: result.truncated },
+          ];
+        } catch (err) {
+          return [entry.id, { status: "error", error: toError(err) }];
+        }
+      }),
+    ).then((settled) => {
+      // A newer generation started while this batch was in flight — drop it so
+      // stale results never overwrite fresher ones (or clobber a cleared state).
+      if (generationRef.current !== generation) return;
+      const next: Record<string, EntryResult> = {};
+      for (const [id, res] of settled) next[id] = res;
+      setResults(next);
+      setPending(false);
+    });
+  }, [entriesKey, searcher, effectiveQuery, belowMinLength]);
+
+  return useMemo<UseWorkspaceContentSearchReturn>(() => {
+    if (!searcher) {
+      return {
+        groups: EMPTY_GROUPS,
+        totalMatches: 0,
+        isLoading: false,
+        isRefetching: false,
+        isUnsupported: true,
+        error: null,
+      };
+    }
+
+    const groups: WorkspaceContentSearchGroup[] = [];
+    let totalMatches = 0;
+    let firstError: Error | null = null;
+    let unsupportedCount = 0;
+    let settledCount = 0;
+
+    for (const entry of entries) {
+      const state = results[entry.id];
+      if (!state) continue;
+      settledCount += 1;
+
+      if (state.status === "unsupported") {
+        unsupportedCount += 1;
+        continue;
+      }
+      if (state.status === "error") {
+        if (!firstError) firstError = state.error;
+        groups.push({ entry, matches: [], truncated: false, error: state.error });
+        continue;
+      }
+
+      totalMatches += state.matches.length;
+      // Worth showing only when it carries matches or a truncation notice.
+      if (state.matches.length > 0 || state.truncated) {
+        groups.push({
+          entry,
+          matches: state.matches,
+          truncated: state.truncated,
+          error: null,
+        });
+      }
+    }
+
+    const hasPriorResults = settledCount > 0;
+    const isUnsupported =
+      entries.length > 0 && unsupportedCount === entries.length;
+
+    return {
+      groups,
+      totalMatches,
+      // First search (nothing settled yet) blanks; a reload over existing
+      // results keeps them visible and signals `isRefetching` instead.
+      isLoading: pending && !hasPriorResults,
+      isRefetching: pending && hasPriorResults,
+      isUnsupported,
+      error: firstError,
+    };
+  }, [entries, results, pending, searcher]);
+}