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/plugin/src/boundaries.test.ts

@@ -89,8 +89,8 @@ describe("plugin SDK import boundaries", () => {
 
 describe("plugin example import boundaries", () => {
   const examples = path.resolve(sourceDirectory, "../../../plugin-examples");
-  const files = readdirSync(examples, { recursive: true }).filter((file) =>
-    /(?<!\.test)\.tsx?$/.test(file),
+  const files = readdirSync(examples, { recursive: true }).filter(
+    (file) => !file.split(path.sep).includes("node_modules") && /(?<!\.test)\.tsx?$/.test(file),
   );
   const owner = (file: string) => {
     const [, directory] = path.relative(examples, file).split(path.sep);

packages/plugin/src/client/contracts.ts

@@ -2,6 +2,7 @@ import type { ComponentType } from "react";
 import type { PaseoApi } from "@getpaseo/client";
 import type { AgentTimelineItem } from "@getpaseo/protocol/agent-types";
 import type { ZodType, input as ZodInput, output as ZodOutput } from "zod";
+import type { PluginFile, PluginFileLocation, PluginFileTab } from "./file.js";
 import type { PluginRpcContract } from "../rpc.js";
 import type {
   PluginButtonRegistration,
@@ -120,6 +121,23 @@ export interface PluginAgentPanelProps extends PluginNavigableHostProps {
   agentId: string;
 }
 
+export interface PluginFilePanelProps extends PluginNavigableHostProps {
+  workspaceId: string;
+  /** The file itself. The panel decides how to read it, show it, and save it. */
+  file: PluginFile;
+  tab: PluginFileTab;
+  location: PluginFileLocation;
+}
+
+export interface PluginFilePanelContribution {
+  id: string;
+  title: string;
+  icon: PluginIcon;
+  /** Extensions without the dot, case-insensitive, and exact filenames. */
+  files: { extensions: readonly string[]; filenames?: readonly string[] };
+  Component: ComponentType<PluginFilePanelProps>;
+}
+
 export interface PluginClientOpenPanelOptions extends PluginOpenPanelOptions {
   workspaceId: string;
   agentId?: string;
@@ -140,6 +158,7 @@ export interface PluginClientContext extends PluginCommandCapabilities, PluginCl
   addScreen(contribution: PluginScreenContribution): PluginCleanup;
   addSidebarHeaderItem(contribution: PluginSidebarItemContribution): PluginCleanup;
   addSidebarFooterItem(contribution: PluginSidebarItemContribution): PluginCleanup;
+  addFilePanel(contribution: PluginFilePanelContribution): PluginCleanup;
   addWorkspacePanel(contribution: PluginWorkspacePanelContribution): PluginCleanup;
   addCommandCenterItem(contribution: PluginCommandCenterItemContribution): PluginCleanup;
   addSlashCommand(contribution: PluginClientSlashCommandContribution): PluginCleanup;

packages/plugin/src/client/file.ts

@@ -0,0 +1,170 @@
+import { useEffect, useState } from "react";
+
+/**
+ * The file a file panel shows. Stable for the life of the tab's target. The stat fields hold the
+ * latest version Paseo knows; read them while rendering. Changing them does not re-render the
+ * panel: `watch`, or a re-render from the read hooks, is how a panel learns they changed.
+ */
+export interface PluginFile {
+  /** Absolute path on the host. */
+  readonly path: string;
+  readonly name: string;
+  /** Lowercase, without the dot; empty when the name has none. */
+  readonly extension: string;
+  readonly size: number;
+  readonly modifiedAt: string;
+  readonly mimeType: string;
+  /** Reads the file as UTF-8. A byte order mark is dropped here and written back by `writeText`. */
+  readText(): Promise<string>;
+  readBytes(): Promise<Uint8Array>;
+  /**
+   * A local URL of the file's current bytes, for `DocumentFrame` and images. Paseo owns it: it stays
+   * valid until a URL of a newer version resolves or the tab closes.
+   */
+  url(): Promise<string>;
+  /**
+   * Writes the file if it has not changed since this handle last read or wrote it. Otherwise
+   * rejects with `PluginFileConflictError`; `force: true` writes anyway. Rejects with
+   * `PluginFileDeletedError` when the file is gone.
+   */
+  writeText(text: string, options?: PluginFileWriteOptions): Promise<void>;
+  writeBytes(bytes: Uint8Array, options?: PluginFileWriteOptions): Promise<void>;
+  /**
+   * Calls `listener` when the file changes on disk or is deleted. This handle's own writes do not
+   * notify. A deletion is reported once a read confirms it; the panel stays mounted. Returns the
+   * unsubscribe function.
+   */
+  watch(listener: (event: PluginFileEvent) => void): () => void;
+}
+
+export interface PluginFileWriteOptions {
+  force?: boolean;
+}
+
+/** What happened to the file on disk. Switch on `type`; later versions may add fields. */
+export type PluginFileEvent = { type: "changed" } | { type: "deleted" };
+
+/** What the panel reports back to its tab. */
+export interface PluginFileTab {
+  /** Shows the tab's unsaved dot and asks before the tab closes. */
+  setModified(modified: boolean): void;
+}
+
+/** The line a link or search result opened the file at. `revision` bumps on every new target. */
+export interface PluginFileLocation {
+  lineStart?: number;
+  lineEnd?: number;
+  revision: number;
+}
+
+/** The file changed on disk since the handle last read or wrote it. */
+export class PluginFileConflictError extends Error {
+  constructor(message = "The file changed on disk.") {
+    super(message);
+    this.name = "PluginFileConflictError";
+  }
+}
+
+/** The file was deleted on disk. */
+export class PluginFileDeletedError extends Error {
+  constructor(message = "The file was deleted.") {
+    super(message);
+    this.name = "PluginFileDeletedError";
+  }
+}
+
+export type PluginFileTextState =
+  | { status: "loading" }
+  | { status: "ready"; text: string }
+  | { status: "error"; error: Error };
+
+export type PluginFileBytesState =
+  | { status: "loading" }
+  | { status: "ready"; bytes: Uint8Array }
+  | { status: "error"; error: Error };
+
+export type PluginFileUrlState =
+  | { status: "loading" }
+  | { status: "ready"; url: string }
+  | { status: "error"; error: Error };
+
+/**
+ * The file's text, re-read when it changes on disk. Keeps the current text during a re-read. A
+ * deleted file is an error holding a `PluginFileDeletedError`.
+ */
+export function useFileText(file: PluginFile): PluginFileTextState {
+  const state = useFileRead(file, "text");
+  return state.status === "ready" ? { status: "ready", text: state.value as string } : state;
+}
+
+/**
+ * The file's bytes, re-read when it changes on disk. Keeps the current bytes during a re-read. A
+ * deleted file is an error holding a `PluginFileDeletedError`.
+ */
+export function useFileBytes(file: PluginFile): PluginFileBytesState {
+  const state = useFileRead(file, "bytes");
+  return state.status === "ready" ? { status: "ready", bytes: state.value as Uint8Array } : state;
+}
+
+/**
+ * A local URL of the file, replaced when it changes on disk. A deleted file is an error holding a
+ * `PluginFileDeletedError`.
+ */
+export function useFileUrl(file: PluginFile): PluginFileUrlState {
+  const state = useFileRead(file, "url");
+  return state.status === "ready" ? { status: "ready", url: state.value as string } : state;
+}
+
+type FileRead = "text" | "bytes" | "url";
+type FileReadState =
+  | { status: "loading" }
+  | { status: "ready"; value: string | Uint8Array }
+  | { status: "error"; error: Error };
+
+function useFileRead(file: PluginFile, read: FileRead): FileReadState {
+  const [state, setState] = useState<{ file: PluginFile; read: FileRead; state: FileReadState }>(
+    () => ({ file, read, state: { status: "loading" } }),
+  );
+  useEffect(() => {
+    let generation = 0;
+    let active = true;
+    const load = async () => {
+      const current = ++generation;
+      let next: FileReadState;
+      try {
+        next = { status: "ready", value: await readFile(file, read) };
+      } catch (error) {
+        next = { status: "error", error: asError(error) };
+      }
+      if (active && current === generation) setState({ file, read, state: next });
+    };
+    void load();
+    const unwatch = file.watch((event) => {
+      if (event.type === "changed") {
+        void load();
+        return;
+      }
+      generation += 1;
+      setState({
+        file,
+        read,
+        state: { status: "error", error: new PluginFileDeletedError() },
+      });
+    });
+    return () => {
+      active = false;
+      unwatch();
+    };
+  }, [file, read]);
+  return state.file === file && state.read === read ? state.state : { status: "loading" };
+}
+
+function readFile(file: PluginFile, read: FileRead): Promise<string | Uint8Array> {
+  if (read === "text") return file.readText();
+  if (read === "bytes") return file.readBytes();
+  return file.url();
+}
+
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

packages/plugin/src/client/index.ts

@@ -1,5 +1,7 @@
 export type {
   PluginHostProps,
+  PluginFilePanelContribution,
+  PluginFilePanelProps,
   PluginSurfaceProps,
   PluginScreenProps,
   PluginPopoverProps,
@@ -46,6 +48,23 @@ export type {
   PluginHeaderButtonContribution,
 } from "./buttons.js";
 export type { PluginIconProps, PluginSerializableIcon, PluginSvgIcon } from "../icons.js";
+export type {
+  PluginFile,
+  PluginFileBytesState,
+  PluginFileEvent,
+  PluginFileLocation,
+  PluginFileTab,
+  PluginFileTextState,
+  PluginFileUrlState,
+  PluginFileWriteOptions,
+} from "./file.js";
+export {
+  PluginFileConflictError,
+  PluginFileDeletedError,
+  useFileBytes,
+  useFileText,
+  useFileUrl,
+} from "./file.js";
 export { usePaseo } from "./paseo-context.js";
 export { useAgent, useWorkspace } from "./client-state.js";
 export { useRpc } from "./rpc-context.js";

packages/plugin/src/client/ui.ts

@@ -85,3 +85,9 @@ export interface SidebarRowProps {
 export declare const SidebarRow: ComponentType<SidebarRowProps>;
 /** A line between groups of rows. Render it from a sidebar item's `Component`. */
 export declare const SidebarSeparator: ComponentType;
+
+/** Paseo's loading state. Fills the panel; the panel decides when to show it. */
+export declare const Loading: ComponentType;
+
+/** Render a local document URL in an isolated frame. */
+export declare const DocumentFrame: ComponentType<{ url: string; testID?: string }>;