feat(browser): add link open target and presentation mode settings

- Add browser linkOpenTarget (internal/system) and linkPresentationMode (panel/overlay) shared settings with schema defaults and migration
- Route external link opens through BrowserPanelManager so http(s) URLs can land in the embedded panel or overlay based on user preference
- Extend BrowserSettings UI with selects for link target and presentation mode
- Propagate presentation mode via open-panel browser event and honor it in useBrowserSync
- Harden supervisor shutdown: track OpenCode server children for forced cleanup and guard ThreadSessionManager against start-after-dispose with new startClose tests

Author: SDSLeon

src/main/browser/BrowserPanelManager.ts

@@ -1,13 +1,15 @@
 import { randomUUID } from "node:crypto";
-import { BrowserWindow } from "electron";
+import { BrowserWindow, shell } from "electron";
 import type {
   BrowserEvent,
   BrowserState,
   BrowserStartPickerResult,
   BrowserTabInfo,
 } from "@/shared/ipc";
 import type { LightcodePaths } from "@/shared/lightcodePaths";
+import type { BrowserLinkOpenTarget, BrowserLinkPresentationMode } from "@/shared/settings";
 import { dbGetState, dbSetState } from "../db";
+import { readSharedSettingsFile } from "../sharedSettingsFile";
 import { saveClipboardImageFile } from "../attachments/localFiles";
 import { IPC_EVENT_CHANNELS } from "@/shared/ipc";
 import { BrowserTab, resolveWebContentsById } from "./BrowserTab";
@@ -17,6 +19,8 @@ import { buildPickerScript } from "./picker/pickerScript";
 const PERSIST_KEY = "browser-panel-tabs-v1";
 const PERSIST_DEBOUNCE_MS = 750;
 const ATTACH_TIMEOUT_MS = 8000;
+const INTERNAL_BROWSER_PROTOCOLS = new Set(["http:", "https:"]);
+const SYSTEM_BROWSER_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
 
 interface PersistedTabsState {
   tabs: Array<{ url: string; title: string }>;
@@ -161,6 +165,51 @@ export class BrowserPanelManager {
     this.emit({ type: "open-panel" });
   }
 
+  private readLinkSettings(): {
+    linkOpenTarget: BrowserLinkOpenTarget;
+    linkPresentationMode: BrowserLinkPresentationMode;
+  } {
+    try {
+      const browser = readSharedSettingsFile(this.paths.settingsPath).browser;
+      return {
+        linkOpenTarget: browser.linkOpenTarget,
+        linkPresentationMode: browser.linkPresentationMode,
+      };
+    } catch {
+      return { linkOpenTarget: "internal", linkPresentationMode: "panel" };
+    }
+  }
+
+  private async openSystemBrowser(rawUrl: string): Promise<boolean> {
+    let url: URL;
+    try {
+      url = new URL(rawUrl);
+    } catch {
+      return false;
+    }
+    if (!SYSTEM_BROWSER_PROTOCOLS.has(url.protocol)) return false;
+    await shell.openExternal(url.toString());
+    return true;
+  }
+
+  async openLink(rawUrl: string): Promise<boolean> {
+    let url: URL;
+    try {
+      url = new URL(rawUrl);
+    } catch {
+      return false;
+    }
+
+    const settings = this.readLinkSettings();
+    if (settings.linkOpenTarget === "system" || !INTERNAL_BROWSER_PROTOCOLS.has(url.protocol)) {
+      return this.openSystemBrowser(url.toString());
+    }
+
+    this.emit({ type: "open-panel", mode: settings.linkPresentationMode });
+    void this.createTab({ url: url.toString(), activate: true }).catch(() => {});
+    return true;
+  }
+
   private toInfo(t: BrowserTab): BrowserTabInfo {
     const s = t.snapshot();
     return {
@@ -206,10 +255,8 @@ export class BrowserPanelManager {
       onAttention: (id) => {
         this.emit({ type: "tab-attention", tabId: id });
       },
-      onPopup: (sourceTabId, popupUrl) => {
-        void this.createTab({ url: popupUrl, activate: false }).then((info) => {
-          if (sourceTabId) this.emit({ type: "tab-attention", tabId: info.tabId });
-        });
+      onPopup: (_sourceTabId, popupUrl) => {
+        void this.openLink(popupUrl).catch(() => {});
       },
     });
     this.tabs.push(tab);

src/main/ipc/localHandlers.ts

@@ -92,7 +92,12 @@ export function createLocalIpcHandlers(
     saveHandoffContext: (payload) =>
       saveHandoffContextFile(options.requireLightcodePaths(), payload),
     openExternal: async (url) => {
-      await shell.openExternal(assertSafeExternalUrl(url));
+      const safeUrl = assertSafeExternalUrl(url);
+      const browserPanel = options.getBrowserPanelManager();
+      if (browserPanel && (await browserPanel.openLink(safeUrl))) {
+        return;
+      }
+      await shell.openExternal(safeUrl);
     },
     focusWindow: () => {
       const win = options.getMainWindow();

src/main/sharedSettingsFile.test.ts

@@ -83,7 +83,12 @@ describe("sharedSettingsFile", () => {
       favoriteModels: [],
       recentModels: [],
       agentHookSupport: {},
-      browser: { allowEval: false, allowDataAccess: false },
+      browser: {
+        allowEval: false,
+        allowDataAccess: false,
+        linkOpenTarget: "internal",
+        linkPresentationMode: "panel",
+      },
     });
 
     expect(readSharedSettingsFile(settingsPath)).toEqual({
@@ -143,7 +148,12 @@ describe("sharedSettingsFile", () => {
       favoriteModels: [],
       recentModels: [],
       agentHookSupport: {},
-      browser: { allowEval: false, allowDataAccess: false },
+      browser: {
+        allowEval: false,
+        allowDataAccess: false,
+        linkOpenTarget: "internal",
+        linkPresentationMode: "panel",
+      },
     });
     expect(readFileSync(settingsPath, "utf8")).toContain('"themeMode": "dark"');
   });
@@ -215,4 +225,22 @@ describe("sharedSettingsFile", () => {
       providerConfigs: {},
     });
   });
+
+  it("normalizes older browser settings without dropping existing flags", () => {
+    const settingsPath = join(makeTempDir(), "settings.json");
+    writeFileSync(
+      settingsPath,
+      JSON.stringify({
+        browser: { allowEval: true, allowDataAccess: true },
+      }),
+      "utf8",
+    );
+
+    expect(readSharedSettingsFile(settingsPath).browser).toEqual({
+      allowEval: true,
+      allowDataAccess: true,
+      linkOpenTarget: "internal",
+      linkPresentationMode: "panel",
+    });
+  });
 });

src/renderer/app.test.tsx

@@ -326,6 +326,7 @@ describe("App", () => {
       threads: [],
       pendingThreadLaunches: {},
       pendingLaunchSegments: {},
+      lastViewedAtByThreadId: {},
       view: { kind: "home" },
     }));
     useGitStore.setState({

src/renderer/views/MainView/parts/RightPanel/parts/BrowserPanel/hooks/useBrowserSync.ts

@@ -19,7 +19,15 @@ export function useBrowserSync(): void {
       } else if (event.type === "tab-attention") {
         setAttention(event.tabId);
       } else if (event.type === "open-panel") {
-        usePanelStore.getState().openBrowserPanel();
+        const panel = usePanelStore.getState();
+        if (event.mode === "overlay") {
+          panel.setBrowserOverlayOpen(true);
+        } else {
+          if (event.mode === "panel") {
+            panel.setBrowserOverlayOpen(false);
+          }
+          panel.openBrowserPanel();
+        }
       } else if (event.type === "picker-cancelled") {
         setPickerActive(false);
       }

src/renderer/views/SettingsOverlay/parts/BrowserSettings.tsx

@@ -1,23 +1,64 @@
+import { startTransition } from "react";
 import { Switch } from "@heroui/react";
+import { Select } from "@/renderer/components/common";
 import { useSharedSettings } from "@/renderer/state/sharedSettingsStore";
+import type { BrowserLinkOpenTarget, BrowserLinkPresentationMode } from "@/shared/settings";
+
+const linkOpenTargetOptions = [
+  { id: "internal", label: "App Browser" },
+  { id: "system", label: "System Browser" },
+] as const;
+
+const linkPresentationModeOptions = [
+  { id: "panel", label: "Right panel" },
+  { id: "overlay", label: "Fullscreen overlay" },
+] as const;
 
 export function BrowserSettings() {
   const allowEval = useSharedSettings((s) => s.browser.allowEval);
   const allowDataAccess = useSharedSettings((s) => s.browser.allowDataAccess);
+  const linkOpenTarget = useSharedSettings((s) => s.browser.linkOpenTarget);
+  const linkPresentationMode = useSharedSettings((s) => s.browser.linkPresentationMode);
   const setBrowserSetting = useSharedSettings((s) => s.setBrowserSetting);
 
   return (
     <div className="h-full min-h-0 overflow-y-auto px-6 pb-8 pt-4">
       <div className="mx-auto max-w-[720px]">
-        <h1 className="mb-2 text-lg font-semibold text-foreground">Browser</h1>
-        <p className="mb-6 text-xs text-muted">
-          The in-app browser lives in the right panel. Threads can opt in to the browser MCP via the
-          composer "+" menu; once enabled they can navigate, click, type, query the DOM, and take
-          screenshots inside this panel. The browser keeps running in the background even when the
-          panel is hidden.
-        </p>
+        <h1 className="mb-6 text-lg font-semibold text-foreground">Browser</h1>
 
         <div className="space-y-4">
+          <SettingRow
+            title="Open links in"
+            description="Choose whether links from Lightcode and browser popups stay in Lightcode or open externally."
+          >
+            <Select
+              aria-label="Open links in"
+              className="w-[180px] shrink-0"
+              options={linkOpenTargetOptions}
+              value={linkOpenTarget}
+              onChange={(value) => {
+                startTransition(() => {
+                  setBrowserSetting("linkOpenTarget", value as BrowserLinkOpenTarget);
+                });
+              }}
+            />
+          </SettingRow>
+          <SettingRow
+            title="Show opened links in"
+            description="When links open in a Lightcode browser tab, choose where the browser is revealed."
+          >
+            <Select
+              aria-label="Show opened links in"
+              className="w-[180px] shrink-0"
+              options={linkPresentationModeOptions}
+              value={linkPresentationMode}
+              onChange={(value) => {
+                startTransition(() => {
+                  setBrowserSetting("linkPresentationMode", value as BrowserLinkPresentationMode);
+                });
+              }}
+            />
+          </SettingRow>
           <SettingRow
             title="Allow eval"
             description={
@@ -26,9 +67,20 @@ export function BrowserSettings() {
                 page. Off by default — turn on only when you trust the loaded sites and the agent.
               </>
             }
-            value={allowEval}
-            onChange={(v) => setBrowserSetting("allowEval", v)}
-          />
+          >
+            <Switch
+              isSelected={allowEval}
+              onChange={(selected) => {
+                startTransition(() => {
+                  setBrowserSetting("allowEval", selected);
+                });
+              }}
+            >
+              <Switch.Control>
+                <Switch.Thumb />
+              </Switch.Control>
+            </Switch>
+          </SettingRow>
           <SettingRow
             title="Allow agents to read/write cookies and storage"
             description={
@@ -38,9 +90,20 @@ export function BrowserSettings() {
                 agent and the sites it visits.
               </>
             }
-            value={allowDataAccess}
-            onChange={(v) => setBrowserSetting("allowDataAccess", v)}
-          />
+          >
+            <Switch
+              isSelected={allowDataAccess}
+              onChange={(selected) => {
+                startTransition(() => {
+                  setBrowserSetting("allowDataAccess", selected);
+                });
+              }}
+            >
+              <Switch.Control>
+                <Switch.Thumb />
+              </Switch.Control>
+            </Switch>
+          </SettingRow>
         </div>
       </div>
     </div>
@@ -50,25 +113,15 @@ export function BrowserSettings() {
 function SettingRow(props: {
   title: string;
   description: React.ReactNode;
-  value: boolean;
-  onChange: (v: boolean) => void;
-  disabled?: boolean;
+  children: React.ReactNode;
 }) {
   return (
-    <div className="flex items-start justify-between gap-4 rounded-lg border border-border bg-[var(--surface-background,#0d1117)] px-4 py-3">
-      <div className="min-w-0 flex-1">
-        <div className="text-sm font-medium text-foreground">{props.title}</div>
-        <div className="mt-1 text-xs text-muted">{props.description}</div>
+    <div className="flex items-center justify-between gap-4">
+      <div className="min-w-0">
+        <p className="text-sm font-medium text-foreground">{props.title}</p>
+        <p className="text-xs text-muted">{props.description}</p>
       </div>
-      <Switch
-        isSelected={props.value}
-        isDisabled={props.disabled === true}
-        onChange={(selected) => props.onChange(selected)}
-      >
-        <Switch.Control>
-          <Switch.Thumb />
-        </Switch.Control>
-      </Switch>
+      {props.children}
     </div>
   );
 }

src/shared/ipc/events.ts

@@ -11,6 +11,7 @@ import type {
   ThreadStatusSource,
 } from "../contracts";
 import type { BrowserState, BrowserTabInfo } from "./procedures/browser";
+import type { BrowserLinkPresentationMode } from "../settings";
 import type { IpcProcedurePayload, SupervisorProcedureName } from "./procedureMap";
 
 export type SupervisorRequest = {
@@ -83,7 +84,7 @@ export type BrowserEvent =
   | { type: "state"; state: BrowserState }
   | { type: "tab-updated"; tab: BrowserTabInfo }
   | { type: "tab-attention"; tabId: string }
-  | { type: "open-panel" }
+  | { type: "open-panel"; mode?: BrowserLinkPresentationMode }
   | { type: "picker-cancelled" };
 
 export type UpdateStatus =