feat(preview): hand server-browser downloads to the viewer

A file a server tab downloaded was discarded. It is now saved under the
environment's state directory until the tab closes (20 per tab, 1 GiB each)
and offered to the viewer in control: web shows a Save toast linking to an
authenticated /api/preview-stream/download route, mobile offers the share
sheet. preview_status lists the tab's downloads with their environment
paths so agents can read them.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: juliusmarminge

apps/mobile/src/features/browser/PreviewStreamWebView.tsx

@@ -2,6 +2,7 @@ import previewStreamScript from "@t3tools/mobile-preview-stream";
 import {
   previewStreamControlLabel,
   type PreviewStreamControl,
+  type PreviewStreamDownload,
   type PreviewStreamInput,
 } from "@t3tools/client-runtime/preview/server-browser-stream";
 import type { EnvironmentId } from "@t3tools/contracts";
@@ -15,11 +16,12 @@ import {
   useState,
   type Ref,
 } from "react";
-import { ActivityIndicator, Platform, Pressable, TextInput, View } from "react-native";
+import { ActivityIndicator, Alert, Platform, Pressable, TextInput, View } from "react-native";
 import { WebView } from "react-native-webview";
 import * as Clipboard from "expo-clipboard";
 
 import { AppText } from "../../components/AppText";
+import { downloadAndShareAttachment } from "../../lib/attachmentDownload";
 import { usePreviewStreamAccess } from "../../state/preview";
 
 import {
@@ -54,6 +56,27 @@ type NativeStreamBridge = {
   readonly compact?: boolean;
 };
 
+/** The file is on the environment; saving it here goes through the share sheet. */
+function offerDownload(download: PreviewStreamDownload) {
+  Alert.alert(`Downloaded ${download.fileName}`, undefined, [
+    { text: "Not now", style: "cancel" },
+    {
+      text: "Save or share",
+      onPress: () =>
+        void downloadAndShareAttachment({
+          url: download.url,
+          attachment: { name: download.fileName, mimeType: "application/octet-stream" },
+          signal: new AbortController().signal,
+        }).catch((cause: unknown) =>
+          Alert.alert(
+            "Could not save the download",
+            cause instanceof Error ? cause.message : undefined,
+          ),
+        ),
+    },
+  ]);
+}
+
 // Consecutive refused tickets before the view stops and offers Reconnect, e.g. a
 // session without operate scope.
 const MAX_REFUSALS = 3;
@@ -323,6 +346,9 @@ function PreviewStreamDocumentView({
             case "clipboard":
               void Clipboard.setStringAsync(message.text).catch(() => undefined);
               return;
+            case "download":
+              offerDownload(message);
+              return;
             case "pictureInPicture":
               onPictureInPicture?.(message, message.detail);
               return;

apps/mobile/src/features/browser/preview-stream-document.ts

@@ -1,5 +1,8 @@
 import type { DeviceHubAccess } from "@t3tools/client-runtime/device/hub-access";
-import type { PreviewStreamControl } from "@t3tools/client-runtime/preview/server-browser-stream";
+import type {
+  PreviewStreamControl,
+  PreviewStreamDownload,
+} from "@t3tools/client-runtime/preview/server-browser-stream";
 
 export interface PreviewStreamConfiguration {
   readonly access: DeviceHubAccess;
@@ -22,6 +25,7 @@ export type PreviewStreamMessage =
   | { readonly type: "gone" }
   | { readonly type: "viewport"; readonly width: number; readonly height: number }
   | { readonly type: "clipboard"; readonly text: string }
+  | ({ readonly type: "download" } & PreviewStreamDownload)
   | {
       readonly type: "pictureInPicture";
       readonly supported: boolean;

apps/mobile/src/features/browser/preview-stream.browser.ts

@@ -171,6 +171,7 @@ export function start(configuration: PreviewStreamConfiguration) {
       {
         onFrame: (jpeg) => painter.paint(jpeg),
         onClipboard: (text) => post({ type: "clipboard", text }),
+        onDownload: (download) => post({ type: "download", ...download }),
         onViewport: (page) => {
           if (viewport?.width === page.width && viewport.height === page.height) return;
           viewport = page;

apps/server/src/preview/ServerBrowser.test.ts

@@ -12,7 +12,9 @@ import {
 } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
+import * as FileSystem from "effect/FileSystem";
 import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import * as Queue from "effect/Queue";
 import type { BrowserContext, Page } from "playwright-core";
 import { afterEach, beforeEach, expect, vi } from "vite-plus/test";
@@ -671,3 +673,46 @@ it.live("page copies reach only the controlling viewer right after its input", (
     }),
   ).pipe(Effect.provide(layer)),
 );
+
+it.live("a page download is saved, offered to the controller, and listed for the agent", () =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const { browser, broker, tabId } = yield* ready;
+      const page = contexts[0]!.page;
+      const viewer = yield* browser.attachViewer(viewerInput(tabId, true));
+      yield* viewer.input({ type: "takeControl" });
+      yield* Queue.clear(viewer.output);
+      const fs = yield* FileSystem.FileSystem;
+      const runPromise = Effect.runPromiseWith(yield* Effect.context<never>());
+      page.emit("download", {
+        failure: async () => null,
+        saveAs: (path: string) => runPromise(fs.writeFileString(path, "a,b")),
+        suggestedFilename: () => "report.csv",
+        url: () => "blob:http://localhost:5173/1",
+      });
+      let offered = yield* Queue.take(viewer.output);
+      while (offered._tag !== "download") offered = yield* Queue.take(viewer.output);
+      expect(offered).toMatchObject({ _tag: "download", fileName: "report.csv", sizeBytes: 3 });
+      const file = yield* browser.openDownload({
+        threadId: scope.threadId,
+        tabId,
+        downloadId: offered.id,
+      });
+      expect(Option.isSome(file) && file.value.fileName).toBe("report.csv");
+      const status = yield* broker.invoke<PreviewAutomationStatus>({
+        scope,
+        tabId,
+        operation: "status",
+        input: {},
+      });
+      expect(status.downloads).toEqual([
+        expect.objectContaining({ fileName: "report.csv", sizeBytes: 3 }),
+      ]);
+      expect(
+        Option.isNone(
+          yield* browser.openDownload({ threadId: scope.threadId, tabId, downloadId: "guess" }),
+        ),
+      ).toBe(true);
+    }),
+  ).pipe(Effect.provide(layer)),
+);

apps/server/src/preview/ServerBrowser.ts

@@ -39,11 +39,12 @@ import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import { constVoid } from "effect/Function";
 import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
 import * as Queue from "effect/Queue";
 import * as Schema from "effect/Schema";
 import type * as Scope from "effect/Scope";
 import * as Stream from "effect/Stream";
-import type { BrowserContext, CDPSession, Dialog, Page } from "playwright-core";
+import type { BrowserContext, CDPSession, Dialog, Download, Page } from "playwright-core";
 
 import { PENDING_ATTACHMENT_THREAD_SEGMENT } from "../attachmentStore.ts";
 import * as ServerConfig from "../config.ts";
@@ -140,6 +141,12 @@ export type ServerBrowserViewerOutput =
       readonly editable: boolean;
     }
   | { readonly _tag: "clipboard"; readonly text: string }
+  | {
+      readonly _tag: "download";
+      readonly id: string;
+      readonly fileName: string;
+      readonly sizeBytes: number;
+    }
   | { readonly _tag: "gone" };
 
 export interface ServerBrowserViewer {
@@ -163,6 +170,12 @@ export class ServerBrowser extends Context.Service<
       ServerBrowserTabNotFoundError | ServerBrowserLaunchError,
       Scope.Scope
     >;
+    /** A finished download of a live tab, for the authenticated download route. */
+    readonly openDownload: (input: {
+      readonly threadId: string;
+      readonly tabId: string;
+      readonly downloadId: string;
+    }) => Effect.Effect<Option.Option<{ readonly path: string; readonly fileName: string }>>;
     /** Deletes a human profile's server-side storage, closing its open tabs first. */
     readonly clearProfile: (profileId: string) => Effect.Effect<void, PreviewClearProfileError>;
   }
@@ -216,6 +229,8 @@ interface ServerTab {
   readonly profileId: string | undefined;
   /** Set when a page in another tab opened this one with `window.open` or a link. */
   readonly openerTabId: string | undefined;
+  /** Finished downloads, newest last; files live until the tab closes. */
+  readonly downloads: Array<ServerDownload>;
   dialog: Dialog | null;
   setting: PreviewViewportSetting;
   loading: boolean;
@@ -230,6 +245,18 @@ interface ServerTab {
   capturing: number;
 }
 
+interface ServerDownload {
+  readonly id: string;
+  readonly fileName: string;
+  readonly path: string;
+  readonly sizeBytes: number;
+  readonly url: string;
+  readonly completedAt: string;
+}
+
+const DOWNLOAD_LIMIT = 20;
+const DOWNLOAD_MAX_BYTES = 1024 * 1024 * 1024;
+
 const tabKey = (threadId: string, tabId: string) => `${threadId}\u0000${tabId}`;
 
 const pushBounded = <A>(
@@ -468,6 +495,7 @@ const make = Effect.gen(function* () {
     void tab.page.close().catch(constVoid);
     if (tab.isolatedContext) void tab.page.context().close().catch(constVoid);
     void tab.recording?.encoder.close().catch(constVoid);
+    void NodeFSP.rm(downloadDir(tab), { recursive: true, force: true }).catch(constVoid);
     reportLiveTabs();
     if (closeSession) {
       runFork(manager.close({ threadId: tab.threadId, tabId: tab.tabId }).pipe(Effect.ignore));
@@ -510,6 +538,7 @@ const make = Effect.gen(function* () {
       isolatedContext,
       profileId: snapshot.profileId,
       openerTabId: adopted?.openerTabId,
+      downloads: [],
       dialog: null,
       setting: snapshot.viewport ?? FILL_PREVIEW_VIEWPORT,
       loading: false,
@@ -577,6 +606,7 @@ const make = Effect.gen(function* () {
       tab.dialog = dialog;
       broadcastControl(tab);
     });
+    page.on("download", (download) => void saveDownload(tab, download));
     // Popups become tabs and keep `window.opener`, so sign-in popups can report back.
     page.on("popup", (popup) => void adoptPopup(tab, popup));
     // Playwright cannot reload a crashed page, so it must leave the tab list.
@@ -602,6 +632,62 @@ const make = Effect.gen(function* () {
     return tab;
   };
 
+  const downloadsRoot = NodePath.join(config.stateDir, "server-browser", "downloads");
+  // Tab ids are opaque server strings; hashing keeps them out of the path.
+  const downloadDir = (tab: ServerTab) =>
+    NodePath.join(
+      downloadsRoot,
+      NodeCrypto.createHash("sha256").update(tabKey(tab.threadId, tab.tabId)).digest("hex"),
+    );
+
+  const saveDownload = async (tab: ServerTab, download: Download) => {
+    const id = NodeCrypto.randomUUID();
+    const path = NodePath.join(downloadDir(tab), id);
+    try {
+      if (await download.failure()) return;
+      await NodeFSP.mkdir(downloadDir(tab), { recursive: true });
+      await download.saveAs(path);
+      const { size } = await NodeFSP.stat(path);
+      if (tab.closing || size > DOWNLOAD_MAX_BYTES) {
+        await NodeFSP.rm(path, { force: true });
+        return;
+      }
+      const saved: ServerDownload = {
+        id,
+        fileName: download.suggestedFilename().slice(0, 255) || "download",
+        path,
+        sizeBytes: size,
+        url: download.url().slice(0, 2048),
+        completedAt: new Date().toISOString(),
+      };
+      tab.downloads.push(saved);
+      for (const evicted of tab.downloads.splice(0, tab.downloads.length - DOWNLOAD_LIMIT)) {
+        await NodeFSP.rm(evicted.path, { force: true }).catch(constVoid);
+      }
+      // Only the person driving the page gets the file offered; agents read it from status.
+      const controller = [...tab.viewers].find((viewer) => viewer.id === tab.control.controller);
+      controller?.push({
+        _tag: "download",
+        id,
+        fileName: saved.fileName,
+        sizeBytes: saved.sizeBytes,
+      });
+    } catch (cause) {
+      await NodeFSP.rm(path, { force: true }).catch(constVoid);
+      runFork(Effect.logWarning("server preview download failed", { cause }));
+    }
+  };
+
+  const openDownload: ServerBrowser["Service"]["openDownload"] = (input) =>
+    Effect.sync(() => {
+      const download = tabs
+        .get(tabKey(input.threadId, input.tabId))
+        ?.downloads.find((candidate) => candidate.id === input.downloadId);
+      return download === undefined
+        ? Option.none()
+        : Option.some({ path: download.path, fileName: download.fileName });
+    });
+
   const preparedContexts = new WeakSet<BrowserContext>();
   const prepareContext = async (context: BrowserContext) => {
     if (preparedContexts.has(context)) return;
@@ -731,6 +817,13 @@ const make = Effect.gen(function* () {
           url: candidate.page.url() === "about:blank" ? null : candidate.page.url(),
           ...(candidate.openerTabId === undefined ? {} : { openerTabId: candidate.openerTabId }),
         })),
+      downloads: tab.downloads.map(({ fileName, path, sizeBytes, url, completedAt }) => ({
+        fileName,
+        path,
+        sizeBytes,
+        url,
+        completedAt,
+      })),
     };
     if (status.url === null || tab.dialog) return status;
     return { ...status, title: (await tab.page.title().catch(() => "")) || null };
@@ -1666,7 +1759,7 @@ const make = Effect.gen(function* () {
       catch: (cause) => new PreviewClearProfileError({ profileId, cause }),
     });
 
-  return ServerBrowser.of({ enabled, attachViewer, clearProfile });
+  return ServerBrowser.of({ enabled, attachViewer, clearProfile, openDownload });
 });
 
 export const layer = Layer.effect(ServerBrowser, make);