feat(plugins): file panels (#7411)

* fix(files): report document MIME types for binary files

File reads now carry the document's MIME type for binary files, so a file panel can
hand the bytes to a viewer that needs the real type (application/pdf).

* feat(plugins): file panels

Plugins contribute file panels with addFilePanel. A file tab hosts the panels that claim the
file: the built-in Markdown, HTML and image panels, plugin panels, and Source, Paseo's editor,
which claims every text file and is always the last candidate. The panel is the tab body;
the bar shows the document's status and a switcher between the file's panels (side by side
up to three, two on a phone, a menu beyond that).

Paseo asks which panel opens a file only when a plugin panel is among several candidates,
once per open, and remembers the answer per extension or exact filename when told to. Open
with in the tab menu and the switcher change the tab's panel; Always use remembers it.
Opening a file at a line switches the tab to Source.

Panels read and write the host's document, so dirty state, autosave and conflicts stay
Paseo's. DocumentFrame shows bytes documents such as PDFs in the browser's viewer.

Replaces the file tab's Preview/Source mode toggle.

* feat(file-panels): choose and forget file panels in Settings > Files

Settings > Files lists each extension or filename where a plugin panel competes with
another candidate, or that has a remembered panel. Each row chooses the panel that opens
it, or Ask every time; Ask again forgets the choice. Source appears as a candidate for
text files. Panels no connected host offers can be forgotten but not chosen.

* docs(plugins): file panel examples and author reference

Adds the pdf-panel and markdown-panel examples, the File panels section of the plugin
reference, and an e2e spec that installs both examples, opens a PDF in the browser
viewer, and edits Markdown through Paseo's document across the switcher, Source,
autosave and conflicts.

* feat(file-panels): panels read and write through a file handle

The file tab stats the file and mounts its panel without reading it. Every
panel, built-in or plugin, gets a PluginFile handle: readText, readBytes, url,
version-checked writeText/writeBytes (PluginFileConflictError unless force),
and watch. useFileText, useFileBytes and useFileUrl read through it, and
Loading joins @getpaseo/plugin/client/ui. Panels own their loading state.

The host document pipeline, the explorer preview cache and the preview
lifecycle are deleted. The daemon classifies a file version from a bounded
sniff and writes base64 content as bytes behind fileByteWrites.

A deleted file keeps its panel mounted; a read confirms the deletion first,
so a remove-and-rewrite is not reported as one. Native Source decodes with
builtins and highlights in idle-time slices, the lines around the opening
line first, so a large file no longer blocks the JS thread.

* fix(file-panels): Settings offers Source where the picker does, and review follow-ups

- Settings > Files offers Source on every key except those a built-in panel of
  another kind (Image) claims, so a plugin that alone claims a text extension
  shows the same choices as the picker.
- Delete the unused isSourceFilePanel.
- The Markdown example warns with the file name when its unmount write fails,
  rather than dropping the edit silently.
- Document that PluginFile stat fields are read at render time and that watch
  or the read hooks are how a panel learns they changed.

* fix(plugins): file events are objects, deletion is a typed error, DocumentFrame owns its fallback

- watch listeners receive { type: "changed" } | { type: "deleted" }, so later
  versions can add fields without breaking them.
- PluginFileDeletedError joins PluginFileConflictError. The read hooks report a
  deleted file with it, and a write over a deleted file rejects with it; Source
  shows that as the deleted notice. PluginFileConflictError now means only
  "changed on disk".
- DocumentFrame on Android shows Paseo's "<TYPE> files can't be shown on this
  device" message for documents its WebView cannot display, so the PDF example
  is useFileUrl + Loading + DocumentFrame with no platform branch.

* test(file-panels): Settings offers Source for a remembered panel no host has

* test(e2e): hide the developer error toast instead of clicking it away

The locator handler that dismissed #error-toast could match a toast that closed before its
click, then wait on it until the test timed out (agent-timeline-resume.spec.ts:45 failed every
attempt on this branch). Hiding the toast with CSS keeps it off app actions with no race.

* test(e2e): desktop browser-tabs hides developer toasts on its attached page

packages/server/src/server/file-explorer/service.test.ts

@@ -19,6 +19,8 @@ import {
   deleteExplorerEntry,
   duplicateExplorerEntry,
   getExplorerFileVersion,
+  getDownloadableFileInfo,
+  readExplorerFileBytes,
   readExplorerFile,
   renameExplorerEntry,
   streamExplorerFile,
@@ -132,6 +134,62 @@ describe("file explorer service", () => {
     }
   });
 
+  it("classifies a file version from its extension and first bytes", async () => {
+    const root = await createTempDir("paseo-file-version-kind-");
+    try {
+      await writeFile(path.join(root, "notes.md"), "# Notes\n", "utf8");
+      await writeFile(path.join(root, "pixel.png"), Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+      await writeFile(path.join(root, "report.pdf"), "%PDF-1.4\n", "utf8");
+      await writeFile(path.join(root, "blob.dat"), Buffer.from([0x00, 0x01, 0x02]));
+      // A multi-byte character split by the sample boundary is still text.
+      await writeFile(path.join(root, "wide.txt"), `${"a".repeat(8191)}é tail`, "utf8");
+
+      const kinds = await Promise.all(
+        ["notes.md", "pixel.png", "report.pdf", "blob.dat", "wide.txt"].map(
+          async (relativePath) => {
+            const version = await getExplorerFileVersion({ root, relativePath });
+            return version.status === "ready" ? [version.kind, version.mimeType] : version.status;
+          },
+        ),
+      );
+
+      expect(kinds).toEqual([
+        ["text", "text/plain"],
+        ["image", "image/png"],
+        ["binary", "application/pdf"],
+        ["binary", "application/octet-stream"],
+        ["text", "text/plain"],
+      ]);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it("writes base64 content as bytes, including over a binary file", async () => {
+    const root = await createTempDir("paseo-file-write-bytes-");
+    try {
+      const filePath = path.join(root, "blob.dat");
+      await writeFile(filePath, Buffer.from([0x00, 0x01, 0x02]));
+      const current = await getExplorerFileVersion({ root, relativePath: "blob.dat" });
+      expect(current.status).toBe("ready");
+      if (current.status !== "ready") return;
+
+      const result = await writeExplorerFile({
+        root,
+        relativePath: "blob.dat",
+        content: Buffer.from([0xff, 0x00, 0xfe]).toString("base64"),
+        contentEncoding: "base64",
+        expectedModifiedAt: current.modifiedAt,
+        expectedRevision: current.revision,
+      });
+
+      expect(result).toMatchObject({ status: "written", size: 3 });
+      expect([...(await readFile(filePath))]).toEqual([0xff, 0x00, 0xfe]);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("never creates a missing file through the write API", async () => {
     const root = await createTempDir("paseo-file-missing-");
     try {
@@ -192,6 +250,36 @@ describe("file explorer service", () => {
     }
   });
 
+  it.each([
+    ["report.pdf", Buffer.from("%PDF-1.4\n%\x00\xff\n%%EOF", "binary")],
+    ["report.PDF", Buffer.from("%PDF-1.4\n%%EOF")],
+  ])("reports application/pdf for %s across file reads and downloads", async (name, bytes) => {
+    const root = await createTempDir("paseo-file-pdf-");
+    try {
+      await writeFile(path.join(root, name), bytes);
+      const target = { root, relativePath: name };
+      expect(await readExplorerFile(target)).toMatchObject({
+        kind: "binary",
+        mimeType: "application/pdf",
+      });
+      expect(await readExplorerFileBytes(target)).toMatchObject({
+        kind: "binary",
+        mimeType: "application/pdf",
+        bytes,
+      });
+      await streamExplorerFile(target, async (file) => {
+        expect(file.kind).toBe("binary");
+        expect(file.mimeType).toBe("application/pdf");
+        const chunks: Uint8Array[] = [];
+        for await (const chunk of file.chunks) chunks.push(chunk);
+        expect(Buffer.concat(chunks)).toEqual(bytes);
+      });
+      expect(await getDownloadableFileInfo(target)).toMatchObject({ mimeType: "application/pdf" });
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+
   it("classifies files with null bytes as binary", async () => {
     const root = await createTempDir("paseo-file-explorer-");
 

packages/server/src/server/file-explorer/service.ts

@@ -21,6 +21,8 @@ export interface ReadFileParams {
 
 export interface WriteFileParams extends ReadFileParams {
   content: string;
+  /** `base64` writes the decoded bytes, so binary files can be written too. */
+  contentEncoding?: "utf-8" | "base64";
   expectedModifiedAt: string;
   expectedRevision?: string;
 }
@@ -33,6 +35,8 @@ export type ExplorerFileVersion =
       size: number;
       modifiedAt: string;
       revision: string;
+      kind?: ExplorerFileKind;
+      mimeType?: string;
     }
   | { status: "missing"; cwd: string; path: string }
   | { status: "error"; cwd: string; path: string; error: string };
@@ -92,6 +96,15 @@ const TEXT_MIME_TYPES: Record<string, string> = {
   ".json": "application/json",
 };
 
+const BINARY_MIME_TYPES: Record<string, string> = {
+  ".pdf": "application/pdf",
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".woff2": "font/woff2",
+};
+
 const DEFAULT_TEXT_MIME_TYPE = "text/plain";
 const FILE_TYPE_SAMPLE_BYTES = 8192;
 export const FILE_EXPLORER_STREAM_CHUNK_BYTES = 256 * 1024;
@@ -266,13 +279,13 @@ export async function readExplorerFileBytes({
       };
     }
 
-    if (isLikelyBinary(buffer) || !isValidUtf8(buffer)) {
+    if (ext in BINARY_MIME_TYPES || isLikelyBinary(buffer) || !isValidUtf8(buffer)) {
       return {
         ...basePayload,
         kind: "binary",
         encoding: "binary",
         bytes: buffer,
-        mimeType: "application/octet-stream",
+        mimeType: BINARY_MIME_TYPES[ext] ?? "application/octet-stream",
       };
     }
 
@@ -305,7 +318,8 @@ export async function streamExplorerFile(
     const advertisedRevision = fileRevision(stats);
     const ext = path.extname(filePath.resolvedPath).toLowerCase();
     const isImage = ext in IMAGE_MIME_TYPES;
-    const isBinary = isImage || (await isFileHandleBinary(handle, advertisedSize));
+    const isBinary =
+      isImage || ext in BINARY_MIME_TYPES || (await isFileHandleBinary(handle, advertisedSize));
     let kind: ExplorerFileKind = "text";
     let mimeType = textMimeTypeForExtension(ext);
     if (isImage) {
@@ -313,7 +327,7 @@ export async function streamExplorerFile(
       mimeType = IMAGE_MIME_TYPES[ext];
     } else if (isBinary) {
       kind = "binary";
-      mimeType = "application/octet-stream";
+      mimeType = BINARY_MIME_TYPES[ext] ?? "application/octet-stream";
     }
 
     await consume({
@@ -398,18 +412,26 @@ export async function getExplorerFileVersion({
   const cwd = expandUserPath(root);
   try {
     const filePath = await resolveScopedPath({ root, relativePath });
-    const stats = await fs.stat(filePath.resolvedPath, { bigint: true });
-    if (!stats.isFile()) {
-      return { status: "error", cwd, path: relativePath, error: "Requested path is not a file" };
+    const handle = await openFileForRead(filePath.resolvedPath);
+    try {
+      const stats = await handle.stat({ bigint: true });
+      if (!stats.isFile()) {
+        return { status: "error", cwd, path: relativePath, error: "Requested path is not a file" };
+      }
+      const type = await sniffFileType(handle, path.extname(filePath.resolvedPath).toLowerCase());
+      return {
+        status: "ready",
+        cwd,
+        path: normalizeRelativePath({ root, targetPath: filePath.requestedPath }),
+        size: Number(stats.size),
+        modifiedAt: stats.mtime.toISOString(),
+        revision: fileRevision(stats),
+        kind: type.kind,
+        mimeType: type.mimeType,
+      };
+    } finally {
+      await handle.close();
     }
-    return {
-      status: "ready",
-      cwd,
-      path: normalizeRelativePath({ root, targetPath: filePath.requestedPath }),
-      size: Number(stats.size),
-      modifiedAt: stats.mtime.toISOString(),
-      revision: fileRevision(stats),
-    };
   } catch (error) {
     if (isMissingEntryError(error)) {
       return { status: "missing", cwd, path: relativePath };
@@ -434,10 +456,11 @@ export async function writeExplorerFile({
   root,
   relativePath,
   content,
+  contentEncoding = "utf-8",
   expectedModifiedAt,
   expectedRevision,
 }: WriteFileParams): Promise<ExplorerFileWriteResult> {
-  const encoded = Buffer.from(content, "utf8");
+  const encoded = Buffer.from(content, contentEncoding === "base64" ? "base64" : "utf8");
   if (encoded.byteLength > MAX_EDITABLE_FILE_BYTES) {
     return { status: "error", error: "File is too large to edit" };
   }
@@ -455,9 +478,11 @@ export async function writeExplorerFile({
       if (stats.size > BigInt(MAX_EDITABLE_FILE_BYTES)) {
         return { status: "error", error: "File is too large to edit" };
       }
-      const current = await handle.readFile();
-      if (isLikelyBinary(current) || !isValidUtf8(current)) {
-        return { status: "error", error: "Binary files cannot be edited" };
+      if (contentEncoding === "utf-8") {
+        const current = await handle.readFile();
+        if (isLikelyBinary(current) || !isValidUtf8(current)) {
+          return { status: "error", error: "Binary files cannot be edited" };
+        }
       }
       currentMode = Number(stats.mode);
       const modifiedAt = stats.mtime.toISOString();
@@ -548,18 +573,10 @@ export async function getDownloadableFileInfo({ root, relativePath }: ReadFilePa
       throw new Error("Requested path is not a file");
     }
 
-    const ext = path.extname(filePath.resolvedPath).toLowerCase();
-    let mimeType = "application/octet-stream";
-    if (ext in IMAGE_MIME_TYPES) {
-      mimeType = IMAGE_MIME_TYPES[ext];
-    } else {
-      const sample = Buffer.alloc(FILE_TYPE_SAMPLE_BYTES);
-      const { bytesRead } = await handle.read(sample, 0, sample.length, 0);
-      const chunk = bytesRead < sample.length ? sample.subarray(0, bytesRead) : sample;
-      if (!isLikelyBinary(chunk)) {
-        mimeType = textMimeTypeForExtension(ext);
-      }
-    }
+    const { mimeType } = await sniffFileType(
+      handle,
+      path.extname(filePath.resolvedPath).toLowerCase(),
+    );
 
     return {
       path: normalizeRelativePath({ root, targetPath: filePath.requestedPath }),
@@ -900,6 +917,34 @@ function isLikelyBinary(buffer: Buffer): boolean {
   return suspicious / buffer.length > 0.3;
 }
 
+/** Classifies a file from its extension and first bytes, without reading the rest of it. */
+async function sniffFileType(
+  handle: FileHandle,
+  ext: string,
+): Promise<{ kind: ExplorerFileKind; mimeType: string }> {
+  if (ext in IMAGE_MIME_TYPES) return { kind: "image", mimeType: IMAGE_MIME_TYPES[ext] };
+  const binary = {
+    kind: "binary" as const,
+    mimeType: BINARY_MIME_TYPES[ext] ?? "application/octet-stream",
+  };
+  if (ext in BINARY_MIME_TYPES) return binary;
+  const sample = Buffer.alloc(FILE_TYPE_SAMPLE_BYTES);
+  const { bytesRead } = await handle.read(sample, 0, sample.length, 0);
+  const chunk = sample.subarray(0, bytesRead);
+  if (isLikelyBinary(chunk) || !isValidUtf8Prefix(chunk)) return binary;
+  return { kind: "text", mimeType: textMimeTypeForExtension(ext) };
+}
+
+/** A sample can end inside a multi-byte character, so only a complete invalid sequence fails. */
+function isValidUtf8Prefix(buffer: Buffer): boolean {
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(buffer, { stream: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function isValidUtf8(buffer: Buffer): boolean {
   try {
     new TextDecoder("utf-8", { fatal: true }).decode(buffer);

packages/server/src/server/session/files/workspace-files-session.ts

@@ -160,6 +160,7 @@ export class WorkspaceFilesSession {
       root: request.cwd,
       relativePath: request.path,
       content: request.content,
+      contentEncoding: request.contentEncoding,
       expectedModifiedAt: request.expectedModifiedAt,
       expectedRevision: request.expectedRevision,
     });

packages/server/src/server/websocket-server.ts

@@ -1885,6 +1885,8 @@ export class VoiceAssistantWebSocketServer {
         workspaceRecovery: true,
         // COMPAT(workspaceFileEditing): added in v0.2.0, remove after 2027-01-18 once daemon floor >= v0.2.0.
         workspaceFileEditing: true,
+        // COMPAT(fileByteWrites): added in v0.13.0, remove gate after 2027-04-20.
+        fileByteWrites: true,
         // COMPAT(providerUsageList): added in v0.1.98, drop the gate when daemon floor >= v0.1.98.
         providerUsageList: true,
         // COMPAT(agentDetach): added in v0.1.98, remove gate after 2026-12-19 once daemon floor >= v0.1.98.