@stigmer/react 3.1.0 → 3.1.2

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

@@ -0,0 +1,348 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup, fireEvent, within } from "@testing-library/react";
+import { forwardRef } from "react";
+
+// ---------------------------------------------------------------------------
+// WorkspaceSurface composes the activity rail (Explorer / Search), a resizable
+// sidebar, and the read-only editor. The explorer tree, search, and viewer are
+// exercised by their own suites; here we mock them as probes and prove the
+// surface's own composition — rail switching, the editor tabs/toolbar, collapse,
+// breadcrumbs, and that the active file (+ its change) reaches a chrome-less
+// FileViewer.
+// ---------------------------------------------------------------------------
+
+type CapturedProps = Record<string, unknown>;
+
+const viewerProps: CapturedProps[] = [];
+vi.mock("../FileViewer", () => ({
+  FileViewer: forwardRef((props: CapturedProps, _ref) => {
+    viewerProps.push(props);
+    return <div data-testid="viewer-probe" />;
+  }),
+}));
+
+vi.mock("../ExplorerTree", () => ({
+  ExplorerTree: () => <div data-testid="explorer-probe" />,
+}));
+
+vi.mock("../WorkspaceFileSearch", () => ({
+  WorkspaceFileSearch: () => <div data-testid="search-probe" />,
+}));
+
+vi.mock("../WorkspaceContentSearch", () => ({
+  WorkspaceContentSearch: () => <div data-testid="content-search-probe" />,
+}));
+
+import { WorkspaceSurface } from "../WorkspaceSurface";
+import { virtualEntryId } from "../../internal/store/index.js";
+import type { WorkspaceEntry } from "../useWorkspaceEntries";
+import type { WorkspaceFileLister } from "../WorkspaceFileLister";
+import type { WorkspaceFileReader } from "../WorkspaceFileReader";
+import type { WorkspaceContentSearcher } from "../WorkspaceContentSearcher";
+
+const gitEntry: WorkspaceEntry = {
+  id: "e1",
+  name: "acme/app",
+  type: "git",
+  gitUrl: "https://github.com/acme/app.git",
+  gitBranch: "main",
+} as WorkspaceEntry;
+
+const lister: WorkspaceFileLister = vi.fn(async () => []) as unknown as WorkspaceFileLister;
+const reader: WorkspaceFileReader = vi.fn(async () => null) as unknown as WorkspaceFileReader;
+const searcher: WorkspaceContentSearcher = vi.fn(async () => ({
+  matches: [],
+  truncated: false,
+})) as unknown as WorkspaceContentSearcher;
+
+function renderSurface(overrides: Partial<React.ComponentProps<typeof WorkspaceSurface>> = {}) {
+  const onOpenFile = vi.fn();
+  const onActivateEditor = vi.fn();
+  const onPinEditor = vi.fn();
+  const onCloseEditor = vi.fn();
+  const onCollapse = vi.fn();
+  render(
+    <WorkspaceSurface
+      entries={[gitEntry]}
+      lister={lister}
+      reader={reader}
+      editors={[{ entryId: "e1", path: "src/main.go", preview: false }]}
+      selectedFile={{ entryId: "e1", path: "src/main.go" }}
+      onOpenFile={onOpenFile}
+      onActivateEditor={onActivateEditor}
+      onPinEditor={onPinEditor}
+      onCloseEditor={onCloseEditor}
+      onCollapse={onCollapse}
+      {...overrides}
+    />,
+  );
+  return { onOpenFile, onActivateEditor, onPinEditor, onCloseEditor, onCollapse };
+}
+
+beforeEach(() => {
+  viewerProps.length = 0;
+});
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe("WorkspaceSurface", () => {
+  it("renders the activity rail with Explorer selected by default", () => {
+    renderSurface();
+    const explorer = screen.getByRole("radio", { name: "Explorer" });
+    const search = screen.getByRole("radio", { name: "Search" });
+    expect(explorer.getAttribute("aria-checked")).toBe("true");
+    expect(search.getAttribute("aria-checked")).toBe("false");
+    // Explorer view: the explorer tree renders; the search surface does not.
+    expect(screen.getByTestId("explorer-probe")).toBeTruthy();
+    expect(screen.queryByTestId("search-probe")).toBeNull();
+  });
+
+  it("switches to the search surface when Search is selected", () => {
+    renderSurface();
+    fireEvent.click(screen.getByRole("radio", { name: "Search" }));
+    expect(screen.getByTestId("search-probe")).toBeTruthy();
+    expect(screen.queryByTestId("explorer-probe")).toBeNull();
+  });
+
+  it("shows only filename search (no Name|Text toggle) when no content searcher is injected", () => {
+    renderSurface();
+    fireEvent.click(screen.getByRole("radio", { name: "Search" }));
+    expect(screen.queryByRole("radiogroup", { name: "Search mode" })).toBeNull();
+    expect(screen.getByTestId("search-probe")).toBeTruthy();
+    expect(screen.queryByTestId("content-search-probe")).toBeNull();
+  });
+
+  it("offers a Name|Text toggle when a content searcher is injected, routing Text to content search", () => {
+    renderSurface({ searcher });
+    fireEvent.click(screen.getByRole("radio", { name: "Search" }));
+
+    const toggle = screen.getByRole("radiogroup", { name: "Search mode" });
+    expect(toggle).toBeTruthy();
+    // Filename search is the default mode.
+    expect(screen.getByTestId("search-probe")).toBeTruthy();
+    expect(screen.queryByTestId("content-search-probe")).toBeNull();
+
+    // Switching to Text routes to the content-search surface.
+    fireEvent.click(within(toggle).getByRole("radio", { name: "Text" }));
+    expect(screen.getByTestId("content-search-probe")).toBeTruthy();
+    expect(screen.queryByTestId("search-probe")).toBeNull();
+  });
+
+  it("hands the open file (and its change) to a chrome-less FileViewer", () => {
+    const change = { path: "src/main.go" } as never;
+    renderSurface({ change });
+    const props = viewerProps.at(-1);
+    expect(props?.selectedFile).toEqual({ entryId: "e1", path: "src/main.go" });
+    expect(props?.showHeader).toBe(false);
+    expect(props?.change).toBe(change);
+  });
+
+  it("forwards a jump-to-line reveal to the FileViewer", () => {
+    const reveal = { line: 12, nonce: 3 };
+    renderSurface({ reveal });
+    expect(viewerProps.at(-1)?.reveal).toBe(reveal);
+  });
+
+  it("shows the open file as a tab", () => {
+    renderSurface();
+    const tab = screen.getByRole("tab", { name: /main\.go/ });
+    expect(tab).toBeTruthy();
+    expect(tab.getAttribute("aria-selected")).toBe("true");
+  });
+
+  it("collapses back to chat when the toolbar control is clicked", () => {
+    const { onCollapse } = renderSurface();
+    fireEvent.click(screen.getByRole("button", { name: "Back to chat" }));
+    expect(onCollapse).toHaveBeenCalledTimes(1);
+  });
+
+  it("shows an empty editor when no file is selected", () => {
+    renderSurface({ selectedFile: null, editors: [] });
+    expect(viewerProps.length).toBe(0);
+    expect(screen.getByText("Select a file to view its contents.")).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Host-injected rail views (extraViews) — the unified-panel extension seam
+// ---------------------------------------------------------------------------
+
+const configView = {
+  id: "configure",
+  label: "Config",
+  icon: <span data-testid="config-icon" />,
+  content: <div data-testid="config-probe" />,
+};
+
+const changesView = {
+  id: "changes",
+  label: "Changes",
+  icon: <span />,
+  badge: 3,
+  content: <div data-testid="changes-probe" />,
+};
+
+describe("WorkspaceSurface extraViews", () => {
+  it("renders injected views in the rail after the built-ins", () => {
+    renderSurface({ extraViews: [configView, changesView] });
+    const radios = screen.getAllByRole("radio");
+    expect(radios.map((r) => r.getAttribute("title"))).toEqual([
+      "Explorer",
+      "Search",
+      "Config",
+      "Changes",
+    ]);
+  });
+
+  it("shows a count badge on a rail view and folds it into the accessible name", () => {
+    renderSurface({ extraViews: [changesView] });
+    const changes = screen.getByRole("radio", { name: "Changes (3)" });
+    expect(changes.textContent).toContain("3");
+  });
+
+  it("renders an extra view's content in the sidebar (with heading) when selected, keeping the editor area", () => {
+    renderSurface({ extraViews: [configView] });
+    fireEvent.click(screen.getByRole("radio", { name: "Config" }));
+    expect(screen.getByTestId("config-probe")).toBeTruthy();
+    expect(screen.queryByTestId("explorer-probe")).toBeNull();
+    // Sidebar heading + the editor area (file tab) both present.
+    expect(screen.getByText("Config")).toBeTruthy();
+    expect(screen.getByRole("tab", { name: /main\.go/ })).toBeTruthy();
+  });
+
+  it("supports controlled view selection via view/onViewChange", () => {
+    const onViewChange = vi.fn();
+    renderSurface({
+      extraViews: [configView],
+      view: "configure",
+      onViewChange,
+    });
+    expect(screen.getByTestId("config-probe")).toBeTruthy();
+    fireEvent.click(screen.getByRole("radio", { name: "Search" }));
+    expect(onViewChange).toHaveBeenCalledWith("search");
+    // Controlled: the view does not change until the owner re-renders.
+    expect(screen.getByTestId("config-probe")).toBeTruthy();
+  });
+
+  it("falls back to the explorer when the active view id no longer exists", () => {
+    // e.g. a contextual view (Inspect) that disappeared while active.
+    renderSurface({ extraViews: [], view: "inspect" });
+    expect(screen.getByTestId("explorer-probe")).toBeTruthy();
+    expect(
+      screen.getByRole("radio", { name: "Explorer" }).getAttribute("aria-checked"),
+    ).toBe("true");
+  });
+
+  it("moves across built-in and injected views with arrow keys", () => {
+    renderSurface({ extraViews: [configView] });
+    const search = screen.getByRole("radio", { name: "Search" });
+    fireEvent.click(search);
+    fireEvent.keyDown(search, { key: "ArrowDown" });
+    expect(screen.getByTestId("config-probe")).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Host-injected virtual documents — editor tabs that are not workspace files
+// (the session's plan.md today). Same open/pin/close semantics as file tabs;
+// only the body rendering diverges.
+// ---------------------------------------------------------------------------
+
+const PLAN_ENTRY_ID = virtualEntryId("plan");
+
+const planDocument = {
+  entryId: PLAN_ENTRY_ID,
+  path: "plan.md",
+  content: <div data-testid="plan-doc-probe" />,
+};
+
+describe("WorkspaceSurface virtualDocuments", () => {
+  it("renders the virtual document's content — no FileViewer, no breadcrumbs", () => {
+    renderSurface({
+      virtualDocuments: [planDocument],
+      editors: [{ entryId: PLAN_ENTRY_ID, path: "plan.md", preview: false }],
+      selectedFile: { entryId: PLAN_ENTRY_ID, path: "plan.md" },
+    });
+    expect(screen.getByTestId("plan-doc-probe")).toBeTruthy();
+    expect(viewerProps.length).toBe(0);
+    expect(screen.queryByRole("navigation", { name: "File location" })).toBeNull();
+  });
+
+  it("shows the virtual document as an ordinary tab (basename label)", () => {
+    renderSurface({
+      virtualDocuments: [planDocument],
+      editors: [
+        { entryId: "e1", path: "src/main.go", preview: false },
+        { entryId: PLAN_ENTRY_ID, path: "plan.md", preview: false },
+      ],
+      selectedFile: { entryId: PLAN_ENTRY_ID, path: "plan.md" },
+    });
+    const tab = screen.getByRole("tab", { name: /plan\.md/ });
+    expect(tab.getAttribute("aria-selected")).toBe("true");
+  });
+
+  it("keeps file tabs on the FileViewer path while a virtual document is injected", () => {
+    renderSurface({
+      virtualDocuments: [planDocument],
+      editors: [
+        { entryId: "e1", path: "src/main.go", preview: false },
+        { entryId: PLAN_ENTRY_ID, path: "plan.md", preview: false },
+      ],
+      selectedFile: { entryId: "e1", path: "src/main.go" },
+    });
+    expect(screen.queryByTestId("plan-doc-probe")).toBeNull();
+    expect(viewerProps.at(-1)?.selectedFile).toEqual({
+      entryId: "e1",
+      path: "src/main.go",
+    });
+  });
+
+  it("a virtual entry id can never alias a real file of the same path", () => {
+    // The NUL-namespaced id is the collision guard: a workspace file named
+    // plan.md under a real entry must not hijack the virtual document body.
+    renderSurface({
+      virtualDocuments: [planDocument],
+      editors: [{ entryId: "e1", path: "plan.md", preview: false }],
+      selectedFile: { entryId: "e1", path: "plan.md" },
+    });
+    expect(screen.queryByTestId("plan-doc-probe")).toBeNull();
+    expect(viewerProps.at(-1)?.selectedFile).toEqual({
+      entryId: "e1",
+      path: "plan.md",
+    });
+  });
+
+  it("scrolls the document body vertically only — wide content reflows, never a sideways scrollbar", () => {
+    renderSurface({
+      virtualDocuments: [planDocument],
+      editors: [{ entryId: PLAN_ENTRY_ID, path: "plan.md", preview: false }],
+      selectedFile: { entryId: PLAN_ENTRY_ID, path: "plan.md" },
+    });
+    const body = screen.getByTestId("plan-doc-probe").parentElement!;
+    expect(body.className).toContain("overflow-y-auto");
+    // overflow-y alone computes overflow-x to auto; the explicit hidden +
+    // min-w-0 pair is what forces documents to reflow at narrow widths.
+    expect(body.className).toContain("overflow-x-hidden");
+    expect(body.className).toContain("min-w-0");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Workspace entry management in the Explorer sidebar
+// ---------------------------------------------------------------------------
+
+describe("WorkspaceSurface entry management", () => {
+  it("renders an Add Folder footer action when onAddLocalFolder is provided", () => {
+    const onAddLocalFolder = vi.fn();
+    renderSurface({ onAddLocalFolder });
+    fireEvent.click(screen.getByRole("button", { name: "Add Folder" }));
+    expect(onAddLocalFolder).toHaveBeenCalledTimes(1);
+  });
+
+  it("omits the Add Folder action without the callback (web has no native picker)", () => {
+    renderSurface();
+    expect(screen.queryByRole("button", { name: "Add Folder" })).toBeNull();
+  });
+});

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

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import {
+  FileChangeSchema,
+  type FileChange,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { FileChangeType } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { findChangeForSelection } from "../findChangeForSelection";
+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 };
+}
+
+function change(
+  fields: { path?: string; absolutePath?: string; changeType?: FileChangeType },
+): FileChange {
+  return create(FileChangeSchema, {
+    path: fields.path ?? "",
+    absolutePath: fields.absolutePath ?? "",
+    changeType: fields.changeType ?? FileChangeType.MODIFY,
+  });
+}
+
+const DAYTONA = "/home/daytona/workspace";
+
+describe("findChangeForSelection", () => {
+  it("matches a single-entry change by exact repo-relative path", () => {
+    const entries = [git("e1", "org/repo")];
+    const changes = [change({ path: "src/main.go" })];
+    expect(
+      findChangeForSelection({ entryId: "e1", path: "src/main.go" }, changes, entries),
+    ).toBe(changes[0]);
+  });
+
+  it("returns null when no change touches the open file", () => {
+    const entries = [git("e1", "org/repo")];
+    const changes = [change({ path: "src/other.go" })];
+    expect(
+      findChangeForSelection({ entryId: "e1", path: "src/main.go" }, changes, entries),
+    ).toBeNull();
+  });
+
+  it("returns null for an empty change list", () => {
+    const entries = [git("e1", "org/repo")];
+    expect(
+      findChangeForSelection({ entryId: "e1", path: "src/main.go" }, [], entries),
+    ).toBeNull();
+  });
+
+  it("does NOT collide across repos with the same basename (entry-correct)", () => {
+    // The crux: a suffix match would attach repoA's change to repoB's file.
+    // Entry-anchored resolution must keep them apart.
+    const entries = [git("a", "org/repoA"), git("b", "org/repoB")];
+    const changes = [
+      change({ path: "org/repoA/src/a.ts" }),
+      change({ path: "org/repoB/src/a.ts" }),
+    ];
+
+    expect(
+      findChangeForSelection({ entryId: "a", path: "src/a.ts" }, changes, entries),
+    ).toBe(changes[0]);
+    expect(
+      findChangeForSelection({ entryId: "b", path: "src/a.ts" }, changes, entries),
+    ).toBe(changes[1]);
+  });
+
+  it("strips the subdir prefix for a multi-git session", () => {
+    const entries = [git("a", "org/repoA"), git("b", "org/repoB")];
+    const changes = [change({ path: "org/repoB/lib/util.ts" })];
+    expect(
+      findChangeForSelection({ entryId: "b", path: "lib/util.ts" }, changes, entries),
+    ).toBe(changes[0]);
+  });
+
+  it("reduces a cloud-absolute change path via the sandbox root", () => {
+    const entries = [git("e1", "org/repo")];
+    const changes = [change({ path: `${DAYTONA}/src/main.go` })];
+    expect(
+      findChangeForSelection(
+        { entryId: "e1", path: "src/main.go" },
+        changes,
+        entries,
+        DAYTONA,
+      ),
+    ).toBe(changes[0]);
+  });
+
+  it("falls back to absolutePath when path is empty", () => {
+    const entries = [local("e1", "app", "/Users/dev/app")];
+    const changes = [change({ path: "", absolutePath: "/Users/dev/app/src/main.go" })];
+    expect(
+      findChangeForSelection({ entryId: "e1", path: "src/main.go" }, changes, entries),
+    ).toBe(changes[0]);
+  });
+
+  it("matches a DELETE change (viewer decides diff-only, not this resolver)", () => {
+    const entries = [git("e1", "org/repo")];
+    const changes = [change({ path: "src/gone.ts", changeType: FileChangeType.DELETE })];
+    const found = findChangeForSelection(
+      { entryId: "e1", path: "src/gone.ts" },
+      changes,
+      entries,
+    );
+    expect(found).toBe(changes[0]);
+    expect(found?.changeType).toBe(FileChangeType.DELETE);
+  });
+
+  it("degrades to null for an ambiguous multi-entry change path", () => {
+    const entries = [git("a", "org/repoA"), git("b", "org/repoB")];
+    // No subdir prefix and no sandbox root → the resolver refuses to guess.
+    const changes = [change({ path: "src/a.ts" })];
+    expect(
+      findChangeForSelection({ entryId: "a", path: "src/a.ts" }, changes, entries),
+    ).toBeNull();
+  });
+
+  it("returns the first matching change (net-per-file lists have one per path)", () => {
+    const entries = [git("e1", "org/repo")];
+    const changes = [
+      change({ path: "src/a.ts" }),
+      change({ path: "src/b.ts" }),
+    ];
+    expect(
+      findChangeForSelection({ entryId: "e1", path: "src/b.ts" }, changes, entries),
+    ).toBe(changes[1]);
+  });
+});

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