refactor(preview): server browser tabs and HTML renders share one headless browser

A host that used both downloaded two Chromiums: the server browser's
Sparticuz pack plus fonts, and the HTML renderer's pinned Chrome for Testing
headless shell. PreviewBrowser now lives in preview/ and is provided once in
server.ts, so ServerBrowser and the HTML toolkit run the same install. Its
messages no longer name html_preview, since agents reach it from either
feature. ServerBrowserToolchain and its system-browser discovery are gone.

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

Author: juliusmarminge

apps/server/src/htmlRender/HtmlRender.test.ts

@@ -24,7 +24,7 @@ import * as NodeURL from "node:url";
 import { resolveAttachmentPathById } from "../attachmentStore.ts";
 import * as ServerConfig from "../config.ts";
 import * as HtmlRender from "./HtmlRender.ts";
-import * as PreviewBrowser from "./PreviewBrowser.ts";
+import * as PreviewBrowser from "../preview/PreviewBrowser.ts";
 
 // Real-browser tests run only when this names a chrome-headless-shell, for
 // example one T3 installed under <T3 home>/tools/chrome-headless-shell.

apps/server/src/htmlRender/HtmlRender.ts

@@ -31,7 +31,7 @@ import { resolveAttachmentRelativePath } from "../attachmentPaths.ts";
 import { createAttachmentId } from "../attachmentStore.ts";
 import * as ServerConfig from "../config.ts";
 import * as HeadlessChrome from "./headlessChrome.ts";
-import * as PreviewBrowser from "./PreviewBrowser.ts";
+import * as PreviewBrowser from "../preview/PreviewBrowser.ts";
 
 const MIB = 1024 * 1024;
 const MAX_IMAGE_BYTES = 10 * MIB;

apps/server/src/mcp/McpHttpServer.ts

@@ -19,7 +19,6 @@ import packageJson from "../../package.json" with { type: "json" };
 import * as ServerConfig from "../config.ts";
 import * as DeviceService from "../device/DeviceService.ts";
 import * as HtmlRender from "../htmlRender/HtmlRender.ts";
-import * as PreviewBrowser from "../htmlRender/PreviewBrowser.ts";
 import * as McpInvocationContext from "./McpInvocationContext.ts";
 import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
 import { PreviewControlsToolkit } from "./toolkits/previewControls/tools.ts";
@@ -700,7 +699,7 @@ const registerHtmlPreview = Effect.fn("McpHttpServer.registerHtmlPreview")(funct
 export const HtmlToolkitRegistrationLive = Layer.mergeAll(
   McpServer.toolkit(HtmlRenderToolkit).pipe(Layer.provide(HtmlRenderToolkitHandlersLive)),
   Layer.effectDiscard(registerHtmlPreview()).pipe(Layer.provide(HtmlPreviewToolkitHandlersLive)),
-).pipe(Layer.provide(HtmlRender.layer), Layer.provide(PreviewBrowser.layer));
+).pipe(Layer.provide(HtmlRender.layer));
 
 const PreviewStandardToolkitRegistrationLive = McpServer.toolkit(PreviewStandardToolkit).pipe(
   Layer.provide(PreviewStandardToolkitHandlersLive),

apps/server/src/mcp/toolkits/core.test.ts

@@ -21,6 +21,7 @@ import * as ServerConfig from "../../config.ts";
 import { OrchestratorProjectionError } from "../../orchestration-v2/Orchestrator.ts";
 import * as ProviderAdapterRegistry from "../../orchestration-v2/ProviderAdapterRegistry.ts";
 import * as ThreadManagement from "../../orchestration-v2/ThreadManagementService.ts";
+import * as PreviewBrowser from "../../preview/PreviewBrowser.ts";
 import * as ProjectService from "../../project/ProjectService.ts";
 import * as ProviderRegistry from "../../provider/Services/ProviderRegistry.ts";
 import * as ScheduledTaskService from "../../scheduledTasks/ScheduledTaskService.ts";
@@ -204,6 +205,7 @@ it.effect("returns an HTML render reference that Codex and Claude tool rows both
     Effect.provide(
       McpHttpServer.HtmlToolkitRegistrationLive.pipe(
         Layer.provideMerge(McpServer.McpServer.layer),
+        Layer.provide(PreviewBrowser.layer),
         Layer.provide(ServerConfig.layerTest(process.cwd(), { prefix: "t3-mcp-html-render-" })),
         Layer.provide(NodeServices.layer),
         // The preview browser is not installed in a fresh home, so nothing downloads.

apps/server/src/mcp/toolkits/worktree/registration.test.ts

@@ -24,6 +24,7 @@ import * as VcsStatusBroadcaster from "../../../vcs/VcsStatusBroadcaster.ts";
 import * as McpHttpServer from "../../McpHttpServer.ts";
 import * as McpSessionRegistry from "../../McpSessionRegistry.ts";
 import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
+import * as PreviewBrowser from "../../../preview/PreviewBrowser.ts";
 
 const StubServicesLive = Layer.mergeAll(
   Layer.mock(Orchestrator.OrchestratorV2)({}),
@@ -75,6 +76,7 @@ it.effect("production mcp layer lists worktree tools over http", () =>
           }),
         ),
         Layer.provide(PreviewAutomationBroker.layer),
+        Layer.provide(PreviewBrowser.layer),
         Layer.provide(StubServicesLive),
         Layer.build,
       );

…er/src/htmlRender/PreviewBrowser.test.ts …erver/src/preview/PreviewBrowser.test.tsapps/server/src/htmlRender/PreviewBrowser.test.ts renamed to apps/server/src/preview/PreviewBrowser.test.ts apps/server/src/htmlRender/PreviewBrowser.test.ts renamed to apps/server/src/preview/PreviewBrowser.test.ts

@@ -171,9 +171,7 @@ it.layer(NodeServices.layer)("PreviewBrowser", (it) => {
       const error = yield* browser.executable.pipe(Effect.flip);
 
       expect(error._tag).toBe("PreviewBrowserInstallError");
-      expect(error.message).toMatch(
-        /^T3 could not install its HTML preview browser: .+ Call html_preview again to retry\.$/,
-      );
+      expect(error.message).toMatch(/^T3 could not install its headless browser: .+ Try again\.$/);
       expect(yield* fs.readDirectory(installRoot)).toEqual([]);
       yield* browser.executable.pipe(Effect.flip);
       expect(requests).toHaveLength(2);
@@ -290,7 +288,5 @@ it("tells the agent how far the install has come", () => {
       totalBytes: 120_477_194,
       unpacking: false,
     }).message,
-  ).toBe(
-    "T3 is installing its HTML preview browser (37 of 120 MB downloaded). Call html_preview again in a minute.",
-  );
+  ).toBe("T3 is installing its headless browser (37 of 120 MB downloaded). Try again in a minute.");
 });

…/server/src/htmlRender/PreviewBrowser.ts apps/server/src/preview/PreviewBrowser.tsapps/server/src/htmlRender/PreviewBrowser.ts renamed to apps/server/src/preview/PreviewBrowser.ts apps/server/src/htmlRender/PreviewBrowser.ts renamed to apps/server/src/preview/PreviewBrowser.ts

@@ -21,8 +21,9 @@ import * as NodeCrypto from "node:crypto";
 import * as ServerConfig from "../config.ts";
 import { openZipArchive } from "../zipArchive.ts";
 
-// HTML previews only ever run T3's own pinned Chrome for Testing headless
-// shell, never a browser the user installed. To bump the pin, pick a version
+// The one browser T3 installs on a host. HTML render previews and server
+// browser tabs both run this pinned Chrome for Testing headless shell, so a host
+// downloads it once; neither uses a browser the user installed. To bump the pin, pick a version
 // from https://googlechromelabs.github.io/chrome-for-testing/known-good-versions-with-downloads.json,
 // download each platform's chrome-headless-shell zip, and replace the version
 // and every byte count and SHA-256 below. Hosts drop the old build after the
@@ -100,7 +101,7 @@ export class PreviewBrowserInstallError extends Schema.TaggedError<PreviewBrowse
   { detail: Schema.String, cause: Schema.optional(Schema.Defect()) },
 ) {
   override get message(): string {
-    return `T3 could not install its HTML preview browser: ${this.detail} Call html_preview again to retry.`;
+    return `T3 could not install its headless browser: ${this.detail} Try again.`;
   }
 }
 const isInstallError = Schema.is(PreviewBrowserInstallError);
@@ -113,7 +114,7 @@ export class PreviewBrowserInstallingError extends Schema.TaggedError<PreviewBro
     const progress = this.unpacking
       ? "unpacking"
       : `${megabytes(this.downloadedBytes)} of ${megabytes(this.totalBytes)} MB downloaded`;
-    return `T3 is installing its HTML preview browser (${progress}). Call html_preview again in a minute.`;
+    return `T3 is installing its headless browser (${progress}). Try again in a minute.`;
   }
 }
 
@@ -122,7 +123,7 @@ export class PreviewBrowserUnsupportedError extends Schema.TaggedError<PreviewBr
   { platform: Schema.String, arch: Schema.String },
 ) {
   override get message(): string {
-    return `HTML previews are not available on ${this.platform}-${this.arch}: Chrome for Testing has no headless shell for it. html_render still works without a preview.`;
+    return `T3's headless browser is not available on ${this.platform}-${this.arch}: Chrome for Testing has no headless shell for it.`;
   }
 }
 
@@ -141,7 +142,7 @@ export class PreviewBrowser extends Context.Service<
     /** The installed headless shell, if any. Never starts or waits on an install. */
     readonly installed: Effect.Effect<Option.Option<string>>;
   }
->()("t3/htmlRender/PreviewBrowser") {}
+>()("t3/preview/PreviewBrowser") {}
 
 export interface PreviewBrowserOptions {
   readonly baseDir: string;

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

@@ -27,7 +27,7 @@ import * as Broker from "../mcp/PreviewAutomationBroker.ts";
 import * as DesktopChannel from "./DesktopBrowserChannel.ts";
 import * as Manager from "./Manager.ts";
 import * as ServerBrowser from "./ServerBrowser.ts";
-import * as Toolchain from "./ServerBrowserToolchain.ts";
+import * as PreviewBrowser from "./PreviewBrowser.ts";
 
 // Keep the manager, broker, ownership, refs, and viewer paths real; replace Chromium I/O only.
 vi.mock("./ServerBrowserContexts.ts", () => ({
@@ -189,8 +189,9 @@ const dependencies = Layer.mergeAll(
     getEnvironmentId: Effect.succeed(scope.environmentId),
     getDescriptor: Effect.die("unused descriptor"),
   }),
-  Layer.succeed(Toolchain.ServerBrowserToolchain, {
-    resolve: Effect.die("mock Chromium does not need an executable"),
+  Layer.succeed(PreviewBrowser.PreviewBrowser, {
+    executable: Effect.die("mock Chromium does not need an executable"),
+    installed: Effect.die("mock Chromium does not need an executable"),
   }),
   Layer.succeed(DesktopChannel.DesktopBrowserChannel, {
     // Only tabs a test marks render on the desktop; the rest stay headless.

apps/server/src/preview/ServerBrowser.ts

@@ -66,7 +66,7 @@ import * as PreviewAutomationBroker from "../mcp/PreviewAutomationBroker.ts";
 import * as DesktopBrowserChannel from "./DesktopBrowserChannel.ts";
 import * as PreviewManager from "./Manager.ts";
 import * as ServerBrowserPage from "./ServerBrowserPage.ts";
-import * as ServerBrowserToolchain from "./ServerBrowserToolchain.ts";
+import * as PreviewBrowser from "./PreviewBrowser.ts";
 import { ServerBrowserContexts } from "./ServerBrowserContexts.ts";
 import { BrowserControlInterrupted, SessionControl } from "./SessionControl.ts";
 
@@ -419,7 +419,7 @@ const make = Effect.gen(function* () {
   const manager = yield* PreviewManager.PreviewManager;
   const broker = yield* PreviewAutomationBroker.PreviewAutomationBroker;
   const environment = yield* ServerEnvironment.ServerEnvironment;
-  const toolchain = yield* ServerBrowserToolchain.ServerBrowserToolchain;
+  const previewBrowser = yield* PreviewBrowser.PreviewBrowser;
   const desktopChannel = yield* DesktopBrowserChannel.DesktopBrowserChannel;
   const runFork = Effect.runForkWith(yield* Effect.context<never>());
 
@@ -436,7 +436,7 @@ const make = Effect.gen(function* () {
 
   const contexts = new ServerBrowserContexts({
     profilesDir: NodePath.join(config.stateDir, "server-browser", "profiles"),
-    resolve: () => Effect.runPromise(toolchain.resolve),
+    executable: () => Effect.runPromise(previewBrowser.executable),
     onContextClose: (context) => {
       for (const tab of tabs.values()) {
         if (tab.page.context() === context) dropTab(tab, true);

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

@@ -52,7 +52,7 @@ const makeBrowser = () => {
 
 const options = () => ({
   profilesDir: "/test/profiles",
-  resolve: vi.fn(async () => ({ executablePath: "/test/chromium", env: { LIB_PATH: "browser" } })),
+  executable: vi.fn(async () => "/test/chromium"),
   env: {},
 });
 
@@ -70,7 +70,7 @@ describe("ServerBrowserContexts", () => {
     launches.launch.mockReturnValue(launch.promise);
     const configuration = options();
     const pool = new ServerBrowserContexts(configuration);
-    expect(configuration.resolve).not.toHaveBeenCalled();
+    expect(configuration.executable).not.toHaveBeenCalled();
     const first = pool.contextFor("default", "agent-a");
     const again = pool.contextFor("default", "agent-a");
     const second = pool.contextFor("default", "agent-b");