dor agent-browser: browser-chrome header (nav + URL + dev-server link) (#141)

Author: nedtwigg

docs/specs/dor-agent-browser.md

@@ -133,57 +133,6 @@ Invariants:
 - Workspace/window refs and target flags will be added only when Dormouse
   actually supports them.
 
-## Iframe Surface: Limitations And Status
-
-> Status: **provisional.** The `dor iframe` surface works for displaying a page,
-> but has structural limitations (below) that may keep it from shipping. The
-> likely path forward is to ship an **agent-browser** surface instead — a
-> Dormouse-controlled browser view (see `lib/src/components/wall/AgentBrowserPanel.tsx`)
-> that does not embed a foreign page as a peer browsing context — and to drop or
-> hide `dor iframe`. That surface is specified in
-> [dor-agent-browser.md](dor-agent-browser.md). Do not build features on top of
-> the iframe surface until this is resolved.
-
-An `<iframe>` pointed at an arbitrary URL is a **separate browsing context** from
-the Wall. Dormouse's input, focus, and attention model assumes a single
-same-document context, so the iframe surface conflicts with it in ways that are
-inherent to the browser, not bugs we can patch away:
-
-- **Focus leaves Dormouse entirely.** When the iframe gains focus, a focused
-  cross-origin frame owns the keyboard. Its keystrokes fire in *its* document and
-  never reach the parent. Dormouse's global shortcuts are a capturing `window`
-  keydown listener (`lib/src/components/wall/use-wall-keyboard.ts`), so dual-tap-⌘,
-  pane navigation, split, and kill all go dead until focus returns to the Wall.
-  The same-origin policy means the parent cannot observe or intercept those keys —
-  this cannot be fixed, only designed around (e.g. a click-to-interact overlay, or
-  an accept-focus model with a mouse-driven escape affordance).
-
-- **The app reads iframe-focus as being backgrounded.** Focusing the iframe fires
-  a `blur` on the parent `window`. Current handlers treat that as the whole app
-  losing focus: `Wall.tsx` clears cross-session attention, and
-  `use-window-focused.ts` flips `windowFocused` to `false`, which drives the
-  active styling (e.g. `SurfacePaneHeader.tsx`'s `isActiveHeader`). The result is
-  every header/focus-ring goes inactive and attention clears the instant the
-  iframe is focused. This part *is* fixable (distinguish `document.activeElement`
-  being one of our own iframes from a real window blur) but is not yet done.
-
-- **No programmatic focus handle.** `focusSession` (`lib/src/lib/terminal-lifecycle.ts`)
-  only knows xterm terminals in a registry. The iframe pane is not registered, so
-  `onClickPanel → enterTerminalMode → focusSession(iframeId)` is a no-op: Dormouse
-  cannot focus the iframe programmatically and cannot tell when it is focused.
-
-- **Some sites refuse to be framed, with no error signal.** Servers that send
-  `X-Frame-Options` or a CSP `frame-ancestors` directive cannot be embedded at
-  all, yielding a blank pane. Cross-origin frames do not report load errors to the
-  embedder (`onError` never fires; `onLoad` fires even for a blocked frame), so the
-  surface cannot reliably distinguish "loading", "blocked", and "broken". The
-  current `IframePanel` shows a best-effort stall hint after a timeout only.
-
-- **The VS Code webview must opt into framing.** The webview CSP
-  (`vscode-ext/src/webview-html.ts`) is `default-src 'none'`; without a `frame-src`
-  directive every `<iframe>` is blocked outright (blank white pane). A
-  `frame-src http: https:` allowance is required for the surface to render at all.
-
 ## Current Implemented Commands
 
 Implemented commands call private `surface.*` control methods. `surface.list`
@@ -215,7 +164,9 @@ from `command-detail`.
 - `dor send` [impl](../../dor/src/commands/send.ts) [docs](../../dor/test/snapshots/help/send.md)
 - `dor read` [impl](../../dor/src/commands/read.ts) [docs](../../dor/test/snapshots/help/read.md)
 - `dor kill` [impl](../../dor/src/commands/kill.ts) [docs](../../dor/test/snapshots/help/kill.md)
-- `dor iframe` [impl](../../dor/src/commands/iframe.ts) [docs](../../dor/test/snapshots/help/iframe.md)
+- `dor iframe` — **provisional**; high-fidelity URL embed with structural
+  limitations, see [dor-iframe.md](dor-iframe.md).
+  [impl](../../dor/src/commands/iframe.ts) [docs](../../dor/test/snapshots/help/iframe.md)
 - `dor agent-browser` / `dor ab` — delegates to the user's `agent-browser`,
   rendered in a Dormouse-native surface; see [dor-agent-browser.md](dor-agent-browser.md)
   (the chosen alternative to the iframe surface)

docs/specs/dor-cli.md

@@ -19,6 +19,12 @@ const config: StorybookConfig = {
       '@tauri-apps/plugin-shell': stub,
       '@tauri-apps/plugin-updater': stub,
       'dormouse-lib': path.resolve(here, '..', 'src'),
+      // Mirror tsconfig.app.json's `dor/* → ../dor/src/*` mapping so stories
+      // that import `Wall` (which pulls `dor/commands/*`, `dor/protocol`)
+      // resolve. Storybook's Vite doesn't read tsconfig paths, so without this
+      // any Wall-importing story fails with "Failed to resolve import 'dor/…'".
+      // Safe next to `dormouse-lib`: a string alias only matches `dor` or `dor/…`.
+      dor: path.resolve(here, '..', '..', 'dor', 'src'),
     };
     return config;
   },

docs/specs/dor-iframe.md

@@ -10,7 +10,7 @@
     "preview": "vite preview",
     "test": "vitest run",
     "test:watch": "vitest",
-    "storybook": "storybook dev -p 6006",
+    "storybook": "storybook dev -p 6006 --no-open",
     "build-storybook": "storybook build"
   },
   "dependencies": {

lib/.storybook/main.ts

@@ -7,14 +7,12 @@ import { IS_MAC } from '../lib/platform';
 import {
   buildAppTitleResolver,
   DEFAULT_ACTIVITY_STATE,
-  deriveHeader,
   getActivitySnapshot,
   getTerminalPaneStateSnapshot,
-  resolveDisplayPrimary,
   subscribeToActivity,
   subscribeToTerminalPaneState,
 } from '../lib/terminal-registry';
-import { createTerminalPaneState, type TerminalPaneState } from '../lib/terminal-state';
+import { createTerminalPaneState, deriveSurfaceLabel, type TerminalPaneState } from '../lib/terminal-state';
 
 export interface BaseboardProps {
   items: DooredItem[];
@@ -227,5 +225,5 @@ function deriveDoorTitle(
 ): string {
   const paneState = terminalStates.get(id) ?? createTerminalPaneState();
   const visible = allPaneStates.length > 0 ? allPaneStates : [paneState];
-  return resolveDisplayPrimary(deriveHeader(paneState, visible, { appTitleForPane }).primary, savedTitle);
+  return deriveSurfaceLabel(paneState, visible, appTitleForPane, savedTitle);
 }

lib/package.json

@@ -39,6 +39,7 @@ import {
   type MobileGestureTrackingState,
 } from '../lib/mobile-gesture-menu';
 import { useDynamicPalette } from '../lib/themes/use-dynamic-palette';
+import { isEditableTarget } from '../lib/dom';
 import { TouchUiContext } from './touch-ui-context';
 import type { SessionStatus } from '../lib/terminal-registry';
 
@@ -508,13 +509,7 @@ export function MobileTerminalUi({
       const active = document.activeElement;
       if (!(active instanceof HTMLElement)) return;
       if (!terminalHostRef.current?.contains(active)) return;
-      if (
-        active instanceof HTMLInputElement
-        || active instanceof HTMLTextAreaElement
-        || active.isContentEditable
-      ) {
-        active.blur();
-      }
+      if (isEditableTarget(active)) active.blur();
     };
     // Wall defers xterm focus via rAF, so a single blur can be reverted after we
     // return; repeat across rAF and a few staggered ticks. See mobile-ui.md §10.

lib/src/components/Baseboard.tsx

@@ -33,8 +33,7 @@ import {
 import {
   buildAppTitleResolver,
   createTerminalPaneState,
-  deriveHeader,
-  resolveDisplayPrimary,
+  deriveSurfaceLabel,
   surfaceRunsCommand,
 } from '../lib/terminal-state';
 import { orchestrateKill } from '../lib/kill-animation';
@@ -56,12 +55,14 @@ import { TerminalPanel } from './wall/TerminalPanel';
 import { TerminalPaneHeader } from './wall/TerminalPaneHeader';
 import { AgentBrowserPanel } from './wall/AgentBrowserPanel';
 import { IframePanel } from './wall/IframePanel';
+import { hostPathDisplay } from './wall/browser-url';
 import { SurfacePaneHeader } from './wall/SurfacePaneHeader';
 import { WorkspaceSelectionOverlay } from './wall/WorkspaceSelectionOverlay';
 import { useDockviewReady } from './wall/use-dockview-ready';
 import { pickSplitDirection } from './wall/dockview-helpers';
 import { useWallKeyboard } from './wall/use-wall-keyboard';
 import { useSessionPersistence } from './wall/use-session-persistence';
+import { useDevServerPortCorrelation } from './wall/use-dev-server-ports';
 import { useWindowFocused } from './wall/use-window-focused';
 import {
   DialogKeyboardContext,
@@ -171,16 +172,6 @@ function surfaceTypeFromParams(params: unknown): DorSurfaceType {
   return 'terminal';
 }
 
-function iframeTitle(url: string): string {
-  try {
-    const parsed = new URL(url);
-    const path = parsed.pathname === '/' ? '' : parsed.pathname;
-    return `${parsed.host}${path}${parsed.search}`;
-  } catch {
-    return url;
-  }
-}
-
 function componentForSurfaceType(type: DorSurfaceType): string {
   return type;
 }
@@ -641,6 +632,9 @@ export function Wall({
     selectedTypeRef,
   });
 
+  // --- Dev-server port → pane correlation (browser header connection chip) ---
+  useDevServerPortCorrelation({ apiRef, doorsRef });
+
   // --- Reattach ---
 
   const handleReattach = useCallback((
@@ -762,9 +756,8 @@ export function Wall({
     return panels.map((panel, index) => {
       const type = surfaceTypeFromParams(panel.params);
       const state = panelStates[index] ?? createTerminalPaneState();
-      const derived = deriveHeader(state, panelStates, { appTitleForPane });
       const title = type === 'terminal'
-        ? resolveDisplayPrimary(derived.primary, panel.title ?? panel.id)
+        ? deriveSurfaceLabel(state, panelStates, appTitleForPane, panel.title ?? panel.id)
         : (panel.title ?? panel.id);
 
       return {
@@ -1296,7 +1289,7 @@ export function Wall({
           minimized: booleanParam(params.minimized),
           params: { surfaceType: 'iframe', url },
           reference: target.value,
-          title: iframeTitle(url),
+          title: hostPathDisplay(url, true),
         });
         if (!result.ok) {
           detail.respond({ ok: false, error: result.message });
@@ -1471,6 +1464,16 @@ export function Wall({
       setConfirmKill(null);
       enterTerminalMode(id);
     },
+    onFocusPane: (id: string) => {
+      setConfirmKill(null);
+      // Visible pane → jump straight in; minimized (a door) → reattach first.
+      if (apiRef.current?.getPanel(id)) {
+        enterTerminalMode(id);
+        return;
+      }
+      const door = doorsRef.current.find((item) => item.id === id);
+      if (door) handleReattachRef.current(door, { enterPassthrough: true });
+    },
     onStartRename: (id: string) => {
       setRenamingPaneId(id);
     },

lib/src/components/MobileTerminalUi.tsx

@@ -12,14 +12,18 @@ import { clsx } from 'clsx';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
 import { getPlatform } from '../../lib/platform';
 import { readTextFromClipboard } from '../../lib/clipboard';
+import { isEditableTarget } from '../../lib/dom';
 import {
   openAgentBrowserScreenModal,
   registerAgentBrowserScreen,
+  type ChromeActions,
+  type ChromeSnapshot,
   type ScreenActions,
   type ScreenRegistration,
   type ScreenSnapshot,
   type ScreenState,
 } from './agent-browser-screen';
+import { hostPathDisplay } from './browser-url';
 import {
   EDIT_OPS,
   MOUSE_BUTTONS,
@@ -84,13 +88,7 @@ type StreamStatus = {
 function tabDisplayTitle(tab: StreamTab): string {
   const title = tab.title?.trim();
   if (title) return title;
-  try {
-    const parsed = new URL(tab.url);
-    const path = parsed.pathname === '/' ? '' : parsed.pathname;
-    return `${parsed.host}${path}` || tab.url;
-  } catch {
-    return tab.url || 'untitled';
-  }
+  return hostPathDisplay(tab.url) || 'untitled';
 }
 
 // Decode a base64 screencast frame to an ImageBitmap (the fallback display path
@@ -397,12 +395,38 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     };
   }, [wsPort, runAgentBrowser, maybeDisengageSync, publishScreen, screenshotLoop, drawBitmap]);
 
-  // --- header title follows the active tab ---
+  // --- header: persisted title + browser-chrome (URL / key) ---
 
+  const activeTab = useMemo(() => tabs.find((tab) => tab.active) ?? tabs[0] ?? null, [tabs]);
+
+  // The persisted panel title (door labels, session save) stays the active
+  // tab's display title; the live browser-chrome header shows the URL instead
+  // (from the snapshot below) and demotes this title to a tooltip.
   useEffect(() => {
-    const active = tabs.find((tab) => tab.active) ?? tabs[0];
-    if (active) api.setTitle(tabDisplayTitle(active));
-  }, [tabs, api]);
+    if (activeTab) api.setTitle(tabDisplayTitle(activeTab));
+  }, [activeTab, api]);
+
+  // The browser-chrome snapshot the header reads. Recomputed each render and
+  // mirrored into a ref so a (re-)registration always seeds the latest; the
+  // publish effect below pushes it to subscribers only on real changes.
+  const chromeSnapshot: ChromeSnapshot = {
+    url: activeTab?.url ?? '',
+    displayUrl: activeTab ? hostPathDisplay(activeTab.url) : '',
+    title: activeTab?.title ?? null,
+    key: params?.key ?? null,
+  };
+  const chromeSnapshotRef = useRef(chromeSnapshot);
+  chromeSnapshotRef.current = chromeSnapshot;
+
+  // Native history nav — `back`/`forward`/`reload` issued like tab actions
+  // (allowlisted in agentBrowserCommand). Stable; reads the live closure via
+  // the ref so the registered controller never goes stale.
+  const chromeActions = useMemo<ChromeActions>(() => ({
+    navigate(url) { if (url) runAgentBrowserRef.current(['open', url]); },
+    back() { runAgentBrowserRef.current(['back']); },
+    forward() { runAgentBrowserRef.current(['forward']); },
+    reload() { runAgentBrowserRef.current(['reload']); },
+  }), []);
 
   // --- screen controller: register for the header/modal bridge ---
 
@@ -437,6 +461,8 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     const registration = registerAgentBrowserScreen(api.id, {
       snapshot: computeSnapshot(),
       actions: screenActions,
+      chrome: chromeSnapshotRef.current,
+      chromeActions,
       hostCapable: !!getPlatform().agentBrowserCommand,
     });
     registrationRef.current = registration;
@@ -446,7 +472,15 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       registration.dispose();
       registrationRef.current = null;
     };
-  }, [api.id, screenActions, computeSnapshot, publishScreen]);
+  }, [api.id, screenActions, chromeActions, computeSnapshot, publishScreen]);
+
+  // Push browser-chrome changes to the header on a channel separate from the
+  // screen snapshot. Gated on the primitive fields so it fires on real
+  // tab/status changes, not every frame pulse.
+  useEffect(() => {
+    registrationRef.current?.updateChrome(chromeSnapshotRef.current);
+    // displayUrl is a pure function of url, so url covers it.
+  }, [chromeSnapshot.url, chromeSnapshot.title, chromeSnapshot.key]);
 
   // Persist sync state into the panel params so it round-trips through the
   // dockview layout blob (and survives reattach). Skip no-op writes.
@@ -729,6 +763,9 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       // contains() check above misses it; without this, typing into the modal's
       // Custom W/H/DPI fields would be swallowed and forwarded to the browser.
       if (e.target instanceof Element && e.target.closest('[role="dialog"]')) return;
+      // Likewise never hijack keystrokes destined for an editable field that
+      // lives outside the pane — notably the header's URL editor.
+      if (isEditableTarget(e.target)) return;
       e.preventDefault();
       if (e.type === 'keydown') handleKeyDownLike(e);
       else sendKey(e, 'keyUp');