From 728a7e23aa5e0a4130d2e8922af100cc0778dfdd Mon Sep 17 00:00:00 2001
From: Trevor Walker <rynfar@gmail.com>
Date: Thu, 24 Sep 2026 06:51:12 -0600
Subject: [PATCH] feat(web): add file context actions across diff and browser

---
 apps/web/src/components/DiffPanel.tsx         |  75 +++++
 .../src/components/chat/ChangedFilesTree.tsx  |  47 +++-
 .../src/components/chat/MessagesTimeline.tsx  |  30 ++
 .../src/components/files/FileBrowserPanel.tsx |  25 +-
 apps/web/src/fileContextMenu.test.ts          | 155 +++++++++++
 apps/web/src/fileContextMenu.ts               | 262 ++++++++++++++++++
 6 files changed, 591 insertions(+), 3 deletions(-)
 create mode 100644 apps/web/src/fileContextMenu.test.ts
 create mode 100644 apps/web/src/fileContextMenu.ts

diff --git a/apps/web/src/components/DiffPanel.tsx b/apps/web/src/components/DiffPanel.tsx
index d954a7ff69..b9c16d26b5 100644
--- a/apps/web/src/components/DiffPanel.tsx
+++ b/apps/web/src/components/DiffPanel.tsx
@@ -26,6 +26,7 @@ import * as Schema from "effect/Schema";
 import * as DateTime from "effect/DateTime";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useOpenInPreferredEditor } from "../editorPreferences";
+import { useFileContextMenuHandler } from "../fileContextMenu";
 import { type DraftId } from "../composerDraftStore";
 import { openDiffFilePrimaryAction } from "../diffFileActions";
 import { useCheckpointDiff } from "~/lib/checkpointDiffState";
@@ -170,6 +171,10 @@ export default function DiffPanel({
   const serverConfig = useAtomValue(
     serverEnvironment.configValueAtom(activeThread?.environmentId ?? null),
   );
+  const onFileContextMenu = useFileContextMenuHandler(
+    activeThread?.environmentId ?? null,
+    activeCwd,
+  );
   const openInPreferredEditor = useOpenInPreferredEditor(
     activeThread?.environmentId ?? null,
     serverConfig?.availableEditors ?? [],
@@ -495,6 +500,29 @@ export default function DiffPanel({
         }),
     [collapsedDiffFileKeys, renderableFileEntries, lazySource, readyFilePaths],
   );
+  const showDiffFileContextMenu = useCallback(
+    (filePath: string, position: { clientX: number; clientY: number }) => {
+      const matching = codeViewFiles.filter((file) => file.filePath === filePath);
+      if (matching.length === 0) return false;
+      return onFileContextMenu(
+        {
+          environmentId: activeThread?.environmentId ?? null,
+          filePath,
+          fileExists: matching.some((file) => file.fileDiff.type !== "deleted"),
+          workspaceRoot: activeCwd,
+          repositoryRoot: activeRepositoryRoot,
+        },
+        position,
+      );
+    },
+    [
+      activeCwd,
+      activeRepositoryRoot,
+      activeThread?.environmentId,
+      codeViewFiles,
+      onFileContextMenu,
+    ],
+  );
   const diffFileKeys = useMemo(
     () => renderableFileEntries.map((file) => file.fileKey),
     [renderableFileEntries],
@@ -1071,6 +1099,53 @@ export default function DiffPanel({
                       );
                       if (file) toggleDiffFileCollapsed(file.fileKey);
                     }}
+                    onContextMenuCapture={(event) => {
+                      const path = event.nativeEvent.composedPath?.() ?? [];
+                      if (
+                        path.some(
+                          (node) =>
+                            node instanceof HTMLButtonElement || node instanceof HTMLAnchorElement,
+                        )
+                      )
+                        return;
+                      const title = path.find(
+                        (node): node is HTMLElement =>
+                          node instanceof HTMLElement && node.hasAttribute("data-title"),
+                      );
+                      const header = path.find(
+                        (node): node is HTMLElement =>
+                          node instanceof HTMLElement && node.hasAttribute("data-diffs-header"),
+                      );
+                      const filePath =
+                        title?.textContent ?? header?.querySelector("[data-title]")?.textContent;
+                      if (!filePath) return;
+                      const rect =
+                        title?.getBoundingClientRect() ?? header?.getBoundingClientRect();
+                      if (
+                        showDiffFileContextMenu(filePath, {
+                          clientX: event.clientX || rect?.left || 0,
+                          clientY: event.clientY || rect?.bottom || 0,
+                        })
+                      )
+                        event.preventDefault();
+                    }}
+                    onKeyDownCapture={(event) => {
+                      if (event.key !== "ContextMenu" && !(event.shiftKey && event.key === "F10"))
+                        return;
+                      const target = event.target;
+                      if (!(target instanceof HTMLElement)) return;
+                      const header = target.closest<HTMLElement>("[data-diffs-header]");
+                      const filePath = header?.querySelector("[data-title]")?.textContent;
+                      if (!filePath || !header) return;
+                      const rect = header.getBoundingClientRect();
+                      if (
+                        showDiffFileContextMenu(filePath, {
+                          clientX: rect.left,
+                          clientY: rect.bottom,
+                        })
+                      )
+                        event.preventDefault();
+                    }}
                   >
                     <AnnotatableCodeView
                       key={collapseScopeKey ?? reviewSectionId}
diff --git a/apps/web/src/components/chat/ChangedFilesTree.tsx b/apps/web/src/components/chat/ChangedFilesTree.tsx
index fbab4cde39..e20317e87e 100644
--- a/apps/web/src/components/chat/ChangedFilesTree.tsx
+++ b/apps/web/src/components/chat/ChangedFilesTree.tsx
@@ -23,6 +23,13 @@ import { MiddleTruncate } from "../ui/middle-truncate";
 
 const EMPTY_DIRECTORY_OVERRIDES: Record<string, boolean> = {};
 
+/** Opens the OS-level context menu for a changed file (reveal in file manager, open in editor). */
+export type ChangedFileContextMenuHandler = (
+  filePath: string,
+  position: { readonly clientX: number; readonly clientY: number },
+  fileExists: boolean,
+) => boolean;
+
 export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
   turnId: TurnId;
   files: ReadonlyArray<TurnDiffFileChange>;
@@ -30,6 +37,7 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
   resolvedTheme: "light" | "dark";
   onToggleAllDirectories: () => void;
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
+  onFileContextMenu?: ChangedFileContextMenuHandler | undefined;
 }) {
   const {
     turnId,
@@ -38,6 +46,7 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
     resolvedTheme,
     onToggleAllDirectories,
     onOpenTurnDiff,
+    onFileContextMenu,
   } = props;
   const summaryStat = useMemo(() => summarizeTurnDiffStats(files), [files]);
   const hasDirectories = files.some((file) => /[/\\]/.test(file.path));
@@ -118,6 +127,7 @@ export const ChangedFilesCard = memo(function ChangedFilesCard(props: {
         allDirectoriesExpanded={allDirectoriesExpanded}
         resolvedTheme={resolvedTheme}
         onOpenTurnDiff={onOpenTurnDiff}
+        onFileContextMenu={onFileContextMenu}
       />
     </div>
   );
@@ -129,9 +139,26 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
   allDirectoriesExpanded: boolean;
   resolvedTheme: "light" | "dark";
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
+  onFileContextMenu?: ChangedFileContextMenuHandler | undefined;
 }) {
-  const { files, allDirectoriesExpanded, onOpenTurnDiff, resolvedTheme, turnId } = props;
+  const {
+    files,
+    allDirectoriesExpanded,
+    onOpenTurnDiff,
+    resolvedTheme,
+    turnId,
+    onFileContextMenu,
+  } = props;
   const treeNodes = useMemo(() => buildTurnDiffTree(files), [files]);
+  const deletedPaths = useMemo(
+    () =>
+      new Set(
+        files
+          .filter((file) => /^(deleted|removed|d)$/iu.test(file.kind))
+          .map((file) => file.path.replaceAll("\\", "/")),
+      ),
+    [files],
+  );
   const directoryPathsKey = useMemo(
     () => collectDirectoryPaths(treeNodes).join("\u0000"),
     [treeNodes],
@@ -215,6 +242,24 @@ export const ChangedFilesTree = memo(function ChangedFilesTree(props: {
         className="group flex w-full items-center gap-2 rounded-md py-1.5 pr-2 text-left transition-colors hover:bg-accent/60 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background"
         style={{ paddingLeft: `${leftPadding}px` }}
         onClick={() => onOpenTurnDiff(turnId, node.path)}
+        onContextMenu={
+          onFileContextMenu
+            ? (event) => {
+                const rect = event.currentTarget.getBoundingClientRect();
+                if (
+                  onFileContextMenu(
+                    node.path,
+                    {
+                      clientX: event.clientX || rect.left,
+                      clientY: event.clientY || rect.bottom,
+                    },
+                    !deletedPaths.has(node.path),
+                  )
+                )
+                  event.preventDefault();
+              }
+            : undefined
+        }
       >
         {hasDirectoryNodes || depth > 0 ? (
           <span aria-hidden="true" className="size-3.5 shrink-0" />
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index 1a267ac48a..be19804844 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -145,6 +145,9 @@ import {
 import { ProposedPlanCard } from "./ProposedPlanCard";
 import { SessionNotificationRow } from "./ComposerSessionInteractionPanel";
 import { ChangedFilesCard } from "./ChangedFilesTree";
+import { useAtomValue } from "@effect/atom-react";
+import { useFileContextMenuHandler } from "../../fileContextMenu";
+import { useProject, useThread } from "../../state/entities";
 import {
   CHAT_TIMELINE_ANCHOR_OFFSET,
   readTimelinePosition,
@@ -2814,12 +2817,24 @@ function AssistantChangedFilesSectionInner({
   resolvedTheme: "light" | "dark";
   onOpenTurnDiff: (turnId: TurnId, filePath?: string) => void;
 }) {
+  const ctx = use(TimelineRowCtx);
   const persistedExpanded = useUiStateStore(
     (store) => store.threadChangedFilesExpandedById[routeThreadKey]?.[turnSummary.turnId],
   );
   const setExpanded = useUiStateStore((store) => store.setThreadChangedFilesExpanded);
   const allDirectoriesExpanded = persistedExpanded ?? false;
 
+  const thread = useThread(ctx.threadRef);
+  const activeProject = useProject(
+    thread && thread.projectId
+      ? { environmentId: thread.environmentId, projectId: thread.projectId }
+      : null,
+  );
+  const onFileContextMenu = useFileContextMenuHandler(
+    ctx.activeThreadEnvironmentId,
+    ctx.workspaceRoot,
+  );
+
   return (
     <ChangedFilesCard
       turnId={turnSummary.turnId}
@@ -2830,6 +2845,21 @@ function AssistantChangedFilesSectionInner({
         setExpanded(routeThreadKey, turnSummary.turnId, !allDirectoriesExpanded)
       }
       onOpenTurnDiff={onOpenTurnDiff}
+      onFileContextMenu={(filePath, event, fileExists) =>
+        onFileContextMenu(
+          {
+            environmentId: ctx.activeThreadEnvironmentId,
+            filePath,
+            fileExists,
+            workspaceRoot: ctx.workspaceRoot,
+            repositoryRoot:
+              thread?.worktreePath == null
+                ? activeProject?.repositoryIdentity?.rootPath
+                : undefined,
+          },
+          event,
+        )
+      }
     />
   );
 }
diff --git a/apps/web/src/components/files/FileBrowserPanel.tsx b/apps/web/src/components/files/FileBrowserPanel.tsx
index 1952fc7c3b..51c6bb172c 100644
--- a/apps/web/src/components/files/FileBrowserPanel.tsx
+++ b/apps/web/src/components/files/FileBrowserPanel.tsx
@@ -7,7 +7,7 @@ import type { EnvironmentId, ProjectEntry } from "@t3tools/contracts";
 import { FileTree, useFileTree, useFileTreeSearch, useFileTreeSelector } from "@pierre/trees/react";
 import { serializeComposerFileLink } from "@t3tools/shared/composerTrigger";
 import { ChevronsDownUpIcon, ChevronsUpDownIcon } from "lucide-react";
-import { useEffect, useMemo, useRef } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
 
 import { Button } from "~/components/ui/button";
 import { InputGroup, InputGroupInput } from "~/components/ui/input-group";
@@ -18,6 +18,7 @@ import { writeTextToClipboard } from "~/hooks/useCopyToClipboard";
 import { useTheme } from "~/hooks/useTheme";
 import { useWorkspaceMutationRefresh } from "~/hooks/useWorkspaceMutationRefresh";
 import { readLocalApi } from "~/localApi";
+import { useFileContextMenu, type FileContextMenuAction } from "~/fileContextMenu";
 import { T3_PIERRE_ICONS } from "~/pierre-icons";
 import { PIERRE_TREE_UNSAFE_CSS, pierreTreeStyle } from "~/pierre-tree-theme";
 
@@ -104,6 +105,7 @@ export default function FileBrowserPanel({
 }: FileBrowserPanelProps) {
   const { resolvedTheme } = useTheme();
   const composerRef = useComposerHandleContext();
+  const fileContextMenu = useFileContextMenu(environmentId, cwd);
   const entriesQuery = useProjectEntriesQuery(environmentId, cwd);
   const entries = entriesQuery.data?.entries ?? [];
   const entryKinds = useMemo(
@@ -143,6 +145,14 @@ export default function FileBrowserPanel({
       return;
     }
     const relativePath = item.path.replace(/\/$/, "");
+    const fileTarget = {
+      environmentId,
+      filePath: relativePath,
+      workspaceRoot: cwd,
+      fileExists: entryKinds.get(relativePath) === "file",
+    };
+    const fileMenuItems = fileContextMenu.buildItems(fileTarget);
+    const fileMenuScope = fileContextMenu.captureScope(fileTarget);
     const mention = serializeComposerFileLink(relativePath);
     const pointer = contextMenuPointerRef.current;
     const pointerIsFresh = pointer !== null && performance.now() - pointer.at < 1000;
@@ -155,9 +165,11 @@ export default function FileBrowserPanel({
         [
           { id: "copy-mention", label: "Copy mention" },
           { id: "add-to-chat", label: "Add to chat" },
+          ...fileMenuItems,
         ],
         position,
       );
+      if (!fileContextMenu.isCurrent(fileTarget, fileMenuScope)) return;
       if (clicked === "copy-mention") {
         try {
           await writeTextToClipboard(mention);
@@ -189,13 +201,22 @@ export default function FileBrowserPanel({
             description: "The chat isn't ready to accept input right now.",
           });
         }
+        return;
+      }
+      if (
+        clicked &&
+        fileMenuItems.some(
+          (item) => item.id === clicked || item.children?.some((child) => child.id === clicked),
+        )
+      ) {
+        await fileContextMenu.activate(clicked as FileContextMenuAction, fileTarget, fileMenuScope);
       }
     } finally {
       context.close();
     }
   };
   const showEntryContextMenuRef = useRef(showEntryContextMenu);
-  useEffect(() => {
+  useLayoutEffect(() => {
     showEntryContextMenuRef.current = showEntryContextMenu;
   });
 
diff --git a/apps/web/src/fileContextMenu.test.ts b/apps/web/src/fileContextMenu.test.ts
new file mode 100644
index 0000000000..e9b5ebb8b9
--- /dev/null
+++ b/apps/web/src/fileContextMenu.test.ts
@@ -0,0 +1,155 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import * as NodeAssert from "node:assert/strict";
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+  buildFileContextMenuItems,
+  isCurrentFileContextMenuScope,
+  isFileContextMenuTargetForEnvironment,
+  resolveFileContextMenuAbsolutePath,
+} from "./fileContextMenu";
+
+const BASE_TARGET = {
+  environmentId: EnvironmentId.make("environment-local"),
+  filePath: "src/index.ts",
+  workspaceRoot: "/workspace/project",
+};
+
+describe("resolveFileContextMenuAbsolutePath", () => {
+  it("joins workspace-relative diff paths onto the workspace root", () => {
+    expect(resolveFileContextMenuAbsolutePath(BASE_TARGET)).toBe("/workspace/project/src/index.ts");
+  });
+
+  it("strips the repository prefix when the repo root is nested in the workspace", () => {
+    expect(
+      resolveFileContextMenuAbsolutePath({
+        ...BASE_TARGET,
+        workspaceRoot: "/workspace/project/packages/app",
+        repositoryRoot: "/workspace/project",
+        filePath: "packages/app/src/index.ts",
+      }),
+    ).toBe("/workspace/project/packages/app/src/index.ts");
+  });
+
+  it("returns null for paths outside the workspace when a repository root is set", () => {
+    expect(
+      resolveFileContextMenuAbsolutePath({
+        ...BASE_TARGET,
+        workspaceRoot: "/workspace/project/packages/app",
+        repositoryRoot: "/workspace/project",
+        filePath: "other/src/index.ts",
+      }),
+    ).toBeNull();
+  });
+
+  it("rejects absolute paths without a workspace root, matching diff path resolution", () => {
+    expect(
+      resolveFileContextMenuAbsolutePath({
+        ...BASE_TARGET,
+        workspaceRoot: undefined,
+        filePath: "/absolute/src/index.ts",
+      }),
+    ).toBeNull();
+  });
+
+  it("does not turn deleted or escaping diff paths into file actions", () => {
+    expect(resolveFileContextMenuAbsolutePath({ ...BASE_TARGET, fileExists: false })).toBeNull();
+    expect(
+      resolveFileContextMenuAbsolutePath({ ...BASE_TARGET, filePath: "../outside.ts" }),
+    ).toBeNull();
+    expect(
+      resolveFileContextMenuAbsolutePath({ ...BASE_TARGET, filePath: "/tmp/outside.ts" }),
+    ).toBeNull();
+  });
+
+  it("keeps spaces and percent characters literal in an environment-host path", () => {
+    expect(resolveFileContextMenuAbsolutePath({ ...BASE_TARGET, filePath: "src/a b%20c.ts" })).toBe(
+      "/workspace/project/src/a b%20c.ts",
+    );
+  });
+});
+
+it("rejects a menu result after a workspace switch, return, or unmount", async () => {
+  const scopeA = {
+    environmentId: BASE_TARGET.environmentId,
+    workspaceRoot: BASE_TARGET.workspaceRoot,
+  };
+  const scopeB = { environmentId: EnvironmentId.make("other"), workspaceRoot: "/other" };
+  const otherWorkspace = {
+    environmentId: BASE_TARGET.environmentId,
+    workspaceRoot: "/workspace/elsewhere",
+  };
+  let current: typeof scopeA | null = scopeA;
+  let resolveMenu!: (value: string) => void;
+  const selected = new Promise<string>((resolve) => {
+    resolveMenu = resolve;
+  });
+  const dispatched: string[] = [];
+  const pending = selected.then((action) => {
+    if (isCurrentFileContextMenuScope(current, scopeA, BASE_TARGET)) dispatched.push(action);
+  });
+  current = scopeB;
+  current = { ...scopeA }; // Same values after a return still belong to a newer committed scope.
+  resolveMenu("open");
+  await pending;
+  expect(dispatched).toEqual([]);
+  expect(isCurrentFileContextMenuScope(otherWorkspace, scopeA, BASE_TARGET)).toBe(false);
+  expect(isCurrentFileContextMenuScope(current, scopeA, BASE_TARGET)).toBe(false);
+  current = null;
+  expect(isCurrentFileContextMenuScope(current, scopeA, BASE_TARGET)).toBe(false);
+});
+
+it("requires the selected environment before exposing file actions", () => {
+  expect(isFileContextMenuTargetForEnvironment(BASE_TARGET.environmentId, BASE_TARGET)).toBe(true);
+  expect(isFileContextMenuTargetForEnvironment(EnvironmentId.make("other"), BASE_TARGET)).toBe(
+    false,
+  );
+  expect(isFileContextMenuTargetForEnvironment(null, BASE_TARGET)).toBe(false);
+});
+
+describe("buildFileContextMenuItems", () => {
+  it("offers open, reveal, and an open-with submenu when all are available", () => {
+    const items = buildFileContextMenuItems({
+      hasAbsolutePath: true,
+      capabilities: {
+        revealLabel: "Reveal in Finder",
+        canOpenDefault: true,
+        editorIds: ["vscode", "cursor", "file-manager"],
+      },
+    });
+
+    expect(items.map((item) => item.id)).toEqual(["open", "reveal-in-folder", "open-with"]);
+    expect(items[0]).toMatchObject({ label: "Open" });
+    expect(items[1]).toMatchObject({ label: "Reveal in Finder" });
+    const openWith = items[2];
+    NodeAssert.ok(openWith);
+    expect(openWith.children?.map((child) => child.id)).toEqual(["editor:vscode", "editor:cursor"]);
+  });
+
+  it("offers only the reveal item when just reveal is enabled", () => {
+    const items = buildFileContextMenuItems({
+      hasAbsolutePath: true,
+      capabilities: {
+        revealLabel: "Reveal in File Explorer",
+        canOpenDefault: false,
+        editorIds: [],
+      },
+    });
+
+    expect(items.map((item) => item.id)).toEqual(["reveal-in-folder"]);
+    expect(items[0]).toMatchObject({ label: "Reveal in File Explorer" });
+  });
+
+  it("offers nothing when the path cannot be resolved", () => {
+    expect(
+      buildFileContextMenuItems({
+        hasAbsolutePath: false,
+        capabilities: {
+          revealLabel: "Reveal in Finder",
+          canOpenDefault: true,
+          editorIds: ["vscode"],
+        },
+      }),
+    ).toEqual([]);
+  });
+});
diff --git a/apps/web/src/fileContextMenu.ts b/apps/web/src/fileContextMenu.ts
new file mode 100644
index 0000000000..7719e8230e
--- /dev/null
+++ b/apps/web/src/fileContextMenu.ts
@@ -0,0 +1,262 @@
+/**
+ * Right-click actions for a workspace file: reveal it in the environment's
+ * file manager and open it in an editor. Reuse the chat file-chip menu's
+ * machinery: reveal rides `shell.openInEditor` with `reveal: true`, which the
+ * server only honors when its `shellRevealInFileManager` config flag is set,
+ * so both actions work for every client and connection mode.
+ */
+import {
+  EDITORS,
+  type ContextMenuItem,
+  type EditorId,
+  type EnvironmentId,
+} from "@t3tools/contracts";
+import { useCallback, useLayoutEffect, useMemo, useRef } from "react";
+
+import { resolveDiffPathForWorkspace } from "./diffFileActions";
+import {
+  revealInFileExplorerLabelForKind,
+  revealInFileExplorerLabelForOs,
+} from "~/components/preview/fileExplorerLabel";
+import { readLocalApi } from "./localApi";
+import { serverEnvironment } from "./state/server";
+import { shellEnvironment } from "./state/shell";
+import { useAtomCommand } from "./state/use-atom-command";
+import { resolvePathLinkTarget } from "./terminal-links";
+import { toastManager } from "./components/ui/toast";
+import { useAtomValue } from "@effect/atom-react";
+
+export type FileContextMenuAction =
+  | "reveal-in-folder"
+  | "open"
+  /** Submenu parent; never the activated id. */
+  | "open-with"
+  | `editor:${EditorId}`;
+
+export interface FileContextMenuTarget {
+  readonly environmentId: EnvironmentId | null;
+  /** Repo- or workspace-relative file path, as shown in diffs. */
+  readonly filePath: string;
+  readonly workspaceRoot: string | undefined;
+  readonly repositoryRoot?: string | undefined;
+  /** Deleted diff entries have no current file to open or reveal. */
+  readonly fileExists?: boolean;
+}
+
+export interface FileContextMenuScope {
+  readonly environmentId: EnvironmentId | null;
+  readonly workspaceRoot: string | undefined;
+}
+
+export function isCurrentFileContextMenuScope(
+  current: FileContextMenuScope | null,
+  captured: FileContextMenuScope | null,
+  target: FileContextMenuTarget,
+): boolean {
+  return (
+    captured !== null &&
+    current === captured &&
+    captured.environmentId === target.environmentId &&
+    captured.workspaceRoot === target.workspaceRoot
+  );
+}
+
+export function isFileContextMenuTargetForEnvironment(
+  environmentId: EnvironmentId | null,
+  target: FileContextMenuTarget,
+): boolean {
+  return environmentId !== null && target.environmentId === environmentId;
+}
+
+/**
+ * Absolute path on the environment host for a diff-style target, resolving
+ * repo-relative paths through the workspace root like every other diff
+ * surface. Returns null when the path cannot be resolved, which callers must
+ * treat as "no file actions available".
+ */
+export function resolveFileContextMenuAbsolutePath(target: FileContextMenuTarget): string | null {
+  const workspaceFilePath = resolveDiffPathForWorkspace({
+    filePath: target.filePath,
+    workspaceRoot: target.workspaceRoot,
+    repositoryRoot: target.repositoryRoot,
+  });
+  if (workspaceFilePath === null || target.fileExists === false) return null;
+  if (target.workspaceRoot === undefined) {
+    return workspaceFilePath.startsWith("/") || /^[a-zA-Z]:/.test(workspaceFilePath)
+      ? workspaceFilePath
+      : null;
+  }
+  return resolvePathLinkTarget(workspaceFilePath, target.workspaceRoot);
+}
+
+const EDITOR_LABEL_BY_ID = new Map(EDITORS.map((editor) => [editor.id, editor.label]));
+
+export interface FileContextMenuCapabilities {
+  readonly revealLabel: string | undefined;
+  readonly canOpenDefault: boolean;
+  readonly editorIds: ReadonlyArray<EditorId>;
+}
+
+/**
+ * Menu items for a resolved file, offering only what the environment's config
+ * advertises: default-app open, reveal (with server-provided wording), and an
+ * "Open with" submenu of detected editors. Empty when nothing can act.
+ */
+export function buildFileContextMenuItems(input: {
+  readonly hasAbsolutePath: boolean;
+  readonly capabilities: FileContextMenuCapabilities;
+}): readonly ContextMenuItem<FileContextMenuAction>[] {
+  // Without a resolvable absolute path nothing here can act on the file.
+  if (!input.hasAbsolutePath) return [];
+  const items: ContextMenuItem<FileContextMenuAction>[] = [];
+  if (input.capabilities.canOpenDefault) {
+    items.push({ id: "open", label: "Open", icon: "pencil" });
+  }
+  if (input.capabilities.revealLabel !== undefined) {
+    items.push({
+      id: "reveal-in-folder",
+      label: input.capabilities.revealLabel,
+      icon: "folder-tree",
+    });
+  }
+  const editorIds = input.capabilities.editorIds.filter((id) => id !== "file-manager");
+  if (editorIds.length > 0) {
+    items.push({
+      id: "open-with",
+      label: "Open with",
+      children: editorIds.map((editorId) => ({
+        id: `editor:${editorId}` as FileContextMenuAction,
+        label: EDITOR_LABEL_BY_ID.get(editorId) ?? editorId,
+      })),
+    });
+  }
+  return items;
+}
+
+/** Builds and dispatches the file context menu for one environment's files. */
+export function useFileContextMenu(
+  environmentId: EnvironmentId | null,
+  workspaceRoot: string | undefined,
+) {
+  const openInEditor = useAtomCommand(shellEnvironment.openInEditor, { reportFailure: false });
+  const serverConfig = useAtomValue(serverEnvironment.configValueAtom(environmentId));
+  const committedScope = useRef<FileContextMenuScope | null>(null);
+  useLayoutEffect(() => {
+    committedScope.current = { environmentId, workspaceRoot };
+    return () => {
+      committedScope.current = null;
+    };
+  }, [environmentId, workspaceRoot]);
+
+  return useMemo(() => {
+    const availableEditors = serverConfig?.availableEditors ?? [];
+    const capabilities: FileContextMenuCapabilities = {
+      // The reveal wording comes from the server because on WSL the reveal can
+      // run through Windows File Explorer even though the host reports Linux.
+      revealLabel:
+        environmentId !== null &&
+        serverConfig?.shellRevealInFileManager === true &&
+        serverConfig.availableEditors.includes("file-manager")
+          ? serverConfig.shellRevealInFileManagerKind === undefined
+            ? revealInFileExplorerLabelForOs(serverConfig.environment.platform.os)
+            : revealInFileExplorerLabelForKind(serverConfig.shellRevealInFileManagerKind)
+          : undefined,
+      canOpenDefault: availableEditors.includes("file-manager"),
+      editorIds: availableEditors,
+    };
+
+    const activate = async (
+      action: FileContextMenuAction,
+      target: FileContextMenuTarget,
+      capturedScope: FileContextMenuScope | null,
+    ): Promise<void> => {
+      const absolutePath = resolveFileContextMenuAbsolutePath(target);
+      if (
+        absolutePath === null ||
+        environmentId === null ||
+        target.environmentId !== environmentId ||
+        target.workspaceRoot !== workspaceRoot ||
+        !isCurrentFileContextMenuScope(committedScope.current, capturedScope, target)
+      )
+        return;
+
+      const reveal = action === "reveal-in-folder";
+      const editor =
+        action === "open" || reveal
+          ? ("file-manager" as const)
+          : (action.slice("editor:".length) as EditorId);
+      if (action === "open" && !capabilities.canOpenDefault) return;
+      if (reveal && capabilities.revealLabel === undefined) return;
+      if (action !== "open" && !reveal && !capabilities.editorIds.includes(editor)) return;
+
+      const result = await openInEditor({
+        environmentId,
+        input: { cwd: absolutePath, editor, ...(reveal ? { reveal: true } : {}) },
+      });
+      if (result._tag !== "Failure") return;
+      toastManager.add({
+        type: "error",
+        title:
+          action === "open"
+            ? "Could not open file"
+            : reveal
+              ? "Unable to reveal file"
+              : `Could not open in ${EDITOR_LABEL_BY_ID.get(editor) ?? editor}`,
+        description: absolutePath,
+      });
+    };
+
+    const show = async (
+      target: FileContextMenuTarget,
+      position?: { x: number; y: number },
+    ): Promise<void> => {
+      const api = readLocalApi();
+      const capturedScope = committedScope.current;
+      const items = buildFileContextMenuItems({
+        hasAbsolutePath:
+          isFileContextMenuTargetForEnvironment(environmentId, target) &&
+          resolveFileContextMenuAbsolutePath(target) !== null,
+        capabilities,
+      });
+      if (items.length === 0 || api === undefined) return;
+      const clicked = await api.contextMenu.show(items, position);
+      if (clicked === null) return;
+      await activate(clicked as FileContextMenuAction, target, capturedScope);
+    };
+
+    return {
+      captureScope: (target: FileContextMenuTarget) =>
+        isCurrentFileContextMenuScope(committedScope.current, committedScope.current, target)
+          ? committedScope.current
+          : null,
+      isCurrent: (target: FileContextMenuTarget, capturedScope: FileContextMenuScope | null) =>
+        isCurrentFileContextMenuScope(committedScope.current, capturedScope, target),
+      buildItems: (target: FileContextMenuTarget) =>
+        buildFileContextMenuItems({
+          hasAbsolutePath:
+            isFileContextMenuTargetForEnvironment(environmentId, target) &&
+            resolveFileContextMenuAbsolutePath(target) !== null,
+          capabilities,
+        }),
+      capabilities,
+      activate,
+      show,
+    };
+  }, [environmentId, workspaceRoot, openInEditor, serverConfig]);
+}
+
+/** Returns an onContextMenu callback that shows the menu at the pointer. */
+export function useFileContextMenuHandler(
+  environmentId: EnvironmentId | null,
+  workspaceRoot: string | undefined,
+) {
+  const contextMenu = useFileContextMenu(environmentId, workspaceRoot);
+  return useCallback(
+    (target: FileContextMenuTarget, event?: { clientX: number; clientY: number }) => {
+      if (readLocalApi() === undefined || contextMenu.buildItems(target).length === 0) return false;
+      void contextMenu.show(target, event ? { x: event.clientX, y: event.clientY } : undefined);
+      return true;
+    },
+    [contextMenu],
+  );
+}