@stigmer/react 3.1.1 → 3.1.2

package/src/workspace/__tests__/resolveWorkspaceFileSelection.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { resolveWorkspaceFileSelection } from "../resolveWorkspaceFileSelection";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+
+function git(id: string, name: string): WorkspaceEntry {
+  return { id, name, type: "git", gitUrl: `https://github.com/${name}.git`, gitBranch: "main" };
+}
+
+function local(id: string, name: string, localPath: string): WorkspaceEntry {
+  return { id, name, type: "local", localPath };
+}
+
+const DAYTONA = "/home/daytona/workspace";
+
+describe("resolveWorkspaceFileSelection", () => {
+  // --- single git entry (cloud): repo cloned at the workspace root ----------
+
+  it("returns a repo-relative path unchanged for a single git entry (identity)", () => {
+    const entries = [git("e1", "org/repo")];
+    expect(resolveWorkspaceFileSelection("src/main.go", entries)).toEqual({
+      entryId: "e1",
+      path: "src/main.go",
+    });
+  });
+
+  it("strips the sandbox workspace root from a cloud-absolute path", () => {
+    const entries = [git("e1", "org/repo")];
+    expect(
+      resolveWorkspaceFileSelection(`${DAYTONA}/src/main.go`, entries, DAYTONA),
+    ).toEqual({ entryId: "e1", path: "src/main.go" });
+  });
+
+  it("normalizes a leading slash", () => {
+    const entries = [git("e1", "org/repo")];
+    expect(resolveWorkspaceFileSelection("/src/main.go", entries)).toEqual({
+      entryId: "e1",
+      path: "src/main.go",
+    });
+  });
+
+  // --- multiple git entries: each cloned into <root>/<entry.name>/ ----------
+
+  it("strips the subdir (entry.name) prefix for a multi-entry git session", () => {
+    const entries = [git("a", "org/repoA"), git("b", "org/repoB")];
+    expect(resolveWorkspaceFileSelection("org/repoB/src/main.go", entries)).toEqual({
+      entryId: "b",
+      path: "src/main.go",
+    });
+  });
+
+  it("strips both the sandbox root and the subdir for a multi-entry absolute path", () => {
+    const entries = [git("a", "org/repoA"), git("b", "org/repoB")];
+    expect(
+      resolveWorkspaceFileSelection(`${DAYTONA}/org/repoA/x.ts`, entries, DAYTONA),
+    ).toEqual({ entryId: "a", path: "x.ts" });
+  });
+
+  it("returns null for a multi-entry path that matches no entry (never mis-attribute)", () => {
+    const entries = [git("a", "org/repoA"), git("b", "org/repoB")];
+    expect(resolveWorkspaceFileSelection("unrelated/x.ts", entries)).toBeNull();
+  });
+
+  // --- local entries (desktop): anchor on the absolute localPath -----------
+
+  it("strips the absolute localPath prefix for a local entry", () => {
+    const entries = [local("e1", "app", "/Users/dev/app")];
+    expect(
+      resolveWorkspaceFileSelection("/Users/dev/app/src/main.go", entries),
+    ).toEqual({ entryId: "e1", path: "src/main.go" });
+  });
+
+  it("accepts an already-root-relative path for a single local entry", () => {
+    const entries = [local("e1", "app", "/Users/dev/app")];
+    expect(resolveWorkspaceFileSelection("src/main.go", entries)).toEqual({
+      entryId: "e1",
+      path: "src/main.go",
+    });
+  });
+
+  it("normalizes Windows backslash paths for a local entry", () => {
+    const entries = [local("e1", "app", "C:\\Users\\dev\\app")];
+    expect(
+      resolveWorkspaceFileSelection("C:\\Users\\dev\\app\\src\\main.go", entries),
+    ).toEqual({ entryId: "e1", path: "src/main.go" });
+  });
+
+  // --- platform mount, roots, and empties -> null (keep copy fallback) ------
+
+  it("returns null for a .stigmer/ platform path", () => {
+    const entries = [git("e1", "org/repo")];
+    expect(resolveWorkspaceFileSelection(".stigmer/skills/x.md", entries)).toBeNull();
+  });
+
+  it("returns null for an absolute .stigmer/ path under the sandbox root", () => {
+    const entries = [git("e1", "org/repo")];
+    expect(
+      resolveWorkspaceFileSelection(`${DAYTONA}/.stigmer/skills/x`, entries, DAYTONA),
+    ).toBeNull();
+  });
+
+  it("returns null for the bare workspace root", () => {
+    const entries = [git("e1", "org/repo")];
+    expect(resolveWorkspaceFileSelection(DAYTONA, entries, DAYTONA)).toBeNull();
+    expect(resolveWorkspaceFileSelection(".", entries)).toBeNull();
+  });
+
+  it("returns null when the path targets a local entry's own root directory", () => {
+    const entries = [local("e1", "app", "/Users/dev/app")];
+    expect(resolveWorkspaceFileSelection("/Users/dev/app", entries)).toBeNull();
+  });
+
+  it("returns null for an empty path", () => {
+    expect(resolveWorkspaceFileSelection("", [git("e1", "org/repo")])).toBeNull();
+  });
+
+  it("returns null when there are no workspace entries", () => {
+    expect(resolveWorkspaceFileSelection("src/main.go", [])).toBeNull();
+  });
+
+  // --- cross-check invariant: transcript-open == tree-open ------------------
+
+  it("produces the same repo-relative path a file-tree click would (single entry)", () => {
+    // The GitHub Trees lister emits repo-root-relative node paths; a tree click
+    // opens { entryId, path: "src/app/page.tsx" }. A transcript click on the
+    // same file must resolve to an identical selection so both hit one fetch.
+    const entries = [git("e1", "org/repo")];
+    const treeSelection = { entryId: "e1", path: "src/app/page.tsx" };
+    expect(resolveWorkspaceFileSelection("src/app/page.tsx", entries)).toEqual(
+      treeSelection,
+    );
+    expect(
+      resolveWorkspaceFileSelection(`${DAYTONA}/src/app/page.tsx`, entries, DAYTONA),
+    ).toEqual(treeSelection);
+  });
+});

package/src/workspace/__tests__/useWorkspaceContentSearch.test.tsx

@@ -0,0 +1,196 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { renderHook, waitFor, cleanup } from "@testing-library/react";
+import { useWorkspaceContentSearch } from "../useWorkspaceContentSearch";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+import type {
+  WorkspaceContentMatch,
+  WorkspaceContentSearchResult,
+  WorkspaceContentSearcher,
+} from "../WorkspaceContentSearcher";
+
+// Real timers with `debounceMs: 0` (mirroring the filename-search hook suite):
+// the debounce collapses to a microtask so `waitFor` drives the async settle
+// deterministically. Fake timers + `advanceTimersByTimeAsync` interact badly
+// with the deferred-promise refetch assertions below (microtask blowup), and
+// the behaviors under test — min-length gating, aggregation, error isolation,
+// refetch-keeps-results, and the stale-generation guard — don't need wall-clock
+// timing to verify.
+
+let entryIdCounter = 0;
+
+function makeEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: `ws-${++entryIdCounter}`,
+    name: "acme/api",
+    type: "local",
+    localPath: "/repo",
+    ...overrides,
+  };
+}
+
+function match(path: string, line: number, preview: string): WorkspaceContentMatch {
+  return { path, line, preview };
+}
+
+function result(
+  matches: WorkspaceContentMatch[],
+  truncated = false,
+): WorkspaceContentSearchResult {
+  return { matches, truncated };
+}
+
+/** A manually-resolvable searcher result, for observing in-flight states. */
+function deferred() {
+  let resolve!: (r: WorkspaceContentSearchResult) => void;
+  const promise = new Promise<WorkspaceContentSearchResult>((res) => {
+    resolve = res;
+  });
+  return { promise, resolve };
+}
+
+afterEach(cleanup);
+
+describe("useWorkspaceContentSearch", () => {
+  it("is unsupported and never searches when no searcher is injected", () => {
+    const entries = [makeEntry()];
+    const { result: r } = renderHook(() =>
+      useWorkspaceContentSearch({
+        entries,
+        searcher: undefined,
+        query: "foo",
+        debounceMs: 0,
+      }),
+    );
+    expect(r.current.isUnsupported).toBe(true);
+    expect(r.current.groups).toEqual([]);
+  });
+
+  it("does not search below the minimum query length", async () => {
+    const entries = [makeEntry()];
+    const searcher = vi.fn(async () => result([])) as unknown as WorkspaceContentSearcher;
+    const { result: r } = renderHook(() =>
+      useWorkspaceContentSearch({ entries, searcher, query: "a", debounceMs: 0 }),
+    );
+    // Give the debounce a tick to (not) fire.
+    await new Promise((res) => setTimeout(res, 20));
+    expect(searcher).not.toHaveBeenCalled();
+    expect(r.current.groups).toEqual([]);
+    expect(r.current.isUnsupported).toBe(false);
+  });
+
+  it("aggregates per-entry line matches", async () => {
+    const a = makeEntry();
+    const b = makeEntry();
+    const searcher: WorkspaceContentSearcher = vi.fn(async (e) =>
+      e.id === a.id
+        ? result([match("a.ts", 1, "foo one"), match("a.ts", 4, "foo two")])
+        : result([match("b.ts", 2, "foo three")]),
+    );
+
+    const { result: r } = renderHook(() =>
+      useWorkspaceContentSearch({ entries: [a, b], searcher, query: "foo", debounceMs: 0 }),
+    );
+    await waitFor(() => expect(r.current.isLoading).toBe(false));
+
+    expect(r.current.totalMatches).toBe(3);
+    expect(
+      r.current.groups.map((g) => ({ id: g.entry.id, lines: g.matches.map((m) => m.line) })),
+    ).toEqual([
+      { id: a.id, lines: [1, 4] },
+      { id: b.id, lines: [2] },
+    ]);
+  });
+
+  it("isolates a per-entry error while other entries still resolve", async () => {
+    const good = makeEntry();
+    const bad = makeEntry();
+    const searcher: WorkspaceContentSearcher = vi.fn(async (e) => {
+      if (e.id === bad.id) throw new Error("disk error");
+      return result([match("a.ts", 1, "foo")]);
+    });
+
+    const { result: r } = renderHook(() =>
+      useWorkspaceContentSearch({ entries: [good, bad], searcher, query: "foo", debounceMs: 0 }),
+    );
+    await waitFor(() => expect(r.current.isLoading).toBe(false));
+
+    expect(r.current.groups.find((g) => g.entry.id === good.id)?.matches).toHaveLength(1);
+    expect(r.current.groups.find((g) => g.entry.id === bad.id)?.error?.message).toBe("disk error");
+    expect(r.current.error?.message).toBe("disk error");
+  });
+
+  it("reports isUnsupported when every entry returns null", async () => {
+    const entries = [makeEntry()];
+    const searcher: WorkspaceContentSearcher = vi.fn(async () => null);
+    const { result: r } = renderHook(() =>
+      useWorkspaceContentSearch({ entries, searcher, query: "foo", debounceMs: 0 }),
+    );
+    await waitFor(() => expect(r.current.isUnsupported).toBe(true));
+    expect(r.current.groups).toEqual([]);
+  });
+
+  it("surfaces a per-entry truncation flag", async () => {
+    const entries = [makeEntry()];
+    const searcher: WorkspaceContentSearcher = vi.fn(async () =>
+      result([match("a.ts", 1, "foo")], true),
+    );
+    const { result: r } = renderHook(() =>
+      useWorkspaceContentSearch({ entries, searcher, query: "foo", debounceMs: 0 }),
+    );
+    await waitFor(() => expect(r.current.isLoading).toBe(false));
+    expect(r.current.groups[0].truncated).toBe(true);
+  });
+
+  it("keeps prior results visible while a new query loads (isRefetching, no blank flash)", async () => {
+    const entry = makeEntry();
+    const second = deferred();
+    const searcher = vi
+      .fn()
+      .mockResolvedValueOnce(result([match("a.ts", 1, "foo")]))
+      .mockReturnValueOnce(second.promise) as unknown as WorkspaceContentSearcher;
+
+    const { result: r, rerender } = renderHook(
+      ({ q }) => useWorkspaceContentSearch({ entries: [entry], searcher, query: q, debounceMs: 0 }),
+      { initialProps: { q: "foo" } },
+    );
+
+    await waitFor(() => expect(r.current.groups[0]?.matches).toHaveLength(1));
+    expect(r.current.isLoading).toBe(false);
+
+    // New query → the second (pending) search starts; old results stay visible.
+    rerender({ q: "bar" });
+    await waitFor(() => expect(r.current.isRefetching).toBe(true));
+    expect(r.current.isLoading).toBe(false);
+    expect(r.current.groups[0].matches).toHaveLength(1);
+
+    // Resolve the second search → new results replace the old ones.
+    second.resolve(result([match("b.ts", 2, "bar"), match("c.ts", 3, "bar")]));
+    await waitFor(() => expect(r.current.isRefetching).toBe(false));
+    expect(r.current.totalMatches).toBe(2);
+  });
+
+  it("ignores a stale in-flight search when the query changes again", async () => {
+    const entry = makeEntry();
+    const first = deferred();
+    const searcher = vi
+      .fn()
+      .mockReturnValueOnce(first.promise)
+      .mockResolvedValueOnce(result([match("new.ts", 1, "bar")])) as unknown as WorkspaceContentSearcher;
+
+    const { result: r, rerender } = renderHook(
+      ({ q }) => useWorkspaceContentSearch({ entries: [entry], searcher, query: q, debounceMs: 0 }),
+      { initialProps: { q: "foo" } },
+    );
+
+    // Supersede the first (still pending) query; the second resolves.
+    rerender({ q: "bar" });
+    await waitFor(() =>
+      expect(r.current.groups.map((g) => g.matches.map((m) => m.path))).toEqual([["new.ts"]]),
+    );
+
+    // The stale first now resolves — it must not clobber the fresher result.
+    first.resolve(result([match("stale.ts", 9, "foo")]));
+    await new Promise((res) => setTimeout(res, 20));
+    expect(r.current.groups.map((g) => g.matches.map((m) => m.path))).toEqual([["new.ts"]]);
+  });
+});

package/src/workspace/__tests__/useWorkspaceFileContent.test.tsx

@@ -0,0 +1,190 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { useWorkspaceFileContent } from "../useWorkspaceFileContent";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+import type {
+  WorkspaceFileContent,
+  WorkspaceFileReader,
+} from "../WorkspaceFileReader";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function gitEntry(id = "e1"): WorkspaceEntry {
+  return {
+    id,
+    name: "acme/repo",
+    type: "git",
+    gitUrl: "https://github.com/acme/repo",
+    gitBranch: "main",
+  };
+}
+
+function textContent(text: string): WorkspaceFileContent {
+  return { text, isBinary: false, size: text.length, encoding: "utf-8" };
+}
+
+// ---------------------------------------------------------------------------
+// useWorkspaceFileContent
+// ---------------------------------------------------------------------------
+
+describe("useWorkspaceFileContent", () => {
+  it("resolves file content on success and is not unsupported", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async () => textContent("hello"));
+    const { result } = renderHook(() =>
+      useWorkspaceFileContent({ entry: gitEntry(), path: "a.ts", reader }),
+    );
+
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.content?.text).toBe("hello");
+    expect(result.current.isUnsupported).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("reports isUnsupported when the reader resolves null", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async () => null);
+    const { result } = renderHook(() =>
+      useWorkspaceFileContent({ entry: gitEntry(), path: "a.ts", reader }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.content).toBeNull();
+    expect(result.current.isUnsupported).toBe(true);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("surfaces a reader throw as error, not unsupported", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    const { result } = renderHook(() =>
+      useWorkspaceFileContent({ entry: gitEntry(), path: "a.ts", reader }),
+    );
+
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+
+    expect(result.current.error?.message).toBe("boom");
+    expect(result.current.isUnsupported).toBe(false);
+    expect(result.current.content).toBeNull();
+  });
+
+  it("stays idle and unsupported when no reader is injected", () => {
+    const { result } = renderHook(() =>
+      useWorkspaceFileContent({ entry: gitEntry(), path: "a.ts", reader: undefined }),
+    );
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isUnsupported).toBe(true);
+    expect(result.current.content).toBeNull();
+  });
+
+  it("does not treat a binary file (present object, text null) as unsupported", async () => {
+    const binary: WorkspaceFileContent = {
+      text: null,
+      isBinary: true,
+      size: 10,
+      encoding: "unknown",
+    };
+    const reader: WorkspaceFileReader = vi.fn(async () => binary);
+    const { result } = renderHook(() =>
+      useWorkspaceFileContent({ entry: gitEntry(), path: "img.png", reader }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.content).toEqual(binary);
+    expect(result.current.isUnsupported).toBe(false);
+  });
+
+  it("stays idle and never calls the reader when no file is selected", () => {
+    const reader = vi.fn(async () => textContent("x")) as WorkspaceFileReader;
+    const { result } = renderHook(() =>
+      useWorkspaceFileContent({ entry: null, path: null, reader }),
+    );
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.isUnsupported).toBe(false);
+    expect(reader).not.toHaveBeenCalled();
+  });
+
+  it("re-reads on refetch()", async () => {
+    let n = 0;
+    const reader: WorkspaceFileReader = vi.fn(async () => textContent(`v${++n}`));
+    const { result } = renderHook(() =>
+      useWorkspaceFileContent({ entry: gitEntry(), path: "a.ts", reader }),
+    );
+
+    await waitFor(() => expect(result.current.content?.text).toBe("v1"));
+
+    act(() => {
+      result.current.refetch();
+    });
+
+    await waitFor(() => expect(result.current.content?.text).toBe("v2"));
+    expect(reader).toHaveBeenCalledTimes(2);
+  });
+
+  it("re-reads when the path changes", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async (_e, p) =>
+      textContent(`content:${p}`),
+    );
+    const { result, rerender } = renderHook(
+      (props: { path: string }) =>
+        useWorkspaceFileContent({ entry: gitEntry(), path: props.path, reader }),
+      { initialProps: { path: "a.ts" } },
+    );
+
+    await waitFor(() => expect(result.current.content?.text).toBe("content:a.ts"));
+
+    rerender({ path: "b.ts" });
+
+    await waitFor(() => expect(result.current.content?.text).toBe("content:b.ts"));
+  });
+
+  it("ignores a stale slow read when the path changes mid-flight", async () => {
+    const deferred = new Map<string, (v: WorkspaceFileContent) => void>();
+    const reader: WorkspaceFileReader = (_e, p) =>
+      new Promise((resolve) => deferred.set(p, resolve));
+
+    const { result, rerender } = renderHook(
+      (props: { path: string }) =>
+        useWorkspaceFileContent({ entry: gitEntry(), path: props.path, reader }),
+      { initialProps: { path: "slow.ts" } },
+    );
+
+    // Switch to a second file before the first resolves.
+    rerender({ path: "fast.ts" });
+
+    // Resolve the current (fast) read first.
+    await act(async () => {
+      deferred.get("fast.ts")!(textContent("FAST"));
+    });
+    await waitFor(() => expect(result.current.content?.text).toBe("FAST"));
+
+    // The stale (slow) read resolves later — it must NOT overwrite FAST.
+    await act(async () => {
+      deferred.get("slow.ts")!(textContent("SLOW"));
+    });
+    expect(result.current.content?.text).toBe("FAST");
+  });
+
+  it("goes idle when the entry is removed (entry -> null)", async () => {
+    const reader: WorkspaceFileReader = vi.fn(async () => textContent("x"));
+    const { result, rerender } = renderHook(
+      (props: { entry: WorkspaceEntry | null }) =>
+        useWorkspaceFileContent({ entry: props.entry, path: "a.ts", reader }),
+      { initialProps: { entry: gitEntry() as WorkspaceEntry | null } },
+    );
+
+    await waitFor(() => expect(result.current.content?.text).toBe("x"));
+
+    rerender({ entry: null });
+
+    await waitFor(() => expect(result.current.content).toBeNull());
+    expect(result.current.isLoading).toBe(false);
+  });
+});

package/src/workspace/__tests__/useWorkspaceFileSearch.test.tsx

@@ -0,0 +1,162 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, cleanup } from "@testing-library/react";
+import { useWorkspaceFileSearch } from "../useWorkspaceFileSearch";
+import { __clearWorkspaceListingCache } from "../workspaceListingCache";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+import type { WorkspaceFileEntry, WorkspaceFileLister } from "../WorkspaceFileLister";
+
+let entryIdCounter = 0;
+
+function makeEntry(overrides?: Partial<WorkspaceEntry>): WorkspaceEntry {
+  return {
+    id: `ws-${++entryIdCounter}`,
+    name: "acme/api",
+    type: "git",
+    gitUrl: "https://github.com/acme/api",
+    gitBranch: "main",
+    ...overrides,
+  };
+}
+
+const FILES_A: WorkspaceFileEntry[] = [
+  { path: "src/index.ts", isDirectory: false },
+  { path: "src/button.tsx", isDirectory: false },
+  { path: "README.md", isDirectory: false },
+];
+
+const FILES_B: WorkspaceFileEntry[] = [
+  { path: "lib/button.ts", isDirectory: false },
+  { path: "lib/util.ts", isDirectory: false },
+];
+
+describe("useWorkspaceFileSearch", () => {
+  beforeEach(() => {
+    __clearWorkspaceListingCache();
+  });
+  afterEach(cleanup);
+
+  it("is unsupported and never fetches when no lister is injected", () => {
+    const lister = vi.fn();
+    const entries = [makeEntry()];
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries, lister: undefined, query: "x" }),
+    );
+    expect(result.current.isUnsupported).toBe(true);
+    expect(result.current.groups).toEqual([]);
+    expect(lister).not.toHaveBeenCalled();
+  });
+
+  it("aggregates ranked matches across multiple entries", async () => {
+    const entryA = makeEntry();
+    const entryB = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async (e) =>
+      e.id === entryA.id ? FILES_A : FILES_B,
+    );
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entryA, entryB], lister, query: "button" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.totalMatches).toBe(2);
+    const groupPaths = result.current.groups.map((g) => ({
+      id: g.entry.id,
+      paths: g.matches.map((m) => m.path),
+    }));
+    expect(groupPaths).toEqual([
+      { id: entryA.id, paths: ["src/button.tsx"] },
+      { id: entryB.id, paths: ["lib/button.ts"] },
+    ]);
+  });
+
+  it("reuses the shared cache — no refetch when warm", async () => {
+    const entry = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async () => FILES_A);
+
+    const first = renderHook(
+      ({ q }) => useWorkspaceFileSearch({ entries: [entry], lister, query: q }),
+      { initialProps: { q: "button" } },
+    );
+    await waitFor(() => expect(first.result.current.isLoading).toBe(false));
+    expect(lister).toHaveBeenCalledTimes(1);
+    first.unmount();
+
+    // Remount (re-enter Search) with the same entry → served from cache.
+    const second = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entry], lister, query: "index" }),
+    );
+    await waitFor(() => expect(second.result.current.isLoading).toBe(false));
+    expect(lister).toHaveBeenCalledTimes(1);
+    expect(second.result.current.groups[0].matches.map((m) => m.path)).toEqual([
+      "src/index.ts",
+    ]);
+  });
+
+  it("isolates a per-entry error while other entries still resolve", async () => {
+    const good = makeEntry();
+    const bad = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async (e) => {
+      if (e.id === bad.id) throw new Error("network down");
+      return FILES_A;
+    });
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [good, bad], lister, query: "button" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const goodGroup = result.current.groups.find((g) => g.entry.id === good.id);
+    const badGroup = result.current.groups.find((g) => g.entry.id === bad.id);
+    expect(goodGroup?.matches.map((m) => m.path)).toEqual(["src/button.tsx"]);
+    expect(badGroup?.error?.message).toBe("network down");
+    expect(result.current.error?.message).toBe("network down");
+  });
+
+  it("surfaces per-group truncated from a notice entry", async () => {
+    const entry = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async () => [
+      { path: "src/button.tsx", isDirectory: false },
+      { path: "... truncated", isDirectory: false, notice: true as const },
+    ]);
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entry], lister, query: "button" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.groups[0].truncated).toBe(true);
+    expect(result.current.groups[0].matches.map((m) => m.path)).toEqual([
+      "src/button.tsx",
+    ]);
+  });
+
+  it("reports isUnsupported when every entry's substrate returns null", async () => {
+    const entry = makeEntry();
+    const lister: WorkspaceFileLister = vi.fn(async () => null);
+
+    const { result } = renderHook(() =>
+      useWorkspaceFileSearch({ entries: [entry], lister, query: "x" }),
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.isUnsupported).toBe(true);
+    expect(result.current.groups).toEqual([]);
+  });
+
+  it("keeps a stable return reference across rerenders with an unchanged query", async () => {
+    const entry = makeEntry();
+    const entries = [entry];
+    const lister: WorkspaceFileLister = vi.fn(async () => FILES_A);
+
+    const { result, rerender } = renderHook(() =>
+      useWorkspaceFileSearch({ entries, lister, query: "button" }),
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    const before = result.current;
+    rerender();
+    expect(result.current).toBe(before);
+  });
+});