Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

Refine collaborative browser preview

Julius Marminge6c6740e381aa
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index f26f2cd1a..0d18b4c71 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -21,6 +21,7 @@
"effect": "catalog:",
"electron": "41.5.0",
"electron-updater": "^6.6.2",
+ "playwright-core": "1.60.0",
"react-grab": "^0.1.32"
},
"devDependencies": {
diff --git a/apps/desktop/src/ipc/channels.ts b/apps/desktop/src/ipc/channels.ts
index 11832664d..fe7b5b6f8 100644
--- a/apps/desktop/src/ipc/channels.ts
+++ b/apps/desktop/src/ipc/channels.ts
@@ -56,6 +56,7 @@ export const PREVIEW_CLEAR_CACHE_CHANNEL = "desktop:preview-clear-cache";
export const PREVIEW_GET_CONFIG_CHANNEL = "desktop:preview-get-config";
export const PREVIEW_PICK_ELEMENT_CHANNEL = "desktop:preview-pick-element";
export const PREVIEW_CANCEL_PICK_ELEMENT_CHANNEL = "desktop:preview-cancel-pick-element";
+export const PREVIEW_CAPTURE_SCREENSHOT_CHANNEL = "desktop:preview-capture-screenshot";
export const PREVIEW_AUTOMATION_STATUS_CHANNEL = "desktop:preview-automation-status";
export const PREVIEW_AUTOMATION_SNAPSHOT_CHANNEL = "desktop:preview-automation-snapshot";
export const PREVIEW_AUTOMATION_CLICK_CHANNEL = "desktop:preview-automation-click";
@@ -64,4 +65,8 @@ export const PREVIEW_AUTOMATION_PRESS_CHANNEL = "desktop:preview-automation-pres
export const PREVIEW_AUTOMATION_SCROLL_CHANNEL = "desktop:preview-automation-scroll";
export const PREVIEW_AUTOMATION_EVALUATE_CHANNEL = "desktop:preview-automation-evaluate";
export const PREVIEW_AUTOMATION_WAIT_FOR_CHANNEL = "desktop:preview-automation-wait-for";
+export const PREVIEW_RECORDING_START_CHANNEL = "desktop:preview-recording-start";
+export const PREVIEW_RECORDING_STOP_CHANNEL = "desktop:preview-recording-stop";
+export const PREVIEW_RECORDING_SAVE_CHANNEL = "desktop:preview-recording-save";
+export const PREVIEW_RECORDING_FRAME_CHANNEL = "desktop:preview-recording-frame";
export const PREVIEW_STATE_CHANGE_CHANNEL = "desktop:preview-state-change";
diff --git a/apps/desktop/src/ipc/methods/preview.ts b/apps/desktop/src/ipc/methods/preview.ts
index 904cef30b..8683cd9d0 100644
--- a/apps/desktop/src/ipc/methods/preview.ts
+++ b/apps/desktop/src/ipc/methods/preview.ts
@@ -17,6 +17,14 @@ previewViewManager.onStateChange((tabId, state) => {
}
});
+previewViewManager.onRecordingFrame((frame) => {
+ for (const window of BrowserWindow.getAllWindows()) {
+ if (!window.isDestroyed()) {
+ window.webContents.send(IpcChannels.PREVIEW_RECORDING_FRAME_CHANNEL, frame);
+ }
+ }
+});
+
const tabIdFrom = (raw: unknown): string => {
if (typeof raw !== "object" || raw === null || !("tabId" in raw)) {
throw new Error("preview tab id is required");
@@ -95,10 +103,16 @@ export const previewMethods = [
),
method(IpcChannels.PREVIEW_CLEAR_COOKIES_CHANNEL, () => previewViewManager.clearCookies()),
method(IpcChannels.PREVIEW_CLEAR_CACHE_CHANNEL, () => previewViewManager.clearCache()),
- method(IpcChannels.PREVIEW_GET_CONFIG_CHANNEL, () => {
+ method(IpcChannels.PREVIEW_GET_CONFIG_CHANNEL, (raw) => {
+ const environmentId =
+ typeof raw === "object" && raw !== null && "environmentId" in raw ? raw.environmentId : null;
+ if (typeof environmentId !== "string" || environmentId.length === 0) {
+ throw new Error("preview environment id is required");
+ }
+ previewViewManager.getBrowserSession(environmentId);
const preloadPath = `${__dirname}/preview-pick-preload.cjs`;
return {
- partition: previewViewManager.getBrowserPartition(),
+ partition: previewViewManager.getBrowserPartition(environmentId),
webPreferences: PREVIEW_WEBVIEW_PREFERENCES,
preloadUrl: pathToFileURL(preloadPath).href,
};
@@ -109,6 +123,9 @@ export const previewMethods = [
method(IpcChannels.PREVIEW_CANCEL_PICK_ELEMENT_CHANNEL, (raw) =>
previewViewManager.cancelPickElement(tabIdFrom(raw)),
),
+ method(IpcChannels.PREVIEW_CAPTURE_SCREENSHOT_CHANNEL, (raw) =>
+ previewViewManager.captureScreenshot(tabIdFrom(raw)),
+ ),
method(IpcChannels.PREVIEW_AUTOMATION_STATUS_CHANNEL, (raw) =>
previewViewManager.automationStatus(tabIdFrom(raw)),
),
@@ -151,4 +168,20 @@ export const previewMethods = [
inputFrom(raw) as Parameters<typeof previewViewManager.automationWaitFor>[1],
),
),
+ method(IpcChannels.PREVIEW_RECORDING_START_CHANNEL, (raw) =>
+ previewViewManager.startRecording(tabIdFrom(raw)),
+ ),
+ method(IpcChannels.PREVIEW_RECORDING_STOP_CHANNEL, (raw) =>
+ previewViewManager.stopRecording(tabIdFrom(raw)),
+ ),
+ method(IpcChannels.PREVIEW_RECORDING_SAVE_CHANNEL, (raw) => {
+ const tabId = tabIdFrom(raw);
+ if (typeof raw !== "object" || raw === null) throw new Error("recording payload is required");
+ const mimeType = "mimeType" in raw ? raw.mimeType : null;
+ const data = "data" in raw ? raw.data : null;
+ if (typeof mimeType !== "string" || !(data instanceof Uint8Array)) {
+ throw new Error("recording mimeType and bytes are required");
+ }
+ return previewViewManager.saveRecording(tabId, mimeType, data);
+ }),
] as const;
diff --git a/apps/desktop/src/playwright-injected-runtime.test.ts b/apps/desktop/src/playwright-injected-runtime.test.ts
new file mode 100644
index 000000000..206920636
--- /dev/null
+++ b/apps/desktop/src/playwright-injected-runtime.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vite-plus/test";
+
+import {
+ playwrightInjectedRuntimeInstallExpression,
+ playwrightInjectedRuntimeSource,
+} from "./playwright-injected-runtime.ts";
+
+describe("playwright injected runtime", () => {
+ it("extracts the pinned runtime from playwright-core", async () => {
+ const source = await playwrightInjectedRuntimeSource();
+ expect(source.length).toBeGreaterThan(100_000);
+ expect(source).toContain("InjectedScript");
+ });
+
+ it("builds an idempotent install expression", async () => {
+ const expression = await playwrightInjectedRuntimeInstallExpression();
+ expect(expression).toContain("__t3PlaywrightInjected");
+ expect(expression).toContain('testIdAttributeName":"data-testid');
+ });
+});
diff --git a/apps/desktop/src/playwright-injected-runtime.ts b/apps/desktop/src/playwright-injected-runtime.ts
new file mode 100644
index 000000000..d4d7c6bd9
--- /dev/null
+++ b/apps/desktop/src/playwright-injected-runtime.ts
@@ -0,0 +1,49 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { runInNewContext } from "node:vm";
+
+const require = createRequire(import.meta.url);
+let sourcePromise: Promise<string> | null = null;
+
+export const playwrightInjectedRuntimeSource = (): Promise<string> => {
+ sourcePromise ??= (async () => {
+ const packageJsonPath = require.resolve("playwright-core/package.json");
+ const coreBundle = await readFile(join(dirname(packageJsonPath), "lib/coreBundle.js"), "utf8");
+ const marker = "source3 = ";
+ const start = coreBundle.indexOf(marker);
+ if (start < 0) throw new Error("Playwright injected runtime marker was not found.");
+ const literalStart = start + marker.length;
+ const literalEnd = coreBundle.indexOf(";\n }\n});", literalStart);
+ if (literalEnd < 0) throw new Error("Playwright injected runtime terminator was not found.");
+ const literal = coreBundle.slice(literalStart, literalEnd);
+ const source = runInNewContext(literal, Object.create(null), { timeout: 1_000 });
+ if (typeof source !== "string" || source.length < 100_000) {
+ throw new Error("Playwright injected runtime extraction returned invalid source.");
+ }
+ return source;
+ })();
+ return sourcePromise;
+};
+
+export const playwrightInjectedRuntimeInstallExpression = async (): Promise<string> => {
+ const source = await playwrightInjectedRuntimeSource();
+ const options = {
+ isUnderTest: false,
+ sdkLanguage: "javascript",
+ testIdAttributeName: "data-testid",
+ stableRafCount: 1,
+ browserName: "chromium",
+ shouldPrependErrorPrefix: false,
+ isUtilityWorld: false,
+ customEngines: [],
+ };
+ return `(() => {
+ if (globalThis.__t3PlaywrightInjected) return true;
+ const module = { exports: {} };
+ ${source}
+ globalThis.__t3PlaywrightInjected = new (module.exports.InjectedScript())(globalThis, ${JSON.stringify(options)});
+ return true;
+ })()`;
+};
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index 8f890c27e..8326673a8 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -1,4 +1,8 @@
-import type { DesktopBridge, DesktopPreviewTabState } from "@t3tools/contracts";
+import type {
+ DesktopBridge,
+ DesktopPreviewRecordingFrame,
+ DesktopPreviewTabState,
+} from "@t3tools/contracts";
import { contextBridge, ipcRenderer } from "electron";
import * as IpcChannels from "./ipc/channels.ts";
@@ -159,10 +163,34 @@ contextBridge.exposeInMainWorld("desktopBridge", {
ipcRenderer.invoke(IpcChannels.PREVIEW_OPEN_DEVTOOLS_CHANNEL, { tabId }),
clearCookies: () => ipcRenderer.invoke(IpcChannels.PREVIEW_CLEAR_COOKIES_CHANNEL),
clearCache: () => ipcRenderer.invoke(IpcChannels.PREVIEW_CLEAR_CACHE_CHANNEL),
- getPreviewConfig: () => ipcRenderer.invoke(IpcChannels.PREVIEW_GET_CONFIG_CHANNEL),
+ getPreviewConfig: (environmentId) =>
+ ipcRenderer.invoke(IpcChannels.PREVIEW_GET_CONFIG_CHANNEL, { environmentId }),
pickElement: (tabId) => ipcRenderer.invoke(IpcChannels.PREVIEW_PICK_ELEMENT_CHANNEL, { tabId }),
cancelPickElement: (tabId) =>
ipcRenderer.invoke(IpcChannels.PREVIEW_CANCEL_PICK_ELEMENT_CHANNEL, { tabId }),
+ captureScreenshot: (tabId) =>
+ ipcRenderer.invoke(IpcChannels.PREVIEW_CAPTURE_SCREENSHOT_CHANNEL, { tabId }),
+ recording: {
+ startScreencast: (tabId) =>
+ ipcRenderer.invoke(IpcChannels.PREVIEW_RECORDING_START_CHANNEL, { tabId }),
+ stopScreencast: (tabId) =>
+ ipcRenderer.invoke(IpcChannels.PREVIEW_RECORDING_STOP_CHANNEL, { tabId }),
+ save: (tabId, mimeType, data) =>
+ ipcRenderer.invoke(IpcChannels.PREVIEW_RECORDING_SAVE_CHANNEL, {
+ tabId,
+ mimeType,
+ data,
+ }),
+ onFrame: (listener) => {
+ const wrappedListener = (_event: Electron.IpcRendererEvent, frame: unknown) => {
+ if (typeof frame !== "object" || frame === null) return;
+ listener(frame as DesktopPreviewRecordingFrame);
+ };
+ ipcRenderer.on(IpcChannels.PREVIEW_RECORDING_FRAME_CHANNEL, wrappedListener);
+ return () =>
+ ipcRenderer.removeListener(IpcChannels.PREVIEW_RECORDING_FRAME_CHANNEL, wrappedListener);
+ },
+ },
automation: {
status: (tabId) =>
ipcRenderer.invoke(IpcChannels.PREVIEW_AUTOMATION_STATUS_CHANNEL, { tabId }),
diff --git a/apps/desktop/src/preview-pick-preload.ts b/apps/desktop/src/preview-pick-preload.ts
index be4df208e..7ca1da41b 100644
--- a/apps/desktop/src/preview-pick-preload.ts
+++ b/apps/desktop/src/preview-pick-preload.ts
@@ -16,6 +16,7 @@ const START_PICK_CHANNEL = "preview:start-pick";
const CANCEL_PICK_CHANNEL = "preview:cancel-pick";
const ELEMENT_PICKED_CHANNEL = "preview:element-picked";
const ANNOTATION_CAPTURED_CHANNEL = "preview:annotation-captured";
+const HUMAN_INPUT_CHANNEL = "preview:human-input";
const OVERLAY_ATTRIBUTE = "data-t3code-annotation-ui";
const Z_INDEX_OVERLAY = 2147483646;
const ACCENT = "#7c3aed";
@@ -42,6 +43,13 @@ interface AnnotationSession {
let activeSession: AnnotationSession | null = null;
let idSequence = 0;
+const reportHumanInput = (event: Event): void => {
+ if (event.isTrusted) ipcRenderer.send(HUMAN_INPUT_CHANNEL);
+};
+
+window.addEventListener("pointerdown", reportHumanInput, true);
+window.addEventListener("keydown", reportHumanInput, true);
+
const nextId = (prefix: string): string => {
idSequence += 1;
return `${prefix}_${idSequence.toString(36)}`;
diff --git a/apps/desktop/src/preview-view-manager.test.ts b/apps/desktop/src/preview-view-manager.test.ts
index 54d33a856..c704ae663 100644
--- a/apps/desktop/src/preview-view-manager.test.ts
+++ b/apps/desktop/src/preview-view-manager.test.ts
@@ -1,8 +1,15 @@
import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
const fromId = vi.fn(() => null);
+const mkdir = vi.fn(async () => undefined);
+const writeFile = vi.fn(async () => undefined);
+
+vi.mock("node:fs/promises", () => ({ mkdir, writeFile }));
vi.mock("electron", () => ({
+ app: {
+ getPath: vi.fn(() => "/tmp/t3-code-test"),
+ },
session: {
fromPartition: vi.fn(),
},
@@ -14,6 +21,8 @@ vi.mock("electron", () => ({
describe("PreviewViewManager automation status", () => {
beforeEach(() => {
fromId.mockClear();
+ mkdir.mockClear();
+ writeFile.mockClear();
});
it("reports an unregistered webview as temporarily unavailable", async () => {
@@ -41,4 +50,53 @@ describe("PreviewViewManager automation status", () => {
});
expect(fromId).not.toHaveBeenCalled();
});
+
+ it("captures a PNG screenshot into browser artifacts", async () => {
+ const png = Buffer.from("preview-png");
+ const capturePage = vi.fn(async () => ({ toPNG: () => png }));
+ const listeners = new Map<string, (...args: never[]) => void>();
+ fromId.mockReturnValue({
+ id: 42,
+ isDestroyed: () => false,
+ getType: () => "webview",
+ getURL: () => "https://example.com/",
+ getTitle: () => "Example",
+ isLoading: () => false,
+ getZoomFactor: () => 1,
+ setZoomFactor: vi.fn(),
+ on: vi.fn((event: string, listener: (...args: never[]) => void) => {
+ listeners.set(event, listener);
+ }),
+ off: vi.fn(),
+ ipc: { on: vi.fn(), off: vi.fn() },
+ navigationHistory: { canGoBack: () => false, canGoForward: () => false },
+ setWindowOpenHandler: vi.fn(),
+ debugger: {
+ isAttached: () => false,
+ attach: vi.fn(),
+ sendCommand: vi.fn(async () => undefined),
+ on: vi.fn(),
+ off: vi.fn(),
+ },
+ capturePage,
+ } as never);
+ const { PreviewViewManager } = await import("./preview-view-manager.ts");
+ const manager = new PreviewViewManager();
+ manager.createTab("tab_1");
+ manager.registerWebview("tab_1", 42);
+
+ const artifact = await manager.captureScreenshot("tab_1");
+
+ expect(capturePage).toHaveBeenCalledOnce();
+ expect(mkdir).toHaveBeenCalledWith("/tmp/t3-code-test/browser-artifacts", {
+ recursive: true,
+ });
+ expect(writeFile).toHaveBeenCalledWith(artifact.path, png);
+ expect(artifact).toMatchObject({
+ tabId: "tab_1",
+ mimeType: "image/png",
+ sizeBytes: png.byteLength,
+ });
+ expect(artifact.path).toMatch(/\/browser-artifacts\/browser-screenshot-[^.]+\.png$/);
+ });
});
diff --git a/apps/desktop/src/preview-view-manager.ts b/apps/desktop/src/preview-view-manager.ts
index ce8f99645..d74033420 100644
--- a/apps/desktop/src/preview-view-manager.ts
+++ b/apps/desktop/src/preview-view-manager.ts
@@ -1,4 +1,5 @@
// @effect-diagnostics globalDate:off
+// @effect-diagnostics nodeBuiltinImport:off
/**
* PreviewViewManager — desktop side of the in-app browser preview.
*
@@ -9,9 +10,15 @@
import type {
PreviewAnnotationPayload,
PreviewAnnotationRect,
+ DesktopPreviewRecordingArtifact,
+ DesktopPreviewRecordingFrame,
+ DesktopPreviewScreenshotArtifact,
PreviewAutomationClickInput,
+ PreviewAutomationActionEvent,
+ PreviewAutomationConsoleEntry,
PreviewAutomationEvaluateInput,
PreviewAutomationPressInput,
+ PreviewAutomationNetworkEntry,
PreviewAutomationScrollInput,
PreviewAutomationSnapshot,
PreviewAutomationStatus,
@@ -19,16 +26,21 @@ import type {
PreviewAutomationWaitForInput,
} from "@t3tools/contracts";
import { normalizePreviewUrl } from "@t3tools/shared/preview";
-import { type BrowserWindow, type Session, session, webContents } from "electron";
+import { app, type BrowserWindow, type Session, session, webContents } from "electron";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
import { setTimeout as sleep } from "node:timers/promises";
import { isPreviewAnnotationPayload } from "./picked-element-payload.ts";
+import { playwrightInjectedRuntimeInstallExpression } from "./playwright-injected-runtime.ts";
-const PREVIEW_PARTITION = "persist:t3code-preview";
+const PREVIEW_PARTITION_PREFIX = "persist:t3code-preview-";
const START_PICK_CHANNEL = "preview:start-pick";
const CANCEL_PICK_CHANNEL = "preview:cancel-pick";
const ELEMENT_PICKED_CHANNEL = "preview:element-picked";
const ANNOTATION_CAPTURED_CHANNEL = "preview:annotation-captured";
+const HUMAN_INPUT_CHANNEL = "preview:human-input";
// Re-export the guest webview security posture from its dedicated module so
// the constant is unit-testable in isolation. See
@@ -55,6 +67,7 @@ export interface PreviewTabState {
canGoBack: boolean;
canGoForward: boolean;
zoomFactor: number;
+ controller: "human" | "agent" | "none";
updatedAt: string;
}
@@ -69,6 +82,7 @@ const MAX_EVALUATION_BYTES = 64_000;
const MAX_VISIBLE_TEXT_LENGTH = 20_000;
const MAX_INTERACTIVE_ELEMENTS = 200;
const MAX_SCREENSHOT_WIDTH = 1280;
+const DIAGNOSTIC_BUFFER_LIMIT = 200;
interface CdpEvaluationResult {
readonly result?: {
@@ -86,7 +100,8 @@ const automationError = (
| "PreviewAutomationExecutionError"
| "PreviewAutomationInvalidSelectorError"
| "PreviewAutomationResultTooLargeError"
- | "PreviewAutomationTimeoutError",
+ | "PreviewAutomationTimeoutError"
+ | "PreviewAutomationControlInterruptedError",
message: string,
detail?: unknown,
): Error & { detail?: unknown } => {
@@ -165,10 +180,12 @@ const nextZoomLevel = (current: number, direction: "in" | "out"): number => {
};
type Listener = (tabId: string, state: PreviewTabState) => void;
+type RecordingFrameListener = (frame: DesktopPreviewRecordingFrame) => void;
interface ManagedListeners {
navigate: () => void;
failed: (event: Event, code: number, description: string) => void;
+ humanInput: () => void;
}
interface PickSession {
@@ -176,6 +193,18 @@ interface PickSession {
readonly cleanup: () => void;
}
+interface BrowserControlSession {
+ readonly webContentsId: number;
+ tail: Promise<void>;
+ initialized: Promise<void>;
+}
+
+interface BrowserDiagnostics {
+ readonly consoleEntries: PreviewAutomationConsoleEntry[];
+ readonly networkEntries: PreviewAutomationNetworkEntry[];
+ readonly requests: Map<string, { url: string; method: string }>;
+}
+
const APP_FORWARDED_SHORTCUTS: ReadonlyArray<{
key: string;
meta: boolean;
@@ -196,17 +225,30 @@ export class PreviewViewManager {
private mainWindow: BrowserWindow | null = null;
private readonly tabs = new Map<string, PreviewTabState>();
private readonly attached = new Map<number, ManagedListeners>();
- private browserSession: Session | null = null;
+ private readonly browserSessions = new Map<string, Session>();
private readonly listeners = new Set<Listener>();
+ private readonly recordingFrameListeners = new Set<RecordingFrameListener>();
/** In-flight preview annotation sessions, keyed by tabId. */
private readonly pickSessions = new Map<string, PickSession>();
+ /** One long-lived CDP attachment and serialized command queue per guest. */
+ private readonly controlSessions = new Map<number, BrowserControlSession>();
+ private readonly diagnostics = new Map<number, BrowserDiagnostics>();
+ private readonly controlEpoch = new Map<string, number>();
+ private readonly actionTimeline = new Map<string, PreviewAutomationActionEvent[]>();
+ private actionSequence = 0;
+ private recordingTabId: string | null = null;
setMainWindow(window: BrowserWindow): void {
this.mainWindow = window;
}
- getBrowserPartition(): string {
- return PREVIEW_PARTITION;
+ getBrowserPartition(scope = "shared"): string {
+ const digest = createHash("sha256").update(scope).digest("hex").slice(0, 20);
+ return `${PREVIEW_PARTITION_PREFIX}${digest}`;
+ }
+
+ isBrowserPartition(partition: string): boolean {
+ return partition.startsWith(PREVIEW_PARTITION_PREFIX);
}
/**
@@ -219,9 +261,11 @@ export class PreviewViewManager {
return PREVIEW_WEBVIEW_PREFERENCES;
}
- getBrowserSession(): Session {
- if (this.browserSession) return this.browserSession;
- const sess = session.fromPartition(PREVIEW_PARTITION);
+ getBrowserSession(scope = "shared"): Session {
+ const partition = this.getBrowserPartition(scope);
+ const existing = this.browserSessions.get(partition);
+ if (existing) return existing;
+ const sess = session.fromPartition(partition);
const ua = sess
.getUserAgent()
.replace(/Electron\/[\d.]+ /, "")
@@ -231,7 +275,7 @@ export class PreviewViewManager {
const allow = ["clipboard-read", "clipboard-write", "notifications", "geolocation"];
callback(allow.includes(perm));
});
- this.browserSession = sess;
+ this.browserSessions.set(partition, sess);
return sess;
}
@@ -245,6 +289,7 @@ export class PreviewViewManager {
canGoBack: false,
canGoForward: false,
zoomFactor: DEFAULT_ZOOM_FACTOR,
+ controller: "none",
updatedAt: new Date().toISOString(),
};
this.tabs.set(tabId, initial);
@@ -257,6 +302,7 @@ export class PreviewViewManager {
if (!tab) return;
this.cancelPickElement(tabId);
if (tab.webContentsId != null) {
+ this.detachControlSession(tab.webContentsId);
this.detachListeners(tab.webContentsId);
}
const closed: PreviewTabState = {
@@ -266,6 +312,7 @@ export class PreviewViewManager {
canGoBack: false,
canGoForward: false,
zoomFactor: DEFAULT_ZOOM_FACTOR,
+ controller: "none",
updatedAt: new Date().toISOString(),
};
this.tabs.delete(tabId);
@@ -294,6 +341,7 @@ export class PreviewViewManager {
return;
}
if (tab.webContentsId != null && tab.webContentsId !== webContentsId) {
+ this.detachControlSession(tab.webContentsId);
this.detachListeners(tab.webContentsId);
// Any in-flight pick is bound to the OLD WebContents via `wc.ipc.on`.
// Cancel it so the toggle button doesn't get stuck pressed waiting
@@ -301,6 +349,7 @@ export class PreviewViewManager {
this.cancelPickElement(tabId);
}
this.attachListeners(tabId, wc);
+ void this.ensureControlSession(wc).catch(() => undefined);
// Restore the persisted zoom factor onto the freshly-attached WebContents
// so a thread-switch + remount lands the user back where they were.
if (Math.abs(tab.zoomFactor - DEFAULT_ZOOM_FACTOR) > ZOOM_EPSILON) {
@@ -364,6 +413,10 @@ export class PreviewViewManager {
wc.devToolsWebContents?.focus();
return;
}
+ this.detachControlSession(wc.id);
+ wc.once("devtools-closed", () => {
+ if (!wc.isDestroyed()) void this.ensureControlSession(wc).catch(() => undefined);
+ });
wc.openDevTools({ mode: "detach" });
}
@@ -372,16 +425,18 @@ export class PreviewViewManager {
* preview tab since they all share `persist:t3code-preview`.
*/
async clearCookies(): Promise<void> {
- const sess = this.getBrowserSession();
- await sess.clearStorageData({
- storages: ["cookies", "localstorage", "indexdb", "websql", "serviceworkers"],
- });
+ await Promise.all(
+ [...this.browserSessions.values()].map((sess) =>
+ sess.clearStorageData({
+ storages: ["cookies", "localstorage", "indexdb", "websql", "serviceworkers"],
+ }),
+ ),
+ );
}
/** Drop the HTTP cache for the preview partition. */
async clearCache(): Promise<void> {
- const sess = this.getBrowserSession();
- await sess.clearCache();
+ await Promise.all([...this.browserSessions.values()].map((sess) => sess.clearCache()));
}
/**
@@ -485,6 +540,65 @@ export class PreviewViewManager {
session.resolve(null);
}
+ async startRecording(tabId: string): Promise<void> {
+ if (this.recordingTabId && this.recordingTabId !== tabId) {
+ throw new Error("Only one browser recording can be active per window.");
+ }
+ const wc = this.requireWebContents(tabId);
+ await this.withControlSession(tabId, wc, "recording.start", async (send) => {
+ await send("Page.enable");
+ await send("Page.startScreencast", {
+ format: "jpeg",
+ quality: 80,
+ maxWidth: 1600,
+ maxHeight: 1200,
+ everyNthFrame: 1,
+ });
+ });
+ this.recordingTabId = tabId;
+ }
+
+ async captureScreenshot(tabId: string): Promise<DesktopPreviewScreenshotArtifact> {
+ const wc = this.requireWebContents(tabId);
+ const createdAt = new Date().toISOString();
+ const id = `browser-screenshot-${Date.now().toString(36)}`;
+ const directory = join(app.getPath("userData"), "browser-artifacts");
+ const path = join(directory, `${id}.png`);
+ const data = (await wc.capturePage()).toPNG();
+ await mkdir(directory, { recursive: true });
+ await writeFile(path, data);
+ return { id, tabId, path, mimeType: "image/png", sizeBytes: data.byteLength, createdAt };
+ }
+
+ async stopRecording(tabId: string): Promise<void> {
+ if (this.recordingTabId !== tabId) return;
+ const wc = this.requireWebContents(tabId);
+ await this.withControlSession(tabId, wc, "recording.stop", async (send) => {
+ await send("Page.stopScreencast");
+ });
+ this.recordingTabId = null;
+ }
+
+ async saveRecording(
+ tabId: string,
+ mimeType: string,
+ data: Uint8Array,
+ ): Promise<DesktopPreviewRecordingArtifact> {
+ const createdAt = new Date().toISOString();
+ const id = `browser-recording-${Date.now().toString(36)}`;
+ const extension = mimeType.includes("mp4") ? "mp4" : "webm";
+ const directory = join(app.getPath("userData"), "browser-artifacts");
+ const path = join(directory, `${id}.${extension}`);
+ await mkdir(directory, { recursive: true });
+ await writeFile(path, data);
+ return { id, tabId, path, mimeType, sizeBytes: data.byteLength, createdAt };
+ }
+
+ onRecordingFrame(listener: RecordingFrameListener): () => void {
+ this.recordingFrameListeners.add(listener);
+ return () => this.recordingFrameListeners.delete(listener);
+ }
+
zoomIn(tabId: string): void {
this.applyZoom(tabId, (current) => nextZoomLevel(current, "in"));
}
@@ -533,7 +647,7 @@ export class PreviewViewManager {
async automationSnapshot(tabId: string): Promise<PreviewAutomationSnapshot> {
const wc = this.requireWebContents(tabId);
- return this.withDebugger(wc, async (send) => {
+ return this.withControlSession(tabId, wc, "snapshot", async (send) => {
await Promise.all([send("Runtime.enable"), send("Accessibility.enable")]);
const page = await this.evaluateWithDebugger<{
url: string;
@@ -604,6 +718,9 @@ export class PreviewViewManager {
return {
...page,
accessibilityTree: accessibility,
+ consoleEntries: [...(this.diagnostics.get(wc.id)?.consoleEntries ?? [])],
+ networkEntries: [...(this.diagnostics.get(wc.id)?.networkEntries ?? [])],
+ actionTimeline: [...(this.actionTimeline.get(tabId) ?? [])],
screenshot: {
mimeType: "image/png",
data: image.toPNG().toString("base64"),
@@ -616,22 +733,29 @@ export class PreviewViewManager {
async automationClick(tabId: string, input: PreviewAutomationClickInput): Promise<void> {
const wc = this.requireWebContents(tabId);
- await this.withDebugger(wc, async (send) => {
+ await this.withControlSession(tabId, wc, "click", async (send) => {
await Promise.all([
send("Runtime.enable"),
send("Input.setIgnoreInputEvents", { ignore: false }),
]);
let x: number;
let y: number;
- if ("selector" in input) {
+ if ("selector" in input || "locator" in input) {
+ await this.ensurePlaywrightInjected(send);
+ const locator = this.automationLocator(input);
const point = await this.evaluateWithDebugger<
{ x: number; y: number } | { invalidSelector: true; message: string } | { notFound: true }
>(
send,
`(() => {
try {
- const element = document.querySelector(${JSON.stringify(input.selector)});
+ const injected = globalThis.__t3PlaywrightInjected;
+ const parsed = injected.parseSelector(${JSON.stringify(locator)});
+ const element = injected.querySelector(parsed, document, true);
if (!element) return { notFound: true };
+ const visible = injected.elementState(element, "visible");
+ const enabled = injected.elementState(element, "enabled");
+ if (!visible.matches || !enabled.matches) return { notFound: true };
element.scrollIntoView({ block: "center", inline: "center" });
const rect = element.getBoundingClientRect();
return { x: rect.left + rect.width / 2, y: rect.top + rect.height / 2 };
@@ -643,20 +767,20 @@ export class PreviewViewManager {
);
if ("invalidSelector" in point) {
throw automationError("PreviewAutomationInvalidSelectorError", point.message, {
- selector: input.selector,
+ selector: locator,
});
}
if ("notFound" in point) {
throw automationError(
"PreviewAutomationExecutionError",
- `No element matches selector ${input.selector}.`,
+ `No element matches locator ${locator}.`,
);
}
x = point.x;
y = point.y;
} else {
- x = input.x;
- y = input.y;
+ x = input.x!;
+ y = input.y!;
}
const viewport = await this.evaluateWithDebugger<{ width: number; height: number }>(
send,
@@ -688,19 +812,17 @@ export class PreviewViewManager {
async automationType(tabId: string, input: PreviewAutomationTypeInput): Promise<void> {
const wc = this.requireWebContents(tabId);
- await this.withDebugger(wc, async (send) => {
+ await this.withControlSession(tabId, wc, "type", async (send) => {
await send("Runtime.enable");
+ const locator = this.automationLocator(input);
+ if (locator) await this.ensurePlaywrightInjected(send);
const focusResult = await this.evaluateWithDebugger<
{ ok: true } | { invalidSelector: true; message: string } | { notFound: true }
>(
send,
`(() => {
try {
- const element = ${
- input.selector
- ? `document.querySelector(${JSON.stringify(input.selector)})`
- : "document.activeElement"
- };
+ const element = ${locator ? `(() => { const injected = globalThis.__t3PlaywrightInjected; return injected.querySelector(injected.parseSelector(${JSON.stringify(locator)}), document, true); })()` : "document.activeElement"};
if (!element) return { notFound: true };
element.focus();
if (${input.clear ?? false}) {
@@ -723,8 +845,8 @@ export class PreviewViewManager {
if ("notFound" in focusResult) {
throw automationError(
"PreviewAutomationExecutionError",
- input.selector
- ? `No element matches selector ${input.selector}.`
+ locator
+ ? `No element matches locator ${locator}.`
: "No element is focused in the preview.",
);
}
@@ -743,7 +865,7 @@ export class PreviewViewManager {
async automationPress(tabId: string, input: PreviewAutomationPressInput): Promise<void> {
const wc = this.requireWebContents(tabId);
- await this.withDebugger(wc, async (send) => {
+ await this.withControlSession(tabId, wc, "press", async (send) => {
const modifiers = (input.modifiers ?? []).reduce((value, modifier) => {
switch (modifier) {
case "Alt":
@@ -771,19 +893,17 @@ export class PreviewViewManager {
async automationScroll(tabId: string, input: PreviewAutomationScrollInput): Promise<void> {
const wc = this.requireWebContents(tabId);
- await this.withDebugger(wc, async (send) => {
+ await this.withControlSession(tabId, wc, "scroll", async (send) => {
await send("Runtime.enable");
+ const locator = this.automationLocator(input);
+ if (locator) await this.ensurePlaywrightInjected(send);
const result = await this.evaluateWithDebugger<
{ ok: true } | { invalidSelector: true; message: string } | { notFound: true }
>(
send,
`(() => {
try {
- const target = ${
- input.selector
- ? `document.querySelector(${JSON.stringify(input.selector)})`
- : "window"
- };
+ const target = ${locator ? `(() => { const injected = globalThis.__t3PlaywrightInjected; return injected.querySelector(injected.parseSelector(${JSON.stringify(locator)}), document, true); })()` : "window"};
if (!target) return { notFound: true };
target.scrollBy({ left: ${input.deltaX ?? 0}, top: ${input.deltaY ?? 0}, behavior: "instant" });
return { ok: true };
@@ -801,7 +921,7 @@ export class PreviewViewManager {
if ("notFound" in result) {
throw automationError(
"PreviewAutomationExecutionError",
- `No element matches selector ${input.selector}.`,
+ `No element matches locator ${locator}.`,
);
}
});
@@ -809,7 +929,7 @@ export class PreviewViewManager {
async automationEvaluate(tabId: string, input: PreviewAutomationEvaluateInput): Promise<unknown> {
const wc = this.requireWebContents(tabId);
- return this.withDebugger(wc, async (send) => {
+ return this.withControlSession(tabId, wc, "evaluate", async (send) => {
await send("Runtime.enable");
const value = await this.evaluateWithDebugger(
send,
@@ -835,8 +955,10 @@ export class PreviewViewManager {
async automationWaitFor(tabId: string, input: PreviewAutomationWaitForInput): Promise<void> {
const wc = this.requireWebContents(tabId);
const timeoutMs = input.timeoutMs ?? 15_000;
- await this.withDebugger(wc, async (send) => {
+ await this.withControlSession(tabId, wc, "waitFor", async (send) => {
await send("Runtime.enable");
+ const locator = this.automationLocator(input);
+ if (locator) await this.ensurePlaywrightInjected(send);
const deadline = Date.now() + timeoutMs;
while (Date.now() <= deadline) {
const result = await this.evaluateWithDebugger<
@@ -845,11 +967,7 @@ export class PreviewViewManager {
send,
`(() => {
try {
- const selectorMatched = ${
- input.selector
- ? `document.querySelector(${JSON.stringify(input.selector)}) !== null`
- : "true"
- };
+ const selectorMatched = ${locator ? `(() => { const injected = globalThis.__t3PlaywrightInjected; return injected.querySelector(injected.parseSelector(${JSON.stringify(locator)}), document, false) !== null; })()` : "true"};
const textMatched = ${
input.text
? `(document.body?.innerText || "").includes(${JSON.stringify(input.text)})`
@@ -896,36 +1014,282 @@ export class PreviewViewManager {
this.update(tabId, { zoomFactor: next });
}
- private async withDebugger<A>(
+ private async withControlSession<A>(
+ tabId: string,
wc: Electron.WebContents,
+ action: string,
use: (
send: (method: string, commandParams?: Record<string, unknown>) => Promise<unknown>,
) => Promise<A>,
): Promise<A> {
- if (wc.debugger.isAttached()) {
- throw automationError(
- "PreviewAutomationExecutionError",
- "Preview automation is unavailable while another debugger is attached.",
- );
- }
- wc.debugger.attach("1.3");
+ const actionEvent: PreviewAutomationActionEvent = {
+ id: `browser-action-${Date.now().toString(36)}-${(this.actionSequence++).toString(36)}`,
+ action,
+ status: "running",
+ startedAt: new Date().toISOString(),
+ };
+ this.pushAction(tabId, actionEvent);
+ const epoch = this.controlEpoch.get(tabId) ?? 0;
+ const control = await this.ensureControlSession(wc);
+ let resolveTail: () => void = () => undefined;
+ const previous = control.tail;
+ control.tail = new Promise<void>((resolve) => {
+ resolveTail = resolve;
+ });
+ await previous;
+ this.update(tabId, { controller: "agent" });
try {
- return await use((method, commandParams) => wc.debugger.sendCommand(method, commandParams));
+ const send = async (method: string, commandParams?: Record<string, unknown>) => {
+ if ((this.controlEpoch.get(tabId) ?? 0) !== epoch) {
+ throw automationError(
+ "PreviewAutomationControlInterruptedError",
+ "Browser control was interrupted by human input.",
+ );
+ }
+ const result = await wc.debugger.sendCommand(method, commandParams);
+ if ((this.controlEpoch.get(tabId) ?? 0) !== epoch) {
+ throw automationError(
+ "PreviewAutomationControlInterruptedError",
+ "Browser control was interrupted by human input.",
+ );
+ }
+ return result;
+ };
+ const result = await use(send);
+ this.replaceAction(tabId, {
+ ...actionEvent,
+ status: "succeeded",
+ completedAt: new Date().toISOString(),
+ });
+ return result;
} catch (cause) {
+ const interrupted =
+ cause instanceof Error && cause.name === "PreviewAutomationControlInterruptedError";
+ this.replaceAction(tabId, {
+ ...actionEvent,
+ status: interrupted ? "interrupted" : "failed",
+ completedAt: new Date().toISOString(),
+ error: cause instanceof Error ? cause.message : String(cause),
+ });
if (cause instanceof Error && cause.name.startsWith("PreviewAutomation")) throw cause;
throw automationError(
"PreviewAutomationExecutionError",
cause instanceof Error ? cause.message : String(cause),
- cause,
+ { tabId, cause },
);
} finally {
- if (wc.debugger.isAttached()) {
- try {
- wc.debugger.detach();
- } catch {
- // The target can disappear while an operation is completing.
+ if (this.tabs.has(tabId)) this.update(tabId, { controller: "none" });
+ resolveTail();
+ }
+ }
+
+ private pushAction(tabId: string, event: PreviewAutomationActionEvent): void {
+ const timeline = this.actionTimeline.get(tabId) ?? [];
+ timeline.push(event);
+ if (timeline.length > 200) timeline.splice(0, timeline.length - 200);
+ this.actionTimeline.set(tabId, timeline);
+ }
+
+ private replaceAction(tabId: string, event: PreviewAutomationActionEvent): void {
+ const timeline = this.actionTimeline.get(tabId);
+ if (!timeline) return;
+ const index = timeline.findIndex((candidate) => candidate.id === event.id);
+ if (index >= 0) timeline[index] = event;
+ }
+
+ private async ensureControlSession(wc: Electron.WebContents): Promise<BrowserControlSession> {
+ const existing = this.controlSessions.get(wc.id);
+ if (existing) {
+ await existing.initialized;
+ return existing;
+ }
+ if (wc.isDevToolsOpened()) {
+ throw automationError(
+ "PreviewAutomationExecutionError",
+ "Close preview DevTools before using agent browser control.",
+ );
+ }
+ if (wc.debugger.isAttached()) {
+ throw automationError(
+ "PreviewAutomationExecutionError",
+ "Preview control cannot attach because another debugger owns this page.",
+ );
+ }
+ const control: BrowserControlSession = {
+ webContentsId: wc.id,
+ tail: Promise.resolve(),
+ initialized: Promise.resolve(),
+ };
+ const diagnostics: BrowserDiagnostics = {
+ consoleEntries: [],
+ networkEntries: [],
+ requests: new Map(),
+ };
+ this.diagnostics.set(wc.id, diagnostics);
+ wc.debugger.on("message", (_event, method, params) => {
+ if (method === "Page.screencastFrame") {
+ const frame = params as Record<string, unknown>;
+ const sessionId = frame["sessionId"];
+ if (typeof sessionId === "number") {
+ void wc.debugger
+ .sendCommand("Page.screencastFrameAck", { sessionId })
+ .catch(() => undefined);
+ }
+ const tabId = this.tabIdForWebContents(wc.id);
+ const metadata =
+ typeof frame["metadata"] === "object" && frame["metadata"] !== null
+ ? (frame["metadata"] as Record<string, unknown>)
+ : {};
+ if (tabId && typeof frame["data"] === "string") {
+ const payload: DesktopPreviewRecordingFrame = {
+ tabId,
+ data: frame["data"],
+ width: typeof metadata["deviceWidth"] === "number" ? metadata["deviceWidth"] : 0,
+ height: typeof metadata["deviceHeight"] === "number" ? metadata["deviceHeight"] : 0,
+ receivedAt: new Date().toISOString(),
+ };
+ for (const listener of this.recordingFrameListeners) listener(payload);
}
}
+ this.captureDiagnosticMessage(diagnostics, method, params as Record<string, unknown>);
+ });
+ control.initialized = (async () => {
+ wc.debugger.attach("1.3");
+ await Promise.all([
+ wc.debugger.sendCommand("Runtime.enable"),
+ wc.debugger.sendCommand("Accessibility.enable"),
+ wc.debugger.sendCommand("Network.enable"),
+ wc.debugger.sendCommand("Log.enable"),
+ ]);
+ })();
+ this.controlSessions.set(wc.id, control);
+ try {
+ await control.initialized;
+ return control;
+ } catch (cause) {
+ this.controlSessions.delete(wc.id);
+ throw cause;
+ }
+ }
+
+ private detachControlSession(webContentsId: number): void {
+ this.controlSessions.delete(webContentsId);
+ this.diagnostics.delete(webContentsId);
+ const wc = webContents.fromId(webContentsId);
+ if (!wc || wc.isDestroyed() || !wc.debugger.isAttached()) return;
+ try {
+ wc.debugger.detach();
+ } catch {
+ // Target teardown can race detachment.
+ }
+ }
+
+ private tabIdForWebContents(webContentsId: number): string | null {
+ for (const [tabId, tab] of this.tabs) {
+ if (tab.webContentsId === webContentsId) return tabId;
+ }
+ return null;
+ }
+
+ private captureDiagnosticMessage(
+ diagnostics: BrowserDiagnostics,
+ method: string,
+ params: Record<string, unknown>,
+ ): void {
+ const timestamp = new Date().toISOString();
+ if (method === "Runtime.consoleAPICalled") {
+ const args = Array.isArray(params["args"]) ? params["args"] : [];
+ const text = args
+ .map((arg) => {
+ if (typeof arg !== "object" || arg === null) return String(arg);
+ const value = arg as Record<string, unknown>;
+ return String(value["value"] ?? value["description"] ?? "");
+ })
+ .join(" ");
+ this.pushBounded(diagnostics.consoleEntries, {
+ level: typeof params["type"] === "string" ? params["type"] : "log",
+ text,
+ timestamp,
+ source: "console",
+ });
+ return;
+ }
+ if (method === "Runtime.exceptionThrown") {
+ const details =
+ typeof params["exceptionDetails"] === "object" && params["exceptionDetails"] !== null
+ ? (params["exceptionDetails"] as Record<string, unknown>)
+ : {};
+ this.pushBounded(diagnostics.consoleEntries, {
+ level: "error",
+ text: String(details["text"] ?? "Uncaught exception"),
+ timestamp,
+ source: "exception",
+ });
+ return;
+ }
+ if (method === "Log.entryAdded") {
+ const entry =
+ typeof params["entry"] === "object" && params["entry"] !== null
+ ? (params["entry"] as Record<string, unknown>)
+ : {};
+ this.pushBounded(diagnostics.consoleEntries, {
+ level: typeof entry["level"] === "string" ? entry["level"] : "info",
+ text: String(entry["text"] ?? ""),
+ timestamp,
+ source: typeof entry["source"] === "string" ? entry["source"] : "log",
+ });
+ return;
+ }
+ const requestId = typeof params["requestId"] === "string" ? params["requestId"] : null;
+ if (method === "Network.requestWillBeSent" && requestId) {
+ const request =
+ typeof params["request"] === "object" && params["request"] !== null
+ ? (params["request"] as Record<string, unknown>)
+ : {};
+ diagnostics.requests.set(requestId, {
+ url: String(request["url"] ?? ""),
+ method: String(request["method"] ?? "GET"),
+ });
+ return;
+ }
+ if (method === "Network.responseReceived" && requestId) {
+ const request = diagnostics.requests.get(requestId);
+ const response =
+ typeof params["response"] === "object" && params["response"] !== null
+ ? (params["response"] as Record<string, unknown>)
+ : {};
+ const status = typeof response["status"] === "number" ? response["status"] : null;
+ if (request && status !== null && status >= 400) {
+ this.pushBounded(diagnostics.networkEntries, {
+ ...request,
+ status,
+ failed: true,
+ timestamp,
+ });
+ }
+ return;
+ }
+ if (method === "Network.loadingFailed" && requestId) {
+ const request = diagnostics.requests.get(requestId);
+ if (request) {
+ this.pushBounded(diagnostics.networkEntries, {
+ ...request,
+ status: null,
+ failed: true,
+ errorText: String(params["errorText"] ?? "Network request failed"),
+ timestamp,
+ });
+ }
+ diagnostics.requests.delete(requestId);
+ return;
+ }
+ if (method === "Network.loadingFinished" && requestId) diagnostics.requests.delete(requestId);
+ }
+
+ private pushBounded<A>(buffer: A[], entry: A): void {
+ buffer.push(entry);
+ if (buffer.length > DIAGNOSTIC_BUFFER_LIMIT) {
+ buffer.splice(0, buffer.length - DIAGNOSTIC_BUFFER_LIMIT);
}
}
@@ -952,6 +1316,28 @@ export class PreviewViewManager {
return response.result?.value as A;
}
+ private automationLocator(input: {
+ readonly selector?: string | undefined;
+ readonly locator?: string | undefined;
+ }): string | null {
+ if (input.locator) return input.locator;
+ if (input.selector) return `css=${input.selector}`;
+ return null;
+ }
+
+ private async ensurePlaywrightInjected(
+ send: (method: string, commandParams?: Record<string, unknown>) => Promise<unknown>,
+ ): Promise<void> {
+ const installed = await this.evaluateWithDebugger<boolean>(
+ send,
+ "Boolean(globalThis.__t3PlaywrightInjected)",
+ true,
+ );
+ if (installed) return;
+ const expression = await playwrightInjectedRuntimeInstallExpression();
+ await this.evaluateWithDebugger(send, expression, true);
+ }
+
onStateChange(listener: Listener): () => void {
this.listeners.add(listener);
return () => {
@@ -964,6 +1350,7 @@ export class PreviewViewManager {
this.closeTab(tabId);
}
this.listeners.clear();
+ this.recordingFrameListeners.clear();
}
private attachListeners(tabId: string, wc: Electron.WebContents): void {
@@ -988,6 +1375,15 @@ export class PreviewViewManager {
},
});
};
+ const humanInput = (): void => {
+ this.controlEpoch.set(tabId, (this.controlEpoch.get(tabId) ?? 0) + 1);
+ this.update(tabId, { controller: "human" });
+ void sleep(750).then(() => {
+ if (this.tabs.get(tabId)?.controller === "human") {
+ this.update(tabId, { controller: "none" });
+ }
+ });
+ };
wc.on("did-navigate", sync);
wc.on("did-navigate-in-page", sync);
@@ -995,6 +1391,7 @@ export class PreviewViewManager {
wc.on("did-start-loading", sync);
wc.on("did-stop-loading", sync);
wc.on("did-fail-load", failed as never);
+ wc.ipc.on(HUMAN_INPUT_CHANNEL, humanInput);
// Keep external links inside the same view (matches ami's policy).
wc.setWindowOpenHandler(({ url }) => {
@@ -1020,7 +1417,7 @@ export class PreviewViewManager {
}
});
- this.attached.set(wc.id, { navigate: sync, failed });
+ this.attached.set(wc.id, { navigate: sync, failed, humanInput });
}
private detachListeners(webContentsId: number): void {
@@ -1035,6 +1432,7 @@ export class PreviewViewManager {
wc.off("did-start-loading", handlers.navigate);
wc.off("did-stop-loading", handlers.navigate);
wc.off("did-fail-load", handlers.failed as never);
+ wc.ipc.off(HUMAN_INPUT_CHANNEL, handlers.humanInput);
}
private isAppShortcut(input: Electron.Input): boolean {
diff --git a/apps/desktop/src/window/DesktopWindow.ts b/apps/desktop/src/window/DesktopWindow.ts
index 0450b413c..953c7a3ad 100644
--- a/apps/desktop/src/window/DesktopWindow.ts
+++ b/apps/desktop/src/window/DesktopWindow.ts
@@ -200,7 +200,10 @@ const make = Effect.gen(function* () {
previewViewManager.setMainWindow(window);
window.webContents.on("will-attach-webview", (event, webPreferences, params) => {
- if (params.partition !== previewViewManager.getBrowserPartition()) {
+ if (
+ typeof params.partition !== "string" ||
+ !previewViewManager.isBrowserPartition(params.partition)
+ ) {
event.preventDefault();
return;
}
diff --git a/apps/server/src/mcp/Layers/McpHttpServer.test.ts b/apps/server/src/mcp/Layers/McpHttpServer.test.ts
index 8d01277ce..908436341 100644
--- a/apps/server/src/mcp/Layers/McpHttpServer.test.ts
+++ b/apps/server/src/mcp/Layers/McpHttpServer.test.ts
@@ -65,6 +65,9 @@ it.effect("registers annotated tools and preserves authenticated request context
visibleText: "Example",
interactiveElements: [],
accessibilityTree: {},
+ consoleEntries: [],
+ networkEntries: [],
+ actionTimeline: [],
screenshot: {
mimeType: "image/png",
data: Buffer.from("png").toString("base64"),
@@ -96,6 +99,21 @@ it.effect("registers annotated tools and preserves authenticated request context
const statusTool = server.tools.find(({ tool }) => tool.name === "preview_status");
expect(statusTool?.tool.annotations?.readOnlyHint).toBe(true);
expect(statusTool?.tool.annotations?.idempotentHint).toBe(true);
+ expect(statusTool?.tool.annotations?.destructiveHint).toBe(false);
+
+ const snapshotTool = server.tools.find(({ tool }) => tool.name === "preview_snapshot");
+ expect(snapshotTool?.tool.annotations?.readOnlyHint).toBe(true);
+ expect(snapshotTool?.tool.annotations?.idempotentHint).toBe(true);
+ expect(snapshotTool?.tool.annotations?.openWorldHint).toBe(true);
+
+ const clickTool = server.tools.find(({ tool }) => tool.name === "preview_click");
+ expect(clickTool?.tool.annotations?.readOnlyHint).toBe(false);
+ expect(clickTool?.tool.annotations?.destructiveHint).toBe(true);
+ expect(clickTool?.tool.annotations?.openWorldHint).toBe(true);
+
+ const navigateTool = server.tools.find(({ tool }) => tool.name === "preview_navigate");
+ expect(navigateTool?.tool.annotations?.destructiveHint).toBe(false);
+ expect(navigateTool?.tool.annotations?.openWorldHint).toBe(true);
const status = yield* server
.callTool({ name: "preview_status", arguments: {} })
diff --git a/apps/server/src/mcp/Layers/PreviewAutomationBroker.test.ts b/apps/server/src/mcp/Layers/PreviewAutomationBroker.test.ts
index d3e43e4c5..7c97da39f 100644
--- a/apps/server/src/mcp/Layers/PreviewAutomationBroker.test.ts
+++ b/apps/server/src/mcp/Layers/PreviewAutomationBroker.test.ts
@@ -63,3 +63,27 @@ it.effect("rejects calls when no focused owner exists", () =>
expect(error).toBeInstanceOf(PreviewAutomationNoFocusedOwnerError);
}),
);
+
+it.effect("routes interactive commands to a hidden durable browser host", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const broker = makePreviewAutomationBroker();
+ const requests = yield* broker.connect("client-hidden");
+ yield* Stream.runForEach(requests, (request) =>
+ broker.respond({ requestId: request.requestId, ok: true }),
+ ).pipe(Effect.forkScoped);
+ yield* Effect.yieldNow;
+ yield* broker.reportOwner({
+ clientId: "client-hidden",
+ environmentId: scope.environmentId,
+ threadId: scope.threadId,
+ tabId: "tab-hidden",
+ visible: false,
+ supportsAutomation: true,
+ focusedAt: "2026-06-11T00:00:00.000Z",
+ });
+
+ yield* broker.invoke<void>({ scope, operation: "click", input: { x: 10, y: 10 } });
+ }),
+ ),
+);
diff --git a/apps/server/src/mcp/Layers/PreviewAutomationBroker.ts b/apps/server/src/mcp/Layers/PreviewAutomationBroker.ts
index 67d3a6ed5..d32523375 100644
--- a/apps/server/src/mcp/Layers/PreviewAutomationBroker.ts
+++ b/apps/server/src/mcp/Layers/PreviewAutomationBroker.ts
@@ -1,4 +1,5 @@
import {
+ PreviewAutomationControlInterruptedError,
PreviewAutomationExecutionError,
PreviewAutomationInvalidSelectorError,
PreviewAutomationNoFocusedOwnerError,
@@ -56,6 +57,8 @@ const makeResponseError = (
return new PreviewAutomationTabNotFoundError({ message: error.message });
case "PreviewAutomationTimeoutError":
return new PreviewAutomationTimeoutError({ message: error.message });
+ case "PreviewAutomationControlInterruptedError":
+ return new PreviewAutomationControlInterruptedError({ message: error.message });
case "PreviewAutomationInvalidSelectorError": {
const detail =
typeof error.detail === "object" && error.detail !== null ? error.detail : undefined;
@@ -193,20 +196,19 @@ export const makePreviewAutomationBroker = (): PreviewAutomationBrokerShape => {
(owner) =>
owner.environmentId === input.scope.environmentId &&
owner.threadId === input.scope.threadId &&
- owner.supportsAutomation &&
- (input.operation === "open" || input.operation === "status" || owner.visible),
+ owner.supportsAutomation,
)
.sort((left, right) => right.focusedAt.localeCompare(left.focusedAt));
const owner = candidates[0];
if (!owner) {
return yield* new PreviewAutomationNoFocusedOwnerError({
- message: "No focused desktop preview owner is available for this thread.",
+ message: "No desktop browser host is available for this thread.",
});
}
const connection = current.clients.get(owner.clientId);
if (!connection) {
return yield* new PreviewAutomationUnavailableError({
- message: "The focused preview owner is not connected.",
+ message: "The browser host is not connected.",
});
}
if (
@@ -216,7 +218,7 @@ export const makePreviewAutomationBroker = (): PreviewAutomationBrokerShape => {
!input.tabId
) {
return yield* new PreviewAutomationTabNotFoundError({
- message: "The focused preview owner does not have an active tab.",
+ message: "The browser host does not have an active tab.",
});
}
const requestId = `preview-${requestSequence++}`;
diff --git a/apps/server/src/mcp/toolkits/preview/handlers.ts b/apps/server/src/mcp/toolkits/preview/handlers.ts
index f5e19bfcf..62f914213 100644
--- a/apps/server/src/mcp/toolkits/preview/handlers.ts
+++ b/apps/server/src/mcp/toolkits/preview/handlers.ts
@@ -1,6 +1,8 @@
import * as Effect from "effect/Effect";
import type {
PreviewAutomationOperation,
+ PreviewAutomationRecordingArtifact,
+ PreviewAutomationRecordingStatus,
PreviewAutomationSnapshot,
PreviewAutomationStatus,
} from "@t3tools/contracts";
@@ -44,4 +46,6 @@ export const PreviewToolkitHandlersLive = PreviewToolkit.toLayer({
preview_scroll: (input) => invoke<void>("scroll", input),
preview_evaluate: (input) => invoke<unknown>("evaluate", input),
preview_wait_for: (input) => invoke<void>("waitFor", input, input.timeoutMs),
+ preview_recording_start: () => invoke<PreviewAutomationRecordingStatus>("recordingStart", {}),
+ preview_recording_stop: () => invoke<PreviewAutomationRecordingArtifact>("recordingStop", {}),
});
diff --git a/apps/server/src/mcp/toolkits/preview/tools.test.ts b/apps/server/src/mcp/toolkits/preview/tools.test.ts
new file mode 100644
index 000000000..1347e0db0
--- /dev/null
+++ b/apps/server/src/mcp/toolkits/preview/tools.test.ts
@@ -0,0 +1,37 @@
+import { expect, it } from "@effect/vitest";
+import { Tool } from "effect/unstable/ai";
+
+import { PreviewToolkit } from "./tools.ts";
+
+const schemaHasDescription = (schema: unknown): boolean => {
+ if (!schema || typeof schema !== "object") return false;
+ const record = schema as Record<string, unknown>;
+ if (typeof record.description === "string" && record.description.length > 0) return true;
+ return [record.anyOf, record.oneOf, record.allOf]
+ .filter(Array.isArray)
+ .some((members) => members.some(schemaHasDescription));
+};
+
+it("exports provider-compatible object schemas with described parameters", () => {
+ for (const tool of Object.values(PreviewToolkit.tools)) {
+ const schema = Tool.getJsonSchema(tool) as {
+ readonly type?: unknown;
+ readonly properties?: Readonly<Record<string, unknown>>;
+ readonly anyOf?: unknown;
+ readonly oneOf?: unknown;
+ };
+ expect(
+ tool.description?.length ?? 0,
+ `${tool.name} should have a useful description`,
+ ).toBeGreaterThan(40);
+ expect(schema.type, `${tool.name} must export a top-level object schema`).toBe("object");
+ expect(schema.anyOf, `${tool.name} must not export a root anyOf`).toBeUndefined();
+ expect(schema.oneOf, `${tool.name} must not export a root oneOf`).toBeUndefined();
+ for (const [field, fieldSchema] of Object.entries(schema.properties ?? {})) {
+ expect(
+ schemaHasDescription(fieldSchema),
+ `${tool.name}.${field} should explain what data the agent must pass`,
+ ).toBe(true);
+ }
+ }
+});
diff --git a/apps/server/src/mcp/toolkits/preview/tools.ts b/apps/server/src/mcp/toolkits/preview/tools.ts
index 32baf050f..effd87fb7 100644
--- a/apps/server/src/mcp/toolkits/preview/tools.ts
+++ b/apps/server/src/mcp/toolkits/preview/tools.ts
@@ -5,6 +5,8 @@ import {
PreviewAutomationNavigateInput,
PreviewAutomationOpenInput,
PreviewAutomationPressInput,
+ PreviewAutomationRecordingArtifact,
+ PreviewAutomationRecordingStatus,
PreviewAutomationScrollInput,
PreviewAutomationSnapshot,
PreviewAutomationStatus,
@@ -17,7 +19,13 @@ import { Tool, Toolkit } from "effect/unstable/ai";
import { McpInvocationContext } from "../../Services/McpInvocationContext.ts";
const browserTool = <T extends Tool.Any>(tool: T): T =>
- tool.annotate(Tool.Destructive, false).annotate(Tool.OpenWorld, true) as T;
+ tool.annotate(Tool.OpenWorld, true).annotate(Tool.Destructive, true) as T;
+
+const safeBrowserTool = <T extends Tool.Any>(tool: T): T =>
+ browserTool(tool).annotate(Tool.Destructive, false) as T;
+
+const readonlyBrowserTool = <T extends Tool.Any>(tool: T): T =>
+ safeBrowserTool(tool).annotate(Tool.Readonly, true).annotate(Tool.Idempotent, true) as T;
export const PreviewStatusTool = Tool.make("preview_status", {
description:
@@ -39,13 +47,15 @@ export const PreviewOpenTool = browserTool(
success: PreviewAutomationStatus,
failure: PreviewAutomationError,
dependencies: [McpInvocationContext],
- }).annotate(Tool.Title, "Open browser preview"),
+ })
+ .annotate(Tool.Title, "Open browser preview")
+ .annotate(Tool.Destructive, false),
);
-export const PreviewNavigateTool = browserTool(
+export const PreviewNavigateTool = safeBrowserTool(
Tool.make("preview_navigate", {
description:
- "Navigate the scoped thread's active preview tab to a URL and wait for the requested readiness condition.",
+ "Navigate the active collaborative browser tab. Pass {url:'https://t3.chat'} for a website, or {target:{kind:'environment-port',port:5173}} for a dev server in the current environment. Exactly one of url or target is required. Defaults to waiting for page loading to stop.",
parameters: PreviewAutomationNavigateInput,
success: PreviewAutomationStatus,
failure: PreviewAutomationError,
@@ -53,21 +63,20 @@ export const PreviewNavigateTool = browserTool(
}).annotate(Tool.Title, "Navigate browser preview"),
);
-export const PreviewSnapshotTool = Tool.make("preview_snapshot", {
- description:
- "Capture bounded page metadata, visible text, interactive elements, accessibility data, and a PNG screenshot from the scoped preview tab.",
- success: PreviewAutomationSnapshot,
- failure: PreviewAutomationError,
- dependencies: [McpInvocationContext],
-})
- .annotate(Tool.Title, "Capture preview snapshot")
- .annotate(Tool.Readonly, true)
- .annotate(Tool.Destructive, false);
+export const PreviewSnapshotTool = readonlyBrowserTool(
+ Tool.make("preview_snapshot", {
+ description:
+ "Inspect the current page before interacting. Returns URL/title/loading state, visible text, semantic interactive elements with reusable selectors and coordinates, accessibility data, recent console/network failures, action history, and a PNG screenshot.",
+ success: PreviewAutomationSnapshot,
+ failure: PreviewAutomationError,
+ dependencies: [McpInvocationContext],
+ }).annotate(Tool.Title, "Inspect browser page"),
+);
export const PreviewClickTool = browserTool(
Tool.make("preview_click", {
description:
- "Click an element selected by CSS selector or click viewport coordinates in the scoped preview tab.",
+ "Click exactly one page target. Prefer locator with a Playwright selector such as role=button[name='Send']; selector accepts legacy CSS; x and y are viewport CSS pixels and must be supplied together. Call preview_snapshot first when the target is unknown.",
parameters: PreviewAutomationClickInput,
failure: PreviewAutomationError,
dependencies: [McpInvocationContext],
@@ -77,7 +86,7 @@ export const PreviewClickTool = browserTool(
export const PreviewTypeTool = browserTool(
Tool.make("preview_type", {
description:
- "Type text into the focused element or a CSS-selected element, optionally clearing its existing value first.",
+ "Insert literal text into one input. Prefer locator with a Playwright role/text selector; selector accepts legacy CSS. If neither is supplied, types into the currently focused element. Set clear=true to replace existing text.",
parameters: PreviewAutomationTypeInput,
failure: PreviewAutomationError,
dependencies: [McpInvocationContext],
@@ -86,17 +95,18 @@ export const PreviewTypeTool = browserTool(
export const PreviewPressTool = browserTool(
Tool.make("preview_press", {
- description: "Dispatch a keyboard key with optional modifiers to the scoped preview tab.",
+ description:
+ "Press one keyboard key in the active page, for example {key:'Enter'}, {key:'Escape'}, or {key:'a',modifiers:['Meta']}. This targets the page's current focus.",
parameters: PreviewAutomationPressInput,
failure: PreviewAutomationError,
dependencies: [McpInvocationContext],
}).annotate(Tool.Title, "Press key in preview page"),
);
-export const PreviewScrollTool = browserTool(
+export const PreviewScrollTool = safeBrowserTool(
Tool.make("preview_scroll", {
description:
- "Scroll the preview viewport or a CSS-selected scroll container by the requested deltas.",
+ "Scroll by CSS pixels. Positive deltaY scrolls down and positive deltaX scrolls right. Without locator/selector it scrolls the viewport; otherwise it scrolls that container. At least one delta is required.",
parameters: PreviewAutomationScrollInput,
failure: PreviewAutomationError,
dependencies: [McpInvocationContext],
@@ -106,7 +116,7 @@ export const PreviewScrollTool = browserTool(
export const PreviewEvaluateTool = browserTool(
Tool.make("preview_evaluate", {
description:
- "Evaluate bounded JavaScript in the scoped preview tab and return a serializable result of at most 64 KB.",
+ "Evaluate a JavaScript expression in the page's main frame and return a serializable result up to 64 KB. Prefer preview_snapshot and semantic click/type/wait tools; use this for inspection or interactions those tools cannot express. The expression may mutate page state.",
parameters: PreviewAutomationEvaluateInput,
success: Schema.Unknown,
failure: PreviewAutomationError,
@@ -114,16 +124,35 @@ export const PreviewEvaluateTool = browserTool(
}).annotate(Tool.Title, "Evaluate JavaScript in preview"),
);
-export const PreviewWaitForTool = browserTool(
+export const PreviewWaitForTool = readonlyBrowserTool(
Tool.make("preview_wait_for", {
description:
- "Wait until a CSS selector, visible-text substring, or URL substring appears in the scoped preview tab.",
+ "Wait until all supplied conditions match: a Playwright locator, legacy CSS selector, visible-text substring, and/or URL substring. Provide at least one condition. Defaults to 15 seconds, maximum 60 seconds.",
parameters: PreviewAutomationWaitForInput,
failure: PreviewAutomationError,
dependencies: [McpInvocationContext],
}).annotate(Tool.Title, "Wait for preview page condition"),
);
+export const PreviewRecordingStartTool = safeBrowserTool(
+ Tool.make("preview_recording_start", {
+ description:
+ "Start recording the active collaborative browser tab while keeping it interactive for both agent and human use.",
+ success: PreviewAutomationRecordingStatus,
+ failure: PreviewAutomationError,
+ dependencies: [McpInvocationContext],
+ }).annotate(Tool.Title, "Start browser recording"),
+);
+
+export const PreviewRecordingStopTool = safeBrowserTool(
+ Tool.make("preview_recording_stop", {
+ description: "Stop the active browser recording and save it as a local evidence artifact.",
+ success: PreviewAutomationRecordingArtifact,
+ failure: PreviewAutomationError,
+ dependencies: [McpInvocationContext],
+ }).annotate(Tool.Title, "Stop browser recording"),
+);
+
export const PreviewToolkit = Toolkit.make(
PreviewStatusTool,
PreviewOpenTool,
@@ -135,4 +164,6 @@ export const PreviewToolkit = Toolkit.make(
PreviewScrollTool,
PreviewEvaluateTool,
PreviewWaitForTool,
+ PreviewRecordingStartTool,
+ PreviewRecordingStopTool,
);
diff --git a/apps/server/src/provider/CodexDeveloperInstructions.ts b/apps/server/src/provider/CodexDeveloperInstructions.ts
index 76055f8b8..b46a4ce1b 100644
--- a/apps/server/src/provider/CodexDeveloperInstructions.ts
+++ b/apps/server/src/provider/CodexDeveloperInstructions.ts
@@ -1,3 +1,14 @@
+const T3_CODE_BROWSER_TOOL_INSTRUCTIONS = `
+
+## T3 Code collaborative browser
+
+You are running inside T3 Code. The \`t3-code\` MCP server is the product-native collaborative browser shared with the user. When it exposes \`preview_*\` tools, prefer those tools for browser navigation, inspection, interaction, screenshots, and recordings.
+
+For browser work, first call \`preview_status\`. If no automation-capable preview is attached, call \`preview_open\` before concluding that the browser is unavailable. Then use \`preview_navigate\`, \`preview_snapshot\`, and the focused interaction tools. Prefer snapshot-provided locators over coordinates.
+
+Do not switch to global browser skills, Chrome, Node REPL browser automation, standalone Playwright, or agent-browser merely because the preview is initially closed or a first call fails. Use an alternative browser system only when the T3 preview tools are absent, the user explicitly requests another browser, or \`preview_open\` returns an explicit unsupported/unavailable error. A failed T3 preview tool call should be inspected and retried with corrected arguments when the error is actionable.
+`;
+
export const CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Plan Mode (Conversational)
You work in 3 phases, and you should *chat your way* to a great plan before finalizing it. A great plan is very detailed-intent- and implementation-wise-so that it can be handed to another engineer or agent to be implemented right away. It must be **decision complete**, where the implementer does not need to make any decisions.
@@ -118,6 +129,7 @@ plan content should be human and agent digestible. The final plan must be plan-o
Do not ask "should I proceed?" in the final output. The user can easily switch out of Plan mode and request implementation if you have included a \`<proposed_plan>\` block in your response. Alternatively, they can decide to stay in Plan mode and continue refining the plan.
Only produce at most one \`<proposed_plan>\` block per turn, and only when you are presenting a complete spec.
+${T3_CODE_BROWSER_TOOL_INSTRUCTIONS}
</collaboration_mode>`;
export const CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS = `<collaboration_mode># Collaboration Mode: Default
@@ -131,4 +143,5 @@ Your active mode changes only when new developer instructions with a different \
The \`request_user_input\` tool is unavailable in Default mode. If you call it while in Default mode, it will return an error.
In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.
+${T3_CODE_BROWSER_TOOL_INSTRUCTIONS}
</collaboration_mode>`;
diff --git a/apps/server/src/provider/Layers/CodexAdapter.test.ts b/apps/server/src/provider/Layers/CodexAdapter.test.ts
index 04ef44d54..7fef85c42 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.test.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.test.ts
@@ -491,6 +491,64 @@ lifecycleLayer("CodexAdapterLive lifecycle", (it) => {
}),
);
+ it.effect("labels MCP lifecycle entries with server and tool names", () =>
+ Effect.gen(function* () {
+ const { adapter, runtime } = yield* startLifecycleRuntime();
+ const firstEventFiber = yield* Stream.runHead(adapter.streamEvents).pipe(Effect.forkChild);
+
+ yield* runtime.emit({
+ id: asEventId("evt-mcp-complete"),
+ kind: "notification",
+ provider: ProviderDriverKind.make("codex"),
+ createdAt: "2026-01-01T00:00:00.000Z",
+ method: "item/completed",
+ threadId: asThreadId("thread-1"),
+ turnId: asTurnId("turn-1"),
+ itemId: asItemId("mcp_1"),
+ payload: {
+ completedAtMs: 1_778_000_000_000,
+ threadId: "thread-1",
+ turnId: "turn-1",
+ item: {
+ type: "mcpToolCall",
+ id: "mcp_1",
+ server: "t3-code",
+ tool: "preview_status",
+ arguments: {},
+ durationMs: 12,
+ error: null,
+ result: { content: [{ type: "text", text: "attached" }] },
+ status: "completed",
+ },
+ },
+ });
+ const firstEvent = yield* Fiber.join(firstEventFiber);
+
+ assert.equal(firstEvent._tag, "Some");
+ if (firstEvent._tag !== "Some" || firstEvent.value.type !== "item.completed") {
+ return;
+ }
+ assert.equal(firstEvent.value.payload.itemType, "mcp_tool_call");
+ assert.equal(firstEvent.value.payload.title, "t3-code · preview_status");
+ assert.deepStrictEqual(firstEvent.value.payload.data, {
+ completedAtMs: 1_778_000_000_000,
+ threadId: "thread-1",
+ turnId: "turn-1",
+ item: {
+ type: "mcpToolCall",
+ id: "mcp_1",
+ server: "t3-code",
+ tool: "preview_status",
+ arguments: {},
+ durationMs: 12,
+ error: null,
+ result: { content: [{ type: "text", text: "attached" }] },
+ status: "completed",
+ },
+ });
+ }),
+ );
+
it.effect("maps completed plan items to canonical proposed-plan completion events", () =>
Effect.gen(function* () {
const { adapter, runtime } = yield* startLifecycleRuntime();
diff --git a/apps/server/src/provider/Layers/CodexAdapter.ts b/apps/server/src/provider/Layers/CodexAdapter.ts
index ea2d89873..edb2bccdb 100644
--- a/apps/server/src/provider/Layers/CodexAdapter.ts
+++ b/apps/server/src/provider/Layers/CodexAdapter.ts
@@ -235,7 +235,10 @@ function toCanonicalItemType(raw: string | undefined | null): CanonicalItemType
return "unknown";
}
-function itemTitle(itemType: CanonicalItemType): string | undefined {
+function itemTitle(itemType: CanonicalItemType, item?: CodexLifecycleItem): string | undefined {
+ if (itemType === "mcp_tool_call" && item?.type === "mcpToolCall") {
+ return `${item.server} · ${item.tool}`;
+ }
switch (itemType) {
case "assistant_message":
return "Assistant message";
@@ -476,7 +479,7 @@ function mapItemLifecycle(
payload: {
itemType,
...(status ? { status } : {}),
- ...(itemTitle(itemType) ? { title: itemTitle(itemType) } : {}),
+ ...(itemTitle(itemType, item) ? { title: itemTitle(itemType, item) } : {}),
...(detail ? { detail } : {}),
...(event.payload !== undefined ? { data: event.payload } : {}),
},
diff --git a/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
index d2e51139b..2d3030398 100644
--- a/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.test.ts
@@ -13,6 +13,7 @@ import {
} from "../CodexDeveloperInstructions.ts";
import {
buildTurnStartParams,
+ hasConfiguredMcpServer,
isRecoverableThreadResumeError,
openCodexThread,
} from "./CodexSessionRuntime.ts";
@@ -149,6 +150,31 @@ describe("buildTurnStartParams", () => {
});
});
+describe("T3 browser developer instructions", () => {
+ it("prefers the product-native preview tools in both collaboration modes", () => {
+ for (const instructions of [
+ CODEX_DEFAULT_MODE_DEVELOPER_INSTRUCTIONS,
+ CODEX_PLAN_MODE_DEVELOPER_INSTRUCTIONS,
+ ]) {
+ assert.match(instructions, /t3-code/);
+ assert.match(instructions, /preview_status/);
+ assert.match(instructions, /preview_open/);
+ assert.match(instructions, /Do not switch to global browser skills/);
+ }
+ });
+});
+
+describe("hasConfiguredMcpServer", () => {
+ it("detects inline Codex MCP configuration arguments", () => {
+ assert.equal(hasConfiguredMcpServer(undefined), false);
+ assert.equal(hasConfiguredMcpServer(["--model", "gpt-5.4"]), false);
+ assert.equal(
+ hasConfiguredMcpServer(["-c", 'mcp_servers.t3-code.url="http://127.0.0.1/mcp"']),
+ true,
+ );
+ });
+});
+
describe("isRecoverableThreadResumeError", () => {
it("matches missing thread errors", () => {
assert.equal(
diff --git a/apps/server/src/provider/Layers/CodexSessionRuntime.ts b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
index fc31ca3ae..e3e20106d 100644
--- a/apps/server/src/provider/Layers/CodexSessionRuntime.ts
+++ b/apps/server/src/provider/Layers/CodexSessionRuntime.ts
@@ -62,6 +62,10 @@ const RECOVERABLE_THREAD_RESUME_ERROR_SNIPPETS = [
"does not exist",
];
+export function hasConfiguredMcpServer(appServerArgs: ReadonlyArray<string> | undefined): boolean {
+ return appServerArgs?.some((argument) => argument.includes("mcp_servers.")) === true;
+}
+
export const CodexResumeCursorSchema = Schema.Struct({
threadId: Schema.String,
});
@@ -1256,6 +1260,15 @@ export const makeCodexSessionRuntime = (
sendTurn: (input) =>
Effect.gen(function* () {
const providerThreadId = yield* readProviderThreadId;
+ if (hasConfiguredMcpServer(options.appServerArgs)) {
+ yield* client.request("config/mcpServer/reload", undefined).pipe(
+ Effect.catch((cause) =>
+ Effect.logWarning("Failed to refresh Codex MCP tool catalog before turn.", {
+ cause,
+ }),
+ ),
+ );
+ }
const normalizedModel = normalizeCodexModelSlug(
input.model ?? (yield* Ref.get(sessionRef)).model,
);
diff --git a/apps/web/src/browser/BrowserSurfaceSlot.tsx b/apps/web/src/browser/BrowserSurfaceSlot.tsx
new file mode 100644
index 000000000..90769f8fb
--- /dev/null
+++ b/apps/web/src/browser/BrowserSurfaceSlot.tsx
@@ -0,0 +1,45 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+import { useBrowserSurfaceStore } from "./browserSurfaceStore";
+
+export function BrowserSurfaceSlot(props: {
+ readonly tabId: string;
+ readonly visible: boolean;
+ readonly className?: string;
+}) {
+ const { tabId, visible, className } = props;
+ const elementRef = useRef<HTMLDivElement | null>(null);
+
+ useEffect(() => {
+ const element = elementRef.current;
+ if (!element) return;
+ const update = () => {
+ const rect = element.getBoundingClientRect();
+ useBrowserSurfaceStore.getState().present(
+ tabId,
+ {
+ x: Math.round(rect.x),
+ y: Math.round(rect.y),
+ width: Math.max(1, Math.round(rect.width)),
+ height: Math.max(1, Math.round(rect.height)),
+ },
+ visible && rect.width > 0 && rect.height > 0,
+ );
+ };
+ update();
+ const observer = new ResizeObserver(update);
+ observer.observe(element);
+ window.addEventListener("resize", update);
+ window.addEventListener("scroll", update, true);
+ return () => {
+ observer.disconnect();
+ window.removeEventListener("resize", update);
+ window.removeEventListener("scroll", update, true);
+ useBrowserSurfaceStore.getState().hide(tabId);
+ };
+ }, [tabId, visible]);
+
+ return <div ref={elementRef} className={className} data-browser-surface-slot={tabId} />;
+}
diff --git a/apps/web/src/browser/ElectronBrowserHost.tsx b/apps/web/src/browser/ElectronBrowserHost.tsx
new file mode 100644
index 000000000..cc611a229
--- /dev/null
+++ b/apps/web/src/browser/ElectronBrowserHost.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import { parseScopedThreadKey } from "@t3tools/client-runtime";
+import { useMemo } from "react";
+
+import { isElectron } from "~/env";
+import { usePreviewStateStore } from "~/previewStateStore";
+
+import { HostedBrowserWebview } from "./HostedBrowserWebview";
+
+export function ElectronBrowserHost() {
+ const previewByThreadKey = usePreviewStateStore((state) => state.byThreadKey);
+ const sessions = useMemo(
+ () =>
+ Object.entries(previewByThreadKey).flatMap(([threadKey, previewState]) => {
+ const threadRef = parseScopedThreadKey(threadKey);
+ return threadRef
+ ? Object.values(previewState.sessions).map((snapshot) => ({
+ threadRef,
+ snapshot,
+ active: previewState.activeTabId === snapshot.tabId,
+ }))
+ : [];
+ }),
+ [previewByThreadKey],
+ );
+
+ if (!isElectron) return null;
+ return (
+ <div className="contents" data-electron-browser-host>
+ {sessions.map(({ threadRef, snapshot }) => {
+ const url = snapshot.navStatus._tag === "Idle" ? null : snapshot.navStatus.url;
+ return (
+ <HostedBrowserWebview
+ key={snapshot.tabId}
+ threadRef={threadRef}
+ tabId={snapshot.tabId}
+ initialUrl={url}
+ />
+ );
+ })}
+ </div>
+ );
+}
diff --git a/apps/web/src/browser/HostedBrowserWebview.tsx b/apps/web/src/browser/HostedBrowserWebview.tsx
new file mode 100644
index 000000000..e158d7eba
--- /dev/null
+++ b/apps/web/src/browser/HostedBrowserWebview.tsx
@@ -0,0 +1,116 @@
+"use client";
+
+import type { DesktopPreviewWebviewConfig, ScopedThreadRef } from "@t3tools/contracts";
+import { useShallow } from "zustand/react/shallow";
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { previewBridge } from "~/components/preview/previewBridge";
+import { usePreviewBridge } from "~/components/preview/usePreviewBridge";
+
+import { useBrowserRecordingStore } from "./browserRecording";
+import { useBrowserSurfaceStore } from "./browserSurfaceStore";
+import { acquireDesktopTab } from "./desktopTabLifetime";
+
+interface ElectronWebview extends HTMLElement {
+ src: string;
+ partition: string;
+ preload?: string;
+ webpreferences?: string;
+ getWebContentsId: () => number;
+}
+
+declare global {
+ interface HTMLElementTagNameMap {
+ webview: ElectronWebview;
+ }
+}
+
+export function HostedBrowserWebview(props: {
+ readonly threadRef: ScopedThreadRef;
+ readonly tabId: string;
+ readonly initialUrl: string | null;
+}) {
+ const { threadRef, tabId, initialUrl } = props;
+ const [config, setConfig] = useState<DesktopPreviewWebviewConfig | null>(null);
+ const initialSrcRef = useRef(initialUrl ?? "about:blank");
+ const webviewRef = useRef<ElectronWebview | null>(null);
+ const presentation = useBrowserSurfaceStore(useShallow((state) => state.byTabId[tabId] ?? null));
+ const recording = useBrowserRecordingStore((state) => state.activeTabId === tabId);
+
+ usePreviewBridge({ threadRef, tabId });
+
+ useEffect(() => acquireDesktopTab(tabId), [tabId]);
+
+ useEffect(() => {
+ let cancelled = false;
+ void previewBridge
+ ?.getPreviewConfig(threadRef.environmentId)
+ .then((next) => {
+ if (!cancelled) setConfig(next);
+ })
+ .catch(() => undefined);
+ return () => {
+ cancelled = true;
+ };
+ }, [threadRef.environmentId]);
+
+ const setWebviewRef = useCallback((node: HTMLElement | null) => {
+ webviewRef.current = node as ElectronWebview | null;
+ if (node && !node.hasAttribute("allowpopups")) node.setAttribute("allowpopups", "true");
+ }, []);
+
+ useEffect(() => {
+ const webview = webviewRef.current;
+ const bridge = previewBridge;
+ if (!webview || !config || !bridge) return;
+ const register = () => {
+ try {
+ const webContentsId = webview.getWebContentsId();
+ if (Number.isInteger(webContentsId) && webContentsId > 0) {
+ void bridge.registerWebview(tabId, webContentsId);
+ }
+ } catch {
+ // A later dom-ready will retry registration.
+ }
+ };
+ webview.addEventListener("dom-ready", register);
+ register();
+ return () => webview.removeEventListener("dom-ready", register);
+ }, [config, tabId]);
+
+ if (!config) return null;
+ const active = presentation?.visible === true && presentation.rect !== null;
+ const lastRect = presentation?.rect;
+ const style =
+ active && lastRect
+ ? {
+ left: lastRect.x,
+ top: lastRect.y,
+ width: lastRect.width,
+ height: lastRect.height,
+ zIndex: 30,
+ pointerEvents: "auto" as const,
+ }
+ : {
+ left: 0,
+ top: 0,
+ width: lastRect?.width ?? 1280,
+ height: lastRect?.height ?? 800,
+ zIndex: recording ? 0 : -1,
+ pointerEvents: "none" as const,
+ };
+
+ return (
+ <webview
+ ref={setWebviewRef}
+ src={initialSrcRef.current}
+ partition={config.partition}
+ webpreferences={config.webPreferences}
+ {...(config.preloadUrl ? { preload: config.preloadUrl } : {})}
+ data-preview-tab={tabId}
+ aria-hidden={active ? undefined : true}
+ className="fixed flex overflow-hidden bg-background"
+ style={style}
+ />
+ );
+}
diff --git a/apps/web/src/browser/browserRecording.ts b/apps/web/src/browser/browserRecording.ts
new file mode 100644
index 000000000..8a1c6f413
--- /dev/null
+++ b/apps/web/src/browser/browserRecording.ts
@@ -0,0 +1,115 @@
+import type {
+ DesktopPreviewRecordingArtifact,
+ DesktopPreviewRecordingFrame,
+} from "@t3tools/contracts";
+import { create } from "zustand";
+
+import { previewBridge } from "~/components/preview/previewBridge";
+import { useBrowserSurfaceStore } from "./browserSurfaceStore";
+
+interface ActiveRecording {
+ readonly tabId: string;
+ readonly canvas: HTMLCanvasElement;
+ readonly context: CanvasRenderingContext2D;
+ readonly recorder: MediaRecorder;
+ readonly chunks: Blob[];
+ readonly mimeType: string;
+ readonly startedAt: string;
+}
+
+interface BrowserRecordingState {
+ activeTabId: string | null;
+ startedAt: string | null;
+ lastArtifact: DesktopPreviewRecordingArtifact | null;
+ setActive: (tabId: string | null, startedAt: string | null) => void;
+ setArtifact: (artifact: DesktopPreviewRecordingArtifact) => void;
+}
+
+export const useBrowserRecordingStore = create<BrowserRecordingState>()((set) => ({
+ activeTabId: null,
+ startedAt: null,
+ lastArtifact: null,
+ setActive: (activeTabId, startedAt) => set({ activeTabId, startedAt }),
+ setArtifact: (lastArtifact) => set({ lastArtifact }),
+}));
+
+let active: ActiveRecording | null = null;
+let unsubscribeFrames: (() => void) | null = null;
+
+const preferredMimeType = (): string => {
+ const candidates = ["video/mp4;codecs=avc1.42E01E", "video/webm;codecs=vp9", "video/webm"];
+ return candidates.find((candidate) => MediaRecorder.isTypeSupported(candidate)) ?? "video/webm";
+};
+
+const drawFrame = (frame: DesktopPreviewRecordingFrame): void => {
+ const recording = active;
+ if (!recording || recording.tabId !== frame.tabId) return;
+ const image = new Image();
+ image.addEventListener(
+ "load",
+ () => {
+ if (active !== recording) return;
+ recording.context.drawImage(image, 0, 0, recording.canvas.width, recording.canvas.height);
+ },
+ { once: true },
+ );
+ image.src = `data:image/jpeg;base64,${frame.data}`;
+};
+
+export async function startBrowserRecording(tabId: string): Promise<void> {
+ const bridge = previewBridge;
+ if (!bridge || active) return;
+ const rect = useBrowserSurfaceStore.getState().byTabId[tabId]?.rect;
+ const canvas = document.createElement("canvas");
+ canvas.width = Math.max(1, rect?.width ?? 1280);
+ canvas.height = Math.max(1, rect?.height ?? 800);
+ const context = canvas.getContext("2d", { alpha: false });
+ if (!context) throw new Error("Browser recording canvas is unavailable.");
+ const mimeType = preferredMimeType();
+ const recorder = new MediaRecorder(canvas.captureStream(12), {
+ mimeType,
+ videoBitsPerSecond: 4_000_000,
+ });
+ const startedAt = new Date().toISOString();
+ const chunks: Blob[] = [];
+ recorder.addEventListener("dataavailable", (event) => {
+ if (event.data.size > 0) chunks.push(event.data);
+ });
+ active = { tabId, canvas, context, recorder, chunks, mimeType, startedAt };
+ unsubscribeFrames ??= bridge.recording.onFrame(drawFrame);
+ recorder.start(1_000);
+ try {
+ await bridge.recording.startScreencast(tabId);
+ useBrowserRecordingStore.getState().setActive(tabId, startedAt);
+ } catch (error) {
+ active = null;
+ recorder.stop();
+ throw error;
+ }
+}
+
+export async function stopBrowserRecording(
+ tabId: string,
+): Promise<DesktopPreviewRecordingArtifact | null> {
+ const bridge = previewBridge;
+ const recording = active;
+ if (!bridge || !recording || recording.tabId !== tabId) return null;
+ await bridge.recording.stopScreencast(tabId);
+ const stopped = new Promise<void>((resolve) =>
+ recording.recorder.addEventListener("stop", () => resolve(), { once: true }),
+ );
+ recording.recorder.stop();
+ await stopped;
+ const blob = new Blob(recording.chunks, { type: recording.mimeType });
+ const artifact = await bridge.recording.save(
+ tabId,
+ recording.mimeType,
+ new Uint8Array(await blob.arrayBuffer()),
+ );
+ active = null;
+ unsubscribeFrames?.();
+ unsubscribeFrames = null;
+ useBrowserRecordingStore.getState().setActive(null, null);
+ useBrowserRecordingStore.getState().setArtifact(artifact);
+ return artifact;
+}
diff --git a/apps/web/src/browser/browserSurfaceStore.ts b/apps/web/src/browser/browserSurfaceStore.ts
new file mode 100644
index 000000000..64fd8e2df
--- /dev/null
+++ b/apps/web/src/browser/browserSurfaceStore.ts
@@ -0,0 +1,53 @@
+import { create } from "zustand";
+
+export interface BrowserSurfaceRect {
+ readonly x: number;
+ readonly y: number;
+ readonly width: number;
+ readonly height: number;
+}
+
+export interface BrowserSurfacePresentation {
+ readonly rect: BrowserSurfaceRect | null;
+ readonly visible: boolean;
+ readonly updatedAt: number;
+}
+
+interface BrowserSurfaceStoreState {
+ readonly byTabId: Record<string, BrowserSurfacePresentation>;
+ readonly present: (tabId: string, rect: BrowserSurfaceRect, visible: boolean) => void;
+ readonly hide: (tabId: string) => void;
+}
+
+const rectEquals = (left: BrowserSurfaceRect | null, right: BrowserSurfaceRect): boolean =>
+ left !== null &&
+ left.x === right.x &&
+ left.y === right.y &&
+ left.width === right.width &&
+ left.height === right.height;
+
+export const useBrowserSurfaceStore = create<BrowserSurfaceStoreState>()((set) => ({
+ byTabId: {},
+ present: (tabId, rect, visible) =>
+ set((state) => {
+ const current = state.byTabId[tabId];
+ if (current && current.visible === visible && rectEquals(current.rect, rect)) return state;
+ return {
+ byTabId: {
+ ...state.byTabId,
+ [tabId]: { rect, visible, updatedAt: Date.now() },
+ },
+ };
+ }),
+ hide: (tabId) =>
+ set((state) => {
+ const current = state.byTabId[tabId];
+ if (!current || !current.visible) return state;
+ return {
+ byTabId: {
+ ...state.byTabId,
+ [tabId]: { ...current, visible: false, updatedAt: Date.now() },
+ },
+ };
+ }),
+}));
diff --git a/apps/web/src/browser/browserTargetResolver.test.ts b/apps/web/src/browser/browserTargetResolver.test.ts
new file mode 100644
index 000000000..a50275eb8
--- /dev/null
+++ b/apps/web/src/browser/browserTargetResolver.test.ts
@@ -0,0 +1,81 @@
+import { EnvironmentId } from "@t3tools/contracts";
+import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
+
+const readEnvironmentConnection = vi.fn();
+
+vi.mock("~/environments/runtime", () => ({ readEnvironmentConnection }));
+
+describe("browser target resolver", () => {
+ beforeEach(() => readEnvironmentConnection.mockReset());
+
+ it("maps environment ports onto a private network host", async () => {
+ readEnvironmentConnection.mockReturnValue({
+ knownEnvironment: { target: { httpBaseUrl: "http://192.168.1.25:3773" } },
+ });
+ const { resolveBrowserNavigationTarget } = await import("./browserTargetResolver");
+ expect(
+ resolveBrowserNavigationTarget(EnvironmentId.make("environment-1"), {
+ kind: "environment-port",
+ port: 5173,
+ path: "/dashboard",
+ }),
+ ).toEqual({
+ requestedUrl: "http://localhost:5173/dashboard",
+ resolvedUrl: "http://192.168.1.25:5173/dashboard",
+ resolutionKind: "direct-private-network",
+ environmentId: "environment-1",
+ });
+ });
+
+ it("refuses public relay hosts until the authenticated gateway exists", async () => {
+ readEnvironmentConnection.mockReturnValue({
+ knownEnvironment: { target: { httpBaseUrl: "https://relay.example.com" } },
+ });
+ const { resolveBrowserNavigationTarget } = await import("./browserTargetResolver");
+ expect(() =>
+ resolveBrowserNavigationTarget(EnvironmentId.make("environment-1"), {
+ kind: "environment-port",
+ port: 5173,
+ }),
+ ).toThrow(/authenticated preview gateway/);
+ });
+
+ it("normalizes schemeless localhost server-picker values", async () => {
+ readEnvironmentConnection.mockReturnValue({
+ knownEnvironment: { target: { httpBaseUrl: "http://localhost:3773" } },
+ });
+ const { resolveDiscoveredServerUrl } = await import("./browserTargetResolver");
+ expect(resolveDiscoveredServerUrl(EnvironmentId.make("environment-1"), "localhost:5173")).toBe(
+ "http://localhost:5173/",
+ );
+ expect(
+ resolveDiscoveredServerUrl(EnvironmentId.make("environment-1"), "0.0.0.0:3000/app"),
+ ).toBe("http://localhost:3000/app");
+ });
+
+ it("normalizes public URLs without treating them as environment ports", async () => {
+ const { resolveDiscoveredServerUrl } = await import("./browserTargetResolver");
+ expect(resolveDiscoveredServerUrl(EnvironmentId.make("environment-1"), "example.com/app")).toBe(
+ "https://example.com/app",
+ );
+ });
+
+ it("supports private IPv6 environment hosts", async () => {
+ readEnvironmentConnection.mockReturnValue({
+ knownEnvironment: { target: { httpBaseUrl: "http://[::1]:3773" } },
+ });
+ const { resolveBrowserNavigationTarget } = await import("./browserTargetResolver");
+ expect(
+ resolveBrowserNavigationTarget(EnvironmentId.make("environment-1"), {
+ kind: "environment-port",
+ port: 5173,
+ path: "/app?mode=test",
+ }).resolvedUrl,
+ ).toBe("http://[::1]:5173/app?mode=test");
+ });
+
+ it("leaves malformed input for the normal navigation error path", async () => {
+ const { resolveDiscoveredServerUrl } = await import("./browserTargetResolver");
+ expect(resolveDiscoveredServerUrl(EnvironmentId.make("environment-1"), " ")).toBe(" ");
+ });
+});
diff --git a/apps/web/src/browser/browserTargetResolver.ts b/apps/web/src/browser/browserTargetResolver.ts
new file mode 100644
index 000000000..122766730
--- /dev/null
+++ b/apps/web/src/browser/browserTargetResolver.ts
@@ -0,0 +1,81 @@
+import type {
+ BrowserNavigationTarget,
+ EnvironmentId,
+ PreviewUrlResolution,
+} from "@t3tools/contracts";
+import { isLoopbackHost, normalizePreviewUrl } from "@t3tools/shared/preview";
+
+import { readEnvironmentConnection } from "~/environments/runtime";
+
+const isPrivateNetworkHost = (host: string): boolean => {
+ const normalized = host.toLowerCase().replace(/^\[|\]$/g, "");
+ if (normalized === "localhost" || normalized === "::1" || normalized.endsWith(".local")) {
+ return true;
+ }
+ if (normalized.endsWith(".ts.net")) return true;
+ const parts = normalized.split(".").map(Number);
+ if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part))) return false;
+ return (
+ parts[0] === 10 ||
+ (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) ||
+ (parts[0] === 192 && parts[1] === 168) ||
+ parts[0] === 127 ||
+ (parts[0] === 169 && parts[1] === 254)
+ );
+};
+
+export function resolveBrowserNavigationTarget(
+ environmentId: EnvironmentId,
+ target: BrowserNavigationTarget,
+): PreviewUrlResolution {
+ if (target.kind === "url") {
+ return {
+ requestedUrl: target.url,
+ resolvedUrl: target.url,
+ resolutionKind: "direct",
+ environmentId,
+ };
+ }
+ const connection = readEnvironmentConnection(environmentId);
+ if (!connection) throw new Error(`Environment ${environmentId} is not connected.`);
+ const environmentUrl = new URL(connection.knownEnvironment.target.httpBaseUrl);
+ if (!isPrivateNetworkHost(environmentUrl.hostname)) {
+ throw new Error(
+ "This environment port needs the planned authenticated preview gateway; its server address is not directly private-network reachable.",
+ );
+ }
+ const protocol = target.protocol ?? "http";
+ const path = target.path?.startsWith("/") ? target.path : `/${target.path ?? ""}`;
+ const requestedUrl = `${protocol}://localhost:${target.port}${path}`;
+ const normalizedEnvironmentHost = environmentUrl.hostname.replace(/^\[|\]$/g, "");
+ const resolvedHost = normalizedEnvironmentHost.includes(":")
+ ? `[${normalizedEnvironmentHost}]`
+ : normalizedEnvironmentHost;
+ const resolved = new URL(path, `${protocol}://${resolvedHost}:${target.port}`);
+ return {
+ requestedUrl,
+ resolvedUrl: resolved.toString(),
+ resolutionKind:
+ normalizedEnvironmentHost === "localhost" || normalizedEnvironmentHost === "127.0.0.1"
+ ? "direct"
+ : "direct-private-network",
+ environmentId,
+ };
+}
+
+export function resolveDiscoveredServerUrl(environmentId: EnvironmentId, rawUrl: string): string {
+ try {
+ const normalizedUrl = normalizePreviewUrl(rawUrl);
+ const parsed = new URL(normalizedUrl);
+ if (!isLoopbackHost(parsed.hostname)) return normalizedUrl;
+ const port = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
+ return resolveBrowserNavigationTarget(environmentId, {
+ kind: "environment-port",
+ port,
+ protocol: parsed.protocol === "https:" ? "https" : "http",
+ path: `${parsed.pathname}${parsed.search}${parsed.hash}`,
+ }).resolvedUrl;
+ } catch {
+ return rawUrl;
+ }
+}
diff --git a/apps/web/src/browser/desktopTabLifetime.ts b/apps/web/src/browser/desktopTabLifetime.ts
new file mode 100644
index 000000000..4254c7e6a
--- /dev/null
+++ b/apps/web/src/browser/desktopTabLifetime.ts
@@ -0,0 +1,30 @@
+import { previewBridge } from "~/components/preview/previewBridge";
+
+interface DesktopTabLease {
+ references: number;
+ closeTimer: number | null;
+}
+
+const leases = new Map<string, DesktopTabLease>();
+
+export function acquireDesktopTab(tabId: string): () => void {
+ const current = leases.get(tabId) ?? { references: 0, closeTimer: null };
+ if (current.closeTimer !== null) window.clearTimeout(current.closeTimer);
+ current.references += 1;
+ current.closeTimer = null;
+ leases.set(tabId, current);
+ if (current.references === 1) void previewBridge?.createTab(tabId);
+
+ return () => {
+ const lease = leases.get(tabId);
+ if (!lease) return;
+ lease.references = Math.max(0, lease.references - 1);
+ if (lease.references > 0) return;
+ lease.closeTimer = window.setTimeout(() => {
+ const latest = leases.get(tabId);
+ if (!latest || latest.references > 0) return;
+ leases.delete(tabId);
+ void previewBridge?.closeTab(tabId);
+ }, 0);
+ };
+}
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 4dd6d9003..0bda0fb7e 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -21,12 +21,7 @@ import {
RuntimeMode,
TerminalOpenInput,
} from "@t3tools/contracts";
-import {
- parseScopedThreadKey,
- scopedThreadKey,
- scopeProjectRef,
- scopeThreadRef,
-} from "@t3tools/client-runtime";
+import { scopedThreadKey, scopeProjectRef, scopeThreadRef } from "@t3tools/client-runtime";
import {
applyClaudePromptEffortPrefix,
createModelSelection,
@@ -43,6 +38,7 @@ import { useVcsStatus } from "~/lib/vcsStatusState";
import { usePrimaryEnvironmentId } from "../environments/primary";
import { readEnvironmentApi } from "../environmentApi";
import { isElectron } from "../env";
+import { PreviewAutomationOwner } from "./preview/PreviewAutomationOwner";
import { readLocalApi } from "../localApi";
import { parseDiffRouteSearch, stripDiffSearchParams } from "../diffRouteSearch";
import {
@@ -70,11 +66,7 @@ import {
togglePendingUserInputOptionSelection,
type PendingUserInputDraftAnswer,
} from "../pendingUserInput";
-import {
- selectProjectsAcrossEnvironments,
- selectThreadsAcrossEnvironments,
- useStore,
-} from "../store";
+import { selectProjectsAcrossEnvironments, useStore } from "../store";
import { createProjectSelectorByRef, createThreadSelectorByRef } from "../storeSelectors";
import { useUiStateStore } from "../uiStateStore";
import {
@@ -98,20 +90,32 @@ import { useCommandPaletteStore } from "../commandPaletteStore";
import { buildTemporaryWorktreeBranchName } from "@t3tools/shared/git";
import { useMediaQuery } from "../hooks/useMediaQuery";
import { RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY } from "../rightPanelLayout";
-import { selectActiveRightPanelKindWithUrl, useRightPanelStore } from "../rightPanelStore";
-import { PreviewAutomationOwner } from "./preview/PreviewAutomationOwner";
-import { isPreviewSupportedInRuntime, usePreviewStateStore } from "../previewStateStore";
+import {
+ selectActiveRightPanelKindWithUrl,
+ selectActiveRightPanelSurface,
+ selectThreadRightPanelState,
+ type RightPanelSurface,
+ useRightPanelStore,
+} from "../rightPanelStore";
+import {
+ isPreviewSupportedInRuntime,
+ selectThreadPreviewState,
+ usePreviewStateStore,
+} from "../previewStateStore";
import { subscribePreviewAction } from "./preview/previewActionBus";
// Lazy: keeps the entire preview component graph (webview host, favicon
// helper, Chromium error icon) out of the web bundle until first open.
const PreviewPanel = lazy(() =>
import("./preview/PreviewPanel").then((mod) => ({ default: mod.PreviewPanel })),
);
+const DiffPanel = lazy(() => import("./DiffPanel"));
import { BranchToolbar } from "./BranchToolbar";
import { resolveShortcutCommand, shortcutLabelForCommand } from "../keybindings";
import PlanSidebar from "./PlanSidebar";
import ThreadTerminalDrawer from "./ThreadTerminalDrawer";
import { ChevronDownIcon, TriangleAlertIcon, WifiOffIcon } from "lucide-react";
+import { RightPanelTabs } from "./RightPanelTabs";
+import { DiffWorkerPoolProvider } from "./DiffWorkerPoolProvider";
import { cn, randomHex } from "~/lib/utils";
import { stackedThreadToast, toastManager } from "./ui/toast";
import { decodeProjectScriptKeybindingRule } from "~/lib/projectScriptKeybindings";
@@ -167,8 +171,6 @@ import { ProviderStatusBanner } from "./chat/ProviderStatusBanner";
import { ThreadErrorBanner } from "./chat/ThreadErrorBanner";
import { ComposerBannerStack, type ComposerBannerStackItem } from "./chat/ComposerBannerStack";
import {
- MAX_HIDDEN_MOUNTED_PREVIEW_THREADS,
- MAX_HIDDEN_MOUNTED_TERMINAL_THREADS,
buildExpiredTerminalContextToastCopy,
buildLocalDraftThread,
collectUserMessageBlobPreviewUrls,
@@ -183,8 +185,6 @@ import {
cloneComposerImageForRetry,
deriveLockedProvider,
readFileAsDataUrl,
- reconcileMountedTerminalThreadIds,
- reconcileRetainedMountedThreadIds,
resolveSendEnvMode,
revokeBlobPreviewUrl,
revokeUserMessagePreviewUrls,
@@ -535,6 +535,7 @@ interface PersistentThreadTerminalDrawerProps {
threadRef: { environmentId: EnvironmentId; threadId: ThreadId };
threadId: ThreadId;
visible: boolean;
+ mode?: "drawer" | "panel";
launchContext: PersistentTerminalLaunchContext | null;
focusRequestId: number;
splitShortcutLabel: string | undefined;
@@ -548,6 +549,7 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
threadRef,
threadId,
visible,
+ mode = "drawer",
launchContext,
focusRequestId,
splitShortcutLabel,
@@ -795,8 +797,9 @@ const PersistentThreadTerminalDrawer = memo(function PersistentThreadTerminalDra
}
return (
- <div className={visible ? undefined : "hidden"}>
+ <div className={cn(visible ? undefined : "hidden", mode === "panel" && "h-full min-h-0")}>
<ThreadTerminalDrawer
+ mode={mode}
threadRef={threadRef}
threadId={threadId}
cwd={cwd}
@@ -962,59 +965,11 @@ export default function ChatView(props: ChatViewProps) {
const terminalUiState = useTerminalUiStateStore((state) =>
selectThreadTerminalUiState(state.terminalUiStateByThreadKey, routeThreadRef),
);
- const openTerminalThreadKeys = useTerminalUiStateStore(
- useShallow((state) =>
- Object.entries(state.terminalUiStateByThreadKey).flatMap(
- ([nextThreadKey, nextTerminalUiState]) =>
- nextTerminalUiState.terminalOpen ? [nextThreadKey] : [],
- ),
- ),
- );
const storeSetTerminalOpen = useTerminalUiStateStore((s) => s.setTerminalOpen);
const storeSplitTerminal = useTerminalUiStateStore((s) => s.splitTerminal);
const storeNewTerminal = useTerminalUiStateStore((s) => s.newTerminal);
const storeSetActiveTerminal = useTerminalUiStateStore((s) => s.setActiveTerminal);
const storeCloseTerminal = useTerminalUiStateStore((s) => s.closeTerminal);
- const serverThreadKeys = useStore(
- useShallow((state) =>
- selectThreadsAcrossEnvironments(state).map((thread) =>
- scopedThreadKey(scopeThreadRef(thread.environmentId, thread.id)),
- ),
- ),
- );
- const draftThreadsByThreadKey = useComposerDraftStore((store) => store.draftThreadsByThreadKey);
- const draftThreadKeys = useMemo(
- () =>
- Object.values(draftThreadsByThreadKey).map((draftThread) =>
- scopedThreadKey(scopeThreadRef(draftThread.environmentId, draftThread.threadId)),
- ),
- [draftThreadsByThreadKey],
- );
- const [mountedTerminalThreadKeys, setMountedTerminalThreadKeys] = useState<string[]>([]);
- const mountedTerminalThreadRefs = useMemo(
- () =>
- mountedTerminalThreadKeys.flatMap((mountedThreadKey) => {
- const mountedThreadRef = parseScopedThreadKey(mountedThreadKey);
- return mountedThreadRef ? [{ key: mountedThreadKey, threadRef: mountedThreadRef }] : [];
- }),
- [mountedTerminalThreadKeys],
- );
- const previewSessionThreadKeys = usePreviewStateStore(
- useShallow((state) =>
- Object.entries(state.byThreadKey).flatMap(([nextThreadKey, nextPreviewState]) =>
- nextPreviewState.snapshot ? [nextThreadKey] : [],
- ),
- ),
- );
- const [mountedPreviewThreadKeys, setMountedPreviewThreadKeys] = useState<string[]>([]);
- const mountedPreviewThreadRefs = useMemo(
- () =>
- mountedPreviewThreadKeys.flatMap((mountedThreadKey) => {
- const mountedThreadRef = parseScopedThreadKey(mountedThreadKey);
- return mountedThreadRef ? [{ key: mountedThreadKey, threadRef: mountedThreadRef }] : [];
- }),
- [mountedPreviewThreadKeys],
- );
const fallbackDraftProjectRef = draftThread
? scopeProjectRef(draftThread.environmentId, draftThread.projectId)
@@ -1105,18 +1060,40 @@ export default function ChatView(props: ChatViewProps) {
const activeRightPanelKind = useRightPanelStore((store) =>
selectActiveRightPanelKindWithUrl(store.byThreadKey, activeThreadRef, diffOpen),
);
+ const rightPanelState = useRightPanelStore((store) =>
+ selectThreadRightPanelState(store.byThreadKey, activeThreadRef),
+ );
+ const activeRightPanelSurface = useRightPanelStore((store) =>
+ selectActiveRightPanelSurface(store.byThreadKey, activeThreadRef),
+ );
+ const activePreviewState = usePreviewStateStore((state) =>
+ selectThreadPreviewState(state.byThreadKey, activeThreadRef),
+ );
const planSidebarOpen = activeRightPanelKind === "plan";
const previewPanelOpen = activeRightPanelKind === "preview" && isPreviewSupportedInRuntime();
- const existingOpenTerminalThreadKeys = useMemo(() => {
- const existingThreadKeys = new Set<string>([...serverThreadKeys, ...draftThreadKeys]);
- return openTerminalThreadKeys.filter((nextThreadKey) => existingThreadKeys.has(nextThreadKey));
- }, [draftThreadKeys, openTerminalThreadKeys, serverThreadKeys]);
- const existingPreviewSessionThreadKeys = useMemo(() => {
- const existingThreadKeys = new Set<string>([...serverThreadKeys, ...draftThreadKeys]);
- return previewSessionThreadKeys.filter((nextThreadKey) =>
- existingThreadKeys.has(nextThreadKey),
+ const terminalPanelOpen = activeRightPanelKind === "terminal";
+ const rightPanelOpen = activeRightPanelSurface !== null;
+
+ useEffect(() => {
+ if (!activeThreadRef) return;
+ useRightPanelStore
+ .getState()
+ .reconcileBrowserSurfaces(activeThreadRef, Object.keys(activePreviewState.sessions));
+ }, [activePreviewState.sessions, activeThreadRef]);
+
+ useEffect(() => {
+ if (!activeThreadRef || !diffOpen) return;
+ useRightPanelStore.getState().open(activeThreadRef, "diff");
+ }, [activeThreadRef, diffOpen]);
+ useEffect(() => {
+ if (!activeThreadRef || !terminalUiState.terminalOpen) return;
+ const state = selectThreadRightPanelState(
+ useRightPanelStore.getState().byThreadKey,
+ activeThreadRef,
);
- }, [draftThreadKeys, previewSessionThreadKeys, serverThreadKeys]);
+ if (state.surfaces.some((surface) => surface.kind === "terminal")) return;
+ useRightPanelStore.getState().open(activeThreadRef, "terminal");
+ }, [activeThreadRef, terminalUiState.terminalOpen]);
const activeLatestTurn = activeThread?.latestTurn ?? null;
const threadPlanCatalog = useThreadPlanCatalog(
useMemo(() => {
@@ -1131,42 +1108,6 @@ export default function ChatView(props: ChatViewProps) {
return threadIds;
}, [activeLatestTurn?.sourceProposedPlan?.threadId, activeThread?.id]),
);
- useEffect(() => {
- setMountedTerminalThreadKeys((currentThreadIds) => {
- const nextThreadIds = reconcileMountedTerminalThreadIds({
- currentThreadIds,
- openThreadIds: existingOpenTerminalThreadKeys,
- activeThreadId: activeThreadKey,
- activeThreadTerminalOpen: Boolean(activeThreadKey && terminalUiState.terminalOpen),
- maxHiddenThreadCount: MAX_HIDDEN_MOUNTED_TERMINAL_THREADS,
- });
- return currentThreadIds.length === nextThreadIds.length &&
- currentThreadIds.every((nextThreadId, index) => nextThreadId === nextThreadIds[index])
- ? currentThreadIds
- : nextThreadIds;
- });
- }, [activeThreadKey, existingOpenTerminalThreadKeys, terminalUiState.terminalOpen]);
- useEffect(() => {
- setMountedPreviewThreadKeys((currentThreadIds) => {
- const nextThreadIds = reconcileRetainedMountedThreadIds({
- currentThreadIds,
- openThreadIds: existingPreviewSessionThreadKeys,
- activeThreadId: activeThreadKey,
- activeThreadOpen: Boolean(activeThreadKey && !shouldUsePlanSidebarSheet),
- maxHiddenThreadCount: MAX_HIDDEN_MOUNTED_PREVIEW_THREADS,
- retainInactiveActiveThread: true,
- });
- return currentThreadIds.length === nextThreadIds.length &&
- currentThreadIds.every((nextThreadId, index) => nextThreadId === nextThreadIds[index])
- ? currentThreadIds
- : nextThreadIds;
- });
- }, [
- activeThreadKey,
- existingPreviewSessionThreadKeys,
- previewPanelOpen,
- shouldUsePlanSidebarSheet,
- ]);
const latestTurnSettled = isLatestTurnSettled(activeLatestTurn, activeThread?.session ?? null);
const activeProjectRef = activeThread
? scopeProjectRef(activeThread.environmentId, activeThread.projectId)
@@ -1961,19 +1902,6 @@ export default function ChatView(props: ChatViewProps) {
}),
[terminalUiState.terminalOpen],
);
- const nonTerminalShortcutLabelOptions = useMemo(
- () => ({
- context: {
- terminalFocus: false,
- terminalOpen: Boolean(terminalUiState.terminalOpen),
- },
- }),
- [terminalUiState.terminalOpen],
- );
- const terminalToggleShortcutLabel = useMemo(
- () => shortcutLabelForCommand(keybindings, "terminal.toggle"),
- [keybindings],
- );
const splitTerminalShortcutLabel = useMemo(
() => shortcutLabelForCommand(keybindings, "terminal.split", terminalShortcutLabelOptions),
[keybindings, terminalShortcutLabelOptions],
@@ -1986,14 +1914,37 @@ export default function ChatView(props: ChatViewProps) {
() => shortcutLabelForCommand(keybindings, "terminal.close", terminalShortcutLabelOptions),
[keybindings, terminalShortcutLabelOptions],
);
- const diffPanelShortcutLabel = useMemo(
- () => shortcutLabelForCommand(keybindings, "diff.toggle", nonTerminalShortcutLabelOptions),
- [keybindings, nonTerminalShortcutLabelOptions],
- );
- const previewPanelShortcutLabel = useMemo(
- () => shortcutLabelForCommand(keybindings, "preview.toggle", nonTerminalShortcutLabelOptions),
- [keybindings, nonTerminalShortcutLabelOptions],
- );
+ const createBrowserSurface = useCallback(() => {
+ if (!activeThreadRef) return;
+ const api = readEnvironmentApi(activeThreadRef.environmentId);
+ if (!api) return;
+ void api.preview
+ .open({ threadId: activeThreadRef.threadId })
+ .then((snapshot) => {
+ usePreviewStateStore.getState().applyServerSnapshot(activeThreadRef, snapshot);
+ useRightPanelStore.getState().openBrowser(activeThreadRef, snapshot.tabId);
+ })
+ .catch(() => undefined);
+ }, [activeThreadRef]);
+ const addDiffSurface = useCallback(() => {
+ if (!activeThreadRef || !isServerThread || !isGitRepo) return;
+ useRightPanelStore.getState().open(activeThreadRef, "diff");
+ onDiffPanelOpen?.();
+ void navigate({
+ to: "/$environmentId/$threadId",
+ params: { environmentId, threadId },
+ replace: true,
+ search: (previous) => ({ ...stripDiffSearchParams(previous), diff: "1" }),
+ });
+ }, [
+ activeThreadRef,
+ environmentId,
+ isGitRepo,
+ isServerThread,
+ navigate,
+ onDiffPanelOpen,
+ threadId,
+ ]);
// Right-panel arbitration:
// - The diff panel's openness is mirrored by the `?diff=1` URL search
// param so it deep-links cleanly. The store still records preview/plan
@@ -2017,20 +1968,33 @@ export default function ChatView(props: ChatViewProps) {
search: (previous) => ({ ...stripDiffSearchParams(previous), diff: undefined }),
});
}
- useRightPanelStore.getState().open(activeThreadRef, "preview");
- }, [activeThreadRef, diffOpen, environmentId, navigate, previewPanelOpen, threadId]);
+ const activeTabId = activePreviewState.activeTabId;
+ if (!activeTabId) {
+ createBrowserSurface();
+ return;
+ }
+ useRightPanelStore.getState().openBrowser(activeThreadRef, activeTabId);
+ }, [
+ activePreviewState.activeTabId,
+ activeThreadRef,
+ createBrowserSurface,
+ diffOpen,
+ environmentId,
+ navigate,
+ previewPanelOpen,
+ threadId,
+ ]);
const onToggleDiff = useCallback(() => {
if (!isServerThread) {
return;
}
if (!diffOpen) {
onDiffPanelOpen?.();
- // Switching to diff: drop whatever the store had (e.g. preview) so
- // that when the user later closes diff, an old store entry doesn't
- // unexpectedly resurface.
if (activeThreadRef) {
- useRightPanelStore.getState().close(activeThreadRef);
+ useRightPanelStore.getState().open(activeThreadRef, "diff");
}
+ } else if (activeThreadRef) {
+ useRightPanelStore.getState().closeSurface(activeThreadRef, "diff");
}
void navigate({
to: "/$environmentId/$threadId",
@@ -2147,8 +2111,13 @@ export default function ChatView(props: ChatViewProps) {
);
const toggleTerminalVisibility = useCallback(() => {
if (!activeThreadRef) return;
- setTerminalOpen(!terminalUiState.terminalOpen);
- }, [activeThreadRef, setTerminalOpen, terminalUiState.terminalOpen]);
+ if (terminalPanelOpen) {
+ useRightPanelStore.getState().close(activeThreadRef);
+ return;
+ }
+ setTerminalOpen(true);
+ useRightPanelStore.getState().open(activeThreadRef, "terminal");
+ }, [activeThreadRef, setTerminalOpen, terminalPanelOpen]);
const splitTerminal = useCallback(() => {
if (!activeThreadRef || hasReachedSplitLimit || !activeThreadId || !activeProject) {
return;
@@ -2348,8 +2317,12 @@ export default function ChatView(props: ChatViewProps) {
activeThreadRef
) {
try {
- await api.preview.open({ threadId: activeThreadId, url: script.previewUrl });
- useRightPanelStore.getState().open(activeThreadRef, "preview");
+ const snapshot = await api.preview.open({
+ threadId: activeThreadId,
+ url: script.previewUrl,
+ });
+ usePreviewStateStore.getState().applyServerSnapshot(activeThreadRef, snapshot);
+ useRightPanelStore.getState().openBrowser(activeThreadRef, snapshot.tabId);
} catch {
// Preview open failures are surfaced via the panel itself.
}
@@ -2579,8 +2552,96 @@ export default function ChatView(props: ChatViewProps) {
const closePreviewPanel = useCallback(() => {
if (!activeThreadRef) return;
useRightPanelStore.getState().close(activeThreadRef);
- }, [activeThreadRef]);
-
+ if (diffOpen) {
+ void navigate({
+ to: "/$environmentId/$threadId",
+ params: { environmentId, threadId },
+ replace: true,
+ search: (previous) => ({ ...stripDiffSearchParams(previous), diff: undefined }),
+ });
+ }
+ }, [activeThreadRef, diffOpen, environmentId, navigate, threadId]);
+ const activateRightPanelSurface = useCallback(
+ (surface: RightPanelSurface) => {
+ if (!activeThreadRef) return;
+ useRightPanelStore.getState().activateSurface(activeThreadRef, surface.id);
+ if (surface.kind === "preview" && surface.resourceId) {
+ usePreviewStateStore.getState().setActiveTab(activeThreadRef, surface.resourceId);
+ }
+ if (surface.kind === "terminal") {
+ setTerminalOpen(true);
+ }
+ if (surface.kind === "diff" && !diffOpen) {
+ onDiffPanelOpen?.();
+ void navigate({
+ to: "/$environmentId/$threadId",
+ params: { environmentId, threadId },
+ replace: true,
+ search: (previous) => ({ ...stripDiffSearchParams(previous), diff: "1" }),
+ });
+ } else if (surface.kind !== "diff" && diffOpen) {
+ void navigate({
+ to: "/$environmentId/$threadId",
+ params: { environmentId, threadId },
+ replace: true,
+ search: (previous) => ({ ...stripDiffSearchParams(previous), diff: undefined }),
+ });
+ }
+ },
+ [
+ activeThreadRef,
+ diffOpen,
+ environmentId,
+ navigate,
+ onDiffPanelOpen,
+ setTerminalOpen,
+ threadId,
+ ],
+ );
+ const toggleRightPanel = useCallback(() => {
+ if (!activeThreadRef) return;
+ if (rightPanelOpen) {
+ closePreviewPanel();
+ return;
+ }
+ const surface = rightPanelState.surfaces.at(-1) ?? null;
+ if (surface) {
+ activateRightPanelSurface(surface);
+ return;
+ }
+ createBrowserSurface();
+ }, [
+ activeThreadRef,
+ activateRightPanelSurface,
+ closePreviewPanel,
+ createBrowserSurface,
+ rightPanelOpen,
+ rightPanelState.surfaces,
+ ]);
+ const closeRightPanelSurface = useCallback(
+ (surface: RightPanelSurface) => {
+ if (!activeThreadRef) return;
+ useRightPanelStore.getState().closeSurface(activeThreadRef, surface.id);
+ if (surface.kind === "preview" && surface.resourceId) {
+ const api = readEnvironmentApi(activeThreadRef.environmentId);
+ void api?.preview
+ .close({ threadId: activeThreadRef.threadId, tabId: surface.resourceId })
+ .catch(() => undefined);
+ }
+ if (surface.kind === "terminal") {
+ setTerminalOpen(false);
+ }
+ if (surface.kind === "diff" && diffOpen) {
+ void navigate({
+ to: "/$environmentId/$threadId",
+ params: { environmentId, threadId },
+ replace: true,
+ search: (previous) => ({ ...stripDiffSearchParams(previous), diff: undefined }),
+ });
+ }
+ },
+ [activeThreadRef, diffOpen, environmentId, navigate, setTerminalOpen, threadId],
+ );
const persistThreadSettingsForNextTurn = useCallback(
async (input: {
threadId: ThreadId;
@@ -3952,314 +4013,323 @@ export default function ChatView(props: ChatViewProps) {
}
return (
- <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden bg-background">
- {/* Top bar */}
- <header
- className={cn(
- "border-b border-border",
- isElectron
- ? cn(
- "drag-region flex h-[52px] items-center px-3 sm:px-5 wco:h-[env(titlebar-area-height)]",
- reserveTitleBarControlInset &&
- "wco:pr-[calc(100vw-env(titlebar-area-width)-env(titlebar-area-x)+1em)]",
- )
- : "pb-2 pl-[calc(env(safe-area-inset-left)+0.75rem)] pr-[calc(env(safe-area-inset-right)+0.75rem)] pt-2 sm:pb-3 sm:pl-[calc(env(safe-area-inset-left)+1.25rem)] sm:pr-[calc(env(safe-area-inset-right)+1.25rem)] sm:pt-3",
- )}
- >
- <ChatHeader
- activeThreadEnvironmentId={activeThread.environmentId}
- activeThreadId={activeThread.id}
- {...(routeKind === "draft" && draftId ? { draftId } : {})}
- activeThreadTitle={activeThread.title}
- activeProjectName={activeProject?.name}
- isGitRepo={isGitRepo}
- openInCwd={gitCwd}
- activeProjectScripts={activeProject?.scripts}
- preferredScriptId={
- activeProject ? (lastInvokedScriptByProjectId[activeProject.id] ?? null) : null
- }
- keybindings={keybindings}
- availableEditors={availableEditors}
- terminalAvailable={activeProject !== undefined}
- terminalOpen={terminalUiState.terminalOpen}
- terminalToggleShortcutLabel={terminalToggleShortcutLabel}
- diffToggleShortcutLabel={diffPanelShortcutLabel}
- previewAvailable={isPreviewSupportedInRuntime()}
- previewOpen={previewPanelOpen}
- previewToggleShortcutLabel={previewPanelShortcutLabel}
- gitCwd={gitCwd}
- diffOpen={diffOpen}
- onRunProjectScript={runProjectScript}
- onAddProjectScript={saveProjectScript}
- onUpdateProjectScript={updateProjectScript}
- onDeleteProjectScript={deleteProjectScript}
- onToggleTerminal={toggleTerminalVisibility}
- onTogglePreview={onTogglePreview}
- onToggleDiff={onToggleDiff}
+ <div className="flex min-h-0 min-w-0 flex-1 overflow-hidden bg-background">
+ {isElectron && activeThreadRef ? (
+ <PreviewAutomationOwner threadRef={activeThreadRef} visible={previewPanelOpen} />
+ ) : null}
+ <div className="flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden">
+ {/* Top bar */}
+ <header
+ className={cn(
+ "border-b border-border",
+ isElectron
+ ? cn(
+ "drag-region flex h-[52px] items-center px-3 sm:px-5 wco:h-[env(titlebar-area-height)]",
+ reserveTitleBarControlInset &&
+ "wco:pr-[calc(100vw-env(titlebar-area-width)-env(titlebar-area-x)+1em)]",
+ )
+ : "pb-2 pl-[calc(env(safe-area-inset-left)+0.75rem)] pr-[calc(env(safe-area-inset-right)+0.75rem)] pt-2 sm:pb-3 sm:pl-[calc(env(safe-area-inset-left)+1.25rem)] sm:pr-[calc(env(safe-area-inset-right)+1.25rem)] sm:pt-3",
+ )}
+ >
+ <ChatHeader
+ activeThreadEnvironmentId={activeThread.environmentId}
+ activeThreadId={activeThread.id}
+ {...(routeKind === "draft" && draftId ? { draftId } : {})}
+ activeThreadTitle={activeThread.title}
+ activeProjectName={activeProject?.name}
+ openInCwd={gitCwd}
+ activeProjectScripts={activeProject?.scripts}
+ preferredScriptId={
+ activeProject ? (lastInvokedScriptByProjectId[activeProject.id] ?? null) : null
+ }
+ keybindings={keybindings}
+ availableEditors={availableEditors}
+ rightPanelAvailable={isPreviewSupportedInRuntime() || isGitRepo}
+ rightPanelOpen={rightPanelOpen}
+ gitCwd={gitCwd}
+ onRunProjectScript={runProjectScript}
+ onAddProjectScript={saveProjectScript}
+ onUpdateProjectScript={updateProjectScript}
+ onDeleteProjectScript={deleteProjectScript}
+ onToggleRightPanel={toggleRightPanel}
+ />
+ </header>
+
+ {/* Error banner */}
+ <ProviderStatusBanner status={activeProviderStatus} />
+ <ThreadErrorBanner
+ error={activeThread.error}
+ onDismiss={() => setThreadError(activeThread.id, null)}
/>
- </header>
+ {/* Main content area with optional plan sidebar */}
+ <div className="flex min-h-0 min-w-0 flex-1">
+ {/* Chat column */}
+ <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+ {/* Messages Wrapper */}
+ <div className="relative flex min-h-0 flex-1 flex-col">
+ {/* Messages — LegendList handles virtualization and scrolling internally */}
+ <MessagesTimeline
+ key={activeThread.id}
+ isWorking={isWorking}
+ activeTurnInProgress={isWorking || !latestTurnSettled}
+ activeTurnStartedAt={activeWorkStartedAt}
+ listRef={legendListRef}
+ timelineEntries={timelineEntries}
+ latestTurn={activeLatestTurn}
+ turnDiffSummaryByAssistantMessageId={turnDiffSummaryByAssistantMessageId}
+ activeThreadEnvironmentId={activeThread.environmentId}
+ routeThreadKey={routeThreadKey}
+ onOpenTurnDiff={onOpenTurnDiff}
+ revertTurnCountByUserMessageId={revertTurnCountByUserMessageId}
+ onRevertUserMessage={onRevertUserMessage}
+ isRevertingCheckpoint={isRevertingCheckpoint}
+ onImageExpand={onExpandTimelineImage}
+ markdownCwd={gitCwd ?? undefined}
+ resolvedTheme={resolvedTheme}
+ timestampFormat={timestampFormat}
+ workspaceRoot={activeWorkspaceRoot}
+ skills={activeProviderStatus?.skills ?? EMPTY_PROVIDER_SKILLS}
+ onIsAtEndChange={onIsAtEndChange}
+ />
- {/* Error banner */}
- <ProviderStatusBanner status={activeProviderStatus} />
- <ThreadErrorBanner
- error={activeThread.error}
- onDismiss={() => setThreadError(activeThread.id, null)}
- />
- {/* Main content area with optional plan sidebar */}
- <div className="flex min-h-0 min-w-0 flex-1">
- {/* Chat column */}
- <div className="flex min-h-0 min-w-0 flex-1 flex-col">
- {/* Messages Wrapper */}
- <div className="relative flex min-h-0 flex-1 flex-col">
- {/* Messages — LegendList handles virtualization and scrolling internally */}
- <MessagesTimeline
- key={activeThread.id}
- isWorking={isWorking}
- activeTurnInProgress={isWorking || !latestTurnSettled}
- activeTurnStartedAt={activeWorkStartedAt}
- listRef={legendListRef}
- timelineEntries={timelineEntries}
- latestTurn={activeLatestTurn}
- turnDiffSummaryByAssistantMessageId={turnDiffSummaryByAssistantMessageId}
- activeThreadEnvironmentId={activeThread.environmentId}
- routeThreadKey={routeThreadKey}
- onOpenTurnDiff={onOpenTurnDiff}
- revertTurnCountByUserMessageId={revertTurnCountByUserMessageId}
- onRevertUserMessage={onRevertUserMessage}
- isRevertingCheckpoint={isRevertingCheckpoint}
- onImageExpand={onExpandTimelineImage}
- markdownCwd={gitCwd ?? undefined}
- resolvedTheme={resolvedTheme}
- timestampFormat={timestampFormat}
- workspaceRoot={activeWorkspaceRoot}
- skills={activeProviderStatus?.skills ?? EMPTY_PROVIDER_SKILLS}
- onIsAtEndChange={onIsAtEndChange}
- />
-
- {/* scroll to bottom pill — shown when user has scrolled away from the bottom */}
- {showScrollToBottom && (
- <div className="pointer-events-none absolute bottom-1 left-1/2 z-30 flex -translate-x-1/2 justify-center py-1.5">
- <button
- type="button"
- onClick={() => scrollToEnd(true)}
- className="pointer-events-auto flex items-center gap-1.5 rounded-full border border-border/60 bg-card px-3 py-1 text-muted-foreground text-xs shadow-sm transition-colors hover:border-border hover:text-foreground hover:cursor-pointer"
- >
- <ChevronDownIcon className="size-3.5" />
- Scroll to bottom
- </button>
- </div>
- )}
- </div>
+ {/* scroll to bottom pill — shown when user has scrolled away from the bottom */}
+ {showScrollToBottom && (
+ <div className="pointer-events-none absolute bottom-1 left-1/2 z-30 flex -translate-x-1/2 justify-center py-1.5">
+ <button
+ type="button"
+ onClick={() => scrollToEnd(true)}
+ className="pointer-events-auto flex items-center gap-1.5 rounded-full border border-border/60 bg-card px-3 py-1 text-muted-foreground text-xs shadow-sm transition-colors hover:border-border hover:text-foreground hover:cursor-pointer"
+ >
+ <ChevronDownIcon className="size-3.5" />
+ Scroll to bottom
+ </button>
+ </div>
+ )}
+ </div>
- {/* Input bar */}
- <div
- className={cn(
- "pl-[calc(env(safe-area-inset-left)+0.75rem)] pr-[calc(env(safe-area-inset-right)+0.75rem)] pt-1.5 sm:pl-[calc(env(safe-area-inset-left)+1.25rem)] sm:pr-[calc(env(safe-area-inset-right)+1.25rem)] sm:pt-2",
- isGitRepo
- ? "pb-[calc(env(safe-area-inset-bottom)+0.25rem)]"
- : "pb-[calc(env(safe-area-inset-bottom)+0.75rem)] sm:pb-[calc(env(safe-area-inset-bottom)+1rem)]",
- )}
- >
- <div className="relative isolate">
- <ComposerBannerStack className="relative z-0" items={composerBannerItems} />
- <div className="relative z-10">
- <ChatComposer
- composerRef={composerRef}
- composerDraftTarget={composerDraftTarget}
- environmentId={environmentId}
- routeKind={routeKind}
- routeThreadRef={routeThreadRef}
- draftId={draftId}
- activeThreadId={activeThreadId}
- activeThreadEnvironmentId={activeThread?.environmentId}
- activeThread={activeThread}
- isServerThread={isServerThread}
- isLocalDraftThread={isLocalDraftThread}
- phase={phase}
- isConnecting={isConnecting}
- isSendBusy={isSendBusy}
- isPreparingWorktree={isPreparingWorktree}
- environmentUnavailable={activeEnvironmentUnavailableState}
- activePendingApproval={activePendingApproval}
- pendingApprovals={pendingApprovals}
- pendingUserInputs={pendingUserInputs}
- activePendingProgress={activePendingProgress}
- activePendingResolvedAnswers={activePendingResolvedAnswers}
- activePendingIsResponding={activePendingIsResponding}
- activePendingDraftAnswers={activePendingDraftAnswers}
- activePendingQuestionIndex={activePendingQuestionIndex}
- respondingRequestIds={respondingRequestIds}
- showPlanFollowUpPrompt={showPlanFollowUpPrompt}
- activeProposedPlan={activeProposedPlan}
- activePlan={activePlan as { turnId?: TurnId } | null}
- sidebarProposedPlan={sidebarProposedPlan as { turnId?: TurnId } | null}
- planSidebarLabel={planSidebarLabel}
- planSidebarOpen={planSidebarOpen}
- runtimeMode={runtimeMode}
- interactionMode={interactionMode}
- lockedProvider={lockedProvider}
- providerStatuses={providerStatuses as ServerProvider[]}
- activeProjectDefaultModelSelection={activeProject?.defaultModelSelection}
- activeThreadModelSelection={activeThread?.modelSelection}
- activeThreadActivities={activeThread?.activities}
- resolvedTheme={resolvedTheme}
- settings={settings}
- keybindings={keybindings}
- terminalOpen={Boolean(terminalUiState.terminalOpen)}
- gitCwd={gitCwd}
- promptRef={promptRef}
- composerImagesRef={composerImagesRef}
- composerTerminalContextsRef={composerTerminalContextsRef}
- composerElementContextsRef={composerElementContextsRef}
- shouldAutoScrollRef={isAtEndRef}
- scheduleStickToBottom={scrollToEnd}
- onSend={onSend}
- onInterrupt={onInterrupt}
- onImplementPlanInNewThread={onImplementPlanInNewThread}
- onRespondToApproval={onRespondToApproval}
- onSelectActivePendingUserInputOption={onSelectActivePendingUserInputOption}
- onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
- onPreviousActivePendingUserInputQuestion={
- onPreviousActivePendingUserInputQuestion
- }
- onChangeActivePendingUserInputCustomAnswer={
- onChangeActivePendingUserInputCustomAnswer
- }
- onProviderModelSelect={onProviderModelSelect}
- getModelDisabledReason={getModelDisabledReason}
- toggleInteractionMode={toggleInteractionMode}
- handleRuntimeModeChange={handleRuntimeModeChange}
- handleInteractionModeChange={handleInteractionModeChange}
- togglePlanSidebar={togglePlanSidebar}
- focusComposer={focusComposer}
- scheduleComposerFocus={scheduleComposerFocus}
- setThreadError={setThreadError}
- onExpandImage={onExpandTimelineImage}
- />
+ {/* Input bar */}
+ <div
+ className={cn(
+ "pl-[calc(env(safe-area-inset-left)+0.75rem)] pr-[calc(env(safe-area-inset-right)+0.75rem)] pt-1.5 sm:pl-[calc(env(safe-area-inset-left)+1.25rem)] sm:pr-[calc(env(safe-area-inset-right)+1.25rem)] sm:pt-2",
+ isGitRepo
+ ? "pb-[calc(env(safe-area-inset-bottom)+0.25rem)]"
+ : "pb-[calc(env(safe-area-inset-bottom)+0.75rem)] sm:pb-[calc(env(safe-area-inset-bottom)+1rem)]",
+ )}
+ >
+ <div className="relative isolate">
+ <ComposerBannerStack className="relative z-0" items={composerBannerItems} />
+ <div className="relative z-10">
+ <ChatComposer
+ composerRef={composerRef}
+ composerDraftTarget={composerDraftTarget}
+ environmentId={environmentId}
+ routeKind={routeKind}
+ routeThreadRef={routeThreadRef}
+ draftId={draftId}
+ activeThreadId={activeThreadId}
+ activeThreadEnvironmentId={activeThread?.environmentId}
+ activeThread={activeThread}
+ isServerThread={isServerThread}
+ isLocalDraftThread={isLocalDraftThread}
+ phase={phase}
+ isConnecting={isConnecting}
+ isSendBusy={isSendBusy}
+ isPreparingWorktree={isPreparingWorktree}
+ environmentUnavailable={activeEnvironmentUnavailableState}
+ activePendingApproval={activePendingApproval}
+ pendingApprovals={pendingApprovals}
+ pendingUserInputs={pendingUserInputs}
+ activePendingProgress={activePendingProgress}
+ activePendingResolvedAnswers={activePendingResolvedAnswers}
+ activePendingIsResponding={activePendingIsResponding}
+ activePendingDraftAnswers={activePendingDraftAnswers}
+ activePendingQuestionIndex={activePendingQuestionIndex}
+ respondingRequestIds={respondingRequestIds}
+ showPlanFollowUpPrompt={showPlanFollowUpPrompt}
+ activeProposedPlan={activeProposedPlan}
+ activePlan={activePlan as { turnId?: TurnId } | null}
+ sidebarProposedPlan={sidebarProposedPlan as { turnId?: TurnId } | null}
+ planSidebarLabel={planSidebarLabel}
+ planSidebarOpen={planSidebarOpen}
+ runtimeMode={runtimeMode}
+ interactionMode={interactionMode}
+ lockedProvider={lockedProvider}
+ providerStatuses={providerStatuses as ServerProvider[]}
+ activeProjectDefaultModelSelection={activeProject?.defaultModelSelection}
+ activeThreadModelSelection={activeThread?.modelSelection}
+ activeThreadActivities={activeThread?.activities}
+ resolvedTheme={resolvedTheme}
+ settings={settings}
+ keybindings={keybindings}
+ terminalOpen={Boolean(terminalUiState.terminalOpen)}
+ gitCwd={gitCwd}
+ promptRef={promptRef}
+ composerImagesRef={composerImagesRef}
+ composerTerminalContextsRef={composerTerminalContextsRef}
+ composerElementContextsRef={composerElementContextsRef}
+ shouldAutoScrollRef={isAtEndRef}
+ scheduleStickToBottom={scrollToEnd}
+ onSend={onSend}
+ onInterrupt={onInterrupt}
+ onImplementPlanInNewThread={onImplementPlanInNewThread}
+ onRespondToApproval={onRespondToApproval}
+ onSelectActivePendingUserInputOption={onSelectActivePendingUserInputOption}
+ onAdvanceActivePendingUserInput={onAdvanceActivePendingUserInput}
+ onPreviousActivePendingUserInputQuestion={
+ onPreviousActivePendingUserInputQuestion
+ }
+ onChangeActivePendingUserInputCustomAnswer={
+ onChangeActivePendingUserInputCustomAnswer
+ }
+ onProviderModelSelect={onProviderModelSelect}
+ getModelDisabledReason={getModelDisabledReason}
+ toggleInteractionMode={toggleInteractionMode}
+ handleRuntimeModeChange={handleRuntimeModeChange}
+ handleInteractionModeChange={handleInteractionModeChange}
+ togglePlanSidebar={togglePlanSidebar}
+ focusComposer={focusComposer}
+ scheduleComposerFocus={scheduleComposerFocus}
+ setThreadError={setThreadError}
+ onExpandImage={onExpandTimelineImage}
+ />
+ </div>
</div>
+ {isGitRepo && (
+ <BranchToolbar
+ environmentId={activeThread.environmentId}
+ threadId={activeThread.id}
+ {...(routeKind === "draft" && draftId ? { draftId } : {})}
+ onEnvModeChange={onEnvModeChange}
+ {...(canOverrideServerThreadEnvMode ? { effectiveEnvModeOverride: envMode } : {})}
+ {...(canOverrideServerThreadEnvMode
+ ? {
+ activeThreadBranchOverride: activeThreadBranch,
+ onActiveThreadBranchOverrideChange: setPendingServerThreadBranch,
+ }
+ : {})}
+ envLocked={envLocked}
+ onComposerFocusRequest={scheduleComposerFocus}
+ {...(canCheckoutPullRequestIntoThread
+ ? { onCheckoutPullRequestRequest: openPullRequestDialog }
+ : {})}
+ {...(hasMultipleEnvironments ? { onEnvironmentChange } : {})}
+ availableEnvironments={logicalProjectEnvironments}
+ />
+ )}
</div>
- {isGitRepo && (
- <BranchToolbar
+
+ {pullRequestDialogState ? (
+ <PullRequestThreadDialog
+ key={pullRequestDialogState.key}
+ open
environmentId={activeThread.environmentId}
threadId={activeThread.id}
- {...(routeKind === "draft" && draftId ? { draftId } : {})}
- onEnvModeChange={onEnvModeChange}
- {...(canOverrideServerThreadEnvMode ? { effectiveEnvModeOverride: envMode } : {})}
- {...(canOverrideServerThreadEnvMode
- ? {
- activeThreadBranchOverride: activeThreadBranch,
- onActiveThreadBranchOverrideChange: setPendingServerThreadBranch,
- }
- : {})}
- envLocked={envLocked}
- onComposerFocusRequest={scheduleComposerFocus}
- {...(canCheckoutPullRequestIntoThread
- ? { onCheckoutPullRequestRequest: openPullRequestDialog }
- : {})}
- {...(hasMultipleEnvironments ? { onEnvironmentChange } : {})}
- availableEnvironments={logicalProjectEnvironments}
+ cwd={activeProject?.cwd ?? null}
+ initialReference={pullRequestDialogState.initialReference}
+ onOpenChange={(open) => {
+ if (!open) {
+ closePullRequestDialog();
+ }
+ }}
+ onPrepared={handlePreparedPullRequestThread}
/>
- )}
+ ) : null}
</div>
-
- {pullRequestDialogState ? (
- <PullRequestThreadDialog
- key={pullRequestDialogState.key}
- open
- environmentId={activeThread.environmentId}
- threadId={activeThread.id}
- cwd={activeProject?.cwd ?? null}
- initialReference={pullRequestDialogState.initialReference}
- onOpenChange={(open) => {
- if (!open) {
- closePullRequestDialog();
- }
- }}
- onPrepared={handlePreparedPullRequestThread}
- />
- ) : null}
+ {/* end chat column */}
</div>
- {/* end chat column */}
-
- {planSidebarOpen && !shouldUsePlanSidebarSheet ? (
- <PlanSidebar
- activePlan={activePlan}
- activeProposedPlan={sidebarProposedPlan}
- label={planSidebarLabel}
- environmentId={environmentId}
- markdownCwd={gitCwd ?? undefined}
- workspaceRoot={activeWorkspaceRoot}
- timestampFormat={timestampFormat}
- mode="sidebar"
- onClose={closePlanSidebar}
- />
- ) : null}
- {!shouldUsePlanSidebarSheet
- ? mountedPreviewThreadRefs.map(
- ({ key: mountedThreadKey, threadRef: mountedThreadRef }) => {
- const visible = previewPanelOpen && mountedThreadKey === activeThreadKey;
- return (
- <div
- key={mountedThreadKey}
- className={cn(
- visible
- ? "contents"
- : "pointer-events-none fixed -left-[10000px] top-0 h-px w-px overflow-hidden opacity-0",
- )}
- aria-hidden={visible ? undefined : true}
- >
- <Suspense fallback={null}>
- <PreviewPanel mode="inline" threadRef={mountedThreadRef} visible={visible} />
- </Suspense>
- </div>
- );
- },
- )
- : null}
+ {/* end horizontal flex container */}
</div>
- {/* end horizontal flex container */}
- {activeThreadRef ? (
- <PreviewAutomationOwner threadRef={activeThreadRef} visible={previewPanelOpen} />
+ {!shouldUsePlanSidebarSheet &&
+ rightPanelOpen &&
+ activeThreadRef &&
+ activeRightPanelSurface ? (
+ <RightPanelTabs
+ mode="inline"
+ surfaces={rightPanelState.surfaces}
+ activeSurfaceId={activeRightPanelSurface.id}
+ previewSessions={activePreviewState.sessions}
+ onActivate={activateRightPanelSurface}
+ onCloseSurface={closeRightPanelSurface}
+ onAddBrowser={createBrowserSurface}
+ onAddDiff={addDiffSurface}
+ diffAvailable={isServerThread && isGitRepo}
+ >
+ {activeRightPanelSurface.kind === "preview" ? (
+ <Suspense fallback={null}>
+ <PreviewPanel
+ mode="embedded"
+ threadRef={activeThreadRef}
+ tabId={activeRightPanelSurface.resourceId}
+ visible
+ />
+ </Suspense>
+ ) : activeRightPanelSurface.kind === "diff" ? (
+ <DiffWorkerPoolProvider>
+ <Suspense fallback={null}>
+ <DiffPanel mode="embedded" />
+ </Suspense>
+ </DiffWorkerPoolProvider>
+ ) : null}
+ </RightPanelTabs>
) : null}
- {mountedTerminalThreadRefs.map(({ key: mountedThreadKey, threadRef: mountedThreadRef }) => (
- <PersistentThreadTerminalDrawer
- key={mountedThreadKey}
- threadRef={mountedThreadRef}
- threadId={mountedThreadRef.threadId}
- visible={mountedThreadKey === activeThreadKey && terminalUiState.terminalOpen}
- launchContext={
- mountedThreadKey === activeThreadKey ? (activeTerminalLaunchContext ?? null) : null
- }
- focusRequestId={mountedThreadKey === activeThreadKey ? terminalFocusRequestId : 0}
- splitShortcutLabel={splitTerminalShortcutLabel ?? undefined}
- newShortcutLabel={newTerminalShortcutLabel ?? undefined}
- closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}
- keybindings={keybindings}
- onAddTerminalContext={addTerminalContextToDraft}
- />
- ))}
- {shouldUsePlanSidebarSheet && previewPanelOpen && activeThreadRef ? (
+ {shouldUsePlanSidebarSheet && rightPanelOpen && activeThreadRef && activeRightPanelSurface ? (
<RightPanelSheet open onClose={closePreviewPanel}>
- <Suspense fallback={null}>
- <PreviewPanel mode="sheet" threadRef={activeThreadRef} visible />
- </Suspense>
- </RightPanelSheet>
- ) : null}
- {shouldUsePlanSidebarSheet ? (
- <RightPanelSheet open={planSidebarOpen} onClose={closePlanSidebar}>
- <PlanSidebar
- activePlan={activePlan}
- activeProposedPlan={sidebarProposedPlan}
- label={planSidebarLabel}
- environmentId={environmentId}
- markdownCwd={gitCwd ?? undefined}
- workspaceRoot={activeWorkspaceRoot}
- timestampFormat={timestampFormat}
+ <RightPanelTabs
mode="sheet"
- onClose={closePlanSidebar}
- />
+ surfaces={rightPanelState.surfaces}
+ activeSurfaceId={activeRightPanelSurface.id}
+ previewSessions={activePreviewState.sessions}
+ onActivate={activateRightPanelSurface}
+ onCloseSurface={closeRightPanelSurface}
+ onAddBrowser={createBrowserSurface}
+ onAddDiff={addDiffSurface}
+ diffAvailable={isServerThread && isGitRepo}
+ >
+ {activeRightPanelSurface.kind === "preview" ? (
+ <Suspense fallback={null}>
+ <PreviewPanel
+ mode="embedded"
+ threadRef={activeThreadRef}
+ tabId={activeRightPanelSurface.resourceId}
+ visible
+ />
+ </Suspense>
+ ) : activeRightPanelSurface.kind === "terminal" ? (
+ <PersistentThreadTerminalDrawer
+ threadRef={activeThreadRef}
+ threadId={activeThreadRef.threadId}
+ visible
+ mode="panel"
+ launchContext={activeTerminalLaunchContext ?? null}
+ focusRequestId={terminalFocusRequestId}
+ splitShortcutLabel={splitTerminalShortcutLabel ?? undefined}
+ newShortcutLabel={newTerminalShortcutLabel ?? undefined}
+ closeShortcutLabel={closeTerminalShortcutLabel ?? undefined}
+ keybindings={keybindings}
+ onAddTerminalContext={addTerminalContextToDraft}
+ />
+ ) : activeRightPanelSurface.kind === "diff" ? (
+ <DiffWorkerPoolProvider>
+ <Suspense fallback={null}>
+ <DiffPanel mode="embedded" />
+ </Suspense>
+ </DiffWorkerPoolProvider>
+ ) : (
+ <PlanSidebar
+ activePlan={activePlan}
+ activeProposedPlan={sidebarProposedPlan}
+ label={planSidebarLabel}
+ environmentId={environmentId}
+ markdownCwd={gitCwd ?? undefined}
+ workspaceRoot={activeWorkspaceRoot}
+ timestampFormat={timestampFormat}
+ mode="embedded"
+ onClose={closePlanSidebar}
+ />
+ )}
+ </RightPanelTabs>
</RightPanelSheet>
) : null}
diff --git a/apps/web/src/components/DiffPanelShell.tsx b/apps/web/src/components/DiffPanelShell.tsx
index 829ed4159..6a2219d61 100644
--- a/apps/web/src/components/DiffPanelShell.tsx
+++ b/apps/web/src/components/DiffPanelShell.tsx
@@ -5,10 +5,10 @@ import { cn } from "~/lib/utils";
import { Skeleton } from "./ui/skeleton";
-export type DiffPanelMode = "inline" | "sheet" | "sidebar";
+export type DiffPanelMode = "inline" | "sheet" | "sidebar" | "embedded";
function getDiffPanelHeaderRowClassName(mode: DiffPanelMode) {
- const shouldUseDragRegion = isElectron && mode !== "sheet";
+ const shouldUseDragRegion = isElectron && mode !== "sheet" && mode !== "embedded";
return cn(
"flex items-center justify-between gap-2 px-4",
shouldUseDragRegion
@@ -22,7 +22,7 @@ export function DiffPanelShell(props: {
header: ReactNode;
children: ReactNode;
}) {
- const shouldUseDragRegion = isElectron && props.mode !== "sheet";
+ const shouldUseDragRegion = isElectron && props.mode !== "sheet" && props.mode !== "embedded";
return (
<div
diff --git a/apps/web/src/components/PlanSidebar.tsx b/apps/web/src/components/PlanSidebar.tsx
index 62bd1ba89..e87361c92 100644
--- a/apps/web/src/components/PlanSidebar.tsx
+++ b/apps/web/src/components/PlanSidebar.tsx
@@ -59,7 +59,7 @@ interface PlanSidebarProps {
markdownCwd: string | undefined;
workspaceRoot: string | undefined;
timestampFormat: TimestampFormat;
- mode?: "sheet" | "sidebar";
+ mode?: "sheet" | "sidebar" | "embedded";
onClose: () => void;
}
diff --git a/apps/web/src/components/RightPanelTabs.tsx b/apps/web/src/components/RightPanelTabs.tsx
new file mode 100644
index 000000000..af2d118e8
--- /dev/null
+++ b/apps/web/src/components/RightPanelTabs.tsx
@@ -0,0 +1,148 @@
+import type { PreviewSessionSnapshot } from "@t3tools/contracts";
+import { ClipboardList, FileDiff, Globe2, Plus, TerminalSquare, X } from "lucide-react";
+import { type ReactNode, useState } from "react";
+
+import type { RightPanelSurface } from "~/rightPanelStore";
+import { cn } from "~/lib/utils";
+import { Menu, MenuItem, MenuPopup, MenuTrigger } from "~/components/ui/menu";
+import { faviconUrlForOrigin } from "~/lib/favicon";
+
+import { PreviewPanelShell, type PreviewPanelMode } from "./preview/PreviewPanelShell";
+
+interface RightPanelTabsProps {
+ mode: PreviewPanelMode;
+ surfaces: readonly RightPanelSurface[];
+ activeSurfaceId: string;
+ previewSessions: Readonly<Record<string, PreviewSessionSnapshot>>;
+ onActivate: (surface: RightPanelSurface) => void;
+ onCloseSurface: (surface: RightPanelSurface) => void;
+ onAddBrowser: () => void;
+ onAddDiff: () => void;
+ diffAvailable: boolean;
+ children: ReactNode;
+}
+
+function surfaceTitle(
+ surface: RightPanelSurface,
+ sessions: Readonly<Record<string, PreviewSessionSnapshot>>,
+): string {
+ switch (surface.kind) {
+ case "diff":
+ return "Diff";
+ case "terminal":
+ return "Terminal";
+ case "plan":
+ return "Plan";
+ case "preview": {
+ const snapshot = surface.resourceId ? sessions[surface.resourceId] : null;
+ if (!snapshot || snapshot.navStatus._tag === "Idle") return "Browser";
+ if (snapshot.navStatus.title.trim().length > 0) return snapshot.navStatus.title;
+ try {
+ return new URL(snapshot.navStatus.url).host || "Browser";
+ } catch {
+ return "Browser";
+ }
+ }
+ }
+}
+
+function PreviewFavicon({ url }: { url: string | null }) {
+ const faviconUrl = faviconUrlForOrigin(url, 32);
+ const [failedUrl, setFailedUrl] = useState<string | null>(null);
+ if (!faviconUrl || failedUrl === faviconUrl) return <Globe2 className="size-3.5 shrink-0" />;
+ return (
+ <img
+ src={faviconUrl}
+ alt=""
+ aria-hidden
+ draggable={false}
+ className="size-3.5 shrink-0 rounded-sm"
+ onError={() => setFailedUrl(faviconUrl)}
+ />
+ );
+}
+
+function SurfaceIcon({
+ surface,
+ sessions,
+}: {
+ surface: RightPanelSurface;
+ sessions: Readonly<Record<string, PreviewSessionSnapshot>>;
+}) {
+ switch (surface.kind) {
+ case "preview": {
+ const snapshot = surface.resourceId ? sessions[surface.resourceId] : null;
+ const url = !snapshot || snapshot.navStatus._tag === "Idle" ? null : snapshot.navStatus.url;
+ return <PreviewFavicon url={url} />;
+ }
+ case "diff":
+ return <FileDiff className="size-3.5 shrink-0" />;
+ case "terminal":
+ return <TerminalSquare className="size-3.5 shrink-0" />;
+ case "plan":
+ return <ClipboardList className="size-3.5 shrink-0" />;
+ }
+}
+
+export function RightPanelTabs(props: RightPanelTabsProps) {
+ return (
+ <PreviewPanelShell mode={props.mode}>
+ <div className="flex h-10 shrink-0 items-center px-2">
+ <div className="flex min-w-0 flex-1 items-center gap-1 overflow-x-auto">
+ {props.surfaces.map((surface) => {
+ const active = surface.id === props.activeSurfaceId;
+ const title = surfaceTitle(surface, props.previewSessions);
+ return (
+ <div
+ key={surface.id}
+ className={cn(
+ "group flex h-7 min-w-0 max-w-52 items-center gap-1.5 rounded-md px-2 text-sm",
+ active
+ ? "bg-accent text-foreground"
+ : "text-muted-foreground hover:bg-accent/60 hover:text-foreground",
+ )}
+ >
+ <button
+ type="button"
+ className="flex min-w-0 flex-1 items-center gap-1.5"
+ onClick={() => props.onActivate(surface)}
+ title={title}
+ >
+ <SurfaceIcon surface={surface} sessions={props.previewSessions} />
+ <span className="truncate">{title}</span>
+ </button>
+ <button
+ type="button"
+ className="rounded p-0.5 opacity-0 hover:bg-muted group-hover:opacity-100 focus:opacity-100"
+ aria-label={`Close ${title}`}
+ onClick={() => props.onCloseSurface(surface)}
+ >
+ <X className="size-3" />
+ </button>
+ </div>
+ );
+ })}
+ </div>
+ <Menu>
+ <MenuTrigger
+ className="relative ml-1 inline-flex size-7 shrink-0 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground"
+ aria-label="Add panel surface"
+ >
+ <Plus className="size-4" />
+ </MenuTrigger>
+ <MenuPopup align="start" side="bottom" sideOffset={6} className="min-w-44">
+ <MenuItem onClick={props.onAddBrowser}>
+ <Globe2 />
+ Browser
+ </MenuItem>
+ <MenuItem onClick={props.onAddDiff} disabled={!props.diffAvailable}>
+ <FileDiff />
+ Diff
+ </MenuItem>
+ </MenuPopup>
+ </Menu>
+ </div>
+ <div className="flex min-h-0 flex-1 flex-col">{props.children}</div>
+ </PreviewPanelShell>
+ );
+}
diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsx
index 0213aa0b0..c4757cb34 100644
--- a/apps/web/src/components/ThreadTerminalDrawer.tsx
+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx
@@ -20,6 +20,7 @@ import {
useState,
} from "react";
import { Popover, PopoverPopup, PopoverTrigger } from "~/components/ui/popover";
+import { cn } from "~/lib/utils";
import { type TerminalContextSelection } from "~/lib/terminalContext";
import { openInPreferredEditor } from "../editorPreferences";
import {
@@ -791,6 +792,7 @@ export function TerminalViewport({
}
interface ThreadTerminalDrawerProps {
+ mode?: "drawer" | "panel";
threadRef: ScopedThreadRef;
threadId: ThreadId;
cwd: string;
@@ -849,6 +851,7 @@ function TerminalActionButton({ label, className, onClick, children }: TerminalA
}
export default function ThreadTerminalDrawer({
+ mode = "drawer",
threadRef,
threadId,
cwd,
@@ -874,6 +877,7 @@ export default function ThreadTerminalDrawer({
terminalLabelsById,
terminalLaunchLocationsById,
}: ThreadTerminalDrawerProps) {
+ const isPanel = mode === "panel";
const [drawerHeight, setDrawerHeight] = useState(() => clampDrawerHeight(height));
const [resizeEpoch, setResizeEpoch] = useState(0);
const drawerHeightRef = useRef(drawerHeight);
@@ -1139,16 +1143,21 @@ export default function ThreadTerminalDrawer({
if (normalizedTerminalIds.length === 0) {
return (
<aside
- className="thread-terminal-drawer relative flex min-w-0 shrink-0 flex-col overflow-hidden border-t border-border/80 bg-background"
- style={{ height: `${drawerHeight}px` }}
+ className={cn(
+ "thread-terminal-drawer relative flex min-w-0 flex-col overflow-hidden bg-background",
+ isPanel ? "h-full flex-1" : "shrink-0 border-t border-border/80",
+ )}
+ style={isPanel ? undefined : { height: `${drawerHeight}px` }}
>
- <div
- className="absolute inset-x-0 top-0 z-20 h-1.5 cursor-row-resize"
- onPointerDown={handleResizePointerDown}
- onPointerMove={handleResizePointerMove}
- onPointerUp={handleResizePointerEnd}
- onPointerCancel={handleResizePointerEnd}
- />
+ {!isPanel ? (
+ <div
+ className="absolute inset-x-0 top-0 z-20 h-1.5 cursor-row-resize"
+ onPointerDown={handleResizePointerDown}
+ onPointerMove={handleResizePointerMove}
+ onPointerUp={handleResizePointerEnd}
+ onPointerCancel={handleResizePointerEnd}
+ />
+ ) : null}
<div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-3 px-4 py-6 text-center text-sm text-muted-foreground">
<p>No terminal sessions for this thread yet.</p>
<button
@@ -1167,16 +1176,21 @@ export default function ThreadTerminalDrawer({
return (
<aside
- className="thread-terminal-drawer relative flex min-w-0 shrink-0 flex-col overflow-hidden border-t border-border/80 bg-background"
- style={{ height: `${drawerHeight}px` }}
+ className={cn(
+ "thread-terminal-drawer relative flex min-w-0 flex-col overflow-hidden bg-background",
+ isPanel ? "h-full flex-1" : "shrink-0 border-t border-border/80",
+ )}
+ style={isPanel ? undefined : { height: `${drawerHeight}px` }}
>
- <div
- className="absolute inset-x-0 top-0 z-20 h-1.5 cursor-row-resize"
- onPointerDown={handleResizePointerDown}
- onPointerMove={handleResizePointerMove}
- onPointerUp={handleResizePointerEnd}
- onPointerCancel={handleResizePointerEnd}
- />
+ {!isPanel ? (
+ <div
+ className="absolute inset-x-0 top-0 z-20 h-1.5 cursor-row-resize"
+ onPointerDown={handleResizePointerDown}
+ onPointerMove={handleResizePointerMove}
+ onPointerUp={handleResizePointerEnd}
+ onPointerCancel={handleResizePointerEnd}
+ />
+ ) : null}
{!hasTerminalSidebar && (
<div className="pointer-events-none absolute right-2 top-2 z-20">
diff --git a/apps/web/src/components/chat/ChatHeader.tsx b/apps/web/src/components/chat/ChatHeader.tsx
index 2110b53d6..c035b2d77 100644
--- a/apps/web/src/components/chat/ChatHeader.tsx
+++ b/apps/web/src/components/chat/ChatHeader.tsx
@@ -9,7 +9,7 @@ import { scopeThreadRef } from "@t3tools/client-runtime";
import { memo } from "react";
import GitActionsControl from "../GitActionsControl";
import { type DraftId } from "~/composerDraftStore";
-import { DiffIcon, Globe, TerminalSquareIcon } from "lucide-react";
+import { PanelRightIcon } from "lucide-react";
import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
import ProjectScriptsControl, { type NewProjectScriptInput } from "../ProjectScriptsControl";
import { Toggle } from "../ui/toggle";
@@ -23,29 +23,19 @@ interface ChatHeaderProps {
draftId?: DraftId;
activeThreadTitle: string;
activeProjectName: string | undefined;
- isGitRepo: boolean;
openInCwd: string | null;
activeProjectScripts: ProjectScript[] | undefined;
preferredScriptId: string | null;
keybindings: ResolvedKeybindingsConfig;
availableEditors: ReadonlyArray<EditorId>;
- terminalAvailable: boolean;
- terminalOpen: boolean;
- terminalToggleShortcutLabel: string | null;
- diffToggleShortcutLabel: string | null;
- /** False on the web build; true only when the desktop preview bridge is present. */
- previewAvailable: boolean;
- previewOpen: boolean;
- previewToggleShortcutLabel: string | null;
+ rightPanelAvailable: boolean;
+ rightPanelOpen: boolean;
gitCwd: string | null;
- diffOpen: boolean;
onRunProjectScript: (script: ProjectScript) => void;
onAddProjectScript: (input: NewProjectScriptInput) => Promise<void>;
onUpdateProjectScript: (scriptId: string, input: NewProjectScriptInput) => Promise<void>;
onDeleteProjectScript: (scriptId: string) => Promise<void>;
- onToggleTerminal: () => void;
- onTogglePreview: () => void;
- onToggleDiff: () => void;
+ onToggleRightPanel: () => void;
}
export function shouldShowOpenInPicker(input: {
@@ -66,28 +56,19 @@ export const ChatHeader = memo(function ChatHeader({
draftId,
activeThreadTitle,
activeProjectName,
- isGitRepo,
openInCwd,
activeProjectScripts,
preferredScriptId,
keybindings,
availableEditors,
- terminalAvailable,
- terminalOpen,
- terminalToggleShortcutLabel,
- diffToggleShortcutLabel,
- previewAvailable,
- previewOpen,
- previewToggleShortcutLabel,
+ rightPanelAvailable,
+ rightPanelOpen,
gitCwd,
- diffOpen,
onRunProjectScript,
onAddProjectScript,
onUpdateProjectScript,
onDeleteProjectScript,
- onToggleTerminal,
- onTogglePreview,
- onToggleDiff,
+ onToggleRightPanel,
}: ChatHeaderProps) {
const primaryEnvironmentId = usePrimaryEnvironmentId();
const showOpenInPicker = shouldShowOpenInPicker({
@@ -145,70 +126,19 @@ export const ChatHeader = memo(function ChatHeader({
render={
<Toggle
className="shrink-0"
- pressed={terminalOpen}
- onPressedChange={onToggleTerminal}
- aria-label="Toggle terminal drawer"
+ pressed={rightPanelOpen}
+ onPressedChange={onToggleRightPanel}
+ aria-label="Toggle right panel"
variant="ghost"
size="xs"
- disabled={!terminalAvailable}
+ disabled={!rightPanelAvailable}
>
- <TerminalSquareIcon className="size-3" />
+ <PanelRightIcon className="size-3.5" />
</Toggle>
}
/>
<TooltipPopup side="bottom">
- {!terminalAvailable
- ? "Terminal is unavailable until this thread has an active project."
- : terminalToggleShortcutLabel
- ? `Toggle terminal drawer (${terminalToggleShortcutLabel})`
- : "Toggle terminal drawer"}
- </TooltipPopup>
- </Tooltip>
- {previewAvailable ? (
- <Tooltip>
- <TooltipTrigger
- render={
- <Toggle
- className="shrink-0"
- pressed={previewOpen}
- onPressedChange={onTogglePreview}
- aria-label="Toggle preview browser"
- variant="outline"
- size="xs"
- >
- <Globe className="size-3" />
- </Toggle>
- }
- />
- <TooltipPopup side="bottom">
- {previewToggleShortcutLabel
- ? `Toggle preview browser (${previewToggleShortcutLabel})`
- : "Toggle preview browser"}
- </TooltipPopup>
- </Tooltip>
- ) : null}
- <Tooltip>
- <TooltipTrigger
- render={
- <Toggle
- className="shrink-0"
- pressed={diffOpen}
- onPressedChange={onToggleDiff}
- aria-label="Toggle diff panel"
- variant="ghost"
- size="xs"
- disabled={!isGitRepo && !diffOpen}
- >
- <DiffIcon className="size-3" />
- </Toggle>
- }
- />
- <TooltipPopup side="bottom">
- {!isGitRepo && !diffOpen
- ? "Diff panel is unavailable because this project is not a git repository."
- : diffToggleShortcutLabel
- ? `Toggle diff panel (${diffToggleShortcutLabel})`
- : "Toggle diff panel"}
+ {rightPanelAvailable ? "Toggle right panel" : "Right panel is unavailable"}
</TooltipPopup>
</Tooltip>
</div>
diff --git a/apps/web/src/components/chat/MessagesTimeline.tsx b/apps/web/src/components/chat/MessagesTimeline.tsx
index 6629e0368..a56330c59 100644
--- a/apps/web/src/components/chat/MessagesTimeline.tsx
+++ b/apps/web/src/components/chat/MessagesTimeline.tsx
@@ -1377,23 +1377,28 @@ function buildToolCallExpandedBody(
workEntry: TimelineWorkEntry,
workspaceRoot: string | undefined,
): string | null {
+ const blocks: string[] = [];
+ if (workEntry.itemType === "mcp_tool_call" && workEntry.toolData !== undefined) {
+ blocks.push(`MCP call\n${JSON.stringify(workEntry.toolData, null, 2)}`);
+ }
const raw = workEntryRawCommand(workEntry);
if (raw?.trim()) {
- return raw.trim();
- }
- if (workEntry.command?.trim()) {
- return workEntry.command.trim();
+ blocks.push(raw.trim());
+ } else if (workEntry.command?.trim()) {
+ blocks.push(workEntry.command.trim());
}
if (workEntry.detail?.trim()) {
- return workEntry.detail.trim();
+ blocks.push(workEntry.detail.trim());
}
const changedFiles = workEntry.changedFiles ?? [];
if (changedFiles.length > 0) {
- return changedFiles
- .map((filePath) => formatWorkspaceRelativePath(filePath, workspaceRoot))
- .join("\n");
+ blocks.push(
+ changedFiles
+ .map((filePath) => formatWorkspaceRelativePath(filePath, workspaceRoot))
+ .join("\n"),
+ );
}
- return null;
+ return blocks.length > 0 ? blocks.join("\n\n") : null;
}
function workEntryIconName(workEntry: TimelineWorkEntry): WorkEntryIconName {
diff --git a/apps/web/src/components/preview/PreviewAutomationOwner.tsx b/apps/web/src/components/preview/PreviewAutomationOwner.tsx
index f9dabb587..fa8d1e3f7 100644
--- a/apps/web/src/components/preview/PreviewAutomationOwner.tsx
+++ b/apps/web/src/components/preview/PreviewAutomationOwner.tsx
@@ -10,15 +10,21 @@ import type {
PreviewAutomationStatus,
ScopedThreadRef,
} from "@t3tools/contracts";
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
import { ensureEnvironmentApi } from "~/environmentApi";
import { selectThreadPreviewState, usePreviewStateStore } from "~/previewStateStore";
import { useRightPanelStore } from "~/rightPanelStore";
+import { resolveBrowserNavigationTarget } from "~/browser/browserTargetResolver";
+import {
+ startBrowserRecording,
+ stopBrowserRecording,
+ useBrowserRecordingStore,
+} from "~/browser/browserRecording";
import { previewBridge } from "./previewBridge";
-const automationClientId =
+const newAutomationClientId = (): string =>
typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
? crypto.randomUUID()
: `preview-${Math.random().toString(36).slice(2)}`;
@@ -112,11 +118,14 @@ export function PreviewAutomationOwner(props: {
readonly visible: boolean;
}) {
const { threadRef, visible } = props;
+ const [automationClientId] = useState(newAutomationClientId);
const ownerStateRef = useRef({ threadRef, visible });
const handlerRef = useRef<(request: PreviewAutomationRequest) => Promise<unknown>>(
async () => undefined,
);
- ownerStateRef.current = { threadRef, visible };
+ useEffect(() => {
+ ownerStateRef.current = { threadRef, visible };
+ }, [threadRef, visible]);
const handleRequest = useCallback(
async (request: PreviewAutomationRequest): Promise<unknown> => {
@@ -136,9 +145,6 @@ export function PreviewAutomationOwner(props: {
return currentStatus(threadRef, visible);
case "open": {
const input = request.input as PreviewAutomationOpenInput;
- if (input.show ?? true) {
- useRightPanelStore.getState().open(threadRef, "preview");
- }
let activeTabId =
(input.reuseExistingTab ?? true) ? (state.snapshot?.tabId ?? null) : null;
if (!activeTabId) {
@@ -151,13 +157,20 @@ export function PreviewAutomationOwner(props: {
} else if (input.url && previewBridge) {
await previewBridge.navigate(activeTabId, input.url);
}
+ if (input.show ?? true) {
+ useRightPanelStore.getState().openBrowser(threadRef, activeTabId);
+ }
await waitForDesktopOverlay(threadRef, request.timeoutMs);
return currentStatus(threadRef, input.show ?? true);
}
case "navigate": {
if (!previewBridge || !tabId) throw new Error("Preview tab is not initialized.");
const input = request.input as PreviewAutomationNavigateInput;
- await previewBridge.navigate(tabId, input.url);
+ const resolution = resolveBrowserNavigationTarget(
+ threadRef.environmentId,
+ input.target ?? { kind: "url", url: input.url! },
+ );
+ await previewBridge.navigate(tabId, resolution.resolvedUrl);
await waitForNavigationReadiness(
tabId,
input.readiness ?? "load",
@@ -204,11 +217,28 @@ export function PreviewAutomationOwner(props: {
tabId,
request.input as Parameters<typeof previewBridge.automation.waitFor>[1],
);
+ case "recordingStart": {
+ if (!tabId) throw new Error("Preview tab is not initialized.");
+ await startBrowserRecording(tabId);
+ return {
+ tabId,
+ recording: true,
+ startedAt: useBrowserRecordingStore.getState().startedAt,
+ };
+ }
+ case "recordingStop": {
+ if (!tabId) throw new Error("Preview tab is not initialized.");
+ const artifact = await stopBrowserRecording(tabId);
+ if (!artifact) throw new Error("No active recording exists for this preview tab.");
+ return artifact;
+ }
}
},
[threadRef, visible],
);
- handlerRef.current = handleRequest;
+ useEffect(() => {
+ handlerRef.current = handleRequest;
+ }, [handleRequest]);
useEffect(() => {
const api = ensureEnvironmentApi(threadRef.environmentId);
@@ -249,7 +279,7 @@ export function PreviewAutomationOwner(props: {
},
},
);
- }, [threadRef.environmentId]);
+ }, [automationClientId, threadRef.environmentId]);
useEffect(() => {
const api = ensureEnvironmentApi(threadRef.environmentId);
@@ -281,7 +311,7 @@ export function PreviewAutomationOwner(props: {
unsubscribe();
void api.preview.automation.clearOwner({ clientId: automationClientId });
};
- }, [threadRef, visible]);
+ }, [automationClientId, threadRef, visible]);
return null;
}
diff --git a/apps/web/src/components/preview/PreviewChromeRow.tsx b/apps/web/src/components/preview/PreviewChromeRow.tsx
index c84d27345..9064dc71d 100644
--- a/apps/web/src/components/preview/PreviewChromeRow.tsx
+++ b/apps/web/src/components/preview/PreviewChromeRow.tsx
@@ -1,6 +1,7 @@
import {
ArrowLeft,
ArrowRight,
+ Camera,
ExternalLink,
Globe,
MousePointerClick,
@@ -36,6 +37,9 @@ interface Props {
onSubmit: (url: string) => void;
/** When provided, renders an "Open in browser" affordance to the right. */
onOpenInBrowser?: (() => void) | undefined;
+ onCapture?: ((record: boolean) => void) | undefined;
+ captureDisabled?: boolean | undefined;
+ recording?: boolean | undefined;
/**
* When provided, renders an annotation-mode toggle button to the right of
* the URL input. Pressed while annotation mode is active (button shows in `pressed`
@@ -69,6 +73,9 @@ export function PreviewChromeRow({
onRefresh,
onSubmit,
onOpenInBrowser,
+ onCapture,
+ captureDisabled,
+ recording,
onPickElement,
pickActive,
pickDisabled,
@@ -97,13 +104,14 @@ export function PreviewChromeRow({
const next = draft.trim();
if (next.length === 0) return;
onSubmit(next);
+ inputRef.current?.blur();
};
return (
<div className="relative">
<form
onSubmit={submit}
- className="flex items-center gap-2 border-b border-border bg-background px-2 py-1.5"
+ className="flex h-10 items-center gap-1 border-b border-border/70 bg-background px-2"
>
<div className="flex items-center gap-0.5" role="group" aria-label="Navigation">
<Tooltip>
@@ -159,7 +167,7 @@ export function PreviewChromeRow({
</Tooltip>
</div>
- <InputGroup className="flex-1">
+ <InputGroup className="h-7 flex-1 rounded-md">
<InputGroupAddon align="inline-start">
<Globe className="size-3.5 text-muted-foreground" aria-hidden />
</InputGroupAddon>
@@ -181,6 +189,26 @@ export function PreviewChromeRow({
data-preview-url-input
size="sm"
/>
+ {onOpenInBrowser ? (
+ <InputGroupAddon align="inline-end">
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ variant="ghost"
+ size="icon-xs"
+ onClick={onOpenInBrowser}
+ aria-label="Open in system browser"
+ type="button"
+ />
+ }
+ >
+ <ExternalLink />
+ </TooltipTrigger>
+ <TooltipPopup>Open in system browser</TooltipPopup>
+ </Tooltip>
+ </InputGroupAddon>
+ ) : null}
</InputGroup>
{onPickElement ? (
@@ -209,22 +237,29 @@ export function PreviewChromeRow({
</TooltipPopup>
</Tooltip>
) : null}
- {onOpenInBrowser ? (
+ {onCapture ? (
<Tooltip>
<TooltipTrigger
render={
<Button
- variant="ghost"
+ variant={recording ? "secondary" : "ghost"}
size="icon-xs"
- onClick={onOpenInBrowser}
- aria-label="Open in system browser"
+ onClick={(event) => onCapture(event.shiftKey)}
+ aria-label={recording ? "Stop recording" : "Capture screenshot"}
type="button"
+ className="relative"
+ disabled={captureDisabled}
/>
}
>
- <ExternalLink />
+ <Camera className={cn(recording && "text-destructive")} />
+ {recording ? (
+ <span className="absolute right-0.5 top-0.5 size-1.5 animate-pulse rounded-full bg-destructive" />
+ ) : null}
</TooltipTrigger>
- <TooltipPopup>Open in system browser</TooltipPopup>
+ <TooltipPopup>
+ {recording ? "Stop recording" : "Screenshot · Shift-click to record"}
+ </TooltipPopup>
</Tooltip>
) : null}
{trailingActions}
diff --git a/apps/web/src/components/preview/PreviewEmptyState.tsx b/apps/web/src/components/preview/PreviewEmptyState.tsx
index 653fb9361..12126c664 100644
--- a/apps/web/src/components/preview/PreviewEmptyState.tsx
+++ b/apps/web/src/components/preview/PreviewEmptyState.tsx
@@ -1,5 +1,5 @@
import type { EnvironmentId } from "@t3tools/contracts";
-import { Globe } from "lucide-react";
+import { Globe, RadioTower } from "lucide-react";
import { Empty, EmptyDescription, EmptyMedia, EmptyTitle } from "~/components/ui/empty";
@@ -41,18 +41,24 @@ export function PreviewEmptyState({
}
return (
- <div className="flex h-full min-h-0 flex-col overflow-y-auto">
- <h2 className="px-4 pt-4 pb-1.5 text-[11px] font-medium uppercase tracking-wide text-muted-foreground/80">
- Local
- </h2>
- <div className="flex flex-col gap-1.5 px-3 pb-4">
- {servers.map((server) => (
- <PreviewLocalServerCard
- key={`${server.host}:${server.port}`}
- server={server}
- onOpen={() => onOpenUrl(server.url)}
- />
- ))}
+ <div className="flex h-full min-h-0 overflow-y-auto px-5 py-8">
+ <div className="m-auto flex w-full max-w-xl flex-col gap-3">
+ <div className="flex items-center gap-2 text-sm text-muted-foreground">
+ <RadioTower className="size-4 shrink-0" />
+ <h2 className="font-medium">Local servers</h2>
+ </div>
+ <div className="flex flex-col divide-y divide-border/60 overflow-hidden rounded-xl border border-border/70 bg-background">
+ {servers.map((server) => (
+ <PreviewLocalServerCard
+ key={`${server.host}:${server.port}`}
+ server={server}
+ onOpen={() => onOpenUrl(server.url)}
+ />
+ ))}
+ </div>
+ <p className="px-1 text-xs text-muted-foreground">
+ Select a listening port to open it in this browser tab.
+ </p>
</div>
</div>
);
diff --git a/apps/web/src/components/preview/PreviewLocalServerCard.tsx b/apps/web/src/components/preview/PreviewLocalServerCard.tsx
index c2e3018d3..54a020cbf 100644
--- a/apps/web/src/components/preview/PreviewLocalServerCard.tsx
+++ b/apps/web/src/components/preview/PreviewLocalServerCard.tsx
@@ -1,5 +1,3 @@
-import { cn } from "~/lib/utils";
-
import { BrowserMockup } from "./BrowserMockup";
import type { PreviewableServer } from "./useDiscoveredLocalServers";
@@ -14,18 +12,14 @@ export function PreviewLocalServerCard({ server, onOpen }: Props) {
<button
type="button"
onClick={onOpen}
- className={cn(
- "group flex w-full items-center gap-3 rounded-xl border border-border/70 bg-card px-3 py-2.5 text-left transition-colors",
- "hover:border-border hover:bg-accent/40",
- "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 focus-visible:ring-offset-background",
- )}
+ className="group flex w-full items-center gap-3 px-3 py-3 text-left hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
>
<BrowserMockup className="size-7 shrink-0" />
<div className="flex min-w-0 flex-1 flex-col">
- <span className="truncate text-sm font-medium text-foreground">
+ <span className="truncate text-sm font-medium text-foreground">{subtitle}</span>
+ <span className="truncate text-xs text-muted-foreground">
{server.host}:{server.port}
</span>
- <span className="truncate text-xs text-muted-foreground">{subtitle}</span>
</div>
{server.listening ? <PulsingDot /> : <DimDot />}
</button>
diff --git a/apps/web/src/components/preview/PreviewMoreMenu.tsx b/apps/web/src/components/preview/PreviewMoreMenu.tsx
index 748a4a270..f11ff4d2d 100644
--- a/apps/web/src/components/preview/PreviewMoreMenu.tsx
+++ b/apps/web/src/components/preview/PreviewMoreMenu.tsx
@@ -36,7 +36,6 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
};
const zoomLabel = `${Math.round(zoomFactor * 100)}%`;
-
return (
<Menu>
<Tooltip>
@@ -60,7 +59,6 @@ export function PreviewMoreMenu({ tabId, hasWebContents, zoomFactor }: Props) {
<MenuItem onClick={callTab(bridge.openDevTools)} disabled={tabDisabled}>
Open DevTools
</MenuItem>
- <MenuSeparator />
{/*
Zoom row: label + inline control cluster. `closeOnClick=false`
keeps the menu open while the user clicks the +/− buttons.
diff --git a/apps/web/src/components/preview/PreviewPanel.tsx b/apps/web/src/components/preview/PreviewPanel.tsx
index edd19a31c..92db1c2cd 100644
--- a/apps/web/src/components/preview/PreviewPanel.tsx
+++ b/apps/web/src/components/preview/PreviewPanel.tsx
@@ -10,15 +10,16 @@ import { PreviewView } from "./PreviewView";
interface Props {
mode: PreviewPanelMode;
threadRef: ScopedThreadRef;
+ tabId?: string | null;
configuredUrls?: ReadonlyArray<string> | undefined;
visible: boolean;
}
-export function PreviewPanel({ mode, threadRef, configuredUrls, visible }: Props) {
+export function PreviewPanel({ mode, threadRef, tabId, configuredUrls, visible }: Props) {
if (!isPreviewSupportedInRuntime()) {
return (
<PreviewPanelShell mode={mode}>
- <div className="flex h-full flex-col items-center justify-center gap-3 p-8 text-center">
+ <div className="flex min-h-0 flex-1 flex-col items-center justify-center gap-3 p-8 text-center">
<p className="max-w-sm text-sm text-muted-foreground">
Preview is only available in the T3 Code desktop app.
</p>
@@ -29,7 +30,12 @@ export function PreviewPanel({ mode, threadRef, configuredUrls, visible }: Props
return (
<PreviewPanelShell mode={mode}>
- <PreviewView threadRef={threadRef} configuredUrls={configuredUrls} visible={visible} />
+ <PreviewView
+ threadRef={threadRef}
+ {...(tabId !== undefined ? { tabId } : {})}
+ configuredUrls={configuredUrls}
+ visible={visible}
+ />
</PreviewPanelShell>
);
}
diff --git a/apps/web/src/components/preview/PreviewPanelShell.tsx b/apps/web/src/components/preview/PreviewPanelShell.tsx
index 71e8dd561..7243a4df4 100644
--- a/apps/web/src/components/preview/PreviewPanelShell.tsx
+++ b/apps/web/src/components/preview/PreviewPanelShell.tsx
@@ -6,7 +6,7 @@ import { cn } from "~/lib/utils";
import { RightPanelResizeHandle } from "./RightPanelResizeHandle";
-export type PreviewPanelMode = "inline" | "sheet" | "sidebar";
+export type PreviewPanelMode = "inline" | "sheet" | "sidebar" | "embedded";
const PREVIEW_PANEL_WIDTH_STORAGE_KEY = "t3code:preview-panel-width";
const PREVIEW_PANEL_MIN_WIDTH = 360;
@@ -22,7 +22,7 @@ const PREVIEW_PANEL_DEFAULT_WIDTH = 540;
* sheet/sidebar modes the parent owns the size.
*/
export function PreviewPanelShell(props: { mode: PreviewPanelMode; children: ReactNode }) {
- const useDragRegion = isElectron && props.mode !== "sheet";
+ const useDragRegion = isElectron && props.mode !== "sheet" && props.mode !== "embedded";
const isInline = props.mode === "inline";
const maxWidth = useViewportClampedMaxWidth();
const { width, handlers } = useResizableWidth({
@@ -36,7 +36,7 @@ export function PreviewPanelShell(props: { mode: PreviewPanelMode; children: Rea
return (
<div
className={cn(
- "relative flex h-full min-w-0 flex-col bg-background",
+ "relative flex h-full min-h-0 min-w-0 flex-col self-stretch bg-background",
isInline ? "shrink-0 border-l border-border" : "w-full",
)}
style={isInline ? { width: `${width}px` } : undefined}
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
index 0f4e66514..0bec9d5d4 100644
--- a/apps/web/src/components/preview/PreviewView.tsx
+++ b/apps/web/src/components/preview/PreviewView.tsx
@@ -13,6 +13,7 @@ import {
} from "~/lib/previewAnnotation";
import { ensureLocalApi } from "~/localApi";
import { selectThreadPreviewState, usePreviewStateStore } from "~/previewStateStore";
+import { resolveDiscoveredServerUrl } from "~/browser/browserTargetResolver";
import { previewBridge } from "./previewBridge";
import { subscribePreviewAction } from "./previewActionBus";
@@ -21,13 +22,20 @@ import { PreviewChromeRow } from "./PreviewChromeRow";
import { PreviewEmptyState } from "./PreviewEmptyState";
import { PreviewMoreMenu } from "./PreviewMoreMenu";
import { PreviewUnreachable } from "./PreviewUnreachable";
-import { PreviewWebview } from "./PreviewWebview";
+import { BrowserSurfaceSlot } from "~/browser/BrowserSurfaceSlot";
import { useLoadingProgress } from "./useLoadingProgress";
import { usePreviewSession } from "./usePreviewSession";
import { ZoomIndicator } from "./ZoomIndicator";
+import {
+ startBrowserRecording,
+ stopBrowserRecording,
+ useBrowserRecordingStore,
+} from "~/browser/browserRecording";
+import { toastManager } from "~/components/ui/toast";
interface Props {
threadRef: ScopedThreadRef;
+ tabId?: string | null;
configuredUrls?: ReadonlyArray<string> | undefined;
visible: boolean;
}
@@ -38,9 +46,10 @@ const localApi = typeof window === "undefined" ? null : ensureLocalApi();
* Single-tab preview surface: chrome row on top, one webview below, empty
* state when no session exists for the thread.
*/
-export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
+export function PreviewView({ threadRef, tabId: requestedTabId, configuredUrls, visible }: Props) {
const [focusUrlNonce, setFocusUrlNonce] = useState(0);
const [pickActive, setPickActive] = useState(false);
+ const activeRecordingTabId = useBrowserRecordingStore((state) => state.activeTabId);
const pickActiveRef = useRef(false);
const isMountedRef = useRef(true);
const previewState = usePreviewStateStore((state) =>
@@ -62,8 +71,9 @@ export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
};
}, []);
- const { snapshot, desktopOverlay } = previewState;
- const tabId = snapshot?.tabId ?? null;
+ const tabId = requestedTabId ?? previewState.activeTabId;
+ const snapshot = tabId ? (previewState.sessions[tabId] ?? null) : null;
+ const desktopOverlay = tabId ? (previewState.desktopByTabId[tabId] ?? null) : null;
const navStatus = snapshot?.navStatus ?? { _tag: "Idle" as const };
const url = navStatus._tag === "Idle" ? "" : navStatus.url;
const loading = desktopOverlay?.loading ?? navStatus._tag === "Loading";
@@ -71,22 +81,24 @@ export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
const canGoForward = desktopOverlay?.canGoForward ?? snapshot?.canGoForward ?? false;
const refreshDisabled = navStatus._tag === "Idle";
const isUnreachable = navStatus._tag === "LoadFailed";
+ const controller = desktopOverlay?.controller ?? "none";
const loadProgress = useLoadingProgress(loading);
const handleSubmitUrl = useCallback(
async (next: string) => {
const api = ensureEnvironmentApi(threadRef.environmentId);
try {
+ const resolvedUrl = resolveDiscoveredServerUrl(threadRef.environmentId, next);
if (tabId && previewBridge) {
// Drive the webview imperatively; `usePreviewBridge` mirrors the
// resolved URL back to the server so other clients stay in sync.
- await previewBridge.navigate(tabId, next);
- rememberUrl(threadRef, next);
+ await previewBridge.navigate(tabId, resolvedUrl);
+ rememberUrl(threadRef, resolvedUrl);
} else {
await openPreviewSession({
previewApi: api.preview,
threadRef,
- url: next,
+ url: resolvedUrl,
applyServerSnapshot,
rememberUrl,
});
@@ -127,6 +139,68 @@ export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
void localApi.shell.openExternal(url).catch(() => undefined);
}, [url]);
+ const handleCapture = useCallback(
+ (record: boolean) => {
+ if (!previewBridge || !tabId) return;
+ const recordingThisTab = activeRecordingTabId === tabId;
+ if (recordingThisTab) {
+ void stopBrowserRecording(tabId).then(
+ (artifact) => {
+ if (!artifact) return;
+ toastManager.add({
+ type: "success",
+ title: "Recording saved",
+ description: artifact.path,
+ });
+ },
+ (error) => {
+ toastManager.add({
+ type: "error",
+ title: "Unable to stop recording",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ });
+ },
+ );
+ return;
+ }
+ if (record) {
+ if (activeRecordingTabId !== null) {
+ toastManager.add({
+ type: "warning",
+ title: "Another preview is recording",
+ description: "Stop the active recording before starting a new one.",
+ });
+ return;
+ }
+ void startBrowserRecording(tabId).catch((error) => {
+ toastManager.add({
+ type: "error",
+ title: "Unable to start recording",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ });
+ });
+ return;
+ }
+ void previewBridge.captureScreenshot(tabId).then(
+ (artifact) => {
+ toastManager.add({
+ type: "success",
+ title: "Screenshot saved",
+ description: artifact.path,
+ });
+ },
+ (error) => {
+ toastManager.add({
+ type: "error",
+ title: "Unable to capture screenshot",
+ description: error instanceof Error ? error.message : "An error occurred.",
+ });
+ },
+ );
+ },
+ [activeRecordingTabId, tabId],
+ );
+
const handlePickElement = useCallback(() => {
if (!previewBridge || !tabId) return;
if (pickActiveRef.current) {
@@ -232,7 +306,7 @@ export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
return (
<div
- className="flex h-full min-h-0 flex-col bg-background"
+ className="flex min-h-0 flex-1 flex-col bg-background"
data-thread-key={scopedThreadKey(threadRef)}
>
<PreviewChromeRow
@@ -248,6 +322,9 @@ export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
onRefresh={handleRefresh}
onSubmit={(next) => void handleSubmitUrl(next)}
onOpenInBrowser={tabId ? handleOpenInBrowser : undefined}
+ onCapture={previewBridge && tabId ? handleCapture : undefined}
+ captureDisabled={!desktopOverlay || isUnreachable}
+ recording={tabId !== null && activeRecordingTabId === tabId}
onPickElement={previewBridge && tabId ? handlePickElement : undefined}
pickActive={pickActive}
// Disable when there's no tab (nothing to pick on) OR the page
@@ -268,13 +345,12 @@ export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
}
/>
- <div className="relative flex-1 overflow-hidden">
+ <div className="relative min-h-0 flex-1 overflow-hidden">
{tabId && snapshot ? (
- <PreviewWebview
+ <BrowserSurfaceSlot
key={tabId}
- threadRef={threadRef}
tabId={tabId}
- initialUrl={url || null}
+ visible={visible && !isUnreachable}
className="absolute inset-0 h-full w-full"
/>
) : (
@@ -288,6 +364,11 @@ export function PreviewView({ threadRef, configuredUrls, visible }: Props) {
{snapshot && desktopOverlay ? (
<ZoomIndicator zoomFactor={desktopOverlay.zoomFactor} />
) : null}
+ {controller !== "none" ? (
+ <div className="pointer-events-none absolute left-3 top-3 z-40 rounded-full border border-border/70 bg-background/90 px-2.5 py-1 text-[11px] font-medium shadow-sm backdrop-blur">
+ {controller === "agent" ? "Agent controlling browser" : "Human control"}
+ </div>
+ ) : null}
{navStatus._tag === "LoadFailed" ? (
<div className="absolute inset-0 z-10 bg-background">
<PreviewUnreachable
diff --git a/apps/web/src/components/preview/PreviewWebview.tsx b/apps/web/src/components/preview/PreviewWebview.tsx
deleted file mode 100644
index 9c4afb414..000000000
--- a/apps/web/src/components/preview/PreviewWebview.tsx
+++ /dev/null
@@ -1,142 +0,0 @@
-"use client";
-
-import type { DesktopPreviewWebviewConfig, ScopedThreadRef } from "@t3tools/contracts";
-import { useCallback, useEffect, useRef, useState } from "react";
-
-import { isElectron } from "~/env";
-
-import { previewBridge } from "./previewBridge";
-import { usePreviewBridge } from "./usePreviewBridge";
-
-interface Props {
- threadRef: ScopedThreadRef;
- tabId: string;
- /**
- * URL to load on first mount. Subsequent prop changes are ignored — once
- * the webview is live, navigation flows exclusively through the bridge
- * (`previewBridge.navigate`, `goBack`, `goForward`, `refresh`). Otherwise,
- * a snapshot URL update from the server would re-set `<webview src>` and
- * race with the `loadURL` we already issued via the bridge.
- */
- initialUrl: string | null;
- className?: string;
-}
-
-interface ElectronWebview extends HTMLElement {
- src: string;
- partition: string;
- preload?: string;
- /**
- * Comma-separated `key=value` web-preferences override. We use it to drop
- * `contextIsolation` so the picker preload can see the guest page's
- * `__REACT_DEVTOOLS_GLOBAL_HOOK__` and resolve component names.
- */
- webpreferences?: string;
- reload: () => void;
- getWebContentsId: () => number;
-}
-
-declare global {
- interface HTMLElementTagNameMap {
- webview: ElectronWebview;
- }
-}
-
-/**
- * Hosts the Electron `<webview>` for a single preview tab. Returns null on
- * web builds. The two-step handshake (createTab → wait for `dom-ready` →
- * registerWebview) is necessary because `getWebContentsId()` only returns a
- * valid id once the embedded contents have parsed; calling it synchronously
- * after mount throws.
- */
-export function PreviewWebview({ threadRef, tabId, initialUrl, className }: Props) {
- const [config, setConfig] = useState<DesktopPreviewWebviewConfig | null>(null);
- const webviewRef = useRef<ElectronWebview | null>(null);
- // Capture once at mount; never re-derived from `initialUrl` props later.
- const initialSrcRef = useRef<string>(initialUrl ?? "about:blank");
- const bridge = previewBridge;
-
- // Per-tab desktop lifecycle: createTab on mount, closeTab on unmount,
- // mirror state into the store, and reflect navigation back to the server.
- usePreviewBridge({ threadRef, tabId });
-
- useEffect(() => {
- if (!bridge) return;
- let cancelled = false;
- bridge
- .getPreviewConfig()
- .then((next) => {
- if (cancelled) return;
- setConfig(next);
- })
- .catch(() => undefined);
- return () => {
- cancelled = true;
- };
- }, [bridge]);
-
- // Stable callback ref so React doesn't re-invoke the closure on every
- // commit (otherwise we'd be re-asserting `allowpopups` and re-storing the
- // ref pointer per render, which is harmless but wasteful).
- const setWebviewRef = useCallback((node: HTMLElement | null) => {
- webviewRef.current = node as ElectronWebview | null;
- if (node && !node.hasAttribute("allowpopups")) {
- // React's @types declare `allowpopups` as `boolean`, but the runtime
- // doesn't list <webview> in its boolean-attribute allowlist, so
- // passing it via JSX triggers a "received true for a non-boolean
- // attribute" warning. Setting it imperatively bypasses React's prop
- // normalization entirely.
- node.setAttribute("allowpopups", "true");
- }
- }, []);
-
- useEffect(() => {
- if (!bridge || !config) return;
- const webview = webviewRef.current;
- if (!webview) return;
-
- const onDomReady = () => {
- try {
- const id = webview.getWebContentsId();
- if (Number.isFinite(id)) {
- void bridge.registerWebview(tabId, id);
- }
- } catch {
- // The next dom-ready (e.g. cross-document navigation) will retry.
- }
- };
- webview.addEventListener("dom-ready", onDomReady as EventListener);
- // Defensive: dom-ready may have fired between React commit and this
- // effect running. Failures fall through to the listener above.
- try {
- const existing = webview.getWebContentsId();
- if (Number.isFinite(existing)) {
- void bridge.registerWebview(tabId, existing);
- }
- } catch {
- // covered by dom-ready listener
- }
-
- return () => {
- webview.removeEventListener("dom-ready", onDomReady as EventListener);
- };
- }, [bridge, config, tabId]);
-
- if (!isElectron || !bridge || !config) return null;
-
- // `preload` and `webpreferences` are HTML attributes Electron only reads
- // at element-attach time — a state update later in the lifecycle would
- // have no effect. The renderer-attached values are also enforced by the
- // main-process `will-attach-webview` validator (defense in depth).
- return (
- <webview
- ref={setWebviewRef}
- src={initialSrcRef.current}
- partition={config.partition}
- webpreferences={config.webPreferences}
- {...(config.preloadUrl ? { preload: config.preloadUrl } : {})}
- data-preview-tab={tabId}
- className={className}
- />
- );
-}
diff --git a/apps/web/src/components/preview/useDiscoveredLocalServers.ts b/apps/web/src/components/preview/useDiscoveredLocalServers.ts
index 9eab8592d..370dd4cba 100644
--- a/apps/web/src/components/preview/useDiscoveredLocalServers.ts
+++ b/apps/web/src/components/preview/useDiscoveredLocalServers.ts
@@ -4,6 +4,7 @@ import { useEffect, useMemo, useState } from "react";
import { ensureEnvironmentApi } from "~/environmentApi";
import type { EnvironmentId } from "@t3tools/contracts";
+import { resolveDiscoveredServerUrl } from "~/browser/browserTargetResolver";
export interface PreviewableServer extends DiscoveredLocalServer {
source: "scanner" | "configured" | "recent";
@@ -42,11 +43,14 @@ export function useDiscoveredLocalServers(
return useMemo(
() =>
mergeServers({
- scanner: scannerSnapshot,
+ scanner: scannerSnapshot.map((server) => ({
+ ...server,
+ url: resolveDiscoveredServerUrl(input.environmentId, server.url),
+ })),
configuredUrls: input.configuredUrls ?? [],
recentlySeenUrls: input.recentlySeenUrls ?? [],
}),
- [scannerSnapshot, input.configuredUrls, input.recentlySeenUrls],
+ [input.environmentId, scannerSnapshot, input.configuredUrls, input.recentlySeenUrls],
);
}
diff --git a/apps/web/src/components/preview/usePreviewBridge.ts b/apps/web/src/components/preview/usePreviewBridge.ts
index 6a80fb820..9eb6eebbb 100644
--- a/apps/web/src/components/preview/usePreviewBridge.ts
+++ b/apps/web/src/components/preview/usePreviewBridge.ts
@@ -14,26 +14,14 @@ import { type DesktopPreviewOverlay, usePreviewStateStore } from "~/previewState
import { previewBridge } from "./previewBridge";
/**
- * Owns the desktop tab lifecycle, mirrors low-latency button state into the
- * store, and reflects bridge navigation events back to the server.
- *
- * Tab create/close is anchored to the panel mount, NOT to the snapshot, so
- * snapshot transitions (`opened` → `closed` → `opened`) cannot tear down and
- * recreate the tab in the wrong order relative to in-flight desktop IPCs.
+ * Mirrors low-latency desktop state into the store and reflects navigation
+ * events back to the server. Webview lifetime is owned by ElectronBrowserHost.
*/
export function usePreviewBridge(input: { threadRef: ScopedThreadRef; tabId: string }): void {
const { threadRef, tabId } = input;
const applyDesktopState = usePreviewStateStore((state) => state.applyDesktopState);
const bridge = previewBridge;
- useEffect(() => {
- if (!bridge) return;
- void bridge.createTab(tabId);
- return () => {
- void bridge.closeTab(tabId);
- };
- }, [bridge, tabId]);
-
// One bridge subscription does both jobs (mirror state + forward to
// server) so the desktop bridge keeps a single listener entry per tab.
const lastReportedUrl = useRef<string | null>(null);
@@ -45,7 +33,7 @@ export function usePreviewBridge(input: { threadRef: ScopedThreadRef; tabId: str
lastReportedKind.current = null;
const unsubscribe = bridge.onStateChange((changedTabId, state) => {
if (changedTabId !== tabId) return;
- applyDesktopState(threadRef, projectDesktopState(state));
+ applyDesktopState(threadRef, tabId, projectDesktopState(state));
const reported = buildReportInput({
threadId: threadRef.threadId,
tabId,
@@ -68,6 +56,7 @@ function projectDesktopState(state: DesktopPreviewTabState): DesktopPreviewOverl
canGoForward: state.canGoForward,
loading: state.navStatus.kind === "Loading",
zoomFactor: state.zoomFactor,
+ controller: state.controller,
};
}
diff --git a/apps/web/src/components/preview/usePreviewSession.ts b/apps/web/src/components/preview/usePreviewSession.ts
index 152765213..1a4446bd3 100644
--- a/apps/web/src/components/preview/usePreviewSession.ts
+++ b/apps/web/src/components/preview/usePreviewSession.ts
@@ -33,7 +33,7 @@ export function usePreviewSession(threadRef: ScopedThreadRef): void {
// `updatedAt` ascending, so the last one is freshest.
const serverSnapshot = result.sessions.at(-1) ?? null;
if (serverSnapshot) {
- applyServerSnapshot(threadRef, serverSnapshot);
+ for (const snapshot of result.sessions) applyServerSnapshot(threadRef, snapshot);
return;
}
// Server has no sessions — try to recover what the renderer
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index e92cad9aa..8d56b6877 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -17,6 +17,7 @@ import { hasCloudPublicConfig } from "./cloud/publicConfig";
import { getRouter } from "./router";
import { APP_DISPLAY_NAME } from "./branding";
import { syncDocumentWindowControlsOverlayClass } from "./lib/windowControlsOverlay";
+import { ElectronBrowserHost } from "./browser/ElectronBrowserHost";
// Electron loads the app from a file-backed shell, so hash history avoids path resolution issues.
const history = isElectron ? createHashHistory() : createBrowserHistory();
@@ -31,7 +32,12 @@ document.title = APP_DISPLAY_NAME;
const clerkPublishableKey = import.meta.env.VITE_CLERK_PUBLISHABLE_KEY as string | undefined;
-const app = <RouterProvider router={router} />;
+const app = (
+ <>
+ <RouterProvider router={router} />
+ <ElectronBrowserHost />
+ </>
+);
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
<React.StrictMode>
diff --git a/apps/web/src/previewStateStore.test.ts b/apps/web/src/previewStateStore.test.ts
index eb7c99810..9a1722380 100644
--- a/apps/web/src/previewStateStore.test.ts
+++ b/apps/web/src/previewStateStore.test.ts
@@ -184,17 +184,39 @@ describe("previewStateStore (single-tab)", () => {
createdAt: snapshot.updatedAt,
snapshot,
});
- store.applyDesktopState(ref, {
+ store.applyDesktopState(ref, snapshot.tabId, {
canGoBack: true,
canGoForward: false,
loading: false,
zoomFactor: 1,
+ controller: "none",
});
const state = selectThreadPreviewState(usePreviewStateStore.getState().byThreadKey, ref);
expect(state.desktopOverlay?.canGoBack).toBe(true);
expect(state.snapshot?.canGoBack).toBe(false);
});
+ it("retains multiple tabs and switches active desktop state", () => {
+ const first = makeSnapshot();
+ const second = { ...makeSnapshot(), tabId: "tab_2", updatedAt: "2026-01-02T00:00:00.000Z" };
+ const store = usePreviewStateStore.getState();
+ store.applyServerSnapshot(ref, first);
+ store.applyServerSnapshot(ref, second);
+ store.applyDesktopState(ref, first.tabId, {
+ canGoBack: true,
+ canGoForward: false,
+ loading: false,
+ zoomFactor: 1,
+ controller: "none",
+ });
+ store.setActiveTab(ref, first.tabId);
+
+ const state = selectThreadPreviewState(usePreviewStateStore.getState().byThreadKey, ref);
+ expect(Object.keys(state.sessions)).toEqual([first.tabId, second.tabId]);
+ expect(state.snapshot?.tabId).toBe(first.tabId);
+ expect(state.desktopOverlay?.canGoBack).toBe(true);
+ });
+
it("applyServerSnapshot null clears snapshot for a thread that had one", () => {
const snapshot = makeSnapshot();
const store = usePreviewStateStore.getState();
diff --git a/apps/web/src/previewStateStore.ts b/apps/web/src/previewStateStore.ts
index 10f5cf585..e9a9fc695 100644
--- a/apps/web/src/previewStateStore.ts
+++ b/apps/web/src/previewStateStore.ts
@@ -26,19 +26,26 @@ export interface DesktopPreviewOverlay {
canGoForward: boolean;
loading: boolean;
zoomFactor: number;
+ controller: "human" | "agent" | "none";
}
export interface ThreadPreviewState {
snapshot: PreviewSessionSnapshot | null;
+ sessions: Record<string, PreviewSessionSnapshot>;
+ activeTabId: string | null;
/** Bridge state takes precedence over `snapshot` for nav button enablement. */
desktopOverlay: DesktopPreviewOverlay | null;
+ desktopByTabId: Record<string, DesktopPreviewOverlay>;
/** Recently-visited URLs surfaced in the empty state. */
recentlySeenUrls: string[];
}
const EMPTY_THREAD_PREVIEW_STATE: ThreadPreviewState = Object.freeze({
snapshot: null,
+ sessions: {},
+ activeTabId: null,
desktopOverlay: null,
+ desktopByTabId: {},
recentlySeenUrls: [] as string[],
});
@@ -46,7 +53,12 @@ export interface PreviewStateStoreState {
byThreadKey: Record<string, ThreadPreviewState>;
applyServerEvent: (ref: ScopedThreadRef, event: PreviewEvent) => void;
applyServerSnapshot: (ref: ScopedThreadRef, snapshot: PreviewSessionSnapshot | null) => void;
- applyDesktopState: (ref: ScopedThreadRef, overlay: DesktopPreviewOverlay | null) => void;
+ applyDesktopState: (
+ ref: ScopedThreadRef,
+ tabId: string,
+ overlay: DesktopPreviewOverlay | null,
+ ) => void;
+ setActiveTab: (ref: ScopedThreadRef, tabId: string) => void;
rememberUrl: (ref: ScopedThreadRef, url: string) => void;
removeThread: (ref: ScopedThreadRef) => void;
}
@@ -96,34 +108,64 @@ export const usePreviewStateStore = create<PreviewStateStoreState>()((set) => ({
snapshot.navStatus._tag === "Idle"
? current.recentlySeenUrls
: dedupeRecentUrls(current.recentlySeenUrls, snapshot.navStatus.url);
- return { ...current, snapshot, recentlySeenUrls };
+ const sessions = { ...current.sessions, [snapshot.tabId]: snapshot };
+ const activeTabId = event.type === "opened" ? snapshot.tabId : current.activeTabId;
+ const activeSnapshot = sessions[activeTabId ?? snapshot.tabId] ?? snapshot;
+ return {
+ ...current,
+ sessions,
+ activeTabId: activeTabId ?? snapshot.tabId,
+ snapshot: activeSnapshot,
+ desktopOverlay: current.desktopByTabId[activeSnapshot.tabId] ?? null,
+ recentlySeenUrls,
+ };
});
break;
case "failed":
nextByThread = updateThread(state, threadKey, (current) => {
- if (!current.snapshot || current.snapshot.tabId !== event.tabId) return current;
+ const existing = current.sessions[event.tabId];
+ if (!existing) return current;
+ const failedSnapshot = {
+ ...existing,
+ navStatus: {
+ _tag: "LoadFailed" as const,
+ url: event.url,
+ title: event.title,
+ code: event.code,
+ description: event.description,
+ },
+ updatedAt: event.createdAt,
+ };
+ const sessions = { ...current.sessions, [event.tabId]: failedSnapshot };
return {
...current,
- snapshot: {
- ...current.snapshot,
- navStatus: {
- _tag: "LoadFailed",
- url: event.url,
- title: event.title,
- code: event.code,
- description: event.description,
- },
- updatedAt: event.createdAt,
- },
+ sessions,
+ snapshot: current.activeTabId === event.tabId ? failedSnapshot : current.snapshot,
};
});
break;
case "closed":
nextByThread = updateThread(state, threadKey, (current) => {
- // Only clear if the closed tab is the one we were tracking; the
- // server may have multiple tabs per thread but we only render one.
- if (current.snapshot && current.snapshot.tabId !== event.tabId) return current;
- return { ...current, snapshot: null, desktopOverlay: null };
+ if (!current.sessions[event.tabId]) return current;
+ const { [event.tabId]: _closed, ...sessions } = current.sessions;
+ const { [event.tabId]: _desktop, ...desktopByTabId } = current.desktopByTabId;
+ const nextSnapshot =
+ Object.values(sessions)
+ .toSorted((a, b) => a.updatedAt.localeCompare(b.updatedAt))
+ .at(-1) ?? null;
+ const activeTabId =
+ current.activeTabId === event.tabId
+ ? (nextSnapshot?.tabId ?? null)
+ : current.activeTabId;
+ const snapshot = activeTabId ? (sessions[activeTabId] ?? nextSnapshot) : nextSnapshot;
+ return {
+ ...current,
+ sessions,
+ desktopByTabId,
+ activeTabId: snapshot?.tabId ?? null,
+ snapshot,
+ desktopOverlay: snapshot ? (desktopByTabId[snapshot.tabId] ?? null) : null,
+ };
});
break;
}
@@ -134,21 +176,59 @@ export const usePreviewStateStore = create<PreviewStateStoreState>()((set) => ({
const threadKey = scopedThreadKey(ref);
const nextByThread = updateThread(state, threadKey, (current) => {
if (!snapshot && current.snapshot === null) return current;
+ if (!snapshot) {
+ return {
+ ...current,
+ snapshot: null,
+ sessions: {},
+ activeTabId: null,
+ desktopOverlay: null,
+ desktopByTabId: {},
+ };
+ }
const recentlySeenUrls =
snapshot && snapshot.navStatus._tag !== "Idle"
? dedupeRecentUrls(current.recentlySeenUrls, snapshot.navStatus.url)
: current.recentlySeenUrls;
- return { ...current, snapshot, recentlySeenUrls };
+ return {
+ ...current,
+ snapshot,
+ sessions: { ...current.sessions, [snapshot.tabId]: snapshot },
+ activeTabId: snapshot.tabId,
+ desktopOverlay: current.desktopByTabId[snapshot.tabId] ?? null,
+ recentlySeenUrls,
+ };
});
return { byThreadKey: nextByThread };
}),
- applyDesktopState: (ref, overlay) =>
+ applyDesktopState: (ref, tabId, overlay) =>
set((state) => {
const threadKey = scopedThreadKey(ref);
- const nextByThread = updateThread(state, threadKey, (current) => ({
- ...current,
- desktopOverlay: overlay,
- }));
+ const nextByThread = updateThread(state, threadKey, (current) => {
+ const desktopByTabId = { ...current.desktopByTabId };
+ if (overlay) desktopByTabId[tabId] = overlay;
+ else delete desktopByTabId[tabId];
+ return {
+ ...current,
+ desktopByTabId,
+ desktopOverlay: current.activeTabId === tabId ? overlay : current.desktopOverlay,
+ };
+ });
+ return { byThreadKey: nextByThread };
+ }),
+ setActiveTab: (ref, tabId) =>
+ set((state) => {
+ const threadKey = scopedThreadKey(ref);
+ const nextByThread = updateThread(state, threadKey, (current) => {
+ const snapshot = current.sessions[tabId];
+ if (!snapshot || current.activeTabId === tabId) return current;
+ return {
+ ...current,
+ activeTabId: tabId,
+ snapshot,
+ desktopOverlay: current.desktopByTabId[tabId] ?? null,
+ };
+ });
return { byThreadKey: nextByThread };
}),
rememberUrl: (ref, url) =>
diff --git a/apps/web/src/rightPanelStore.test.ts b/apps/web/src/rightPanelStore.test.ts
index 7865c57f8..1820898cb 100644
--- a/apps/web/src/rightPanelStore.test.ts
+++ b/apps/web/src/rightPanelStore.test.ts
@@ -4,7 +4,9 @@ import { beforeEach, describe, expect, it } from "vite-plus/test";
import {
selectActiveRightPanel,
+ selectActiveRightPanelSurface,
selectActiveRightPanelKindWithUrl,
+ selectThreadRightPanelState,
useRightPanelStore,
} from "./rightPanelStore";
@@ -22,10 +24,13 @@ describe("rightPanelStore", () => {
expect(selectActiveRightPanel(useRightPanelStore.getState().byThreadKey, refB)).toBeNull();
});
- it("opening a different kind replaces the previous one", () => {
+ it("opening a different kind keeps both surfaces and activates the new one", () => {
useRightPanelStore.getState().open(refA, "plan");
useRightPanelStore.getState().open(refA, "preview");
expect(selectActiveRightPanel(useRightPanelStore.getState().byThreadKey, refA)).toBe("preview");
+ expect(
+ selectThreadRightPanelState(useRightPanelStore.getState().byThreadKey, refA).surfaces,
+ ).toHaveLength(2);
});
it("close clears the active panel", () => {
@@ -67,4 +72,40 @@ describe("rightPanelStore", () => {
useRightPanelStore.getState().close(refA);
expect(useRightPanelStore.getState().byThreadKey).toEqual({});
});
+
+ it("tracks one surface per browser session", () => {
+ useRightPanelStore.getState().openBrowser(refA, "tab-a");
+ useRightPanelStore.getState().openBrowser(refA, "tab-b");
+
+ const state = selectThreadRightPanelState(useRightPanelStore.getState().byThreadKey, refA);
+ expect(state.surfaces.map((surface) => surface.id)).toEqual(["browser:tab-a", "browser:tab-b"]);
+ expect(selectActiveRightPanelSurface(useRightPanelStore.getState().byThreadKey, refA)).toEqual({
+ id: "browser:tab-b",
+ kind: "preview",
+ resourceId: "tab-b",
+ });
+ });
+
+ it("closing the active surface activates a neighboring surface", () => {
+ useRightPanelStore.getState().openBrowser(refA, "tab-a");
+ useRightPanelStore.getState().open(refA, "terminal");
+ useRightPanelStore.getState().closeSurface(refA, "terminal");
+
+ expect(selectActiveRightPanelSurface(useRightPanelStore.getState().byThreadKey, refA)?.id).toBe(
+ "browser:tab-a",
+ );
+ });
+
+ it("reconciles browser surfaces without deleting other surface kinds", () => {
+ useRightPanelStore.getState().open(refA, "terminal");
+ useRightPanelStore.getState().openBrowser(refA, "tab-a");
+ useRightPanelStore.getState().openBrowser(refA, "tab-b");
+ useRightPanelStore.getState().reconcileBrowserSurfaces(refA, ["tab-b", "tab-c"]);
+
+ expect(
+ selectThreadRightPanelState(useRightPanelStore.getState().byThreadKey, refA).surfaces.map(
+ (surface) => surface.id,
+ ),
+ ).toEqual(["terminal", "browser:tab-b", "browser:tab-c"]);
+ });
});
diff --git a/apps/web/src/rightPanelStore.ts b/apps/web/src/rightPanelStore.ts
index b8bba44fd..c5e0b23a6 100644
--- a/apps/web/src/rightPanelStore.ts
+++ b/apps/web/src/rightPanelStore.ts
@@ -1,13 +1,10 @@
/**
- * Per-thread arbiter for the right-side panel.
+ * Thread-scoped right-panel surface state.
*
- * Three tenants share the same slot: the plan sidebar, the diff panel, and
- * the preview panel. Only one is open at a time per thread; the choice is
- * remembered across thread switches.
- *
- * The diff panel still uses `?diff=1` as URL truth for deep-linking — when
- * that param is present the diff tenant wins regardless of what's persisted
- * here. See `selectActiveRightPanelKindWithUrl` for the resolution rule.
+ * This is intentionally a shallow workspace model: it owns an ordered set of
+ * surface descriptors and the active surface, while each feature continues to
+ * own its durable resource state. Browser surfaces point at preview tab ids;
+ * singleton surfaces bridge the existing terminal, diff, and plan features.
*/
import { scopedThreadKey } from "@t3tools/client-runtime";
import type { ScopedThreadRef } from "@t3tools/contracts";
@@ -16,35 +13,77 @@ import { createJSONStorage, persist } from "zustand/middleware";
import { resolveStorage } from "./lib/storage";
-export const RIGHT_PANEL_KINDS = ["plan", "diff", "preview"] as const;
+export const RIGHT_PANEL_KINDS = ["plan", "diff", "preview", "terminal"] as const;
export type RightPanelKind = (typeof RIGHT_PANEL_KINDS)[number];
-const RIGHT_PANEL_STORAGE_KEY = "t3code:right-panel-state:v1";
+export type RightPanelSurface =
+ | { id: `browser:${string}`; kind: "preview"; resourceId: string }
+ | { id: "browser:new"; kind: "preview"; resourceId: null }
+ | { id: "terminal"; kind: "terminal" }
+ | { id: "diff"; kind: "diff" }
+ | { id: "plan"; kind: "plan" };
+
+const RIGHT_PANEL_STORAGE_KEY = "t3code:right-panel-state:v2";
-interface ThreadRightPanelState {
- active: RightPanelKind | null;
+export interface ThreadRightPanelState {
+ activeSurfaceId: string | null;
+ surfaces: RightPanelSurface[];
}
interface RightPanelStoreState {
byThreadKey: Record<string, ThreadRightPanelState>;
open: (ref: ScopedThreadRef, kind: RightPanelKind) => void;
+ openBrowser: (ref: ScopedThreadRef, tabId: string | null) => void;
+ activateSurface: (ref: ScopedThreadRef, surfaceId: string) => void;
+ closeSurface: (ref: ScopedThreadRef, surfaceId: string) => void;
+ reconcileBrowserSurfaces: (ref: ScopedThreadRef, tabIds: readonly string[]) => void;
close: (ref: ScopedThreadRef) => void;
toggle: (ref: ScopedThreadRef, kind: RightPanelKind) => void;
removeThread: (ref: ScopedThreadRef) => void;
}
+const EMPTY_THREAD_STATE: ThreadRightPanelState = { activeSurfaceId: null, surfaces: [] };
+
+const singletonSurface = (kind: Exclude<RightPanelKind, "preview">): RightPanelSurface => {
+ switch (kind) {
+ case "terminal":
+ return { id: "terminal", kind };
+ case "diff":
+ return { id: "diff", kind };
+ case "plan":
+ return { id: "plan", kind };
+ }
+};
+
+const browserSurface = (tabId: string | null): RightPanelSurface =>
+ tabId
+ ? { id: `browser:${tabId}`, kind: "preview", resourceId: tabId }
+ : { id: "browser:new", kind: "preview", resourceId: null };
+
+const upsertSurface = (
+ current: ThreadRightPanelState,
+ surface: RightPanelSurface,
+ activate = true,
+): ThreadRightPanelState => ({
+ surfaces: current.surfaces.some((entry) => entry.id === surface.id)
+ ? current.surfaces
+ : [...current.surfaces, surface],
+ activeSurfaceId: activate ? surface.id : current.activeSurfaceId,
+});
+
const updateThread = (
byThreadKey: Record<string, ThreadRightPanelState>,
threadKey: string,
- next: ThreadRightPanelState,
+ updater: (current: ThreadRightPanelState) => ThreadRightPanelState,
): Record<string, ThreadRightPanelState> => {
- const current = byThreadKey[threadKey];
- if (current && current.active === next.active) return byThreadKey;
- if (next.active === null) {
- if (!current) return byThreadKey;
+ const current = byThreadKey[threadKey] ?? EMPTY_THREAD_STATE;
+ const next = updater(current);
+ if (next.activeSurfaceId === null && next.surfaces.length === 0) {
+ if (!(threadKey in byThreadKey)) return byThreadKey;
const { [threadKey]: _removed, ...rest } = byThreadKey;
return rest;
}
+ if (next === current) return byThreadKey;
return { ...byThreadKey, [threadKey]: next };
};
@@ -54,21 +93,92 @@ export const useRightPanelStore = create<RightPanelStoreState>()(
byThreadKey: {},
open: (ref, kind) =>
set((state) => ({
- byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), { active: kind }),
+ byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), (current) => {
+ if (kind === "preview") {
+ const existing = current.surfaces.find((surface) => surface.kind === "preview");
+ return upsertSurface(current, existing ?? browserSurface(null));
+ }
+ return upsertSurface(current, singletonSurface(kind));
+ }),
+ })),
+ openBrowser: (ref, tabId) =>
+ set((state) => ({
+ byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), (current) => {
+ const surface = browserSurface(tabId);
+ const withoutPlaceholder = tabId
+ ? current.surfaces.filter((entry) => entry.id !== "browser:new")
+ : current.surfaces;
+ return upsertSurface({ ...current, surfaces: withoutPlaceholder }, surface);
+ }),
+ })),
+ activateSurface: (ref, surfaceId) =>
+ set((state) => ({
+ byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), (current) =>
+ current.surfaces.some((surface) => surface.id === surfaceId)
+ ? { ...current, activeSurfaceId: surfaceId }
+ : current,
+ ),
+ })),
+ closeSurface: (ref, surfaceId) =>
+ set((state) => ({
+ byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), (current) => {
+ const index = current.surfaces.findIndex((surface) => surface.id === surfaceId);
+ if (index < 0) return current;
+ const surfaces = current.surfaces.filter((surface) => surface.id !== surfaceId);
+ if (current.activeSurfaceId !== surfaceId) return { ...current, surfaces };
+ const fallback = surfaces[Math.min(index, surfaces.length - 1)] ?? null;
+ return { surfaces, activeSurfaceId: fallback?.id ?? null };
+ }),
+ })),
+ reconcileBrowserSurfaces: (ref, tabIds) =>
+ set((state) => ({
+ byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), (current) => {
+ const validIds = new Set(tabIds.map((tabId) => `browser:${tabId}`));
+ const nonBrowser = current.surfaces.filter((surface) => surface.kind !== "preview");
+ const existingBrowser = current.surfaces.filter(
+ (surface): surface is Extract<RightPanelSurface, { kind: "preview" }> =>
+ surface.kind === "preview" &&
+ surface.id !== "browser:new" &&
+ validIds.has(surface.id),
+ );
+ const knownIds = new Set(existingBrowser.map((surface) => surface.id));
+ const added = tabIds
+ .filter((tabId) => !knownIds.has(`browser:${tabId}`))
+ .map((tabId) => browserSurface(tabId));
+ const surfaces = [...nonBrowser, ...existingBrowser, ...added];
+ const activeStillExists = surfaces.some(
+ (surface) => surface.id === current.activeSurfaceId,
+ );
+ const fallbackBrowser = surfaces.find((surface) => surface.kind === "preview");
+ return {
+ surfaces,
+ activeSurfaceId: activeStillExists
+ ? current.activeSurfaceId
+ : (fallbackBrowser?.id ?? surfaces[0]?.id ?? null),
+ };
+ }),
})),
close: (ref) =>
set((state) => ({
- byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), { active: null }),
+ byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), (current) => ({
+ ...current,
+ activeSurfaceId: null,
+ })),
})),
toggle: (ref, kind) =>
- set((state) => {
- const threadKey = scopedThreadKey(ref);
- const current = state.byThreadKey[threadKey]?.active ?? null;
- const next: RightPanelKind | null = current === kind ? null : kind;
- return {
- byThreadKey: updateThread(state.byThreadKey, threadKey, { active: next }),
- };
- }),
+ set((state) => ({
+ byThreadKey: updateThread(state.byThreadKey, scopedThreadKey(ref), (current) => {
+ const active = current.surfaces.find(
+ (surface) => surface.id === current.activeSurfaceId,
+ );
+ if (active?.kind === kind) return { ...current, activeSurfaceId: null };
+ if (kind === "preview") {
+ const existing = current.surfaces.find((surface) => surface.kind === "preview");
+ return upsertSurface(current, existing ?? browserSurface(null));
+ }
+ return upsertSurface(current, singletonSurface(kind));
+ }),
+ })),
removeThread: (ref) =>
set((state) => {
const threadKey = scopedThreadKey(ref);
@@ -79,7 +189,7 @@ export const useRightPanelStore = create<RightPanelStoreState>()(
}),
{
name: RIGHT_PANEL_STORAGE_KEY,
- version: 1,
+ version: 2,
storage: createJSONStorage(() =>
resolveStorage(typeof window !== "undefined" ? window.localStorage : undefined),
),
@@ -88,22 +198,30 @@ export const useRightPanelStore = create<RightPanelStoreState>()(
),
);
+export function selectThreadRightPanelState(
+ byThreadKey: Record<string, ThreadRightPanelState>,
+ ref: ScopedThreadRef | null | undefined,
+): ThreadRightPanelState {
+ if (!ref) return EMPTY_THREAD_STATE;
+ return byThreadKey[scopedThreadKey(ref)] ?? EMPTY_THREAD_STATE;
+}
+
export function selectActiveRightPanel(
byThreadKey: Record<string, ThreadRightPanelState>,
ref: ScopedThreadRef | null | undefined,
): RightPanelKind | null {
- if (!ref) return null;
- return byThreadKey[scopedThreadKey(ref)]?.active ?? null;
+ const state = selectThreadRightPanelState(byThreadKey, ref);
+ return state.surfaces.find((surface) => surface.id === state.activeSurfaceId)?.kind ?? null;
+}
+
+export function selectActiveRightPanelSurface(
+ byThreadKey: Record<string, ThreadRightPanelState>,
+ ref: ScopedThreadRef | null | undefined,
+): RightPanelSurface | null {
+ const state = selectThreadRightPanelState(byThreadKey, ref);
+ return state.surfaces.find((surface) => surface.id === state.activeSurfaceId) ?? null;
}
-/**
- * Resolves the active right panel taking the `?diff=1` URL truth into
- * account. When `diff=1` the diff panel always wins.
- *
- * Prefer using `useSyncDiffSearchToRightPanel` (in ChatView) to mirror the
- * URL into the store and consume `selectActiveRightPanel` directly — this
- * helper exists for callers that don't want to install the sync effect.
- */
export function selectActiveRightPanelKindWithUrl(
byThreadKey: Record<string, ThreadRightPanelState>,
ref: ScopedThreadRef | null | undefined,
diff --git a/apps/web/src/routes/_chat.$environmentId.$threadId.tsx b/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
index 1877fee6f..13b6f9a5d 100644
--- a/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
+++ b/apps/web/src/routes/_chat.$environmentId.$threadId.tsx
@@ -1,149 +1,20 @@
import { createFileRoute, retainSearchParams, useNavigate } from "@tanstack/react-router";
-import { Suspense, lazy, useCallback, useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo } from "react";
import ChatView from "../components/ChatView";
import { threadHasStarted } from "../components/ChatView.logic";
-import { DiffWorkerPoolProvider } from "../components/DiffWorkerPoolProvider";
-import {
- DiffPanelHeaderSkeleton,
- DiffPanelLoadingState,
- DiffPanelShell,
- type DiffPanelMode,
-} from "../components/DiffPanelShell";
import { finalizePromotedDraftThreadByRef, useComposerDraftStore } from "../composerDraftStore";
-import {
- type DiffRouteSearch,
- parseDiffRouteSearch,
- stripDiffSearchParams,
-} from "../diffRouteSearch";
-import { useMediaQuery } from "../hooks/useMediaQuery";
-import { RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY } from "../rightPanelLayout";
+import { type DiffRouteSearch, parseDiffRouteSearch } from "../diffRouteSearch";
import { selectEnvironmentState, selectThreadExistsByRef, useStore } from "../store";
import { createThreadSelectorByRef } from "../storeSelectors";
-import { resolveThreadRouteRef, buildThreadRouteParams } from "../threadRoutes";
-import { RightPanelSheet } from "../components/RightPanelSheet";
-import { Sidebar, SidebarInset, SidebarProvider, SidebarRail } from "~/components/ui/sidebar";
-
-const DiffPanel = lazy(() => import("../components/DiffPanel"));
-const DIFF_INLINE_SIDEBAR_WIDTH_STORAGE_KEY = "chat_diff_sidebar_width";
-const DIFF_INLINE_DEFAULT_WIDTH = "clamp(24rem,34vw,36rem)";
-const DIFF_INLINE_SIDEBAR_MIN_WIDTH = 22 * 16;
-const DIFF_INLINE_SIDEBAR_MAX_WIDTH = 256 * 16;
-const COMPOSER_COMPACT_MIN_LEFT_CONTROLS_WIDTH_PX = 208;
-
-const DiffLoadingFallback = (props: { mode: DiffPanelMode }) => {
- return (
- <DiffPanelShell mode={props.mode} header={<DiffPanelHeaderSkeleton />}>
- <DiffPanelLoadingState label="Loading diff viewer..." />
- </DiffPanelShell>
- );
-};
-
-const LazyDiffPanel = (props: { mode: DiffPanelMode }) => {
- return (
- <DiffWorkerPoolProvider>
- <Suspense fallback={<DiffLoadingFallback mode={props.mode} />}>
- <DiffPanel mode={props.mode} />
- </Suspense>
- </DiffWorkerPoolProvider>
- );
-};
-
-const DiffPanelInlineSidebar = (props: {
- diffOpen: boolean;
- onCloseDiff: () => void;
- onOpenDiff: () => void;
- renderDiffContent: boolean;
-}) => {
- const { diffOpen, onCloseDiff, onOpenDiff, renderDiffContent } = props;
- const onOpenChange = useCallback(
- (open: boolean) => {
- if (open) {
- onOpenDiff();
- return;
- }
- onCloseDiff();
- },
- [onCloseDiff, onOpenDiff],
- );
- const shouldAcceptInlineSidebarWidth = useCallback(
- ({ nextWidth, wrapper }: { nextWidth: number; wrapper: HTMLElement }) => {
- const composerForm = document.querySelector<HTMLElement>("[data-chat-composer-form='true']");
- if (!composerForm) return true;
- const composerViewport = composerForm.parentElement;
- if (!composerViewport) return true;
- const previousSidebarWidth = wrapper.style.getPropertyValue("--sidebar-width");
- wrapper.style.setProperty("--sidebar-width", `${nextWidth}px`);
-
- const viewportStyle = window.getComputedStyle(composerViewport);
- const viewportPaddingLeft = Number.parseFloat(viewportStyle.paddingLeft) || 0;
- const viewportPaddingRight = Number.parseFloat(viewportStyle.paddingRight) || 0;
- const viewportContentWidth = Math.max(
- 0,
- composerViewport.clientWidth - viewportPaddingLeft - viewportPaddingRight,
- );
- const formRect = composerForm.getBoundingClientRect();
- const composerFooter = composerForm.querySelector<HTMLElement>(
- "[data-chat-composer-footer='true']",
- );
- const composerRightActions = composerForm.querySelector<HTMLElement>(
- "[data-chat-composer-actions='right']",
- );
- const composerRightActionsWidth = composerRightActions?.getBoundingClientRect().width ?? 0;
- const composerFooterGap = composerFooter
- ? Number.parseFloat(window.getComputedStyle(composerFooter).columnGap) ||
- Number.parseFloat(window.getComputedStyle(composerFooter).gap) ||
- 0
- : 0;
- const minimumComposerWidth =
- COMPOSER_COMPACT_MIN_LEFT_CONTROLS_WIDTH_PX + composerRightActionsWidth + composerFooterGap;
- const hasComposerOverflow = composerForm.scrollWidth > composerForm.clientWidth + 0.5;
- const overflowsViewport = formRect.width > viewportContentWidth + 0.5;
- const violatesMinimumComposerWidth = composerForm.clientWidth + 0.5 < minimumComposerWidth;
-
- if (previousSidebarWidth.length > 0) {
- wrapper.style.setProperty("--sidebar-width", previousSidebarWidth);
- } else {
- wrapper.style.removeProperty("--sidebar-width");
- }
-
- return !hasComposerOverflow && !overflowsViewport && !violatesMinimumComposerWidth;
- },
- [],
- );
-
- return (
- <SidebarProvider
- defaultOpen={false}
- open={diffOpen}
- onOpenChange={onOpenChange}
- className="w-auto min-h-0 flex-none bg-transparent"
- style={{ "--sidebar-width": DIFF_INLINE_DEFAULT_WIDTH } as React.CSSProperties}
- >
- <Sidebar
- side="right"
- collapsible="offcanvas"
- className="border-l border-border bg-card text-foreground"
- resizable={{
- maxWidth: DIFF_INLINE_SIDEBAR_MAX_WIDTH,
- minWidth: DIFF_INLINE_SIDEBAR_MIN_WIDTH,
- shouldAcceptWidth: shouldAcceptInlineSidebarWidth,
- storageKey: DIFF_INLINE_SIDEBAR_WIDTH_STORAGE_KEY,
- }}
- >
- {renderDiffContent ? <LazyDiffPanel mode="sidebar" /> : null}
- <SidebarRail />
- </Sidebar>
- </SidebarProvider>
- );
-};
+import { resolveThreadRouteRef } from "../threadRoutes";
+import { SidebarInset } from "~/components/ui/sidebar";
function ChatThreadRouteView() {
const navigate = useNavigate();
const threadRef = Route.useParams({
select: (params) => resolveThreadRouteRef(params),
});
- const search = Route.useSearch();
const bootstrapComplete = useStore(
(store) => selectEnvironmentState(store, threadRef?.environmentId ?? null).bootstrapComplete,
);
@@ -159,120 +30,35 @@ function ChatThreadRouteView() {
threadRef ? store.getDraftThreadByRef(threadRef) : null,
);
const environmentHasDraftThreads = useComposerDraftStore((store) => {
- if (!threadRef) {
- return false;
- }
+ if (!threadRef) return false;
return store.hasDraftThreadsInEnvironment(threadRef.environmentId);
});
const routeThreadExists = threadExists || draftThreadExists;
const serverThreadStarted = threadHasStarted(serverThread);
const environmentHasAnyThreads = environmentHasServerThreads || environmentHasDraftThreads;
- const diffOpen = search.diff === "1";
- const shouldUseDiffSheet = useMediaQuery(RIGHT_PANEL_INLINE_LAYOUT_MEDIA_QUERY);
- const currentThreadKey = threadRef ? `${threadRef.environmentId}:${threadRef.threadId}` : null;
- const [diffPanelMountState, setDiffPanelMountState] = useState(() => ({
- threadKey: currentThreadKey,
- hasOpenedDiff: diffOpen,
- }));
- const hasOpenedDiff =
- diffPanelMountState.threadKey === currentThreadKey
- ? diffPanelMountState.hasOpenedDiff
- : diffOpen;
- const markDiffOpened = useCallback(() => {
- setDiffPanelMountState((previous) => {
- if (previous.threadKey === currentThreadKey && previous.hasOpenedDiff) {
- return previous;
- }
- return {
- threadKey: currentThreadKey,
- hasOpenedDiff: true,
- };
- });
- }, [currentThreadKey]);
- const closeDiff = useCallback(() => {
- if (!threadRef) {
- return;
- }
- void navigate({
- to: "/$environmentId/$threadId",
- params: buildThreadRouteParams(threadRef),
- search: { diff: undefined },
- });
- }, [navigate, threadRef]);
- const openDiff = useCallback(() => {
- if (!threadRef) {
- return;
- }
- markDiffOpened();
- void navigate({
- to: "/$environmentId/$threadId",
- params: buildThreadRouteParams(threadRef),
- search: (previous) => {
- const rest = stripDiffSearchParams(previous);
- return { ...rest, diff: "1" };
- },
- });
- }, [markDiffOpened, navigate, threadRef]);
useEffect(() => {
- if (!threadRef || !bootstrapComplete) {
- return;
- }
-
+ if (!threadRef || !bootstrapComplete) return;
if (!routeThreadExists && environmentHasAnyThreads) {
void navigate({ to: "/", replace: true });
}
}, [bootstrapComplete, environmentHasAnyThreads, navigate, routeThreadExists, threadRef]);
useEffect(() => {
- if (!threadRef || !serverThreadStarted || !draftThread?.promotedTo) {
- return;
- }
+ if (!threadRef || !serverThreadStarted || !draftThread?.promotedTo) return;
finalizePromotedDraftThreadByRef(threadRef);
}, [draftThread?.promotedTo, serverThreadStarted, threadRef]);
- if (!threadRef || !bootstrapComplete || !routeThreadExists) {
- return null;
- }
-
- const shouldRenderDiffContent = diffOpen || hasOpenedDiff;
-
- if (!shouldUseDiffSheet) {
- return (
- <>
- <SidebarInset className="h-svh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground md:h-dvh">
- <ChatView
- environmentId={threadRef.environmentId}
- threadId={threadRef.threadId}
- onDiffPanelOpen={markDiffOpened}
- reserveTitleBarControlInset={!diffOpen}
- routeKind="server"
- />
- </SidebarInset>
- <DiffPanelInlineSidebar
- diffOpen={diffOpen}
- onCloseDiff={closeDiff}
- onOpenDiff={openDiff}
- renderDiffContent={shouldRenderDiffContent}
- />
- </>
- );
- }
+ if (!threadRef || !bootstrapComplete || !routeThreadExists) return null;
return (
- <>
- <SidebarInset className="h-svh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground md:h-dvh">
- <ChatView
- environmentId={threadRef.environmentId}
- threadId={threadRef.threadId}
- onDiffPanelOpen={markDiffOpened}
- routeKind="server"
- />
- </SidebarInset>
- <RightPanelSheet open={diffOpen} onClose={closeDiff}>
- {shouldRenderDiffContent ? <LazyDiffPanel mode="sheet" /> : null}
- </RightPanelSheet>
- </>
+ <SidebarInset className="h-svh min-h-0 overflow-hidden overscroll-y-none bg-background text-foreground md:h-dvh">
+ <ChatView
+ environmentId={threadRef.environmentId}
+ threadId={threadRef.threadId}
+ routeKind="server"
+ />
+ </SidebarInset>
);
}
diff --git a/apps/web/src/session-logic.test.ts b/apps/web/src/session-logic.test.ts
index 970b16797..beb40aadf 100644
--- a/apps/web/src/session-logic.test.ts
+++ b/apps/web/src/session-logic.test.ts
@@ -934,6 +934,67 @@ describe("deriveWorkLogEntries", () => {
expect(entry?.toolLifecycleStatus).toBe("completed");
});
+ it("preserves MCP server, tool, arguments, and results for expanded display", () => {
+ const item = {
+ type: "mcpToolCall",
+ server: "t3-code",
+ tool: "preview_status",
+ arguments: {},
+ status: "completed",
+ result: { content: [{ type: "text", text: "attached" }] },
+ };
+ const activities: OrchestrationThreadActivity[] = [
+ makeActivity({
+ id: "mcp-tool-done",
+ kind: "tool.completed",
+ summary: "t3-code · preview_status",
+ payload: {
+ itemType: "mcp_tool_call",
+ title: "t3-code · preview_status",
+ data: { item },
+ },
+ }),
+ ];
+
+ const [entry] = deriveWorkLogEntries(activities);
+ expect(entry?.toolTitle).toBe("t3-code · preview_status");
+ expect(entry?.toolData).toEqual(item);
+ });
+
+ it("keeps MCP payloads while collapsing lifecycle updates", () => {
+ const item = {
+ type: "mcpToolCall",
+ server: "t3-code",
+ tool: "preview_snapshot",
+ arguments: { interactiveOnly: true },
+ status: "completed",
+ };
+ const activities: OrchestrationThreadActivity[] = [
+ makeActivity({
+ id: "mcp-tool-progress",
+ kind: "tool.updated",
+ summary: "t3-code · preview_snapshot",
+ payload: {
+ itemType: "mcp_tool_call",
+ toolCallId: "call-1",
+ data: { item },
+ },
+ }),
+ makeActivity({
+ id: "mcp-tool-complete",
+ kind: "tool.completed",
+ summary: "t3-code · preview_snapshot",
+ payload: {
+ itemType: "mcp_tool_call",
+ toolCallId: "call-1",
+ },
+ }),
+ ];
+
+ const [entry] = deriveWorkLogEntries(activities);
+ expect(entry?.toolData).toEqual(item);
+ });
+
it("unwraps PowerShell command wrappers for displayed command text", () => {
const activities: OrchestrationThreadActivity[] = [
makeActivity({
diff --git a/apps/web/src/session-logic.ts b/apps/web/src/session-logic.ts
index 95680e98b..5576ebeff 100644
--- a/apps/web/src/session-logic.ts
+++ b/apps/web/src/session-logic.ts
@@ -71,6 +71,7 @@ export interface WorkLogEntry {
changedFiles?: ReadonlyArray<string>;
tone: "thinking" | "tool" | "info" | "error";
toolTitle?: string;
+ toolData?: unknown;
itemType?: ToolLifecycleItemType;
requestKind?: PendingApproval["requestKind"];
/** From runtime item / task payload `status` when present (e.g. tool.updated). */
@@ -734,6 +735,12 @@ function toDerivedWorkLogEntry(activity: OrchestrationThreadActivity): DerivedWo
if (title) {
entry.toolTitle = title;
}
+ if (itemType === "mcp_tool_call") {
+ const data = asRecord(payload?.data);
+ if (data?.item !== undefined) {
+ entry.toolData = data.item;
+ }
+ }
if (itemType) {
entry.itemType = itemType;
}
@@ -811,6 +818,7 @@ function mergeDerivedWorkLogEntries(
const collapseKey = next.collapseKey ?? previous.collapseKey;
const toolCallId = next.toolCallId ?? previous.toolCallId;
const toolLifecycleStatus = next.toolLifecycleStatus ?? previous.toolLifecycleStatus;
+ const toolData = next.toolData ?? previous.toolData;
return {
...previous,
...next,
@@ -824,6 +832,7 @@ function mergeDerivedWorkLogEntries(
...(collapseKey ? { collapseKey } : {}),
...(toolCallId ? { toolCallId } : {}),
...(toolLifecycleStatus !== undefined ? { toolLifecycleStatus } : {}),
+ ...(toolData !== undefined ? { toolData } : {}),
};
}
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index bb0a1bd1e..00c5f130c 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -451,6 +451,7 @@ export interface DesktopPreviewTabState {
canGoForward: boolean;
/** Current zoom factor (1.0 = 100%). */
zoomFactor: number;
+ controller: "human" | "agent" | "none";
updatedAt: string;
}
@@ -477,6 +478,32 @@ export interface DesktopPreviewWebviewConfig {
preloadUrl: string | null;
}
+export interface DesktopPreviewRecordingFrame {
+ tabId: string;
+ data: string;
+ width: number;
+ height: number;
+ receivedAt: string;
+}
+
+export interface DesktopPreviewRecordingArtifact {
+ id: string;
+ tabId: string;
+ path: string;
+ mimeType: string;
+ sizeBytes: number;
+ createdAt: string;
+}
+
+export interface DesktopPreviewScreenshotArtifact {
+ id: string;
+ tabId: string;
+ path: string;
+ mimeType: "image/png";
+ sizeBytes: number;
+ createdAt: string;
+}
+
/**
* Single stack frame captured by react-grab's `getElementContext`. We surface
* the source file/line so coding agents can jump straight to the JSX that
@@ -672,7 +699,7 @@ export interface DesktopPreviewBridge {
* `getPickPreloadPath`) so adding a new field here only requires touching
* the contract + main, not the renderer's mount logic.
*/
- getPreviewConfig: () => Promise<DesktopPreviewWebviewConfig>;
+ getPreviewConfig: (environmentId: EnvironmentId) => Promise<DesktopPreviewWebviewConfig>;
/**
* Activate the in-page element picker for the given tab. Resolves with
* the picked payload, or `null` when the user cancels (Escape / nav). The
@@ -681,6 +708,17 @@ export interface DesktopPreviewBridge {
pickElement: (tabId: string) => Promise<PreviewAnnotationPayload | null>;
/** Cancel an in-flight preview annotation session. */
cancelPickElement: (tabId: string) => Promise<void>;
+ captureScreenshot: (tabId: string) => Promise<DesktopPreviewScreenshotArtifact>;
+ recording: {
+ startScreencast: (tabId: string) => Promise<void>;
+ stopScreencast: (tabId: string) => Promise<void>;
+ save: (
+ tabId: string,
+ mimeType: string,
+ data: Uint8Array,
+ ) => Promise<DesktopPreviewRecordingArtifact>;
+ onFrame: (listener: (frame: DesktopPreviewRecordingFrame) => void) => () => void;
+ };
automation: {
status: (tabId: string) => Promise<PreviewAutomationStatus>;
snapshot: (tabId: string) => Promise<PreviewAutomationSnapshot>;
diff --git a/packages/contracts/src/previewAutomation.ts b/packages/contracts/src/previewAutomation.ts
index eaadbcb48..791591a7a 100644
--- a/packages/contracts/src/previewAutomation.ts
+++ b/packages/contracts/src/previewAutomation.ts
@@ -3,10 +3,19 @@ import { Schema } from "effect";
import { EnvironmentId, ThreadId, TrimmedNonEmptyString } from "./baseSchemas.ts";
import { PreviewTabId } from "./preview.ts";
-const BoundedUrl = TrimmedNonEmptyString.check(Schema.isMaxLength(2048));
+const BoundedUrl = Schema.String.check(Schema.isTrimmed())
+ .check(
+ Schema.isNonEmpty({
+ description:
+ "Absolute http(s) URL or a schemeless host such as t3.chat or localhost:5173. Schemeless public hosts use https; loopback hosts use http.",
+ }),
+ )
+ .check(Schema.isMaxLength(2048));
const OptionalTimeoutMs = Schema.optional(
- Schema.Int.check(Schema.isGreaterThan(0)).check(Schema.isLessThanOrEqualTo(60_000)),
-);
+ Schema.Int.check(Schema.isGreaterThan(0))
+ .check(Schema.isLessThanOrEqualTo(60_000))
+ .annotate({ description: "Maximum wait in milliseconds. Defaults to 15000; maximum 60000." }),
+).annotate({ description: "Maximum wait in milliseconds. Defaults to 15000; maximum 60000." });
export const PreviewAutomationOperation = Schema.Literals([
"status",
@@ -19,6 +28,8 @@ export const PreviewAutomationOperation = Schema.Literals([
"scroll",
"evaluate",
"waitFor",
+ "recordingStart",
+ "recordingStop",
]);
export type PreviewAutomationOperation = typeof PreviewAutomationOperation.Type;
@@ -33,66 +44,294 @@ export const PreviewAutomationStatus = Schema.Struct({
export type PreviewAutomationStatus = typeof PreviewAutomationStatus.Type;
export const PreviewAutomationOpenInput = Schema.Struct({
- url: Schema.optional(BoundedUrl),
- show: Schema.optional(Schema.Boolean),
- reuseExistingTab: Schema.optional(Schema.Boolean),
+ url: Schema.optional(BoundedUrl).annotate({
+ description:
+ "Optional initial page URL, for example https://t3.chat or localhost:5173. Omit to open a blank tab.",
+ }),
+ show: Schema.optional(
+ Schema.Boolean.annotate({
+ description: "Whether to reveal the preview panel to the human. Defaults to true.",
+ }),
+ ),
+ reuseExistingTab: Schema.optional(
+ Schema.Boolean.annotate({
+ description:
+ "Reuse the thread's active browser tab when available. Defaults to true; set false to create a new tab.",
+ }),
+ ),
+}).annotate({
+ description:
+ "Opens the collaborative browser for the current thread. Use preview_navigate afterward when readiness waiting matters.",
});
export type PreviewAutomationOpenInput = typeof PreviewAutomationOpenInput.Type;
+export const BrowserNavigationTarget = Schema.Union([
+ Schema.Struct({
+ kind: Schema.Literal("url").annotate({
+ description: "Selects direct URL navigation.",
+ }),
+ url: BoundedUrl.annotate({
+ description: "Direct website URL.",
+ }),
+ }),
+ Schema.Struct({
+ kind: Schema.Literal("environment-port").annotate({
+ description: "Selects a dev-server port relative to the current execution environment.",
+ }),
+ port: Schema.Int.check(Schema.isGreaterThan(0))
+ .check(Schema.isLessThan(65_536))
+ .annotate({ description: "Dev-server TCP port inside the current environment." }),
+ protocol: Schema.optional(
+ Schema.Literals(["http", "https"]).annotate({
+ description: "Dev-server protocol. Defaults to http.",
+ }),
+ ),
+ path: Schema.optional(
+ Schema.String.annotate({
+ description: "Optional path, query, and fragment, for example /settings?tab=account.",
+ }),
+ ),
+ }),
+]);
+export type BrowserNavigationTarget = typeof BrowserNavigationTarget.Type;
+
export const PreviewAutomationNavigateInput = Schema.Struct({
- url: BoundedUrl,
- readiness: Schema.optional(Schema.Literals(["load", "domContentLoaded", "none"])),
+ url: Schema.optional(BoundedUrl).annotate({
+ description:
+ "Website URL, for example https://t3.chat. Use this for public pages and directly reachable URLs.",
+ }),
+ target: Schema.optional(
+ BrowserNavigationTarget.annotate({
+ description:
+ "Environment-relative target. Prefer {kind:'environment-port',port:5173} for a dev server in the current environment.",
+ }),
+ ).annotate({
+ description:
+ "Environment-relative target. Prefer {kind:'environment-port',port:5173} for a dev server in the current environment.",
+ }),
+ readiness: Schema.optional(
+ Schema.Literals(["load", "domContentLoaded", "none"]).annotate({
+ description:
+ "Readiness milestone before returning. 'load' waits for loading to stop (default), 'domContentLoaded' waits for an interactive document, and 'none' returns immediately.",
+ }),
+ ).annotate({
+ description:
+ "Readiness milestone before returning. 'load' is the default; use 'none' only when a later wait call will verify the page.",
+ }),
timeoutMs: OptionalTimeoutMs,
-});
+})
+ .check(
+ Schema.makeFilter(
+ (input) =>
+ Number(input.url !== undefined) + Number(input.target !== undefined) === 1 ||
+ "Provide exactly one of url or target.",
+ ),
+ )
+ .annotate({
+ description:
+ "Navigates the active browser tab. Provide exactly one of url or target; for most public pages use url.",
+ });
export type PreviewAutomationNavigateInput = typeof PreviewAutomationNavigateInput.Type;
-export const PreviewAutomationClickInput = Schema.Union([
- Schema.Struct({
- selector: TrimmedNonEmptyString,
- timeoutMs: OptionalTimeoutMs,
+const Locator = TrimmedNonEmptyString.annotate({
+ description:
+ "Playwright selector, preferably role/text based, for example role=button[name='Send'] or text=Continue. Use snapshot first to inspect the page.",
+});
+
+const LegacySelector = TrimmedNonEmptyString.annotate({
+ description:
+ "Legacy CSS selector such as button[type='submit']. Prefer locator for resilient role/text targeting.",
+});
+
+export const PreviewAutomationClickInput = Schema.Struct({
+ selector: Schema.optional(LegacySelector).annotate({
+ description:
+ "Legacy CSS selector such as button[type='submit']. Prefer locator for resilient role/text targeting.",
}),
- Schema.Struct({
- x: Schema.Number,
- y: Schema.Number,
- timeoutMs: OptionalTimeoutMs,
+ locator: Schema.optional(Locator).annotate({
+ description:
+ "Playwright selector, preferably role/text based, for example role=button[name='Send'] or text=Continue. Use snapshot first to inspect the page.",
}),
-]);
+ x: Schema.optional(
+ Schema.Finite.annotate({
+ description: "Viewport-relative X coordinate in CSS pixels. Must be paired with y.",
+ }),
+ ),
+ y: Schema.optional(
+ Schema.Finite.annotate({
+ description: "Viewport-relative Y coordinate in CSS pixels. Must be paired with x.",
+ }),
+ ),
+ timeoutMs: OptionalTimeoutMs,
+})
+ .check(
+ Schema.makeFilter((input) => {
+ const selectorModes =
+ Number(input.selector !== undefined) + Number(input.locator !== undefined);
+ const hasX = input.x !== undefined;
+ const hasY = input.y !== undefined;
+ if (hasX !== hasY) return "Coordinates require both x and y.";
+ const coordinateModes = hasX && hasY ? 1 : 0;
+ return selectorModes + coordinateModes === 1 || "Provide exactly one click target.";
+ }),
+ )
+ .annotate({
+ description:
+ "Clicks one target. Provide exactly one of locator, selector, or the x/y coordinate pair.",
+ });
export type PreviewAutomationClickInput = typeof PreviewAutomationClickInput.Type;
export const PreviewAutomationTypeInput = Schema.Struct({
- text: Schema.String,
- selector: Schema.optional(TrimmedNonEmptyString),
- clear: Schema.optional(Schema.Boolean),
+ text: Schema.String.annotate({ description: "Literal text to insert." }),
+ selector: Schema.optional(LegacySelector).annotate({
+ description: "Legacy CSS selector for the input. Prefer locator.",
+ }),
+ locator: Schema.optional(Locator).annotate({
+ description:
+ "Playwright selector for the input, for example role=textbox[name='Message'] or textarea[placeholder*='Message'].",
+ }),
+ clear: Schema.optional(
+ Schema.Boolean.annotate({
+ description: "Clear the existing input value before inserting text. Defaults to false.",
+ }),
+ ),
timeoutMs: OptionalTimeoutMs,
-});
+})
+ .check(
+ Schema.makeFilter(
+ (input) =>
+ !(input.selector !== undefined && input.locator !== undefined) ||
+ "Provide at most one of selector or locator.",
+ ),
+ )
+ .annotate({
+ description:
+ "Types into locator/selector, or into the currently focused element when neither target is provided.",
+ });
export type PreviewAutomationTypeInput = typeof PreviewAutomationTypeInput.Type;
export const PreviewAutomationPressInput = Schema.Struct({
- key: TrimmedNonEmptyString,
- modifiers: Schema.optional(Schema.Array(Schema.Literals(["Alt", "Control", "Meta", "Shift"]))),
-});
+ key: Schema.String.check(Schema.isTrimmed())
+ .check(
+ Schema.isNonEmpty({
+ description:
+ "Keyboard key name such as Enter, Escape, Tab, ArrowDown, Backspace, or a single character.",
+ }),
+ )
+ .annotateKey({
+ description:
+ "Keyboard key name such as Enter, Escape, Tab, ArrowDown, Backspace, or a single character.",
+ }),
+ modifiers: Schema.optional(
+ Schema.Array(Schema.Literals(["Alt", "Control", "Meta", "Shift"])).annotate({
+ description: "Modifier keys held while pressing key.",
+ }),
+ ),
+}).annotate({ description: "Presses one keyboard key in the active browser tab." });
export type PreviewAutomationPressInput = typeof PreviewAutomationPressInput.Type;
export const PreviewAutomationScrollInput = Schema.Struct({
- deltaX: Schema.optional(Schema.Number),
- deltaY: Schema.optional(Schema.Number),
- selector: Schema.optional(TrimmedNonEmptyString),
-});
+ deltaX: Schema.optional(
+ Schema.Finite.annotate({
+ description: "Horizontal scroll delta in CSS pixels. Positive scrolls right. Defaults to 0.",
+ }),
+ ),
+ deltaY: Schema.optional(
+ Schema.Finite.annotate({
+ description: "Vertical scroll delta in CSS pixels. Positive scrolls down. Defaults to 0.",
+ }),
+ ),
+ selector: Schema.optional(LegacySelector).annotate({
+ description: "Legacy CSS selector for a scrollable container. Omit to scroll the viewport.",
+ }),
+ locator: Schema.optional(Locator).annotate({
+ description: "Playwright selector for a scrollable container. Omit to scroll the viewport.",
+ }),
+})
+ .check(
+ Schema.makeFilter((input) => {
+ if (input.selector !== undefined && input.locator !== undefined) {
+ return "Provide at most one of selector or locator.";
+ }
+ return (
+ input.deltaX !== undefined || input.deltaY !== undefined || "Provide deltaX or deltaY."
+ );
+ }),
+ )
+ .annotate({
+ description:
+ "Scrolls the viewport, or a locator/selector container. Provide deltaX, deltaY, or both.",
+ });
export type PreviewAutomationScrollInput = typeof PreviewAutomationScrollInput.Type;
export const PreviewAutomationEvaluateInput = Schema.Struct({
- expression: TrimmedNonEmptyString.check(Schema.isMaxLength(64_000)),
- awaitPromise: Schema.optional(Schema.Boolean),
- returnByValue: Schema.optional(Schema.Boolean),
+ expression: Schema.String.check(Schema.isTrimmed())
+ .check(
+ Schema.isNonEmpty({
+ description:
+ "JavaScript expression evaluated in the page's main frame, for example document.title or (() => ({href: location.href}))().",
+ }),
+ )
+ .check(Schema.isMaxLength(64_000))
+ .annotateKey({
+ description:
+ "JavaScript expression evaluated in the page's main frame, for example document.title or (() => ({href: location.href}))().",
+ }),
+ awaitPromise: Schema.optional(
+ Schema.Boolean.annotate({ description: "Await a returned Promise. Defaults to true." }),
+ ),
+ returnByValue: Schema.optional(
+ Schema.Boolean.annotate({
+ description:
+ "Serialize and return the value instead of a remote object reference. Defaults to true.",
+ }),
+ ),
+}).annotate({
+ description:
+ "Evaluates JavaScript in the page. Prefer snapshot and semantic actions; use evaluate for inspection or unsupported interactions.",
});
export type PreviewAutomationEvaluateInput = typeof PreviewAutomationEvaluateInput.Type;
export const PreviewAutomationWaitForInput = Schema.Struct({
- selector: Schema.optional(TrimmedNonEmptyString),
- text: Schema.optional(TrimmedNonEmptyString),
- urlIncludes: Schema.optional(TrimmedNonEmptyString),
+ selector: Schema.optional(LegacySelector).annotate({
+ description: "Legacy CSS selector that must match an element. Prefer locator.",
+ }),
+ locator: Schema.optional(Locator).annotate({
+ description:
+ "Playwright selector that must match an element, for example role=button[name='Send'].",
+ }),
+ text: Schema.optional(
+ TrimmedNonEmptyString.annotate({
+ description: "Case-sensitive substring that must appear in visible document text.",
+ }),
+ ).annotate({
+ description: "Case-sensitive substring that must appear in visible document text.",
+ }),
+ urlIncludes: Schema.optional(
+ TrimmedNonEmptyString.annotate({
+ description: "Substring that must appear in the current absolute URL.",
+ }),
+ ).annotate({ description: "Substring that must appear in the current absolute URL." }),
timeoutMs: OptionalTimeoutMs,
-});
+})
+ .check(
+ Schema.makeFilter((input) => {
+ if (input.selector !== undefined && input.locator !== undefined) {
+ return "Provide at most one of selector or locator.";
+ }
+ return (
+ input.selector !== undefined ||
+ input.locator !== undefined ||
+ input.text !== undefined ||
+ input.urlIncludes !== undefined ||
+ "Provide at least one wait condition."
+ );
+ }),
+ )
+ .annotate({
+ description:
+ "Waits until all provided conditions match. Use after click/type when the page changes asynchronously.",
+ });
export type PreviewAutomationWaitForInput = typeof PreviewAutomationWaitForInput.Type;
export const PreviewAutomationElement = Schema.Struct({
@@ -107,6 +346,34 @@ export const PreviewAutomationElement = Schema.Struct({
});
export type PreviewAutomationElement = typeof PreviewAutomationElement.Type;
+export const PreviewAutomationConsoleEntry = Schema.Struct({
+ level: Schema.String,
+ text: Schema.String,
+ timestamp: Schema.String,
+ source: Schema.optional(Schema.String),
+});
+export type PreviewAutomationConsoleEntry = typeof PreviewAutomationConsoleEntry.Type;
+
+export const PreviewAutomationNetworkEntry = Schema.Struct({
+ url: Schema.String,
+ method: Schema.String,
+ status: Schema.NullOr(Schema.Number),
+ failed: Schema.Boolean,
+ errorText: Schema.optional(Schema.String),
+ timestamp: Schema.String,
+});
+export type PreviewAutomationNetworkEntry = typeof PreviewAutomationNetworkEntry.Type;
+
+export const PreviewAutomationActionEvent = Schema.Struct({
+ id: Schema.String,
+ action: Schema.String,
+ status: Schema.Literals(["running", "succeeded", "failed", "interrupted"]),
+ startedAt: Schema.String,
+ completedAt: Schema.optional(Schema.String),
+ error: Schema.optional(Schema.String),
+});
+export type PreviewAutomationActionEvent = typeof PreviewAutomationActionEvent.Type;
+
export const PreviewAutomationSnapshot = Schema.Struct({
url: Schema.String,
title: Schema.String,
@@ -114,6 +381,9 @@ export const PreviewAutomationSnapshot = Schema.Struct({
visibleText: Schema.String,
interactiveElements: Schema.Array(PreviewAutomationElement),
accessibilityTree: Schema.Unknown,
+ consoleEntries: Schema.Array(PreviewAutomationConsoleEntry),
+ networkEntries: Schema.Array(PreviewAutomationNetworkEntry),
+ actionTimeline: Schema.Array(PreviewAutomationActionEvent),
screenshot: Schema.Struct({
mimeType: Schema.Literal("image/png"),
data: Schema.String,
@@ -123,6 +393,23 @@ export const PreviewAutomationSnapshot = Schema.Struct({
});
export type PreviewAutomationSnapshot = typeof PreviewAutomationSnapshot.Type;
+export const PreviewAutomationRecordingStatus = Schema.Struct({
+ tabId: PreviewTabId,
+ recording: Schema.Boolean,
+ startedAt: Schema.NullOr(Schema.String),
+});
+export type PreviewAutomationRecordingStatus = typeof PreviewAutomationRecordingStatus.Type;
+
+export const PreviewAutomationRecordingArtifact = Schema.Struct({
+ id: Schema.String,
+ tabId: PreviewTabId,
+ path: Schema.String,
+ mimeType: Schema.String,
+ sizeBytes: Schema.Int,
+ createdAt: Schema.String,
+});
+export type PreviewAutomationRecordingArtifact = typeof PreviewAutomationRecordingArtifact.Type;
+
export const PreviewAutomationOwner = Schema.Struct({
clientId: TrimmedNonEmptyString,
environmentId: EnvironmentId,
@@ -183,6 +470,11 @@ export class PreviewAutomationTimeoutError extends Schema.TaggedErrorClass<Previ
{ message: Schema.String },
) {}
+export class PreviewAutomationControlInterruptedError extends Schema.TaggedErrorClass<PreviewAutomationControlInterruptedError>()(
+ "PreviewAutomationControlInterruptedError",
+ { message: Schema.String },
+) {}
+
export class PreviewAutomationExecutionError extends Schema.TaggedErrorClass<PreviewAutomationExecutionError>()(
"PreviewAutomationExecutionError",
{ message: Schema.String, detail: Schema.optional(Schema.Unknown) },
@@ -204,6 +496,7 @@ export const PreviewAutomationError = Schema.Union([
PreviewAutomationUnsupportedClientError,
PreviewAutomationTabNotFoundError,
PreviewAutomationTimeoutError,
+ PreviewAutomationControlInterruptedError,
PreviewAutomationExecutionError,
PreviewAutomationInvalidSelectorError,
PreviewAutomationResultTooLargeError,
@@ -213,7 +506,7 @@ export type PreviewAutomationError = typeof PreviewAutomationError.Type;
export const PreviewUrlResolution = Schema.Struct({
requestedUrl: Schema.String,
resolvedUrl: Schema.String,
- resolutionKind: Schema.Literal("direct"),
+ resolutionKind: Schema.Literals(["direct", "direct-private-network"]),
environmentId: EnvironmentId,
});
export type PreviewUrlResolution = typeof PreviewUrlResolution.Type;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9b012818b..de9a7b2a8 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -128,6 +128,9 @@ importers:
electron-updater:
specifier: ^6.6.2
version: 6.8.3
+ playwright-core:
+ specifier: 1.60.0
+ version: 1.60.0
react-grab:
specifier: ^0.1.32
version: 0.1.44([email protected])