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.

feat(web): configurable browser defaults in Settings → Integrations (#7082)

Julius Marminge949feb61e4bf
diff --git a/apps/desktop/src/ipc/methods/preview.ts b/apps/desktop/src/ipc/methods/preview.ts
index febdefa98..2453cfc0b 100644
--- a/apps/desktop/src/ipc/methods/preview.ts
+++ b/apps/desktop/src/ipc/methods/preview.ts
@@ -14,6 +14,7 @@ import {
DesktopPreviewRegisterWebviewInputSchema,
DesktopPreviewScreenshotArtifactSchema,
DesktopPreviewSetColorSchemeInputSchema,
+ DesktopPreviewCreateTabInputSchema,
DesktopPreviewTabInputSchema,
DesktopPreviewWebviewConfigSchema,
PreviewAnnotationSubmissionResultSchema,
@@ -48,11 +49,15 @@ export const installPreviewEventForwarding = Effect.fn(
export const createTab = DesktopIpc.makeIpcMethod({
channel: IpcChannels.PREVIEW_CREATE_TAB_CHANNEL,
- payload: DesktopPreviewTabInputSchema,
+ payload: DesktopPreviewCreateTabInputSchema,
result: Schema.Void,
- handler: Effect.fn("desktop.ipc.preview.createTab")(function* ({ tabId }) {
+ handler: Effect.fn("desktop.ipc.preview.createTab")(function* ({
+ tabId,
+ zoomFactor,
+ colorScheme,
+ }) {
const manager = yield* PreviewManager.PreviewManager;
- yield* manager.createTab(tabId);
+ yield* manager.createTab(tabId, { zoomFactor, colorScheme });
}),
});
diff --git a/apps/desktop/src/preload.ts b/apps/desktop/src/preload.ts
index 6741e3922..b56be717e 100644
--- a/apps/desktop/src/preload.ts
+++ b/apps/desktop/src/preload.ts
@@ -163,7 +163,12 @@ contextBridge.exposeInMainWorld("desktopBridge", {
};
},
preview: {
- createTab: (tabId) => ipcRenderer.invoke(IpcChannels.PREVIEW_CREATE_TAB_CHANNEL, { tabId }),
+ createTab: (tabId, defaults) =>
+ ipcRenderer.invoke(IpcChannels.PREVIEW_CREATE_TAB_CHANNEL, {
+ tabId,
+ zoomFactor: defaults?.zoomFactor,
+ colorScheme: defaults?.colorScheme,
+ }),
closeTab: (tabId) => ipcRenderer.invoke(IpcChannels.PREVIEW_CLOSE_TAB_CHANNEL, { tabId }),
registerWebview: (tabId, webContentsId) =>
ipcRenderer.invoke(IpcChannels.PREVIEW_REGISTER_WEBVIEW_CHANNEL, { tabId, webContentsId }),
diff --git a/apps/desktop/src/preview/Manager.ts b/apps/desktop/src/preview/Manager.ts
index e5a08e7da..63abde47d 100644
--- a/apps/desktop/src/preview/Manager.ts
+++ b/apps/desktop/src/preview/Manager.ts
@@ -16,6 +16,7 @@ import type {
DesktopPreviewRecordingArtifact,
DesktopPreviewRecordingFrame,
DesktopPreviewScreenshotArtifact,
+ DesktopPreviewTabDefaults,
PreviewAutomationClickInput,
PreviewAutomationActionEvent,
PreviewAutomationConsoleEntry,
@@ -334,6 +335,21 @@ const findZoomStep = (current: number): number => {
return Math.abs(ZOOM_LEVELS[index]! - current) < ZOOM_EPSILON ? index : index - 1;
};
+/**
+ * Clamp a client-supplied zoom factor onto the discrete ladder. The setting is
+ * chosen from the same ladder, but it arrives over IPC from a schema that only
+ * guarantees a positive number, so an out-of-band value snaps to the nearest
+ * step rather than leaving the guest at a zoom the zoom controls can't reach.
+ */
+const normalizeZoomFactor = (value: number | undefined): number => {
+ if (value === undefined || !Number.isFinite(value)) return DEFAULT_ZOOM_FACTOR;
+ let closest = ZOOM_LEVELS[0]!;
+ for (const level of ZOOM_LEVELS) {
+ if (Math.abs(level - value) < Math.abs(closest - value)) closest = level;
+ }
+ return closest;
+};
+
const nextZoomLevel = (current: number, direction: "in" | "out"): number => {
const step = findZoomStep(current);
if (direction === "in") {
@@ -1614,6 +1630,7 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
const createTabUnlocked = Effect.fn("PreviewManager.createTabUnlocked")(function* (
tabId: string,
+ defaults?: DesktopPreviewTabDefaults,
) {
const updatedAt = yield* currentIso;
const result = yield* SynchronizedRef.modify(
@@ -1632,9 +1649,9 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
navStatus: { kind: "Idle" },
canGoBack: false,
canGoForward: false,
- zoomFactor: DEFAULT_ZOOM_FACTOR,
+ zoomFactor: normalizeZoomFactor(defaults?.zoomFactor),
pictureInPicture: false,
- colorScheme: "system",
+ colorScheme: defaults?.colorScheme ?? "system",
controller: "none",
updatedAt,
};
@@ -1653,8 +1670,11 @@ const makeNativeOperations = Effect.fn("PreviewManager.makeOperations")(function
return result.state;
});
- const createTab = Effect.fn("PreviewManager.createTab")(function* (tabId: string) {
- return yield* withTabLifecycleLock(tabId, createTabUnlocked(tabId));
+ const createTab = Effect.fn("PreviewManager.createTab")(function* (
+ tabId: string,
+ defaults?: DesktopPreviewTabDefaults,
+ ) {
+ return yield* withTabLifecycleLock(tabId, createTabUnlocked(tabId, defaults));
});
const closeTabUnlocked = Effect.fn("PreviewManager.closeTabUnlocked")(function* (tabId: string) {
@@ -3802,7 +3822,10 @@ export class PreviewManager extends Context.Service<
readonly setMainWindow: (window: BrowserWindow) => Effect.Effect<void, PreviewManagerError>;
readonly getBrowserSession: (scope?: string) => Effect.Effect<Session, PreviewManagerError>;
readonly isBrowserPartition: (partition: string) => boolean;
- readonly createTab: (tabId: string) => Effect.Effect<PreviewTabState, PreviewManagerError>;
+ readonly createTab: (
+ tabId: string,
+ defaults?: DesktopPreviewTabDefaults,
+ ) => Effect.Effect<PreviewTabState, PreviewManagerError>;
readonly closeTab: (tabId: string) => Effect.Effect<void, PreviewManagerError>;
readonly registerWebview: (
tabId: string,
diff --git a/apps/desktop/src/settings/DesktopClientSettings.test.ts b/apps/desktop/src/settings/DesktopClientSettings.test.ts
index 23a75eb3f..1c17d5821 100644
--- a/apps/desktop/src/settings/DesktopClientSettings.test.ts
+++ b/apps/desktop/src/settings/DesktopClientSettings.test.ts
@@ -13,6 +13,10 @@ import * as DesktopEnvironment from "../app/DesktopEnvironment.ts";
import * as DesktopClientSettings from "./DesktopClientSettings.ts";
const clientSettings: ClientSettings = {
+ browserDefaultViewport: { _tag: "preset", width: 1024, height: 600, presetId: "nest-hub" },
+ browserDefaultZoomFactor: 1.25,
+ browserDefaultAppearance: "dark",
+ browserAutoShowFloatingPreview: false,
confirmQuit: true,
confirmThreadArchive: true,
confirmThreadDelete: false,
diff --git a/apps/server/src/mcp/toolkits/preview/handlers.test.ts b/apps/server/src/mcp/toolkits/preview/handlers.test.ts
index 93985fc9d..2c4e66746 100644
--- a/apps/server/src/mcp/toolkits/preview/handlers.test.ts
+++ b/apps/server/src/mcp/toolkits/preview/handlers.test.ts
@@ -3,12 +3,10 @@ import { describe, expect, it } from "vite-plus/test";
import { normalizePreviewOpenInput } from "./handlers.ts";
describe("normalizePreviewOpenInput", () => {
- it("opens the inline preview and reuses the current tab by default", () => {
- expect(normalizePreviewOpenInput({})).toEqual({
- open: true,
- reuseExistingTab: true,
- show: true,
- });
+ it("leaves an unstated visibility for the client preference to decide", () => {
+ // Filling `open` in here would outrank `browserAutoShowFloatingPreview`,
+ // which is desktop-local and cannot be read from the server.
+ expect(normalizePreviewOpenInput({})).toEqual({ reuseExistingTab: true });
});
it("preserves an explicit background-only opt-out", () => {
diff --git a/apps/server/src/mcp/toolkits/preview/handlers.ts b/apps/server/src/mcp/toolkits/preview/handlers.ts
index 25be8b363..17da78014 100644
--- a/apps/server/src/mcp/toolkits/preview/handlers.ts
+++ b/apps/server/src/mcp/toolkits/preview/handlers.ts
@@ -15,14 +15,21 @@ import * as McpInvocationContext from "../../McpInvocationContext.ts";
import * as PreviewAutomationBroker from "../../PreviewAutomationBroker.ts";
import { PreviewSnapshotToolkit, PreviewStandardToolkit, PreviewToolkit } from "./tools.ts";
+/**
+ * Collapses the `show` alias onto `open` and defaults tab reuse.
+ *
+ * Deliberately leaves an unstated `open` unstated. Whether a preview the agent
+ * said nothing about surfaces is the user's `browserAutoShowFloatingPreview`
+ * preference, which is desktop-local and unreadable from here — filling in
+ * `true` would silently override it for every `preview_open`.
+ */
export function normalizePreviewOpenInput(
input: PreviewAutomationOpenInput,
): PreviewAutomationOpenInput {
- const open = input.open ?? input.show ?? true;
+ const open = input.open ?? input.show;
return {
...input,
- open,
- show: open,
+ ...(open === undefined ? {} : { open, show: open }),
reuseExistingTab: input.reuseExistingTab ?? true,
};
}
diff --git a/apps/server/src/preview/Manager.ts b/apps/server/src/preview/Manager.ts
index e38e28ecd..09bbe0a41 100644
--- a/apps/server/src/preview/Manager.ts
+++ b/apps/server/src/preview/Manager.ts
@@ -24,6 +24,7 @@ import {
FILL_PREVIEW_VIEWPORT,
PreviewSessionLookupError,
type PreviewSessionSnapshot,
+ type PreviewViewportSetting,
} from "@t3tools/contracts";
import {
isPreviewUrlNormalizationError,
@@ -121,6 +122,7 @@ const buildLoadingSnapshot = (input: {
readonly tabId: string;
readonly url: string;
readonly title: string;
+ readonly viewport: PreviewViewportSetting;
readonly updatedAt: string;
}): PreviewSessionSnapshot => ({
threadId: input.threadId,
@@ -128,13 +130,14 @@ const buildLoadingSnapshot = (input: {
navStatus: { _tag: "Loading", url: input.url, title: input.title },
canGoBack: false,
canGoForward: false,
- viewport: FILL_PREVIEW_VIEWPORT,
+ viewport: input.viewport,
updatedAt: input.updatedAt,
});
const buildIdleSnapshot = (input: {
readonly threadId: string;
readonly tabId: string;
+ readonly viewport: PreviewViewportSetting;
readonly updatedAt: string;
}): PreviewSessionSnapshot => ({
threadId: input.threadId,
@@ -142,7 +145,7 @@ const buildIdleSnapshot = (input: {
navStatus: { _tag: "Idle" },
canGoBack: false,
canGoForward: false,
- viewport: FILL_PREVIEW_VIEWPORT,
+ viewport: input.viewport,
updatedAt: input.updatedAt,
});
@@ -215,15 +218,20 @@ export const make = Effect.gen(function* PreviewManagerMake() {
function* (input) {
const tabId = newPreviewTabId();
const updatedAt = yield* currentIsoTimestamp;
+ // Clients with a configured default send the viewport up front so the
+ // session is born at the right size; older clients omit it and keep the
+ // historical fill-panel behaviour.
+ const viewport = input.viewport ?? FILL_PREVIEW_VIEWPORT;
const snapshot = input.url
? buildLoadingSnapshot({
threadId: input.threadId,
tabId,
url: yield* normalizeUrl(input.url),
title: "",
+ viewport,
updatedAt,
})
- : buildIdleSnapshot({ threadId: input.threadId, tabId, updatedAt });
+ : buildIdleSnapshot({ threadId: input.threadId, tabId, viewport, updatedAt });
yield* SynchronizedRef.modifyEffect(stateRef, (state) =>
Effect.gen(function* () {
const revision = state.revision + 1;
diff --git a/apps/web/src/browser/BrowserDeviceToolbar.tsx b/apps/web/src/browser/BrowserDeviceToolbar.tsx
index 65d2b538a..e8ad80b59 100644
--- a/apps/web/src/browser/BrowserDeviceToolbar.tsx
+++ b/apps/web/src/browser/BrowserDeviceToolbar.tsx
@@ -26,6 +26,7 @@ import { cn } from "~/lib/utils";
import { BROWSER_DEVICE_TOOLBAR_HEIGHT, resizeFreeformViewport } from "./browserViewportLayout";
import { commitViewportAndAspectRatio } from "./browserDeviceToolbarState";
+import { ScreenRotationIcon } from "./ScreenRotationIcon";
const RESPONSIVE_VALUE = "responsive";
const SELECT_ITEMS = [
@@ -33,26 +34,6 @@ const SELECT_ITEMS = [
...PREVIEW_VIEWPORT_PRESETS.map((preset) => ({ value: preset.id, label: preset.label })),
];
-function ScreenRotationIcon() {
- return (
- <svg
- viewBox="0 0 24 24"
- fill="none"
- stroke="currentColor"
- strokeWidth="2"
- strokeLinecap="round"
- strokeLinejoin="round"
- aria-hidden="true"
- >
- <rect x="7.25" y="7.25" width="9.5" height="9.5" rx="1.4" transform="rotate(-45 12 12)" />
- <path d="M12.5 2a10 10 0 0 1 8.4 5.4" />
- <path d="M20.8 3.5v4h-4" />
- <path d="M11.5 22a10 10 0 0 1-8.4-5.4" />
- <path d="M3.2 20.5v-4h4" />
- </svg>
- );
-}
-
interface Props {
readonly setting: Exclude<PreviewViewportSetting, { readonly _tag: "fill" }>;
readonly width: number;
diff --git a/apps/web/src/browser/ScreenRotationIcon.tsx b/apps/web/src/browser/ScreenRotationIcon.tsx
new file mode 100644
index 000000000..6e6bf7483
--- /dev/null
+++ b/apps/web/src/browser/ScreenRotationIcon.tsx
@@ -0,0 +1,26 @@
+/**
+ * Screen-rotation glyph shared by the in-browser device toolbar and the
+ * default-viewport setting, so the orientation control reads the same in both
+ * places.
+ *
+ * @module ScreenRotationIcon
+ */
+export function ScreenRotationIcon() {
+ return (
+ <svg
+ viewBox="0 0 24 24"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ aria-hidden="true"
+ >
+ <rect x="7.25" y="7.25" width="9.5" height="9.5" rx="1.4" transform="rotate(-45 12 12)" />
+ <path d="M12.5 2a10 10 0 0 1 8.4 5.4" />
+ <path d="M20.8 3.5v4h-4" />
+ <path d="M11.5 22a10 10 0 0 1-8.4-5.4" />
+ <path d="M3.2 20.5v-4h4" />
+ </svg>
+ );
+}
diff --git a/apps/web/src/browser/browserDefaults.ts b/apps/web/src/browser/browserDefaults.ts
new file mode 100644
index 000000000..da8bf6a65
--- /dev/null
+++ b/apps/web/src/browser/browserDefaults.ts
@@ -0,0 +1,114 @@
+/**
+ * Browser defaults - resolves the configured starting state for preview tabs.
+ *
+ * Settings → Integrations → Browser lets the user pick the viewport, zoom, and
+ * appearance a preview tab should open at. Those preferences apply to every
+ * entry point that opens a tab without stating its own: the user opening a
+ * browser panel, and agents calling `preview_open` with no size.
+ *
+ * The values live in client settings because the Chromium guest they configure
+ * is desktop-local, so this module reads them through the same external store
+ * the settings UI writes to, and exposes a non-hook accessor for the imperative
+ * open paths that run outside React.
+ *
+ * @module browserDefaults
+ */
+import type {
+ DesktopPreviewTabDefaults,
+ PreviewAppearancePreference,
+ PreviewViewportSetting,
+} from "@t3tools/contracts";
+
+import {
+ ensureClientSettingsHydrated,
+ getClientSettings,
+ useClientSettings,
+} from "~/hooks/useSettings";
+
+import { resolveResponsiveBrowserViewportSize } from "./browserViewportLayout";
+
+export interface BrowserDefaults {
+ readonly viewport: PreviewViewportSetting;
+ readonly zoomFactor: number;
+ readonly appearance: PreviewAppearancePreference;
+ readonly autoShowFloatingPreview: boolean;
+}
+
+const toBrowserDefaults = (settings: {
+ readonly browserDefaultViewport: PreviewViewportSetting;
+ readonly browserDefaultZoomFactor: number;
+ readonly browserDefaultAppearance: PreviewAppearancePreference;
+ readonly browserAutoShowFloatingPreview: boolean;
+}): BrowserDefaults => ({
+ viewport: settings.browserDefaultViewport,
+ zoomFactor: settings.browserDefaultZoomFactor,
+ appearance: settings.browserDefaultAppearance,
+ autoShowFloatingPreview: settings.browserAutoShowFloatingPreview,
+});
+
+/** Non-hook accessor for imperative open paths (menu actions, automation hosts). */
+export function getBrowserDefaults(): BrowserDefaults {
+ return toBrowserDefaults(getClientSettings());
+}
+
+/**
+ * The defaults, once client settings have actually loaded.
+ *
+ * Opening a preview is asynchronous anyway, and before hydration the snapshot
+ * is the schema defaults rather than the user's — a tab opened in that window
+ * would be born at the wrong viewport, zoom and appearance and never corrected.
+ */
+export async function resolveBrowserDefaults(): Promise<BrowserDefaults> {
+ await ensureClientSettingsHydrated();
+ return getBrowserDefaults();
+}
+
+export function useBrowserDefaults(): BrowserDefaults {
+ return useClientSettings(toBrowserDefaults);
+}
+
+/**
+ * The zoom/appearance half of the defaults, in the shape `createTab` takes.
+ * Passing these at creation rather than after registration keeps the guest from
+ * painting a frame at 100%/system first.
+ */
+export function browserDefaultTabState(
+ defaults: BrowserDefaults = getBrowserDefaults(),
+): DesktopPreviewTabDefaults {
+ return { zoomFactor: defaults.zoomFactor, colorScheme: defaults.appearance };
+}
+
+/**
+ * The viewport a *newly opened* tab should start at. Sent with `preview.open`
+ * so the session is born at the configured size instead of being resized a
+ * frame later, which the user would see as a visible reflow.
+ */
+export function browserDefaultOpenViewport(
+ defaults: BrowserDefaults = getBrowserDefaults(),
+): PreviewViewportSetting {
+ return defaults.viewport;
+}
+
+/**
+ * The viewport to switch to when the user turns the device toolbar on for a tab
+ * currently in fill mode.
+ *
+ * A configured non-fill default is what the user said they want to look at, so
+ * it wins. When the default is fill there is no stated preference to honour, so
+ * fall back to fitting the panel — and only when the panel hasn't been measured
+ * yet does a fixed size apply.
+ */
+export const FALLBACK_RESPONSIVE_VIEWPORT_SIZE = { width: 1024, height: 768 } as const;
+
+export function browserResponsiveViewportForToggle(input: {
+ readonly defaults?: BrowserDefaults;
+ readonly panelRect: { readonly width: number; readonly height: number } | null;
+ readonly zoomFactor: number | undefined;
+}): PreviewViewportSetting {
+ const defaults = input.defaults ?? getBrowserDefaults();
+ if (defaults.viewport._tag !== "fill") return defaults.viewport;
+ const size = input.panelRect
+ ? resolveResponsiveBrowserViewportSize(input.panelRect, input.zoomFactor)
+ : FALLBACK_RESPONSIVE_VIEWPORT_SIZE;
+ return { _tag: "freeform", ...size };
+}
diff --git a/apps/web/src/browser/desktopTabLifetime.test.ts b/apps/web/src/browser/desktopTabLifetime.test.ts
index feb015c91..80bfa0d27 100644
--- a/apps/web/src/browser/desktopTabLifetime.test.ts
+++ b/apps/web/src/browser/desktopTabLifetime.test.ts
@@ -1,4 +1,9 @@
-import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import {
+ DEFAULT_PREVIEW_APPEARANCE,
+ DEFAULT_PREVIEW_ZOOM_FACTOR,
+ EnvironmentId,
+ ThreadId,
+} from "@t3tools/contracts";
import { afterEach, beforeEach, describe, expect, it, vi } from "vite-plus/test";
const { closeTab, createTab, stopBrowserRecording } = vi.hoisted(() => ({
@@ -16,6 +21,12 @@ vi.mock("./browserRecording", () => ({
}));
import { acquireDesktopTab } from "./desktopTabLifetime";
+
+/** Client settings are unset in tests, so creation carries the schema defaults. */
+const DEFAULT_TAB_STATE = {
+ zoomFactor: DEFAULT_PREVIEW_ZOOM_FACTOR,
+ colorScheme: DEFAULT_PREVIEW_APPEARANCE,
+};
import { previewRuntimeTabId } from "./previewRuntimeTabId";
describe("desktopTabLifetime", () => {
@@ -42,14 +53,16 @@ describe("desktopTabLifetime", () => {
const first = acquireDesktopTab("tab_readiness");
const second = acquireDesktopTab("tab_readiness");
- expect(createTab).toHaveBeenCalledOnce();
+ // Both leases share one creation, and it is still in flight: creation now
+ // waits for client settings to hydrate so the guest is born at the user's
+ // zoom and appearance rather than painting at the defaults first.
expect(first.ready).toBe(second.ready);
let ready = false;
void first.ready.then(() => {
ready = true;
});
- await Promise.resolve();
+ await vi.waitFor(() => expect(createTab).toHaveBeenCalledOnce());
expect(ready).toBe(false);
resolveCreation?.();
@@ -81,8 +94,8 @@ describe("desktopTabLifetime", () => {
const second = acquireDesktopTab(tabB);
await Promise.all([first.ready, second.ready]);
- expect(createTab).toHaveBeenCalledWith(tabA);
- expect(createTab).toHaveBeenCalledWith(tabB);
+ expect(createTab).toHaveBeenCalledWith(tabA, DEFAULT_TAB_STATE);
+ expect(createTab).toHaveBeenCalledWith(tabB, DEFAULT_TAB_STATE);
expect(createTab).toHaveBeenCalledTimes(2);
first.release();
diff --git a/apps/web/src/browser/desktopTabLifetime.ts b/apps/web/src/browser/desktopTabLifetime.ts
index 98dffda0e..8575392e2 100644
--- a/apps/web/src/browser/desktopTabLifetime.ts
+++ b/apps/web/src/browser/desktopTabLifetime.ts
@@ -1,5 +1,6 @@
import { previewBridge } from "~/components/preview/previewBridge";
+import { browserDefaultTabState, resolveBrowserDefaults } from "./browserDefaults";
import { stopBrowserRecording } from "./browserRecording";
interface DesktopTabLease {
@@ -41,7 +42,11 @@ export function acquireDesktopTab(tabId: string): AcquiredDesktopTab {
({
references: 0,
closeTimer: null,
- ready: enqueueDesktopTabOperation(tabId, () => previewBridge?.createTab(tabId)),
+ // Zoom/appearance defaults travel with creation so the guest never
+ // paints a frame at 100%/system before the preference is applied.
+ ready: enqueueDesktopTabOperation(tabId, async () =>
+ previewBridge?.createTab(tabId, browserDefaultTabState(await resolveBrowserDefaults())),
+ ),
} satisfies DesktopTabLease);
if (current.closeTimer !== null) window.clearTimeout(current.closeTimer);
current.references += 1;
diff --git a/apps/web/src/components/preview/PreviewAutomationHosts.tsx b/apps/web/src/components/preview/PreviewAutomationHosts.tsx
index 2a007fb4c..acf7e52e3 100644
--- a/apps/web/src/components/preview/PreviewAutomationHosts.tsx
+++ b/apps/web/src/components/preview/PreviewAutomationHosts.tsx
@@ -38,6 +38,7 @@ import {
} from "~/browser/browserRecording";
import { resolveBrowserRecordingStopTarget } from "~/browser/browserRecordingScope";
import { useBrowserSurfaceStore } from "~/browser/browserSurfaceStore";
+import { browserDefaultOpenViewport, resolveBrowserDefaults } from "~/browser/browserDefaults";
import { runBrowserViewportMutation } from "~/browser/browserViewportActions";
import { previewRuntimeTabId } from "~/browser/previewRuntimeTabId";
import { isElectron } from "~/env";
@@ -380,6 +381,9 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
input: {
threadId: request.threadId,
...(resolvedInputUrl ? { url: resolvedInputUrl } : {}),
+ // An agent that didn't state a size gets the user's
+ // configured default, same as a hand-opened tab.
+ viewport: browserDefaultOpenViewport(await resolveBrowserDefaults()),
},
});
if (result._tag === "Failure") {
@@ -428,7 +432,10 @@ function PreviewAutomationHost(props: { readonly environmentId: EnvironmentId })
updatePreviewServerSnapshot(threadRef, resizeResult.value);
}
}
- const shouldPresentPreview = shouldOpenPreviewMiniPlayer(input);
+ const shouldPresentPreview = shouldOpenPreviewMiniPlayer(
+ input,
+ (await resolveBrowserDefaults()).autoShowFloatingPreview,
+ );
if (shouldPresentPreview) {
usePreviewMiniPlayerStore.getState().open(threadRef, activeTabId);
}
diff --git a/apps/web/src/components/preview/PreviewView.test.tsx b/apps/web/src/components/preview/PreviewView.test.tsx
index d9671e2f2..c3fe5337d 100644
--- a/apps/web/src/components/preview/PreviewView.test.tsx
+++ b/apps/web/src/components/preview/PreviewView.test.tsx
@@ -1,4 +1,10 @@
-import { EnvironmentId, ThreadId } from "@t3tools/contracts";
+import {
+ DEFAULT_PREVIEW_APPEARANCE,
+ DEFAULT_PREVIEW_ZOOM_FACTOR,
+ EnvironmentId,
+ FILL_PREVIEW_VIEWPORT,
+ ThreadId,
+} from "@t3tools/contracts";
import { renderToStaticMarkup } from "react-dom/server";
import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
@@ -41,6 +47,34 @@ vi.mock("~/state/session", () => ({
readPreparedConnection: mocks.readPreparedConnection,
}));
+// Stubbed at the direct dependency rather than letting the real module pull in
+// `useSettings` -> `state/server`, which would drag the whole settings and
+// connection graph into a test that only cares about the browser chrome.
+vi.mock("~/browser/browserDefaults", () => ({
+ useBrowserDefaults: () => ({
+ viewport: FILL_PREVIEW_VIEWPORT,
+ zoomFactor: DEFAULT_PREVIEW_ZOOM_FACTOR,
+ appearance: DEFAULT_PREVIEW_APPEARANCE,
+ autoShowFloatingPreview: true,
+ }),
+ getBrowserDefaults: () => ({
+ viewport: FILL_PREVIEW_VIEWPORT,
+ zoomFactor: DEFAULT_PREVIEW_ZOOM_FACTOR,
+ appearance: DEFAULT_PREVIEW_APPEARANCE,
+ autoShowFloatingPreview: true,
+ }),
+ browserDefaultOpenViewport: () => FILL_PREVIEW_VIEWPORT,
+ browserDefaultTabState: () => ({
+ zoomFactor: DEFAULT_PREVIEW_ZOOM_FACTOR,
+ colorScheme: DEFAULT_PREVIEW_APPEARANCE,
+ }),
+ browserResponsiveViewportForToggle: () => ({
+ _tag: "freeform" as const,
+ width: 1024,
+ height: 768,
+ }),
+}));
+
vi.mock("~/composerDraftStore", () => ({
useComposerDraftStore: (
select: (store: { addPreviewAnnotation: () => void; addImage: () => void }) => unknown,
diff --git a/apps/web/src/components/preview/PreviewView.tsx b/apps/web/src/components/preview/PreviewView.tsx
index 0805037a1..5a828b863 100644
--- a/apps/web/src/components/preview/PreviewView.tsx
+++ b/apps/web/src/components/preview/PreviewView.tsx
@@ -43,7 +43,7 @@ import {
commitBrowserViewportChange,
subscribeBrowserViewportChange,
} from "~/browser/browserViewportActions";
-import { resolveResponsiveBrowserViewportSize } from "~/browser/browserViewportLayout";
+import { browserResponsiveViewportForToggle, useBrowserDefaults } from "~/browser/browserDefaults";
import { previewRuntimeTabId } from "~/browser/previewRuntimeTabId";
import { PreviewUnreachable } from "./PreviewUnreachable";
import { revealInFileExplorerLabel } from "./fileExplorerLabel";
@@ -144,6 +144,7 @@ export function PreviewView({
const controller = desktopOverlay?.controller ?? "none";
const loadProgress = useLoadingProgress(loading);
const viewport = snapshot?.viewport ?? FILL_PREVIEW_VIEWPORT;
+ const browserDefaults = useBrowserDefaults();
const panelRect = useBrowserSurfaceStore((state) =>
runtimeTabId ? (state.byTabId[runtimeTabId]?.rect ?? null) : null,
);
@@ -249,12 +250,14 @@ export function PreviewView({
return;
}
- const responsiveSize = panelRect
- ? resolveResponsiveBrowserViewportSize(panelRect, desktopOverlay?.zoomFactor)
- : { width: 1024, height: 768 };
- void commitBrowserViewportChange(runtimeTabId, { _tag: "freeform", ...responsiveSize }).catch(
- () => undefined,
- );
+ void commitBrowserViewportChange(
+ runtimeTabId,
+ browserResponsiveViewportForToggle({
+ defaults: browserDefaults,
+ panelRect,
+ zoomFactor: desktopOverlay?.zoomFactor,
+ }),
+ ).catch(() => undefined);
};
useEffect(() => {
diff --git a/apps/web/src/components/preview/addBrowserSurface.test.ts b/apps/web/src/components/preview/addBrowserSurface.test.ts
index 5dfc1a42e..4299374b3 100644
--- a/apps/web/src/components/preview/addBrowserSurface.test.ts
+++ b/apps/web/src/components/preview/addBrowserSurface.test.ts
@@ -1,4 +1,9 @@
-import type { PreviewOpenInput, PreviewSessionSnapshot, ScopedThreadRef } from "@t3tools/contracts";
+import {
+ FILL_PREVIEW_VIEWPORT,
+ type PreviewOpenInput,
+ type PreviewSessionSnapshot,
+ type ScopedThreadRef,
+} from "@t3tools/contracts";
import { AsyncResult } from "effect/unstable/reactivity";
import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
@@ -40,7 +45,10 @@ describe("addBrowserSurface", () => {
await addBrowserSurface({ threadRef, openPreview: ({ input }) => openPreview(input) });
- expect(openPreview).toHaveBeenCalledWith({ threadId: "thread-1" });
+ expect(openPreview).toHaveBeenCalledWith({
+ threadId: "thread-1",
+ viewport: FILL_PREVIEW_VIEWPORT,
+ });
expect(Object.keys(readThreadPreviewState(threadRef).sessions)).toEqual(["tab-1", "tab-2"]);
expect(
selectThreadRightPanelState(
diff --git a/apps/web/src/components/preview/openPreviewSession.test.ts b/apps/web/src/components/preview/openPreviewSession.test.ts
index 2e84fec5e..138c3dd36 100644
--- a/apps/web/src/components/preview/openPreviewSession.test.ts
+++ b/apps/web/src/components/preview/openPreviewSession.test.ts
@@ -1,4 +1,9 @@
-import type { PreviewOpenInput, PreviewSessionSnapshot, ScopedThreadRef } from "@t3tools/contracts";
+import {
+ FILL_PREVIEW_VIEWPORT,
+ type PreviewOpenInput,
+ type PreviewSessionSnapshot,
+ type ScopedThreadRef,
+} from "@t3tools/contracts";
import * as Cause from "effect/Cause";
import { AsyncResult } from "effect/unstable/reactivity";
import { beforeEach, describe, expect, it, vi } from "vite-plus/test";
@@ -41,7 +46,10 @@ describe("openPreviewSession", () => {
threadRef,
});
- expect(open).toHaveBeenCalledWith({ threadId: "thread-1" });
+ expect(open).toHaveBeenCalledWith({
+ threadId: "thread-1",
+ viewport: FILL_PREVIEW_VIEWPORT,
+ });
expect(readThreadPreviewState(threadRef).snapshot).toEqual(idleSnapshot);
expect(readThreadPreviewState(threadRef).recentlySeenUrls).toEqual([]);
});
@@ -55,7 +63,11 @@ describe("openPreviewSession", () => {
url: "t3.chat",
});
- expect(open).toHaveBeenCalledWith({ threadId: "thread-1", url: "t3.chat" });
+ expect(open).toHaveBeenCalledWith({
+ threadId: "thread-1",
+ url: "t3.chat",
+ viewport: FILL_PREVIEW_VIEWPORT,
+ });
expect(readThreadPreviewState(threadRef).snapshot).toEqual(snapshot);
expect(readThreadPreviewState(threadRef).recentlySeenUrls).toEqual(["https://t3.chat/"]);
});
diff --git a/apps/web/src/components/preview/openPreviewSession.ts b/apps/web/src/components/preview/openPreviewSession.ts
index f86ea31a1..1a3ceabad 100644
--- a/apps/web/src/components/preview/openPreviewSession.ts
+++ b/apps/web/src/components/preview/openPreviewSession.ts
@@ -2,10 +2,12 @@ import type {
EnvironmentId,
PreviewOpenInput,
PreviewSessionSnapshot,
+ PreviewViewportSetting,
ScopedThreadRef,
} from "@t3tools/contracts";
import type { AtomCommandResult } from "@t3tools/client-runtime/state/runtime";
+import { browserDefaultOpenViewport, resolveBrowserDefaults } from "~/browser/browserDefaults";
import { applyPreviewServerSnapshot, rememberPreviewUrl } from "~/previewStateStore";
interface OpenPreviewSessionInput<E> {
@@ -15,6 +17,8 @@ interface OpenPreviewSessionInput<E> {
}) => Promise<AtomCommandResult<PreviewSessionSnapshot, E>>;
threadRef: ScopedThreadRef;
url?: string;
+ /** Overrides the configured default; automation passes an explicit size. */
+ viewport?: PreviewViewportSetting;
}
export async function openPreviewSession<E>(
@@ -25,6 +29,7 @@ export async function openPreviewSession<E>(
input: {
threadId: input.threadRef.threadId,
...(input.url === undefined ? {} : { url: input.url }),
+ viewport: input.viewport ?? browserDefaultOpenViewport(await resolveBrowserDefaults()),
},
});
if (result._tag === "Failure") {
diff --git a/apps/web/src/components/preview/previewAutomationOpenReadiness.test.ts b/apps/web/src/components/preview/previewAutomationOpenReadiness.test.ts
index 9ead8cfe1..dc8836c14 100644
--- a/apps/web/src/components/preview/previewAutomationOpenReadiness.test.ts
+++ b/apps/web/src/components/preview/previewAutomationOpenReadiness.test.ts
@@ -77,3 +77,18 @@ describe("preview automation open readiness", () => {
).toBeNull();
});
});
+
+describe("shouldOpenPreviewMiniPlayer with the floating-preview preference", () => {
+ it("honours the preference when the agent said nothing either way", () => {
+ // `preview_open` no longer arrives with `open` pre-filled, so an agent
+ // that omitted it leaves the decision to the user's setting.
+ expect(shouldOpenPreviewMiniPlayer({}, false)).toBe(false);
+ expect(shouldOpenPreviewMiniPlayer({}, true)).toBe(true);
+ });
+
+ it("lets an explicit request outrank the preference in both directions", () => {
+ expect(shouldOpenPreviewMiniPlayer({ open: true }, false)).toBe(true);
+ expect(shouldOpenPreviewMiniPlayer({ open: false }, true)).toBe(false);
+ expect(shouldOpenPreviewMiniPlayer({ show: true }, false)).toBe(true);
+ });
+});
diff --git a/apps/web/src/components/preview/previewAutomationOpenReadiness.ts b/apps/web/src/components/preview/previewAutomationOpenReadiness.ts
index c9d29fd44..7f525b425 100644
--- a/apps/web/src/components/preview/previewAutomationOpenReadiness.ts
+++ b/apps/web/src/components/preview/previewAutomationOpenReadiness.ts
@@ -5,14 +5,28 @@ import {
type PreviewViewportSetting,
} from "@t3tools/contracts";
+/**
+ * Viewport an agent-opened tab falls back to when the user has no configured
+ * browser default. Agents screenshot and assert against what they open, so a
+ * brand-new tab left in fill mode would be sized by whatever the panel happens
+ * to be — deterministic beats incidental here.
+ */
export const DEFAULT_PREVIEW_AUTOMATION_VIEWPORT = {
_tag: "freeform",
width: 1280,
height: 800,
} as const satisfies PreviewViewportSetting;
-export function shouldOpenPreviewMiniPlayer(input: PreviewAutomationOpenInput): boolean {
- return input.open ?? input.show ?? true;
+/**
+ * An explicit `open`/`show` is the agent deliberately surfacing or suppressing
+ * its work, so it outranks the preference; the setting only decides what
+ * happens when the agent said nothing either way.
+ */
+export function shouldOpenPreviewMiniPlayer(
+ input: PreviewAutomationOpenInput,
+ autoShowFloatingPreview = true,
+): boolean {
+ return input.open ?? input.show ?? autoShowFloatingPreview;
}
export function previewAutomationOpenNeedsOverlay(
@@ -22,6 +36,13 @@ export function previewAutomationOpenNeedsOverlay(
return input.url !== undefined || snapshot.navStatus._tag !== "Idle";
}
+/**
+ * Whether a freshly opened automation tab still needs a viewport applied.
+ *
+ * A configured browser default is sent with `preview.open`, so the snapshot
+ * already carries it and nothing is needed here. Fill means the user has no
+ * stated preference, which is where the agent fallback applies.
+ */
export function previewAutomationDefaultViewport(
reusedExistingTab: boolean,
snapshot: PreviewSessionSnapshot,
diff --git a/apps/web/src/components/settings/IntegrationsSettings.tsx b/apps/web/src/components/settings/IntegrationsSettings.tsx
new file mode 100644
index 000000000..1ffc7e3f3
--- /dev/null
+++ b/apps/web/src/components/settings/IntegrationsSettings.tsx
@@ -0,0 +1,436 @@
+/**
+ * Integrations settings - preferences for surfaces T3 Code embeds rather than
+ * owns. Browser is the first section: the defaults a preview tab opens at,
+ * applied to both hand-opened tabs and agent `preview_open` calls that don't
+ * state their own size.
+ *
+ * @module IntegrationsSettings
+ */
+import {
+ DEFAULT_BROWSER_AUTO_SHOW_FLOATING_PREVIEW,
+ DEFAULT_BROWSER_VIEWPORT,
+ DEFAULT_PREVIEW_APPEARANCE,
+ DEFAULT_PREVIEW_ZOOM_FACTOR,
+ FILL_PREVIEW_VIEWPORT,
+ PREVIEW_VIEWPORT_MAX_AREA,
+ PREVIEW_VIEWPORT_MAX_DIMENSION,
+ PREVIEW_VIEWPORT_MIN_DIMENSION,
+ PREVIEW_ZOOM_LEVELS,
+ type PreviewAppearancePreference,
+ type PreviewViewportSetting,
+} from "@t3tools/contracts";
+import { PREVIEW_VIEWPORT_PRESETS } from "@t3tools/shared/previewViewport";
+import { InfoIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+import { ScreenRotationIcon } from "~/browser/ScreenRotationIcon";
+import { isElectron } from "../../env";
+
+import { Button } from "../ui/button";
+import { NumberField, NumberFieldGroup, NumberFieldInput } from "../ui/number-field";
+import {
+ Select,
+ SelectGroup,
+ SelectGroupLabel,
+ SelectItem,
+ SelectPopup,
+ SelectTrigger,
+ SelectValue,
+} from "../ui/select";
+import { Switch } from "../ui/switch";
+import { Tooltip, TooltipPopup, TooltipTrigger } from "../ui/tooltip";
+import { useClientSettings, useUpdatePrimarySettings } from "~/hooks/useSettings";
+
+import {
+ SettingResetButton,
+ SettingsPageContainer,
+ SettingsRow,
+ SettingsSection,
+} from "./settingsLayout";
+import { searchableSetting } from "./settingsSearch";
+
+const FILL_VALUE = "fill";
+const RESPONSIVE_VALUE = "responsive";
+
+/**
+ * The size a "Responsive" default falls back to when the user switches away
+ * from Fill and hasn't typed dimensions yet. Fill has no dimensions to carry
+ * over, so the picker needs something concrete to seed the inputs with.
+ */
+const RESPONSIVE_SEED_SIZE = { width: 1280, height: 800 } as const;
+
+const NO_GROUPING: Intl.NumberFormatOptions = { useGrouping: false };
+
+const APPEARANCE_LABELS: Readonly<Record<PreviewAppearancePreference, string>> = {
+ system: "System",
+ light: "Light",
+ dark: "Dark",
+};
+
+const zoomLabel = (zoomFactor: number) => `${Math.round(zoomFactor * 100)}%`;
+
+const viewportSelectValue = (viewport: PreviewViewportSetting): string => {
+ if (viewport._tag === "fill") return FILL_VALUE;
+ if (
+ viewport._tag === "preset" &&
+ PREVIEW_VIEWPORT_PRESETS.some((preset) => preset.id === viewport.presetId)
+ ) {
+ return viewport.presetId;
+ }
+ return RESPONSIVE_VALUE;
+};
+
+/**
+ * The trigger renders this rather than a bare `SelectValue`, which would fall
+ * back to printing the raw stored value ("fill") because the options are built
+ * inline instead of from an `items` map.
+ */
+const viewportSelectLabel = (viewport: PreviewViewportSetting): string => {
+ const value = viewportSelectValue(viewport);
+ if (value === FILL_VALUE) return "Fill panel";
+ if (value === RESPONSIVE_VALUE) return "Responsive";
+ return PREVIEW_VIEWPORT_PRESETS.find((preset) => preset.id === value)?.label ?? "Responsive";
+};
+
+const isValidDimension = (value: number) =>
+ Number.isInteger(value) &&
+ value >= PREVIEW_VIEWPORT_MIN_DIMENSION &&
+ value <= PREVIEW_VIEWPORT_MAX_DIMENSION;
+
+/**
+ * A sized viewport with width and height swapped. Presets keep their identity
+ * through a rotation — `resolvePreviewViewport` already stores rotated presets
+ * as the preset id plus swapped dimensions — so a rotated iPad is still an
+ * iPad, not an anonymous custom size.
+ */
+const rotateViewport = (
+ viewport: Exclude<PreviewViewportSetting, { readonly _tag: "fill" }>,
+): PreviewViewportSetting => ({
+ ...viewport,
+ width: viewport.height,
+ height: viewport.width,
+});
+
+function BrowserViewportSetting({ disabled }: { readonly disabled: boolean }) {
+ const viewport = useClientSettings((settings) => settings.browserDefaultViewport);
+ const updateSettings = useUpdatePrimarySettings();
+
+ const sized = viewport._tag === "fill" ? null : viewport;
+ const presentedSize = {
+ width: sized?.width ?? RESPONSIVE_SEED_SIZE.width,
+ height: sized?.height ?? RESPONSIVE_SEED_SIZE.height,
+ };
+
+ const selectViewport = (value: string | null) => {
+ if (value === FILL_VALUE) {
+ updateSettings({ browserDefaultViewport: FILL_PREVIEW_VIEWPORT });
+ return;
+ }
+ if (value === RESPONSIVE_VALUE) {
+ updateSettings({
+ browserDefaultViewport: {
+ _tag: "freeform",
+ width: sized?.width ?? RESPONSIVE_SEED_SIZE.width,
+ height: sized?.height ?? RESPONSIVE_SEED_SIZE.height,
+ },
+ });
+ return;
+ }
+ const preset = PREVIEW_VIEWPORT_PRESETS.find((candidate) => candidate.id === value);
+ if (!preset) return;
+ updateSettings({
+ browserDefaultViewport: {
+ _tag: "preset",
+ width: preset.width,
+ height: preset.height,
+ presetId: preset.id,
+ },
+ });
+ };
+
+ // Committed on blur rather than per keystroke: typing "2560" passes through
+ // "256", which is a legal dimension, so an onValueChange handler would
+ // persist that intermediate size and churn the settings file on every key.
+ const commitDimension = (axis: "width" | "height", value: number | null) => {
+ if (value === null || !isValidDimension(value)) return;
+ const next = { ...presentedSize, [axis]: value };
+ if (next.width * next.height > PREVIEW_VIEWPORT_MAX_AREA) return;
+ if (sized && next.width === sized.width && next.height === sized.height) return;
+ // Typing a size means the preset no longer describes it.
+ updateSettings({ browserDefaultViewport: { _tag: "freeform", ...next } });
+ };
+
+ return (
+ <SettingsRow
+ {...searchableSetting("browser-default-viewport")}
+ description="The viewport a browser tab opens at, for both you and agents. Fill sizes the page to the panel; any other choice opens the device toolbar at that size."
+ resetAction={
+ !disabled && viewport._tag !== DEFAULT_BROWSER_VIEWPORT._tag ? (
+ <SettingResetButton
+ label="default browser viewport"
+ onClick={() => updateSettings({ browserDefaultViewport: DEFAULT_BROWSER_VIEWPORT })}
+ />
+ ) : null
+ }
+ control={
+ <div className="flex w-full flex-wrap items-center justify-end gap-2 sm:w-auto">
+ <Select
+ value={viewportSelectValue(viewport)}
+ onValueChange={selectViewport}
+ disabled={disabled}
+ >
+ <SelectTrigger
+ size="sm"
+ className="w-full min-w-0 sm:w-44"
+ aria-label="Default browser viewport"
+ >
+ <SelectValue>{viewportSelectLabel(viewport)}</SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false} className="min-w-64">
+ <SelectItem value={FILL_VALUE}>Fill panel</SelectItem>
+ <SelectItem value={RESPONSIVE_VALUE}>Responsive</SelectItem>
+ <SelectGroup>
+ <SelectGroupLabel>Standard</SelectGroupLabel>
+ {PREVIEW_VIEWPORT_PRESETS.map((preset) => (
+ <SelectItem key={preset.id} value={preset.id}>
+ <span className="flex w-full items-center justify-between gap-5">
+ <span>{preset.label}</span>
+ <span className="text-xs tabular-nums text-muted-foreground">
+ {preset.detail}
+ </span>
+ </span>
+ </SelectItem>
+ ))}
+ </SelectGroup>
+ </SelectPopup>
+ </Select>
+
+ {sized ? (
+ <div className="flex min-w-0 items-center gap-1">
+ <NumberField
+ value={presentedSize.width}
+ min={PREVIEW_VIEWPORT_MIN_DIMENSION}
+ max={PREVIEW_VIEWPORT_MAX_DIMENSION}
+ disabled={disabled}
+ // Pixel counts read as raw numbers; grouping would show "1,024".
+ format={NO_GROUPING}
+ size="sm"
+ className="w-20"
+ onValueCommitted={(value) => commitDimension("width", value)}
+ >
+ <NumberFieldGroup>
+ <NumberFieldInput aria-label="Default viewport width" />
+ </NumberFieldGroup>
+ </NumberField>
+ <span className="text-xs text-muted-foreground">×</span>
+ <NumberField
+ value={presentedSize.height}
+ min={PREVIEW_VIEWPORT_MIN_DIMENSION}
+ max={PREVIEW_VIEWPORT_MAX_DIMENSION}
+ disabled={disabled}
+ format={NO_GROUPING}
+ size="sm"
+ className="w-20"
+ onValueCommitted={(value) => commitDimension("height", value)}
+ >
+ <NumberFieldGroup>
+ <NumberFieldInput aria-label="Default viewport height" />
+ </NumberFieldGroup>
+ </NumberField>
+ <Tooltip>
+ <TooltipTrigger
+ render={
+ <Button
+ size="icon-sm"
+ variant="ghost-muted"
+ disabled={disabled}
+ aria-label={`Rotate to ${
+ presentedSize.height >= presentedSize.width ? "landscape" : "portrait"
+ }`}
+ onClick={() =>
+ updateSettings({ browserDefaultViewport: rotateViewport(sized) })
+ }
+ >
+ <ScreenRotationIcon />
+ </Button>
+ }
+ />
+ <TooltipPopup side="top">Rotate</TooltipPopup>
+ </Tooltip>
+ </div>
+ ) : null}
+ </div>
+ }
+ />
+ );
+}
+
+function BrowserZoomSetting({ disabled }: { readonly disabled: boolean }) {
+ const zoomFactor = useClientSettings((settings) => settings.browserDefaultZoomFactor);
+ const updateSettings = useUpdatePrimarySettings();
+
+ return (
+ <SettingsRow
+ {...searchableSetting("browser-default-zoom")}
+ description="Page zoom applied to new browser tabs."
+ resetAction={
+ !disabled && zoomFactor !== DEFAULT_PREVIEW_ZOOM_FACTOR ? (
+ <SettingResetButton
+ label="default browser zoom"
+ onClick={() =>
+ updateSettings({ browserDefaultZoomFactor: DEFAULT_PREVIEW_ZOOM_FACTOR })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Select
+ disabled={disabled}
+ value={String(zoomFactor)}
+ onValueChange={(value) => {
+ const next = PREVIEW_ZOOM_LEVELS.find((level) => String(level) === value);
+ if (next !== undefined) updateSettings({ browserDefaultZoomFactor: next });
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Default browser zoom">
+ <SelectValue>{zoomLabel(zoomFactor)}</SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {PREVIEW_ZOOM_LEVELS.map((level) => (
+ <SelectItem hideIndicator key={level} value={String(level)}>
+ {zoomLabel(level)}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ />
+ );
+}
+
+function BrowserAppearanceSetting({ disabled }: { readonly disabled: boolean }) {
+ const appearance = useClientSettings((settings) => settings.browserDefaultAppearance);
+ const updateSettings = useUpdatePrimarySettings();
+
+ return (
+ <SettingsRow
+ {...searchableSetting("browser-default-appearance")}
+ description="The color scheme pages are told to prefer. System follows your OS setting."
+ resetAction={
+ !disabled && appearance !== DEFAULT_PREVIEW_APPEARANCE ? (
+ <SettingResetButton
+ label="default browser appearance"
+ onClick={() => updateSettings({ browserDefaultAppearance: DEFAULT_PREVIEW_APPEARANCE })}
+ />
+ ) : null
+ }
+ control={
+ <Select
+ disabled={disabled}
+ value={appearance}
+ onValueChange={(value) => {
+ if (value === "system" || value === "light" || value === "dark") {
+ updateSettings({ browserDefaultAppearance: value });
+ }
+ }}
+ >
+ <SelectTrigger className="w-full sm:w-40" aria-label="Default browser appearance">
+ <SelectValue>{APPEARANCE_LABELS[appearance]}</SelectValue>
+ </SelectTrigger>
+ <SelectPopup align="end" alignItemWithTrigger={false}>
+ {Object.entries(APPEARANCE_LABELS).map(([value, label]) => (
+ <SelectItem hideIndicator key={value} value={value}>
+ {label}
+ </SelectItem>
+ ))}
+ </SelectPopup>
+ </Select>
+ }
+ />
+ );
+}
+
+function BrowserAutoShowFloatingPreviewSetting({ disabled }: { readonly disabled: boolean }) {
+ const autoShow = useClientSettings((settings) => settings.browserAutoShowFloatingPreview);
+ const updateSettings = useUpdatePrimarySettings();
+
+ return (
+ <SettingsRow
+ {...searchableSetting("browser-auto-show-floating-preview")}
+ description="Pop the floating preview into view when an agent opens a browser. An agent that explicitly asks to show or hide its preview still gets what it asked for."
+ resetAction={
+ !disabled && autoShow !== DEFAULT_BROWSER_AUTO_SHOW_FLOATING_PREVIEW ? (
+ <SettingResetButton
+ label="auto-show floating preview"
+ onClick={() =>
+ updateSettings({
+ browserAutoShowFloatingPreview: DEFAULT_BROWSER_AUTO_SHOW_FLOATING_PREVIEW,
+ })
+ }
+ />
+ ) : null
+ }
+ control={
+ <Switch
+ disabled={disabled}
+ checked={autoShow}
+ onCheckedChange={(checked) =>
+ updateSettings({ browserAutoShowFloatingPreview: Boolean(checked) })
+ }
+ aria-label="Auto-show floating preview"
+ />
+ }
+ />
+ );
+}
+
+/**
+ * Frames the client-local preview defaults as one unavailable block.
+ *
+ * Disabling each control on its own left the labels and descriptions at full
+ * strength, so the group still read as editable. Boxing it puts the reason at
+ * the top and dims everything it covers, which is also why the explanation
+ * sits outside the dimmed area — the one part that must stay readable is the
+ * part saying why the rest isn't.
+ *
+ * Disabled rather than hidden because these are *client* settings: editing
+ * them from a browser tab would write preferences belonging to a different
+ * client, reading as though the desktop app had been configured when it
+ * hadn't.
+ */
+function DesktopOnlyBrowserDefaults({ children }: { readonly children: ReactNode }) {
+ return (
+ <div className="rounded-xl border border-border/60 bg-muted/20 py-1.5">
+ <div className="flex items-start gap-2 px-3 py-2 text-[12px] leading-relaxed text-muted-foreground sm:px-4">
+ <InfoIcon className="mt-0.5 size-3.5 shrink-0 text-warning" />
+ <p>Only available in the desktop app.</p>
+ </div>
+ <div className="[&_h3]:opacity-64 [&_p]:opacity-64">{children}</div>
+ </div>
+ );
+}
+
+export function IntegrationsSettingsPanel() {
+ // Client-local preview defaults are editable only where the preview exists.
+ const previewDefaultsDisabled = !isElectron;
+ const previewDefaults = (
+ <>
+ <BrowserViewportSetting disabled={previewDefaultsDisabled} />
+ <BrowserZoomSetting disabled={previewDefaultsDisabled} />
+ <BrowserAppearanceSetting disabled={previewDefaultsDisabled} />
+ <BrowserAutoShowFloatingPreviewSetting disabled={previewDefaultsDisabled} />
+ </>
+ );
+
+ return (
+ <SettingsPageContainer>
+ <SettingsSection id="browser" title="Browser">
+ {previewDefaultsDisabled ? (
+ <DesktopOnlyBrowserDefaults>{previewDefaults}</DesktopOnlyBrowserDefaults>
+ ) : (
+ previewDefaults
+ )}
+ </SettingsSection>
+ </SettingsPageContainer>
+ );
+}
diff --git a/apps/web/src/components/settings/SettingsPanels.logic.test.ts b/apps/web/src/components/settings/SettingsPanels.logic.test.ts
index ec4ad4ff5..5c715eb4e 100644
--- a/apps/web/src/components/settings/SettingsPanels.logic.test.ts
+++ b/apps/web/src/components/settings/SettingsPanels.logic.test.ts
@@ -12,7 +12,9 @@ import {
backgroundActivitySharedPolicySettings,
buildProviderInstanceUpdatePatch,
formatDiagnosticsDescription,
+ getChangedBrowserSettingLabels,
getChangedTypographySettingLabels,
+ isSamePreviewViewport,
hasChangedBackgroundActivitySettings,
isProjectGroupingEnabled,
projectGroupingModeFromToggle,
@@ -242,3 +244,54 @@ describe("buildProviderInstanceUpdatePatch", () => {
expect(patch.providers).toBeUndefined();
});
});
+
+describe("getChangedBrowserSettingLabels", () => {
+ it("reports nothing for the defaults", () => {
+ expect(getChangedBrowserSettingLabels(DEFAULT_UNIFIED_SETTINGS)).toEqual([]);
+ });
+
+ it("treats a structurally equal viewport as unchanged", () => {
+ // The viewport is a tagged union, so identity comparison would report a
+ // freshly decoded copy of the default as dirty and offer to "restore" it.
+ expect(
+ getChangedBrowserSettingLabels({
+ ...DEFAULT_UNIFIED_SETTINGS,
+ browserDefaultViewport: { ...DEFAULT_UNIFIED_SETTINGS.browserDefaultViewport },
+ }),
+ ).toEqual([]);
+ });
+
+ it("labels each browser default that differs", () => {
+ expect(
+ getChangedBrowserSettingLabels({
+ ...DEFAULT_UNIFIED_SETTINGS,
+ browserDefaultViewport: { _tag: "freeform", width: 900, height: 600 },
+ browserDefaultZoomFactor: 1.5,
+ browserDefaultAppearance: "dark",
+ browserAutoShowFloatingPreview: !DEFAULT_UNIFIED_SETTINGS.browserAutoShowFloatingPreview,
+ }),
+ ).toEqual(["Browser viewport", "Browser zoom", "Browser appearance", "Floating preview"]);
+ });
+});
+
+describe("isSamePreviewViewport", () => {
+ it("separates presets that share a size", () => {
+ // Two presets can agree on width and height and still be different
+ // entries in the picker, so the id has to take part in the comparison.
+ expect(
+ isSamePreviewViewport(
+ { _tag: "preset", width: 390, height: 844, presetId: "iphone-12-pro" },
+ { _tag: "preset", width: 390, height: 844, presetId: "ipad-mini" },
+ ),
+ ).toBe(false);
+ });
+
+ it("separates a freeform viewport from a preset of the same size", () => {
+ expect(
+ isSamePreviewViewport(
+ { _tag: "freeform", width: 390, height: 844 },
+ { _tag: "preset", width: 390, height: 844, presetId: "iphone-12-pro" },
+ ),
+ ).toBe(false);
+ });
+});
diff --git a/apps/web/src/components/settings/SettingsPanels.logic.ts b/apps/web/src/components/settings/SettingsPanels.logic.ts
index 39f4f3cda..a5d5d9958 100644
--- a/apps/web/src/components/settings/SettingsPanels.logic.ts
+++ b/apps/web/src/components/settings/SettingsPanels.logic.ts
@@ -3,6 +3,7 @@ import type {
BackgroundActivitySettings,
ProviderDriverKind,
ProviderInstanceConfig,
+ PreviewViewportSetting,
ProviderInstanceId,
ServerSettings,
SidebarProjectGroupingMode,
@@ -108,6 +109,55 @@ export function getChangedTypographySettingLabels(settings: TypographySettings):
];
}
+export type BrowserDefaultSettings = Pick<
+ UnifiedSettings,
+ | "browserDefaultViewport"
+ | "browserDefaultZoomFactor"
+ | "browserDefaultAppearance"
+ | "browserAutoShowFloatingPreview"
+>;
+
+/**
+ * True when two viewport settings describe the same viewport.
+ *
+ * The setting is a tagged union rather than a scalar, so identity comparison
+ * reports every stored viewport as changed — including one that matches the
+ * default.
+ */
+export function isSamePreviewViewport(
+ left: PreviewViewportSetting,
+ right: PreviewViewportSetting,
+): boolean {
+ if (left._tag !== right._tag) return false;
+ if (left._tag === "fill" || right._tag === "fill") return true;
+ if (left.width !== right.width || left.height !== right.height) return false;
+ return left._tag === "preset" && right._tag === "preset"
+ ? left.presetId === right.presetId
+ : true;
+}
+
+/** Labels the browser-default rows that differ from the defaults. */
+export function getChangedBrowserSettingLabels(settings: BrowserDefaultSettings): string[] {
+ return [
+ ...(isSamePreviewViewport(
+ settings.browserDefaultViewport,
+ DEFAULT_UNIFIED_SETTINGS.browserDefaultViewport,
+ )
+ ? []
+ : ["Browser viewport"]),
+ ...(settings.browserDefaultZoomFactor !== DEFAULT_UNIFIED_SETTINGS.browserDefaultZoomFactor
+ ? ["Browser zoom"]
+ : []),
+ ...(settings.browserDefaultAppearance !== DEFAULT_UNIFIED_SETTINGS.browserDefaultAppearance
+ ? ["Browser appearance"]
+ : []),
+ ...(settings.browserAutoShowFloatingPreview !==
+ DEFAULT_UNIFIED_SETTINGS.browserAutoShowFloatingPreview
+ ? ["Floating preview"]
+ : []),
+ ];
+}
+
export function resolveBackgroundActivityProfileOption(
settings: ServerSettings,
): BackgroundActivityProfile | "advanced" {
diff --git a/apps/web/src/components/settings/SettingsPanels.tsx b/apps/web/src/components/settings/SettingsPanels.tsx
index a4828f1ae..4bdf596de 100644
--- a/apps/web/src/components/settings/SettingsPanels.tsx
+++ b/apps/web/src/components/settings/SettingsPanels.tsx
@@ -122,6 +122,7 @@ import {
backgroundActivitySharedPolicySettings,
durationToSeconds,
formatDiagnosticsDescription,
+ getChangedBrowserSettingLabels,
getChangedTypographySettingLabels,
normalizeIntervalSeconds,
PROVIDER_HEALTH_INTERVAL_STEP_SECONDS,
@@ -529,10 +530,15 @@ export function useSettingsRestore(onRestored?: () => void) {
? ["Quit confirmation"]
: []),
...(isTextGenerationModelDirty ? ["Text generation model"] : []),
+ ...getChangedBrowserSettingLabels(settings),
],
[
isTextGenerationModelDirty,
isBackgroundActivityDirty,
+ settings.browserDefaultViewport,
+ settings.browserDefaultZoomFactor,
+ settings.browserDefaultAppearance,
+ settings.browserAutoShowFloatingPreview,
settings.confirmQuit,
settings.confirmThreadArchive,
settings.confirmThreadDelete,
@@ -657,6 +663,10 @@ export function useSettingsRestore(onRestored?: () => void) {
fontSizePrompt: DEFAULT_UNIFIED_SETTINGS.fontSizePrompt,
fontSizeCode: DEFAULT_UNIFIED_SETTINGS.fontSizeCode,
fontSizeTerminal: DEFAULT_UNIFIED_SETTINGS.fontSizeTerminal,
+ browserDefaultViewport: DEFAULT_UNIFIED_SETTINGS.browserDefaultViewport,
+ browserDefaultZoomFactor: DEFAULT_UNIFIED_SETTINGS.browserDefaultZoomFactor,
+ browserDefaultAppearance: DEFAULT_UNIFIED_SETTINGS.browserDefaultAppearance,
+ browserAutoShowFloatingPreview: DEFAULT_UNIFIED_SETTINGS.browserAutoShowFloatingPreview,
});
onRestored?.();
}, [
diff --git a/apps/web/src/components/settings/SettingsSidebarNav.tsx b/apps/web/src/components/settings/SettingsSidebarNav.tsx
index 174c9e9fe..5a5978487 100644
--- a/apps/web/src/components/settings/SettingsSidebarNav.tsx
+++ b/apps/web/src/components/settings/SettingsSidebarNav.tsx
@@ -10,6 +10,7 @@ import {
import {
ArchiveIcon,
ArrowLeftIcon,
+ BlocksIcon,
BotIcon,
GitBranchIcon,
KeyboardIcon,
@@ -49,6 +50,7 @@ const SETTINGS_SECTION_ICONS: Readonly<
"/settings/appearance": PaletteIcon,
"/settings/keybindings": KeyboardIcon,
"/settings/providers": BotIcon,
+ "/settings/integrations": BlocksIcon,
"/settings/source-control": GitBranchIcon,
"/settings/connections": Link2Icon,
"/settings/archived": ArchiveIcon,
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index e3aef6705..83cf3de75 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -5,6 +5,7 @@ export type SettingsPath =
| "/settings/appearance"
| "/settings/keybindings"
| "/settings/providers"
+ | "/settings/integrations"
| "/settings/source-control"
| "/settings/connections"
| "/settings/archived";
@@ -28,6 +29,7 @@ export const SETTINGS_SECTION_LABELS: Readonly<Record<SettingsPath, string>> = {
"/settings/appearance": "Appearance",
"/settings/keybindings": "Keybindings",
"/settings/providers": "Providers",
+ "/settings/integrations": "Integrations",
"/settings/source-control": "Source Control",
"/settings/connections": "Connections",
"/settings/archived": "Archive",
@@ -195,6 +197,30 @@ export const SETTINGS_SEARCH_ITEMS = [
title: "Providers",
to: "/settings/providers",
},
+ {
+ id: "browser-default-viewport",
+ title: "Default browser viewport",
+ to: "/settings/integrations",
+ targetId: "browser",
+ },
+ {
+ id: "browser-default-zoom",
+ title: "Default browser zoom",
+ to: "/settings/integrations",
+ targetId: "browser",
+ },
+ {
+ id: "browser-default-appearance",
+ title: "Default browser appearance",
+ to: "/settings/integrations",
+ targetId: "browser",
+ },
+ {
+ id: "browser-auto-show-floating-preview",
+ title: "Auto-show floating preview",
+ to: "/settings/integrations",
+ targetId: "browser",
+ },
{
id: "source-control",
title: "Source control",
diff --git a/apps/web/src/hooks/useSettings.ts b/apps/web/src/hooks/useSettings.ts
index 590949c09..5e633a5de 100644
--- a/apps/web/src/hooks/useSettings.ts
+++ b/apps/web/src/hooks/useSettings.ts
@@ -185,6 +185,17 @@ export function getClientSettings(): ClientSettings {
return getClientSettingsSnapshot();
}
+/**
+ * Resolves once client settings have been read from disk.
+ *
+ * The pre-hydration snapshot is just the schema defaults, so imperative paths
+ * that open a preview must await this or they bake the built-in viewport, zoom
+ * and appearance into a tab that never picks up the user's saved values.
+ */
+export function ensureClientSettingsHydrated(): Promise<void> {
+ return hydrateClientSettings();
+}
+
export function useClientSettingsHydrated(): boolean {
return useSyncExternalStore(
subscribeClientSettingsHydration,
diff --git a/apps/web/src/routeTree.gen.ts b/apps/web/src/routeTree.gen.ts
index 697eb607c..f7c47ace6 100644
--- a/apps/web/src/routeTree.gen.ts
+++ b/apps/web/src/routeTree.gen.ts
@@ -18,6 +18,7 @@ import { Route as ChatIndexRouteImport } from './routes/_chat.index'
import { Route as SettingsSourceControlRouteImport } from './routes/settings.source-control'
import { Route as SettingsProvidersRouteImport } from './routes/settings.providers'
import { Route as SettingsKeybindingsRouteImport } from './routes/settings.keybindings'
+import { Route as SettingsIntegrationsRouteImport } from './routes/settings.integrations'
import { Route as SettingsGeneralRouteImport } from './routes/settings.general'
import { Route as SettingsDiagnosticsRouteImport } from './routes/settings.diagnostics'
import { Route as SettingsConnectionsRouteImport } from './routes/settings.connections'
@@ -73,6 +74,11 @@ const SettingsKeybindingsRoute = SettingsKeybindingsRouteImport.update({
path: '/keybindings',
getParentRoute: () => SettingsRoute,
} as any)
+const SettingsIntegrationsRoute = SettingsIntegrationsRouteImport.update({
+ id: '/integrations',
+ path: '/integrations',
+ getParentRoute: () => SettingsRoute,
+} as any)
const SettingsGeneralRoute = SettingsGeneralRouteImport.update({
id: '/general',
path: '/general',
@@ -139,6 +145,7 @@ export interface FileRoutesByFullPath {
'/settings/connections': typeof SettingsConnectionsRoute
'/settings/diagnostics': typeof SettingsDiagnosticsRoute
'/settings/general': typeof SettingsGeneralRoute
+ '/settings/integrations': typeof SettingsIntegrationsRoute
'/settings/keybindings': typeof SettingsKeybindingsRoute
'/settings/providers': typeof SettingsProvidersRoute
'/settings/source-control': typeof SettingsSourceControlRoute
@@ -158,6 +165,7 @@ export interface FileRoutesByTo {
'/settings/connections': typeof SettingsConnectionsRoute
'/settings/diagnostics': typeof SettingsDiagnosticsRoute
'/settings/general': typeof SettingsGeneralRoute
+ '/settings/integrations': typeof SettingsIntegrationsRoute
'/settings/keybindings': typeof SettingsKeybindingsRoute
'/settings/providers': typeof SettingsProvidersRoute
'/settings/source-control': typeof SettingsSourceControlRoute
@@ -180,6 +188,7 @@ export interface FileRoutesById {
'/settings/connections': typeof SettingsConnectionsRoute
'/settings/diagnostics': typeof SettingsDiagnosticsRoute
'/settings/general': typeof SettingsGeneralRoute
+ '/settings/integrations': typeof SettingsIntegrationsRoute
'/settings/keybindings': typeof SettingsKeybindingsRoute
'/settings/providers': typeof SettingsProvidersRoute
'/settings/source-control': typeof SettingsSourceControlRoute
@@ -203,6 +212,7 @@ export interface FileRouteTypes {
| '/settings/connections'
| '/settings/diagnostics'
| '/settings/general'
+ | '/settings/integrations'
| '/settings/keybindings'
| '/settings/providers'
| '/settings/source-control'
@@ -222,6 +232,7 @@ export interface FileRouteTypes {
| '/settings/connections'
| '/settings/diagnostics'
| '/settings/general'
+ | '/settings/integrations'
| '/settings/keybindings'
| '/settings/providers'
| '/settings/source-control'
@@ -243,6 +254,7 @@ export interface FileRouteTypes {
| '/settings/connections'
| '/settings/diagnostics'
| '/settings/general'
+ | '/settings/integrations'
| '/settings/keybindings'
| '/settings/providers'
| '/settings/source-control'
@@ -326,6 +338,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof SettingsKeybindingsRouteImport
parentRoute: typeof SettingsRoute
}
+ '/settings/integrations': {
+ id: '/settings/integrations'
+ path: '/integrations'
+ fullPath: '/settings/integrations'
+ preLoaderRoute: typeof SettingsIntegrationsRouteImport
+ parentRoute: typeof SettingsRoute
+ }
'/settings/general': {
id: '/settings/general'
path: '/general'
@@ -421,6 +440,7 @@ interface SettingsRouteChildren {
SettingsConnectionsRoute: typeof SettingsConnectionsRoute
SettingsDiagnosticsRoute: typeof SettingsDiagnosticsRoute
SettingsGeneralRoute: typeof SettingsGeneralRoute
+ SettingsIntegrationsRoute: typeof SettingsIntegrationsRoute
SettingsKeybindingsRoute: typeof SettingsKeybindingsRoute
SettingsProvidersRoute: typeof SettingsProvidersRoute
SettingsSourceControlRoute: typeof SettingsSourceControlRoute
@@ -432,6 +452,7 @@ const SettingsRouteChildren: SettingsRouteChildren = {
SettingsConnectionsRoute: SettingsConnectionsRoute,
SettingsDiagnosticsRoute: SettingsDiagnosticsRoute,
SettingsGeneralRoute: SettingsGeneralRoute,
+ SettingsIntegrationsRoute: SettingsIntegrationsRoute,
SettingsKeybindingsRoute: SettingsKeybindingsRoute,
SettingsProvidersRoute: SettingsProvidersRoute,
SettingsSourceControlRoute: SettingsSourceControlRoute,
diff --git a/apps/web/src/routes/settings.integrations.tsx b/apps/web/src/routes/settings.integrations.tsx
new file mode 100644
index 000000000..3fa49ae93
--- /dev/null
+++ b/apps/web/src/routes/settings.integrations.tsx
@@ -0,0 +1,11 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+import { IntegrationsSettingsPanel } from "../components/settings/IntegrationsSettings";
+
+function SettingsIntegrationsRoute() {
+ return <IntegrationsSettingsPanel />;
+}
+
+export const Route = createFileRoute("/settings/integrations")({
+ component: SettingsIntegrationsRoute,
+});
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index d872a422a..9be21da65 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -956,6 +956,24 @@ export const DesktopPreviewTabInputSchema = Schema.Struct({
tabId: DesktopPreviewTabIdSchema,
});
+/**
+ * Tab creation carries the client's configured browser defaults so the guest
+ * is born already zoomed and color-scheme-emulated. Applying them after
+ * creation instead would paint one frame at 100%/system first, which reads as
+ * a flash on every tab open. Both fields are optional so an older renderer
+ * still gets the historical defaults.
+ */
+export const DesktopPreviewCreateTabInputSchema = Schema.Struct({
+ tabId: DesktopPreviewTabIdSchema,
+ zoomFactor: Schema.optional(Schema.Number.check(Schema.isGreaterThan(0))),
+ colorScheme: Schema.optional(DesktopPreviewColorSchemeSchema),
+});
+
+export interface DesktopPreviewTabDefaults {
+ readonly zoomFactor?: number | undefined;
+ readonly colorScheme?: DesktopPreviewColorScheme | undefined;
+}
+
export const DesktopPreviewRegisterWebviewInputSchema = Schema.Struct({
tabId: DesktopPreviewTabIdSchema,
webContentsId: Schema.Int.check(Schema.isGreaterThan(0)),
@@ -1109,7 +1127,7 @@ export interface DesktopBridge {
}
export interface DesktopPreviewBridge {
- createTab: (tabId: string) => Promise<void>;
+ createTab: (tabId: string, defaults?: DesktopPreviewTabDefaults) => Promise<void>;
closeTab: (tabId: string) => Promise<void>;
registerWebview: (tabId: string, webContentsId: number) => Promise<void>;
navigate: (tabId: string, url: string) => Promise<void>;
diff --git a/packages/contracts/src/preview.ts b/packages/contracts/src/preview.ts
index b8c5741a6..a1b743afc 100644
--- a/packages/contracts/src/preview.ts
+++ b/packages/contracts/src/preview.ts
@@ -118,6 +118,30 @@ export const FILL_PREVIEW_VIEWPORT = {
_tag: "fill",
} as const satisfies PreviewViewportSetting;
+/**
+ * Discrete zoom levels mirroring Chrome's preset ladder. Zoom is applied by the
+ * desktop main process to the Chromium guest, but the ladder lives here so the
+ * settings UI can offer exactly the steps the zoom controls step through.
+ */
+export const PREVIEW_ZOOM_LEVELS = [
+ 0.25, 0.33, 0.5, 0.67, 0.75, 0.8, 0.9, 1.0, 1.1, 1.25, 1.5, 1.75, 2.0, 2.5, 3.0, 4.0, 5.0,
+] as const;
+
+export const PreviewZoomFactor = Schema.Literals(PREVIEW_ZOOM_LEVELS);
+export type PreviewZoomFactor = typeof PreviewZoomFactor.Type;
+
+export const DEFAULT_PREVIEW_ZOOM_FACTOR: PreviewZoomFactor = 1.0;
+
+/**
+ * Preferred `prefers-color-scheme` for preview guests. `system` clears the
+ * emulation override so the guest follows the OS. Structurally identical to
+ * `DesktopPreviewColorScheme`, which is the IPC-layer spelling of the same set.
+ */
+export const PreviewAppearancePreference = Schema.Literals(["system", "light", "dark"]);
+export type PreviewAppearancePreference = typeof PreviewAppearancePreference.Type;
+
+export const DEFAULT_PREVIEW_APPEARANCE: PreviewAppearancePreference = "system";
+
export const PreviewNavStatus = Schema.Union([
Schema.TaggedStruct("Idle", {}),
Schema.TaggedStruct("Loading", {
@@ -153,6 +177,13 @@ export const PreviewOpenInput = Schema.Struct({
threadId: ThreadId,
/** Omit to create an empty (Idle) tab the user can type into. */
url: Schema.optional(Url),
+ /**
+ * Initial viewport for the new tab. Omitting it keeps the historical
+ * fill-panel behaviour; clients that have a configured default send it here
+ * so the session is born at the right size instead of being resized a frame
+ * later (which the user would see as a visible reflow).
+ */
+ viewport: Schema.optional(PreviewViewportSetting),
});
export type PreviewOpenInput = typeof PreviewOpenInput.Type;
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 22ce210ed..2410274f8 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -10,6 +10,14 @@ import {
ProviderOptionSelections,
} from "./model.ts";
import { ModelSelection } from "./orchestration.ts";
+import {
+ DEFAULT_PREVIEW_APPEARANCE,
+ DEFAULT_PREVIEW_ZOOM_FACTOR,
+ FILL_PREVIEW_VIEWPORT,
+ PreviewAppearancePreference,
+ PreviewViewportSetting,
+ PreviewZoomFactor,
+} from "./preview.ts";
import { ProviderInstanceConfig, ProviderInstanceId } from "./providerInstance.ts";
// ── Client Settings (local-only) ───────────────────────────────
@@ -111,7 +119,34 @@ export const DEFAULT_ENVIRONMENT_IDENTIFICATION_MODE: EnvironmentIdentificationM
export const FontFamilyPreference = Schema.String.check(Schema.isMaxLength(200));
export type FontFamilyPreference = typeof FontFamilyPreference.Type;
+/**
+ * Defaults for the in-app preview browser, applied whenever a tab is opened
+ * without an explicit viewport/zoom/appearance — by the user opening a browser
+ * tab, or by an agent calling `preview_open` with no size. Client-local
+ * because the Chromium guest they configure is desktop-local.
+ */
+export const DEFAULT_BROWSER_VIEWPORT: PreviewViewportSetting = FILL_PREVIEW_VIEWPORT;
+export const DEFAULT_BROWSER_AUTO_SHOW_FLOATING_PREVIEW = true;
+
export const ClientSettingsSchema = Schema.Struct({
+ browserDefaultViewport: PreviewViewportSetting.pipe(
+ Schema.withDecodingDefault(Effect.succeed(DEFAULT_BROWSER_VIEWPORT)),
+ ),
+ browserDefaultZoomFactor: PreviewZoomFactor.pipe(
+ Schema.withDecodingDefault(Effect.succeed(DEFAULT_PREVIEW_ZOOM_FACTOR)),
+ ),
+ browserDefaultAppearance: PreviewAppearancePreference.pipe(
+ Schema.withDecodingDefault(Effect.succeed(DEFAULT_PREVIEW_APPEARANCE)),
+ ),
+ /**
+ * Whether an agent opening a preview pops the floating mini player into
+ * view. Only applies when the agent didn't ask either way — an explicit
+ * `open`/`show` on `preview_open` still wins, since that is the agent
+ * deliberately showing or hiding its work.
+ */
+ browserAutoShowFloatingPreview: Schema.Boolean.pipe(
+ Schema.withDecodingDefault(Effect.succeed(DEFAULT_BROWSER_AUTO_SHOW_FLOATING_PREVIEW)),
+ ),
// Desktop-only: require holding the quit shortcut (Cmd/Ctrl+Q) before the
// app quits; a quick tap only shows a hint. Browser clients ignore it.
confirmQuit: Schema.Boolean.pipe(Schema.withDecodingDefault(Effect.succeed(true))),
@@ -759,6 +794,10 @@ export const ServerSettingsPatch = Schema.Struct({
export type ServerSettingsPatch = typeof ServerSettingsPatch.Type;
export const ClientSettingsPatch = Schema.Struct({
+ browserDefaultViewport: Schema.optionalKey(PreviewViewportSetting),
+ browserDefaultZoomFactor: Schema.optionalKey(PreviewZoomFactor),
+ browserDefaultAppearance: Schema.optionalKey(PreviewAppearancePreference),
+ browserAutoShowFloatingPreview: Schema.optionalKey(Schema.Boolean),
confirmQuit: Schema.optionalKey(Schema.Boolean),
confirmThreadArchive: Schema.optionalKey(Schema.Boolean),
confirmThreadDelete: Schema.optionalKey(Schema.Boolean),