Add workspace file viewer and artifact links (#7681)

## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Agent work is issue-centered, and reviewers often need to inspect files, artifacts, and path references produced during that work. > - Before this branch, workspace-relative paths and artifact file references were not first-class inspectable objects in the board UI. > - Safe file viewing needs shared resource contracts, server-side workspace boundary checks, and UI that opens files without exposing arbitrary host paths. > - The workspace file viewer branch needed to stay as one active PR and be rebased onto current `paperclipai/paperclip:master` for review. > - This pull request adds the workspace file resource API, issue-page file viewer and browser, markdown file-reference links, and artifact file chips. > - The benefit is that board users can inspect relevant files from issue context while preserving workspace boundaries and auditability. ## Linked Issues or Issue Description No public GitHub issue exists for this branch. Internal Paperclip issues: `PAP-1953`, `PAP-10539`, `PAP-10733`. Problem / motivation: - Board users need to open workspace-relative files mentioned by agents or attached as work-product metadata without switching to a terminal. - The UI needs to support both direct file-path opening and workspace browsing/searching from an issue page. - The server must enforce company access, workspace boundaries, size limits, rate limits, and safe audit logging. Related PR: - Prior closed attempt: #4442 - Single active PR for this branch: #7681 ## What Changed - Added shared workspace file resource types, validators, and workspace-file `resourceRef` metadata validation for work products. - Added server routes/services for resolving, listing, and previewing workspace-relative files with access checks, scan caps, list-specific limits, and audit logging. - Added the issue file viewer provider, sheet, workspace browser, command-palette action, markdown workspace-file autolinks, and artifact file chips. - Updated issue workspace UI and stories/tests for file browsing and workspace file opening. - Rebased the branch onto current `paperclipai/paperclip:master` and updated the existing single PR branch. - Addressed current-head Greptile follow-ups by applying `offset` consistently across search/recent/changed file listings, restoring stopped-service port ownership checks before auto-port reuse, and stabilizing the workspace browser pagination test. ## Verification Current local verification after rebase to `public/master`: - `pnpm exec vitest run packages/shared/src/work-product.test.ts server/src/__tests__/file-resources.test.ts server/src/__tests__/instance-settings-routes.test.ts server/src/__tests__/instance-settings-service.test.ts server/src/__tests__/workspace-runtime.test.ts ui/src/components/FileViewerSheet.test.tsx ui/src/components/FileViewerSheet.copy.test.tsx ui/src/components/WorkspaceFileBrowser.test.tsx ui/src/components/WorkspaceFileMarkdownBody.test.tsx ui/src/context/FileViewerContext.test.ts ui/src/lib/remark-workspace-file-refs.test.ts ui/src/lib/workspace-file-parser.test.ts ui/src/components/IssueWorkspaceCard.test.tsx` - 13 files passed, 197 tests passed. - `pnpm -r --filter @paperclipai/shared --filter @paperclipai/server --filter @paperclipai/ui typecheck` - passed. - `pnpm exec vitest run ui/src/components/WorkspaceFileBrowser.test.tsx` - 1 file passed, 25 tests passed. - `pnpm exec vitest run server/src/__tests__/file-resources.test.ts server/src/__tests__/workspace-runtime.test.ts` - 2 files passed, 90 tests passed. - `pnpm -r --filter @paperclipai/server typecheck` - passed. - Confirmed branch is `0` behind and `46` ahead of current `public/master` after rebase and follow-up commits. - Confirmed the PR diff does not include `pnpm-lock.yaml`. - Confirmed the PR diff does not include `.github/workflows` changes. - Searched GitHub for duplicate or related workspace file viewer PRs/issues; #4442 is the prior closed attempt and this PR is the single active PR for the branch. - No screenshots were committed; the task explicitly asked not to add design screenshots or images unless they were part of the work. Current remote verification on head `a698a7bc10137baf7d25bd5722e1d6e0343387c1`: - Greptile Review - success, 64 files reviewed, 0 comments added, no unresolved Greptile review threads. - PR workflow `verify` - success. - Typecheck + Release Registry, General tests, workspace test shards, serialized server suites, Build, Canary Dry Run, e2e, Socket, and Snyk - success. - `security-review` - neutral, with output saying a draft advisory was filed for maintainer review and is not a merge block. - `commitperclip PR Review / review` - cancelled after the security gate detected flags and timed out while creating/reviewing the advisory. I reran it once and it cancelled the same way; no actionable code/test failure was exposed in the job logs. ## Risks - This is a broad UI/server feature PR, so review needs to pay attention to route authorization, workspace boundary handling, and markdown autolink false positives. - Workspace browsing intentionally caps list results and scan depth; very large workspaces may require users to refine search terms. - Remote workspace preview remains unavailable until remote file-access support is implemented. - The neutral commitperclip security-review advisory needs maintainer review, but the check output says it is not a merge block. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected - check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent in a Paperclip/Codex local tool-use environment, medium reasoning, with shell/GitHub CLI tool use for branch inspection, verification, rebase, PR update, Greptile review, and CI inspection. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-09 17:17:43 -05:00
parent bf62e3fbf1
commit 468edd8b22
64 changed files with 10816 additions and 82 deletions
@@ -0,0 +1,179 @@
+// @vitest-environment node
+
+import { describe, expect, it } from "vitest";
+import {
+  FILE_VIEWER_NAVIGATE_OPTIONS,
+  readBrowseStateFromSearch,
+  readFileViewerStateFromSearch,
+  writeBrowseStateToSearch,
+  writeFolderViewerStateToSearch,
+  writeFileViewerStateToSearch,
+} from "./FileViewerContext";
+
+describe("FILE_VIEWER_NAVIGATE_OPTIONS", () => {
+  it("preserves page scroll when the viewer updates URL search params", () => {
+    expect(FILE_VIEWER_NAVIGATE_OPTIONS.preventScrollReset).toBe(true);
+    expect(FILE_VIEWER_NAVIGATE_OPTIONS.replace).toBe(false);
+  });
+});
+
+describe("readFileViewerStateFromSearch", () => {
+  it("returns null when no file param is present", () => {
+    expect(readFileViewerStateFromSearch("")).toBeNull();
+    expect(readFileViewerStateFromSearch("?other=1")).toBeNull();
+  });
+
+  it("reads file, line, column, workspace from the search", () => {
+    const state = readFileViewerStateFromSearch("?file=ui/src/a.ts&line=42&column=3&workspace=project");
+    expect(state).toEqual({
+      path: "ui/src/a.ts",
+      line: 42,
+      column: 3,
+      workspace: "project",
+      projectId: null,
+      workspaceId: null,
+    });
+  });
+
+  it("defaults to auto workspace when param missing", () => {
+    const state = readFileViewerStateFromSearch("?file=ui/src/a.ts");
+    expect(state?.workspace).toBe("auto");
+  });
+
+  it("clamps invalid workspace to auto", () => {
+    const state = readFileViewerStateFromSearch("?file=ui/src/a.ts&workspace=bogus");
+    expect(state?.workspace).toBe("auto");
+  });
+
+  it("treats invalid line/column as null", () => {
+    const state = readFileViewerStateFromSearch("?file=x.ts&line=abc&column=-1");
+    expect(state?.line).toBeNull();
+    expect(state?.column).toBeNull();
+  });
+});
+
+describe("writeFileViewerStateToSearch", () => {
+  it("sets all params when opening", () => {
+    const next = writeFileViewerStateToSearch(
+      "?existing=1",
+      {
+        path: "ui/src/a.ts",
+        line: 42,
+        column: 3,
+        workspace: "project",
+        projectId: null,
+        workspaceId: null,
+      },
+    );
+    const params = new URLSearchParams(next);
+    expect(params.get("file")).toBe("ui/src/a.ts");
+    expect(params.get("line")).toBe("42");
+    expect(params.get("column")).toBe("3");
+    expect(params.get("workspace")).toBe("project");
+    expect(params.get("existing")).toBe("1");
+  });
+
+  it("omits workspace when auto", () => {
+    const next = writeFileViewerStateToSearch(
+      "",
+      { path: "a.ts", line: null, column: null, workspace: "auto", projectId: null, workspaceId: null },
+    );
+    expect(next.includes("workspace")).toBe(false);
+  });
+
+  it("round-trips explicit target project workspace params", () => {
+    const targetPath = "content-os/cases/active/2026-06-06-pap-10199-bundled-skills/README.md";
+    const next = writeFileViewerStateToSearch(
+      "?existing=1",
+      {
+        path: targetPath,
+        line: 7,
+        column: null,
+        workspace: "auto",
+        projectId: "17acae7d-9d0c-46bf-9c82-be9694ac3461",
+        workspaceId: "0de5f74f-a7d4-4f73-a9a0-455a2b968cf2",
+      },
+    );
+    const state = readFileViewerStateFromSearch(next);
+    expect(state).toEqual({
+      path: targetPath,
+      line: 7,
+      column: null,
+      workspace: "auto",
+      projectId: "17acae7d-9d0c-46bf-9c82-be9694ac3461",
+      workspaceId: "0de5f74f-a7d4-4f73-a9a0-455a2b968cf2",
+    });
+  });
+
+  it("clears viewer params when closing", () => {
+    const next = writeFileViewerStateToSearch(
+      "?file=a.ts&line=1&column=2&workspace=project&projectId=project-1&workspaceId=workspace-1&keep=yes",
+      null,
+    );
+    const params = new URLSearchParams(next);
+    expect(params.get("file")).toBeNull();
+    expect(params.get("line")).toBeNull();
+    expect(params.get("column")).toBeNull();
+    expect(params.get("workspace")).toBeNull();
+    expect(params.get("projectId")).toBeNull();
+    expect(params.get("workspaceId")).toBeNull();
+    expect(params.get("keep")).toBe("yes");
+  });
+
+  it("returns empty string when no params remain", () => {
+    const next = writeFileViewerStateToSearch("?file=a.ts", null);
+    expect(next).toBe("");
+  });
+});
+
+describe("folder browse search state", () => {
+  it("round-trips explicit target folder browse params", () => {
+    const targetPath = "content-os/cases/active/2026-06-06-pap-10199-bundled-skills/";
+    const next = writeFolderViewerStateToSearch("?tab=thread", {
+      path: targetPath,
+      projectId: "17acae7d-9d0c-46bf-9c82-be9694ac3461",
+      workspaceId: "0de5f74f-a7d4-4f73-a9a0-455a2b968cf2",
+    });
+
+    expect(readFileViewerStateFromSearch(next)).toBeNull();
+    expect(readBrowseStateFromSearch(next)).toEqual({
+      q: null,
+      folderPath: targetPath,
+      projectId: "17acae7d-9d0c-46bf-9c82-be9694ac3461",
+      workspaceId: "0de5f74f-a7d4-4f73-a9a0-455a2b968cf2",
+    });
+  });
+
+  it("updates browse params without closing the active file preview", () => {
+    const next = writeBrowseStateToSearch(
+      "?tab=thread&file=ui/src/components/FileViewerSheet.tsx&line=5&browse=1",
+      {
+        q: " FileViewerSheet ",
+        folderPath: "ui/src/components",
+        projectId: null,
+        workspaceId: null,
+      },
+    );
+
+    const params = new URLSearchParams(next);
+    expect(params.get("file")).toBe("ui/src/components/FileViewerSheet.tsx");
+    expect(params.get("line")).toBe("5");
+    expect(params.get("browse")).toBe("1");
+    expect(params.get("q")).toBe("FileViewerSheet");
+    expect(params.get("folder")).toBe("ui/src/components");
+    expect(params.get("tab")).toBe("thread");
+  });
+
+  it("clears browse params while preserving the file preview", () => {
+    const next = writeBrowseStateToSearch(
+      "?file=ui/src/components/FileViewerSheet.tsx&browse=1&q=FileViewerSheet&folder=ui/src/components",
+      { q: null, folderPath: null },
+    );
+
+    const params = new URLSearchParams(next);
+    expect(params.get("file")).toBe("ui/src/components/FileViewerSheet.tsx");
+    expect(params.get("browse")).toBe("1");
+    expect(params.get("q")).toBeNull();
+    expect(params.get("folder")).toBeNull();
+  });
+});
@@ -0,0 +1,327 @@
+import { createContext, useContext, useCallback, useMemo, type ReactNode } from "react";
+import { useLocation, useNavigate, type NavigateOptions } from "@/lib/router";
+import type { WorkspaceFileSelector } from "@paperclipai/shared";
+import type { ParsedWorkspaceFileRef } from "@/lib/workspace-file-parser";
+
+export interface FileViewerUrlState {
+  path: string;
+  line: number | null;
+  column: number | null;
+  workspace: WorkspaceFileSelector;
+  projectId: string | null;
+  workspaceId: string | null;
+}
+
+export interface FileViewerContextValue {
+  issueId: string;
+  /** Current viewer state derived from the URL, or null if closed. */
+  state: FileViewerUrlState | null;
+  /** True when the sheet is in browse mode (URL carries `browse=1`). */
+  browse: boolean;
+  /** The active browse search query (URL `q`), or null. */
+  query: string | null;
+  browseProjectId: string | null;
+  browseWorkspaceId: string | null;
+  folderPath: string | null;
+  open(
+    ref: Pick<ParsedWorkspaceFileRef, "path" | "line" | "column" | "projectId" | "workspaceId"> & {
+      workspace?: WorkspaceFileSelector;
+    },
+    opts?: {
+      fromBrowse?: boolean;
+      browseState?: Partial<FileViewerBrowseState>;
+    },
+  ): void;
+  /** Open (or stay in) browse mode, optionally seeding the search query. */
+  openBrowse(opts?: { q?: string }): void;
+  /** Update URL-backed browse state without closing the active preview. */
+  updateBrowseState(opts: Partial<FileViewerBrowseState>): void;
+  openFolder(
+    ref: Pick<ParsedWorkspaceFileRef, "path" | "projectId" | "workspaceId"> & {
+      workspace?: WorkspaceFileSelector;
+    },
+  ): void;
+  /** From a file opened via browse, return to the browse list. */
+  backToFiles(): void;
+  close(): void;
+}
+
+const FileViewerContext = createContext<FileViewerContextValue | null>(null);
+
+export const FILE_VIEWER_NAVIGATE_OPTIONS = {
+  replace: false,
+  preventScrollReset: true,
+} satisfies NavigateOptions;
+
+export function readFileViewerStateFromSearch(search: string): FileViewerUrlState | null {
+  const params = new URLSearchParams(search);
+  const path = params.get("file");
+  if (!path) return null;
+  const lineRaw = params.get("line");
+  const columnRaw = params.get("column");
+  const workspaceRaw = params.get("workspace");
+  const projectIdRaw = params.get("projectId");
+  const workspaceIdRaw = params.get("workspaceId");
+  const hasExplicitTarget = Boolean(projectIdRaw && workspaceIdRaw);
+  const line = lineRaw ? Number.parseInt(lineRaw, 10) : NaN;
+  const column = columnRaw ? Number.parseInt(columnRaw, 10) : NaN;
+  const workspace = (workspaceRaw === "execution" || workspaceRaw === "project")
+    ? workspaceRaw
+    : "auto";
+  return {
+    path,
+    line: Number.isFinite(line) && line > 0 ? line : null,
+    column: Number.isFinite(column) && column > 0 ? column : null,
+    workspace,
+    projectId: hasExplicitTarget ? projectIdRaw : null,
+    workspaceId: hasExplicitTarget ? workspaceIdRaw : null,
+  };
+}
+
+export function writeFileViewerStateToSearch(current: string, next: FileViewerUrlState | null): string {
+  const params = new URLSearchParams(current);
+  // A direct file open/close is never a browse origin — clear browse params too.
+  params.delete("browse");
+  params.delete("q");
+  params.delete("folder");
+  if (!next) {
+    params.delete("file");
+    params.delete("line");
+    params.delete("column");
+    params.delete("workspace");
+    params.delete("projectId");
+    params.delete("workspaceId");
+  } else {
+    params.set("file", next.path);
+    if (next.line !== null) params.set("line", String(next.line));
+    else params.delete("line");
+    if (next.column !== null) params.set("column", String(next.column));
+    else params.delete("column");
+    if (next.workspace && next.workspace !== "auto") params.set("workspace", next.workspace);
+    else params.delete("workspace");
+    if (next.projectId) params.set("projectId", next.projectId);
+    else params.delete("projectId");
+    if (next.workspaceId) params.set("workspaceId", next.workspaceId);
+    else params.delete("workspaceId");
+  }
+  const str = params.toString();
+  return str ? `?${str}` : "";
+}
+
+export interface FileViewerBrowseState {
+  q: string | null;
+  folderPath: string | null;
+  projectId: string | null;
+  workspaceId: string | null;
+}
+
+export function readBrowseStateFromSearch(search: string): FileViewerBrowseState | null {
+  const params = new URLSearchParams(search);
+  if (params.get("browse") !== "1") return null;
+  const q = params.get("q");
+  const folder = params.get("folder");
+  const projectId = params.get("projectId");
+  const workspaceId = params.get("workspaceId");
+  return {
+    q: q && q.length > 0 ? q : null,
+    folderPath: folder && folder.length > 0 ? folder : null,
+    projectId: projectId || null,
+    workspaceId: workspaceId || null,
+  };
+}
+
+export function writeFolderViewerStateToSearch(
+  current: string,
+  next: {
+    path: string;
+    projectId: string | null;
+    workspaceId: string | null;
+  },
+): string {
+  const params = new URLSearchParams(current);
+  params.delete("file");
+  params.delete("line");
+  params.delete("column");
+  params.delete("workspace");
+  params.delete("q");
+  params.set("browse", "1");
+  params.set("folder", next.path);
+  if (next.projectId) params.set("projectId", next.projectId);
+  else params.delete("projectId");
+  if (next.workspaceId) params.set("workspaceId", next.workspaceId);
+  else params.delete("workspaceId");
+  const str = params.toString();
+  return str ? `?${str}` : "";
+}
+
+export function writeBrowseStateToSearch(current: string, next: Partial<FileViewerBrowseState>): string {
+  const params = new URLSearchParams(current);
+  params.set("browse", "1");
+  if ("q" in next) {
+    const q = next.q?.trim() ?? "";
+    if (q) params.set("q", q);
+    else params.delete("q");
+  }
+  if ("folderPath" in next) {
+    const folderPath = next.folderPath?.trim() ?? "";
+    if (folderPath) params.set("folder", folderPath);
+    else params.delete("folder");
+  }
+  if ("projectId" in next) {
+    if (next.projectId) params.set("projectId", next.projectId);
+    else params.delete("projectId");
+  }
+  if ("workspaceId" in next) {
+    if (next.workspaceId) params.set("workspaceId", next.workspaceId);
+    else params.delete("workspaceId");
+  }
+  const str = params.toString();
+  return str ? `?${str}` : "";
+}
+
+interface FileViewerProviderProps {
+  issueId: string;
+  children: ReactNode;
+  enabled?: boolean;
+}
+
+export function FileViewerProvider({ issueId, children, enabled = true }: FileViewerProviderProps) {
+  if (!enabled) return <>{children}</>;
+  return <EnabledFileViewerProvider issueId={issueId}>{children}</EnabledFileViewerProvider>;
+}
+
+function EnabledFileViewerProvider({ issueId, children }: Omit<FileViewerProviderProps, "enabled">) {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const state = useMemo(() => readFileViewerStateFromSearch(location.search), [location.search]);
+  const browseState = useMemo(() => readBrowseStateFromSearch(location.search), [location.search]);
+
+  const navigateSearch = useCallback(
+    (nextSearch: string, opts?: Partial<NavigateOptions>) => {
+      if (nextSearch === location.search) return;
+      navigate(
+        { pathname: location.pathname, hash: location.hash, search: nextSearch },
+        { ...FILE_VIEWER_NAVIGATE_OPTIONS, ...opts, state: location.state },
+      );
+    },
+    [location.hash, location.pathname, location.state, navigate],
+  );
+
+  const open = useCallback<FileViewerContextValue["open"]>(
+    (ref, opts) => {
+      let nextSearch = writeFileViewerStateToSearch(location.search, {
+        path: ref.path,
+        line: ref.line ?? null,
+        column: ref.column ?? null,
+        workspace: ref.workspace ?? "auto",
+        projectId: ref.projectId ?? null,
+        workspaceId: ref.workspaceId ?? null,
+      });
+      if (opts?.fromBrowse) {
+        const params = new URLSearchParams(nextSearch);
+        params.set("browse", "1");
+        const previousParams = new URLSearchParams(location.search);
+        const prevQ = previousParams.get("q");
+        const prevFolder = previousParams.get("folder");
+        const nextQ = Object.prototype.hasOwnProperty.call(opts.browseState ?? {}, "q")
+          ? opts.browseState?.q
+          : prevQ;
+        const nextFolder = Object.prototype.hasOwnProperty.call(opts.browseState ?? {}, "folderPath")
+          ? opts.browseState?.folderPath
+          : prevFolder;
+        if (nextQ) params.set("q", nextQ);
+        else params.delete("q");
+        if (nextFolder) params.set("folder", nextFolder);
+        else params.delete("folder");
+        nextSearch = params.toString() ? `?${params.toString()}` : "";
+      }
+      navigateSearch(nextSearch);
+    },
+    [location.search, navigateSearch],
+  );
+
+  const openBrowse = useCallback<FileViewerContextValue["openBrowse"]>(
+    (opts) => {
+      const params = new URLSearchParams(location.search);
+      params.delete("file");
+      params.delete("line");
+      params.delete("column");
+      params.delete("folder");
+      params.set("browse", "1");
+      if (typeof opts?.q === "string" && opts.q.length > 0) params.set("q", opts.q);
+      else params.delete("q");
+      navigateSearch(params.toString() ? `?${params.toString()}` : "");
+    },
+    [location.search, navigateSearch],
+  );
+
+  const updateBrowseState = useCallback<FileViewerContextValue["updateBrowseState"]>(
+    (opts) => {
+      navigateSearch(writeBrowseStateToSearch(location.search, opts), { replace: true });
+    },
+    [location.search, navigateSearch],
+  );
+
+  const openFolder = useCallback<FileViewerContextValue["openFolder"]>(
+    (ref) => {
+      const nextSearch = writeFolderViewerStateToSearch(location.search, {
+        path: ref.path,
+        projectId: ref.projectId ?? null,
+        workspaceId: ref.workspaceId ?? null,
+      });
+      navigateSearch(nextSearch);
+    },
+    [location.search, navigateSearch],
+  );
+
+  const backToFiles = useCallback(() => {
+    const params = new URLSearchParams(location.search);
+    params.delete("file");
+    params.delete("line");
+    params.delete("column");
+    params.delete("workspace");
+    params.set("browse", "1");
+    navigateSearch(params.toString() ? `?${params.toString()}` : "");
+  }, [location.search, navigateSearch]);
+
+  const close = useCallback(() => {
+    const params = new URLSearchParams(writeFileViewerStateToSearch(location.search, null).replace(/^\?/, ""));
+    params.delete("browse");
+    params.delete("q");
+    params.delete("folder");
+    navigateSearch(params.toString() ? `?${params.toString()}` : "");
+  }, [location.search, navigateSearch]);
+
+  const value = useMemo<FileViewerContextValue>(
+    () => ({
+      issueId,
+      state,
+      browse: browseState !== null,
+      query: browseState?.q ?? null,
+      browseProjectId: browseState?.projectId ?? null,
+      browseWorkspaceId: browseState?.workspaceId ?? null,
+      folderPath: browseState?.folderPath ?? null,
+      open,
+      openBrowse,
+      updateBrowseState,
+      openFolder,
+      backToFiles,
+      close,
+    }),
+    [issueId, state, browseState, open, openBrowse, updateBrowseState, openFolder, backToFiles, close],
+  );
+
+  return <FileViewerContext.Provider value={value}>{children}</FileViewerContext.Provider>;
+}
+
+export function useFileViewer(): FileViewerContextValue | null {
+  return useContext(FileViewerContext);
+}
+
+export function useRequiredFileViewer(): FileViewerContextValue {
+  const ctx = useContext(FileViewerContext);
+  if (!ctx) {
+    throw new Error("useRequiredFileViewer must be used within a FileViewerProvider");
+  }
+  return ctx;
+}