@stigmer/react 3.1.1 → 3.1.3

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

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { findHighlightRanges } from "../matchContentPreview";
+
+describe("findHighlightRanges", () => {
+  it("returns no ranges for an empty or whitespace query", () => {
+    expect(findHighlightRanges("hello world", "")).toEqual([]);
+    expect(findHighlightRanges("hello world", "   ")).toEqual([]);
+  });
+
+  it("returns no ranges when the query is absent", () => {
+    expect(findHighlightRanges("hello world", "xyz")).toEqual([]);
+  });
+
+  it("finds a single occurrence", () => {
+    expect(findHighlightRanges("hello world", "world")).toEqual([
+      { start: 6, end: 11 },
+    ]);
+  });
+
+  it("finds every occurrence on the line", () => {
+    expect(findHighlightRanges("foo bar foo baz foo", "foo")).toEqual([
+      { start: 0, end: 3 },
+      { start: 8, end: 11 },
+      { start: 16, end: 19 },
+    ]);
+  });
+
+  it("matches case-insensitively but reports offsets into the original text", () => {
+    expect(findHighlightRanges("TODO todo ToDo", "todo")).toEqual([
+      { start: 0, end: 4 },
+      { start: 5, end: 9 },
+      { start: 10, end: 14 },
+    ]);
+  });
+
+  it("does not produce overlapping ranges (advances past each match)", () => {
+    // "aa" in "aaaa" → [0,2) and [2,4), not [1,3).
+    expect(findHighlightRanges("aaaa", "aa")).toEqual([
+      { start: 0, end: 2 },
+      { start: 2, end: 4 },
+    ]);
+  });
+
+  it("trims the query before matching", () => {
+    expect(findHighlightRanges("hello world", "  world  ")).toEqual([
+      { start: 6, end: 11 },
+    ]);
+  });
+
+  it("handles multibyte text with correct code-unit offsets", () => {
+    const text = "日本 needle 世界";
+    const [range] = findHighlightRanges(text, "needle");
+    expect(text.slice(range.start, range.end)).toBe("needle");
+  });
+});

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

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest";
+import { matchWorkspaceFiles } from "../matchWorkspaceFiles";
+import type { WorkspaceFileEntry } from "../WorkspaceFileLister";
+
+function file(path: string): WorkspaceFileEntry {
+  return { path, isDirectory: false };
+}
+
+describe("matchWorkspaceFiles", () => {
+  it("returns [] for an empty or whitespace query", () => {
+    const files = [file("src/index.ts")];
+    expect(matchWorkspaceFiles(files, "")).toEqual([]);
+    expect(matchWorkspaceFiles(files, "   ")).toEqual([]);
+  });
+
+  it("matches case-insensitively on the full relative path", () => {
+    const files = [file("src/Components/Button.tsx")];
+    const result = matchWorkspaceFiles(files, "button");
+    expect(result).toHaveLength(1);
+    expect(result[0].path).toBe("src/Components/Button.tsx");
+  });
+
+  it("finds files by a cross-segment path substring", () => {
+    const files = [file("src/utils/helper.ts"), file("README.md")];
+    const result = matchWorkspaceFiles(files, "utils/helper");
+    expect(result.map((m) => m.path)).toEqual(["src/utils/helper.ts"]);
+  });
+
+  it("excludes directories", () => {
+    const files: WorkspaceFileEntry[] = [
+      { path: "src", isDirectory: true },
+      { path: "src/index.ts", isDirectory: false },
+    ];
+    const result = matchWorkspaceFiles(files, "src");
+    expect(result.map((m) => m.path)).toEqual(["src/index.ts"]);
+  });
+
+  it("excludes advisory notice entries even if the query matches the message", () => {
+    const files: WorkspaceFileEntry[] = [
+      { path: "src/tree.ts", isDirectory: false },
+      { path: "... (tree truncated by GitHub — repository has too many files)", isDirectory: false, notice: true },
+    ];
+    const result = matchWorkspaceFiles(files, "tree");
+    expect(result.map((m) => m.path)).toEqual(["src/tree.ts"]);
+  });
+
+  it("returns [] when nothing matches", () => {
+    expect(matchWorkspaceFiles([file("src/index.ts")], "zzz")).toEqual([]);
+  });
+
+  it("reports the contiguous highlight range as code-unit offsets", () => {
+    const [m] = matchWorkspaceFiles([file("src/index.ts")], "index");
+    expect(m.matchStart).toBe(4);
+    expect(m.matchEnd).toBe(9);
+    expect("src/index.ts".slice(m.matchStart, m.matchEnd)).toBe("index");
+  });
+
+  it("ranks a basename hit above a path-only hit", () => {
+    const files = [
+      file("app/main.ts"), // "app" is only in the dir segment (path-only)
+      file("src/app.ts"), // "app" is the basename
+    ];
+    const result = matchWorkspaceFiles(files, "app");
+    expect(result[0].path).toBe("src/app.ts");
+    expect(result[1].path).toBe("app/main.ts");
+  });
+
+  it("ranks an earlier match offset first among basename hits", () => {
+    const files = [file("src/index.ts"), file("index.ts")];
+    const result = matchWorkspaceFiles(files, "index");
+    // "index.ts" matches at offset 0; "src/index.ts" at offset 4.
+    expect(result.map((m) => m.path)).toEqual(["index.ts", "src/index.ts"]);
+  });
+
+  it("breaks ties by shorter path then lexicographically", () => {
+    const files = [
+      file("b/thing.ts"),
+      file("a/thing.ts"),
+      file("thing.ts"),
+    ];
+    const result = matchWorkspaceFiles(files, "thing");
+    // "thing.ts" (offset 0) first; the two offset-2 hits tie on length → lexicographic.
+    expect(result.map((m) => m.path)).toEqual([
+      "thing.ts",
+      "a/thing.ts",
+      "b/thing.ts",
+    ]);
+  });
+
+  it("handles unicode paths and slices the range consistently", () => {
+    const files = [file("src/café/résumé.ts")];
+    const [m] = matchWorkspaceFiles(files, "résumé");
+    expect(m).toBeDefined();
+    expect("src/café/résumé.ts".slice(m.matchStart, m.matchEnd)).toBe("résumé");
+  });
+
+  it("is deterministic regardless of input order", () => {
+    const a = [file("z.ts"), file("a.ts"), file("m.ts")];
+    const b = [file("a.ts"), file("m.ts"), file("z.ts")];
+    const qa = matchWorkspaceFiles(a, ".ts").map((m) => m.path);
+    const qb = matchWorkspaceFiles(b, ".ts").map((m) => m.path);
+    expect(qa).toEqual(qb);
+  });
+});

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