dsh-builtin-browser 0.1.21 → 0.1.22

package/src/browser-electron/provider.ts

@@ -8,9 +8,9 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import { writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { isAbsolute, join, resolve, sep } from 'node:path'
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
 import type {
   BrowserA11yRequest,
   BrowserA11yResult,
@@ -134,6 +134,20 @@ export interface ElectronBrowserViewHost {
    * tell which task's page is currently visible.
    */
   showView?(handle: ElectronViewHandle, label?: string): void
+  /**
+   * Optional: (re)present a view and WAIT until the host confirms it. Chromium
+   * silently drops CDP-synthesized input (`Input.*`) for a view that has no
+   * display surface, which made clicks/typing report success while the page
+   * received nothing (and made the first input after a navigation vanish,
+   * because the replaced renderer has no surface yet). Unlike
+   * {@link showView}, this round-trips an RPC barrier that is ordered AFTER
+   * the show on the same socket, so its reply means the view is on screen.
+   * Rejects when the view cannot be presented; a host without this method is
+   * assumed to present every view (headless/probe hosts).
+   * @param handle - the handle to present.
+   * @param label - human-readable session/task label, as in {@link showView}.
+   */
+  presentView?(handle: ElectronViewHandle, label?: string): Promise<void>
   /**
    * Optional cheap usability probe (no network): whether the host can back
    * views at all right now. The self-hosted host checks for a usable Electron
@@ -303,6 +317,31 @@ const KEY_SPECS: Readonly<Record<string, { readonly key: string; readonly code:
 /** Supported key names, exported for the tool's enum and error messages. */
 export const BROWSER_KEY_NAMES: readonly string[] = Object.keys(KEY_SPECS)
 
+/**
+ * Localized names a system Downloads folder may carry, in probe order: the
+ * English default first, then the Chinese spellings — a zh-CN desktop calls
+ * the folder `下载`, a zh-TW one `下載`, and neither is `Downloads`.
+ */
+const DOWNLOAD_DIR_NAMES: readonly string[] = ['Downloads', '下载', '下載']
+
+/**
+ * Resolve the default download directory when the config names none: an
+ * existing `XDG_DOWNLOAD_DIR` wins (the freedesktop standard, which is what a
+ * localized Linux desktop writes), then the first localized `Downloads` folder
+ * that exists under the home directory, and finally the English name — created
+ * on first use — when none exists yet.
+ * @returns the absolute default download directory.
+ */
+function defaultDownloadDir(): string {
+  const xdg = process.env.XDG_DOWNLOAD_DIR
+  if (typeof xdg === 'string' && xdg !== '' && existsSync(xdg)) return xdg
+  for (const name of DOWNLOAD_DIR_NAMES) {
+    const candidate = join(homedir(), name)
+    if (existsSync(candidate)) return candidate
+  }
+  return join(homedir(), DOWNLOAD_DIR_NAMES[0] ?? 'Downloads')
+}
+
 /**
  * Browser provider over Electron views. Sessions hold an ordered list of
  * tabs; each tab is one view created by the host. The active tab receives
@@ -326,9 +365,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
     this.httpOnly = config.httpOnly ?? true
     this.snapshotMaxElements = config.snapshotMaxElements ?? 60
     this.contentMaxChars = config.contentMaxChars ?? 100_000
-    // Confine downloads to a dedicated directory by default: the OS Downloads
-    // folder is the human-visible, browser-natural place for downloaded files.
-    this.downloadDir = config.downloadDir ?? join(homedir(), 'Downloads')
+    // Confine downloads AND screenshot saves to a dedicated directory by
+    // default: the OS Downloads folder is the human-visible, browser-natural
+    // place for written files, and it is the one directory the DSH file
+    // sandbox does not have to arbitrate. The localized name is probed so a
+    // Chinese desktop (`~/下载`) works without configuring `downloadDir`.
+    this.downloadDir = config.downloadDir ?? defaultDownloadDir()
     // Route toolbar (host UI) actions into the session model: the human and
     // the agent then always drive the same tabs, history, and navigation.
     this.host.onUserAction?.(action => { void this.handleUserAction(action) })
@@ -433,10 +475,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
    */
   private locateTab(session: BrowserSessionId, tabId: string): { s: Session; index: number } {
     const s = this.session(session)
-    const own = s.tabs.findIndex(tab => tab.id === tabId)
+    // Accept the bare uuid as well as the "tab:<uuid>" form the tools print:
+    // ids are globally unique, so requiring the printed prefix only produced a
+    // misleading "is not open in this session" error that listed the very tab
+    // the caller had just named.
+    const wanted = stripTabPrefix(tabId)
+    const own = s.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted)
     if (own >= 0) return { s, index: own }
     for (const other of this.sessions.values()) {
-      const index = other.tabs.findIndex(tab => tab.id === tabId)
+      const index = other.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted)
       if (index >= 0) return { s: other, index }
     }
     const ownIds = s.tabs.map(t => t.id).join(', ') || '(none)'
@@ -479,6 +526,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // evaluate paths so a wedged navigation surfaces as an error instead of
       // blocking the tool call forever.
       const timeoutMs = 30_000
+      // Document identity of the page we are leaving (see settleDocument).
+      const before = await this.documentStamp(handle)
       const result = await withTimeout(
         handle.sendCommand(CDP_PAGE_NAVIGATE, { url } satisfies CdpNavigateParams),
         timeoutMs,
@@ -494,7 +543,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
       if (typeof errorText === 'string' && errorText !== '') {
         throw new BrowserError(`browser: navigation to "${url}" failed: ${errorText}`, 'BROWSER_NAVIGATION_FAILED')
       }
+      // Record as soon as the navigation has committed: history bookkeeping must
+      // not wait on the best-effort settle below (which only delays what the
+      // NEXT observation sees, not whether this action happened).
       this.record(s, 'navigate', { url }, true)
+      await this.settleDocument(handle, before, signal)
       this.showActive(s)
     } catch (error) {
       if (!(error instanceof BrowserError && (error as { code?: string }).code === 'BROWSER_NAVIGATION_BLOCKED')) {
@@ -504,6 +557,113 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
+  /**
+   * A per-document stamp: `performance.timeOrigin` is unique per document load,
+   * so it tells a same-URL reload and an A→B→A redirect apart from the document
+   * that was current before the navigation. Empty string when unreadable.
+   */
+  private async documentStamp(handle: ElectronViewHandle): Promise<string> {
+    const probe = await this.documentProbe(handle)
+    return probe?.stamp ?? ''
+  }
+
+  /**
+   * One cheap in-page reading of the document's identity and parse state.
+   *
+   * Returns null when the page did NOT answer (mid-commit, execution context
+   * destroyed) — the caller keeps waiting. A page that answered with an
+   * unexpected shape (an override or a non-conforming host; the production
+   * expression always yields a string) is reported as `unknown` rather than as
+   * "no answer": blocking the navigation for the whole budget on a page that
+   * demonstrably responded has no upside.
+   */
+  private async documentProbe(handle: ElectronViewHandle): Promise<{ stamp: string; readyState: string } | null> {
+    try {
+      const result = await withTimeout(
+        handleSendEvaluate(handle, 'String(performance.timeOrigin) + "|" + document.readyState'),
+        3_000,
+        undefined,
+        'browser: document probe timed out',
+      )
+      if (!result.ok) return null
+      if (typeof result.value !== 'string') return { stamp: '', readyState: 'unknown' }
+      const [stamp = '', readyState = ''] = result.value.split('|')
+      return { stamp, readyState }
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Page.navigate resolves at navigation COMMIT, not at load: the new document
+   * is already current (so location.href and document.title are the new page's)
+   * while its DOM is still being parsed. browser_open snapshots immediately
+   * after navigating, which is why it could report the right title with zero
+   * interactive elements — and why a separate browser_snapshot right after
+   * always found them.
+   *
+   * Wait — bounded, best-effort — for the new document to settle: readyState
+   * must reach interactive/complete AND the document identity must have
+   * changed. A page that never settles must not fail a navigation that already
+   * succeeded, so a timeout here is swallowed.
+   */
+  private async settleDocument(handle: ElectronViewHandle, before: string, signal?: AbortSignal): Promise<void> {
+    const started = Date.now()
+    const deadline = started + SETTLE_TIMEOUT_MS
+    for (;;) {
+      if (signal?.aborted === true) return
+      // A probe failure is expected while the navigation commits (the context is
+      // being destroyed) — keep polling rather than giving up.
+      const probe = await this.documentProbe(handle)
+      if (probe !== null) {
+        const settled = probe.readyState === 'interactive'
+          || probe.readyState === 'complete'
+          || probe.readyState === 'unknown'
+        const isNewDocument = before === '' || probe.stamp === '' || probe.stamp !== before
+        // The common case: the new document exists and is parsed — return now.
+        if (settled && isNewDocument) return
+        // Same document (hash navigation, cancelled/aborted load): there is no
+        // parse to wait for, so do not burn the budget. Outlast the brief
+        // window in which the OUTGOING document may still answer instead.
+        if (settled && Date.now() - started >= SETTLE_GRACE_MS) return
+      }
+      if (Date.now() >= deadline) return
+      await delay(SETTLE_POLL_MS, signal)
+    }
+  }
+
+  /**
+   * Make sure the active tab's view can actually receive synthesized input.
+   * Chromium drops `Input.*` events for a view with no display surface, so this
+   * runs before click/type/key and fails loudly (BROWSER_VIEW_NOT_PRESENTED)
+   * rather than reporting a success the page never saw.
+   */
+  private async present(s: Session, signal?: AbortSignal): Promise<void> {
+    const { handle } = this.activeTab(s)
+    const present = this.host.presentView?.bind(this.host)
+    if (present === undefined) {
+      this.showActive(s)
+      return
+    }
+    signal?.throwIfAborted()
+    const timeoutMs = 10_000
+    try {
+      await withTimeout(
+        present(handle, s.label),
+        timeoutMs,
+        signal,
+        `browser: presenting the page view timed out after ${timeoutMs}ms`,
+      )
+      this.showActive(s)
+    } catch (error) {
+      throw new BrowserError(
+        `browser: the page view is not presented, so synthesized input would be silently dropped (${String(error)})`,
+        'BROWSER_VIEW_NOT_PRESENTED',
+        { cause: error },
+      )
+    }
+  }
+
   /** Execute JS in the active tab's page context. */
   async execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult> {
     const s = this.session(session)
@@ -1033,6 +1193,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       x = request.x
       y = request.y
     }
+    // Input.* is only delivered to a view with a current display surface; the
+    // barrier also re-presents after a navigation replaced the renderer.
+    await this.present(s, signal)
     const press = (type: 'mousePressed' | 'mouseReleased'): Promise<Record<string, unknown>> =>
       handle.sendCommand('Input.dispatchMouseEvent', { type, x, y, button: 'left', clickCount: 1 } satisfies CdpMouseParams)
     const timeoutMs = 30_000
@@ -1078,6 +1241,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     const text = 'text' in request ? request.text : ''
     const timeoutMs = 30_000
+    // Input.insertText goes through the Input domain: same display-surface
+    // requirement as click/key.
+    await this.present(s, signal)
     try {
       await withTimeout(
         handle.sendCommand('Input.insertText', { text } satisfies CdpInsertTextParams),
@@ -1149,6 +1315,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     const entry = entries[target]
     if (entry?.id === undefined) throw new BrowserError('browser: history entry missing id', 'BROWSER_HISTORY_INVALID')
+    // A history step is a navigation too: the classic A→B→A redirect would
+    // otherwise read the outgoing document's identity (see settleDocument).
+    const before = await this.documentStamp(handle)
     await withTimeout(
       handle.sendCommand('Page.navigateToHistoryEntry', { entryId: entry.id }),
       timeoutMs,
@@ -1157,6 +1326,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       () => { void handle.sendCommand('Page.stopLoading').catch(() => {}) },
     )
     this.record(s, direction === -1 ? 'back' : 'forward', {}, true)
+    await this.settleDocument(handle, before, signal)
     this.showActive(s)
   }
 
@@ -1176,6 +1346,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
     const timeoutMs = 30_000
+    // Same-URL reload: only the per-load document identity can tell the new
+    // document from the old one, so capture it before reloading.
+    const before = await this.documentStamp(handle)
     await withTimeout(
       handle.sendCommand('Page.reload', { ignoreCache: false }),
       timeoutMs,
@@ -1185,6 +1358,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       () => { void handle.sendCommand('Page.stopLoading').catch(() => {}) },
     )
     this.record(s, 'reload', {}, true)
+    await this.settleDocument(handle, before, signal)
     this.showActive(s)
   }
 
@@ -1199,6 +1373,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
     const params = { key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.vk, nativeVirtualKeyCode: spec.vk, ...spec.text !== undefined ? { text: spec.text } : {} }
     const timeoutMs = 15_000
+    // Input.dispatchKeyEvent is subject to the same display-surface rule.
+    await this.present(s, signal)
     const release = (): Promise<Record<string, unknown>> =>
       handle.sendCommand('Input.dispatchKeyEvent', { type: 'keyUp', ...params })
     try {
@@ -1677,13 +1853,54 @@ export class ElectronBrowserProvider implements BrowserProvider {
   }
 
   /**
-   * Download a URL to a local file, keeping the session's cookies/login.
-   * Requires the self-hosted host (which implements view-level download); the
-   * desktop shell's embedded views delegate downloads to the real browser UI.
-   * Admission: only HTTP(S) targets (the in-page fetch cannot meaningfully
-   * fetch anything else), and the save path must be absolute — confined to
-   * `downloadDir` when one is configured, so a prompt-injected agent cannot
-   * write arbitrary machine paths.
+   * Admit a caller-supplied save path for a file the browser writes to disk.
+   * ONE gate for both `browser_download` and `browser_screenshot`: the path
+   * must be absolute, must resolve inside `downloadDir`, and must not already
+   * exist. Without it a prompt-injected agent could write — or silently
+   * replace — any file the DSH process can reach, which also escapes the file
+   * sandbox every other tool in the set runs under.
+   * @param savePath - the caller's target path.
+   * @param kind - the operation, used in the error code and message.
+   * @returns the resolved absolute target path.
+   * @throws BrowserError when the path is relative, outside the directory, or occupied.
+   */
+  private admitSavePath(savePath: string, kind: 'download' | 'screenshot'): string {
+    const code = kind === 'download' ? 'BROWSER_DOWNLOAD_BLOCKED' : 'BROWSER_SCREENSHOT_BLOCKED'
+    if (!isAbsolute(savePath)) {
+      throw new BrowserError(`browser: ${kind} savePath must be an absolute path`, code)
+    }
+    const file = resolve(savePath)
+    if (this.downloadDir !== undefined) {
+      const dir = resolve(this.downloadDir)
+      // Case-insensitive comparison: Windows paths are case-insensitive, and
+      // resolve() does not normalize case. Without this, C:\Users\X\Downloads
+      // and c:\users\x\downloads would be treated as different roots.
+      const dirLower = dir.toLowerCase()
+      const fileLower = file.toLowerCase()
+      if (fileLower !== dirLower && !fileLower.startsWith(dirLower + sep.toLowerCase())) {
+        throw new BrowserError(`browser: ${kind} savePath must be inside downloadDir "${dir}"`, code)
+      }
+    }
+    // Never replace an existing file: its previous content is unrecoverable,
+    // and the admitted directory may hold files the human put there. A new
+    // name is one tool call away.
+    if (existsSync(file)) {
+      throw new BrowserError(`browser: refusing to overwrite existing file "${file}" — use another name`, code)
+    }
+    return file
+  }
+
+  /**
+   * Download an HTTP(S) URL with the session's cookies to a local file.
+   * Admission is the shared {@link admitSavePath} gate; only the self-hosted
+   * host implements it (the desktop shell's embedded views delegate downloads
+   * to the real browser UI). Both admitted paths and screenshots are confined
+   * to `downloadDir`, so a prompt-injected agent cannot write arbitrary
+   * machine paths.
+   * @param session - the session whose cookies are used.
+   * @param request - the URL plus the absolute target path.
+   * @param signal - optional cancellation.
+   * @returns the path the file was written to.
    */
   async download(session: BrowserSessionId, request: { readonly url: string; readonly savePath: string }, signal?: AbortSignal): Promise<{ readonly path: string }> {
     const s = this.session(session)
@@ -1701,23 +1918,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
       throw new BrowserError(`browser: refusing download of non-HTTP(S) URL "${request.url}"`, 'BROWSER_DOWNLOAD_BLOCKED')
     }
-    // savePath admission: must be absolute; when downloadDir is configured it
-    // must resolve inside it (no ..-escape).
-    if (!isAbsolute(request.savePath)) {
-      throw new BrowserError('browser: download savePath must be an absolute path', 'BROWSER_DOWNLOAD_BLOCKED')
-    }
-    if (this.downloadDir !== undefined) {
-      const dir = resolve(this.downloadDir)
-      const file = resolve(request.savePath)
-      // Case-insensitive comparison: Windows paths are case-insensitive, and
-      // resolve() does not normalize case. Without this, C:\Users\X\Downloads
-      // and c:\users\x\downloads would be treated as different roots.
-      const dirLower = dir.toLowerCase()
-      const fileLower = file.toLowerCase()
-      if (fileLower !== dirLower && !fileLower.startsWith(dirLower + sep.toLowerCase())) {
-        throw new BrowserError(`browser: download savePath must be inside downloadDir "${dir}"`, 'BROWSER_DOWNLOAD_BLOCKED')
-      }
-    }
+    // savePath admission: the shared gate — absolute, inside `downloadDir`,
+    // and never an existing file. Screenshots use the very same one.
+    const savePath = this.admitSavePath(request.savePath, 'download')
     const downloadable = handle as { download?(url: string, savePath: string): Promise<void> }
     if (typeof downloadable.download !== 'function') {
       throw new BrowserError('browser: download is only available on the self-hosted browser', 'BROWSER_DOWNLOAD_UNSUPPORTED')
@@ -1730,13 +1933,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // reply is harmlessly consumed by the RPC layer.
     const timeoutMs = 60_000
     await withTimeout(
-      downloadable.download(request.url, request.savePath),
+      downloadable.download(request.url, savePath),
       timeoutMs,
       signal,
       `browser: download timed out after ${timeoutMs}ms`,
     )
-    this.record(s, 'download', { url: request.url, savePath: request.savePath }, true, { result: request.savePath })
-    return { path: request.savePath }
+    this.record(s, 'download', { url: request.url, savePath }, true, { result: savePath })
+    return { path: savePath }
   }
 
   /**
@@ -1829,15 +2032,25 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return this.saveScreenshot(data, request?.savePath, 'image/png')
   }
 
-  /** Build the data URL and optionally write the image to disk. */
+  /**
+   * Build the data URL and optionally write the image to disk. The caller's
+   * path goes through the SAME {@link admitSavePath} gate as a download — it
+   * must be absolute, resolve inside `downloadDir`, and not be an existing
+   * file — so a screenshot cannot be used to write to, or silently replace,
+   * files anywhere the DSH process happens to have permission (issue #13).
+   */
   private saveScreenshot(base64: string, savePath: string | undefined, mime: string): { dataUrl: string; path?: string } {
     if (savePath !== undefined) {
+      // Admission failures propagate unchanged: they describe the caller's
+      // path, not a disk problem.
+      const target = this.admitSavePath(savePath, 'screenshot')
       try {
-        writeFileSync(savePath, Buffer.from(base64, 'base64'))
-        return { dataUrl: `data:${mime};base64,${base64}`, path: savePath }
+        mkdirSync(dirname(target), { recursive: true })
+        writeFileSync(target, Buffer.from(base64, 'base64'))
+        return { dataUrl: `data:${mime};base64,${base64}`, path: target }
       } catch (error) {
         // Report the write problem but keep the capture usable.
-        throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
+        throw new BrowserError(`browser: screenshot save to "${target}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
       }
     }
     return { dataUrl: `data:${mime};base64,${base64}` }
@@ -2066,6 +2279,39 @@ export class ElectronBrowserProvider implements BrowserProvider {
   }
 }
 
+/**
+ * Hard cap on waiting for a navigation's new document to be parsed. Bounded and
+ * best-effort: a page that never settles must not fail the navigation.
+ */
+const SETTLE_TIMEOUT_MS = 5_000
+
+/**
+ * When the document already looks settled but its identity has NOT changed
+ * (same-document navigation, or the outgoing document still answering), wait
+ * only this long before returning — there is no parse in flight to wait for.
+ */
+const SETTLE_GRACE_MS = 150
+
+/** Poll interval for the document-settle loop. */
+const SETTLE_POLL_MS = 25
+
+/** `tab:<uuid>` ↔ `<uuid>`: ids accept either form (see locateTab). */
+function stripTabPrefix(id: string): string {
+  return id.startsWith('tab:') ? id.slice(4) : id
+}
+
+/** Abortable sleep used by the settle loop. */
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(() => {
+      if (signal !== undefined) signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = (): void => { clearTimeout(timer); resolve() }
+    if (signal !== undefined) signal.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
 /**
  * Bound a promise so a wedged CDP call surfaces as an error instead of
  * hanging the tool call forever. The caller's signal, when provided, wins

package/src/browser-electron/remote-host.ts

@@ -26,6 +26,7 @@
  */
 
 import { execFileSync, spawn, type ChildProcessByStdio } from 'node:child_process'
+import { appendFileSync, mkdirSync, statSync, writeFileSync } from 'node:fs'
 import { randomBytes } from 'node:crypto'
 import { createRequire } from 'node:module'
 import { existsSync, readFileSync, readdirSync, readlinkSync } from 'node:fs'
@@ -38,6 +39,9 @@ import type { ExportedCookie } from '../browser/types.js'
 /** How long to wait for the child to signal readiness before failing. */
 const READY_TIMEOUT_MS = 20_000
 
+/** Budget for the present/barrier round-trips (see presentView). */
+const PRESENT_TIMEOUT_MS = 10_000
+
 /** Safety cap on a single RPC reply line (base64 downloads are the big ones). */
 const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024
 
@@ -355,23 +359,32 @@ function compareVersions(a: string, b: string): number {
   return 0
 }
 
-/** From an electron package entry file, find the dist executable beside it. */
-function electronExeBeside(entry: string): string | undefined {
-  const candidates = [
-    join(dirname(entry), 'dist', 'electron.exe'),
-    join(dirname(entry), 'dist', 'electron'),
-    join(dirname(entry), '..', 'dist', 'electron.exe'),
-    join(dirname(entry), '..', 'dist', 'electron'),
+/** Candidate executable layouts used by the Electron npm package on one platform. */
+function electronDistCandidates(pkgRoot: string, platform: NodeJS.Platform = process.platform): string[] {
+  // macOS keeps the runnable binary inside the Electron.app bundle; unlike
+  // Windows/Linux there is no dist/electron(.exe) sibling to probe.
+  if (platform === 'darwin') {
+    return [join(pkgRoot, 'dist', 'Electron.app', 'Contents', 'MacOS', 'Electron')]
+  }
+  return [
+    join(pkgRoot, 'dist', 'electron.exe'),
+    join(pkgRoot, 'dist', 'electron'),
   ]
-  for (const candidate of candidates) {
-    if (existsSync(candidate)) return candidate
+}
+
+/** From an electron package entry file, find the dist executable beside it. */
+function electronExeBeside(entry: string, platform: NodeJS.Platform = process.platform): string | undefined {
+  const packageRoots = [dirname(entry), join(dirname(entry), '..')]
+  for (const packageRoot of packageRoots) {
+    const candidate = electronDistExe(packageRoot, platform)
+    if (candidate !== undefined) return candidate
   }
   return undefined
 }
 
 /** From an electron package root, find its dist executable. */
-function electronDistExe(pkgRoot: string): string | undefined {
-  for (const candidate of [join(pkgRoot, 'dist', 'electron.exe'), join(pkgRoot, 'dist', 'electron')]) {
+function electronDistExe(pkgRoot: string, platform: NodeJS.Platform = process.platform): string | undefined {
+  for (const candidate of electronDistCandidates(pkgRoot, platform)) {
     if (existsSync(candidate)) return candidate
   }
   return undefined
@@ -452,8 +465,13 @@ class ElectronChildClient {
     })
     this.child.stderr.setEncoding('utf8')
     this.child.stderr.on('data', chunk => {
-      // Diagnostics only; never parse stderr as protocol.
-      process.stderr.write(`[dsh-browser host] ${String(chunk)}`)
+      // Diagnostics only; never parse stderr as protocol. Mirror to a log file
+      // as well: under a plain `dsh web` self-host these lines only ever reach
+      // the DSH process's stderr, so a host that crashes in a restart loop left
+      // the user with a string of timeouts and no stack to act on.
+      const text = String(chunk)
+      process.stderr.write(`[dsh-browser host] ${text}`)
+      appendHostLog(text)
     })
     // Send the spawn token over stdin (first line). The child reads it from
     // stdin instead of argv so the token is never visible in the process
@@ -464,11 +482,17 @@ class ElectronChildClient {
     // A failed spawn (bad/corrupt binary) emits 'error' — without a listener
     // that would crash the whole DSH process.
     this.child.on('error', error => {
-      process.stderr.write(`[dsh-browser host] spawn error: ${String(error)}\n`)
+      const line = `spawn error: ${String(error)}`
+      process.stderr.write(`[dsh-browser host] ${line}\n`)
+      appendHostLog(`${line}\n`)
       this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`))
     })
     this.child.on('exit', (code, signal) => {
-      this.fail(new Error(`dsh-builtin-browser: browser host exited (code=${String(code)} signal=${String(signal)})`))
+      // The exit code/signal is the other half of a crash report; without it a
+      // restart loop is indistinguishable from a clean stop.
+      const line = `browser host exited (code=${String(code)} signal=${String(signal)})`
+      appendHostLog(`${line}\n`)
+      this.fail(new Error(`dsh-builtin-browser: ${line}`))
     })
   }
 
@@ -860,6 +884,39 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       .catch(() => { /* host unavailable */ })
   }
 
+  /**
+   * (Re)present a view and WAIT for the child to confirm it, so the provider
+   * can dispatch CDP `Input.*` knowing the view has a display surface.
+   *
+   * Two things this fixes, both silent before:
+   *  - showing a view that does not exist yet is a no-op in the child, so the
+   *    view must be materialized first (a fresh tab's createView races the
+   *    provider's showActive);
+   *  - a view whose renderer was replaced by a navigation is \"already\n   *    visible\" and therefore skipped by the child's flicker-avoidance fast
+   *    path, leaving the new renderer without a surface.
+   *
+   * The barrier ping is meaningful because the child handles messages strictly
+   * in order: its reply is queued behind the showView and so only arrives once
+   * the visibility change has been applied.
+   */
+  async presentView(handle: ElectronViewHandle, label?: string): Promise<void> {
+    await this.ready()
+    const client = this.client
+    if (client === undefined) throw new HostGoneError('browser host unavailable')
+    // A view created after the last createView does not exist in the child yet.
+    // ensureMaterialized also rebuilds it against a fresh child after a host
+    // death, which is the path that used to leave sessions timing out forever.
+    if (handle instanceof DeferredRemoteView) {
+      await withTimeout(handle.ensureMaterialized(), PRESENT_TIMEOUT_MS, 'browser host did not materialize the view')
+    }
+    await withTimeout(
+      client.call('showView', { viewId: handle.id, ...label !== undefined ? { label } : {} }),
+      PRESENT_TIMEOUT_MS,
+      'browser host did not confirm the view presentation',
+    )
+    await withTimeout(client.call('ping'), PRESENT_TIMEOUT_MS, 'browser host stopped answering')
+  }
+
   /** Route a view into its session's own window (one window per session). */
   groupView(handle: ElectronViewHandle, windowId: string, label?: string): void {
     this.groups.set(handle.id, { windowId, ...label !== undefined ? { label } : {} })
@@ -977,6 +1034,33 @@ class DeferredRemoteView implements ElectronViewHandle {
   async restoreAuth(cookies: ExportedCookie[]): Promise<number> {
     return this.withRecovery(view => view.restoreAuth(cookies))
   }
+
+  /** Materialize this view in the child (no-op when already there). */
+  async ensureMaterialized(): Promise<void> {
+    await this.withRecovery(async () => undefined)
+  }
+}
+
+/**
+ * Append one host-diagnostics chunk to `$DSH_HOME/logs/dsh-builtin-browser-host.log`.
+ * Best-effort and self-limiting: diagnostics must never break the host or grow
+ * without bound, so failures are swallowed and the file is truncated when it
+ * gets large (a crash loop writes quickly).
+ */
+const HOST_LOG_MAX_BYTES = 2 * 1024 * 1024
+
+function appendHostLog(text: string): void {
+  const home = process.env.DSH_HOME
+  if (home === undefined || home === '') return
+  try {
+    const dir = join(home, 'logs')
+    const file = join(dir, 'dsh-builtin-browser-host.log')
+    try {
+      if (statSync(file).size > HOST_LOG_MAX_BYTES) writeFileSync(file, '')
+    } catch { /* first write, or unreadable: just append */ }
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(file, text)
+  } catch { /* diagnostics are best-effort only */ }
 }
 
 /** Reject a promise if it does not settle within the budget. */
@@ -1001,6 +1085,9 @@ export function defaultHostMainPath(): string {
  * steps; `resolveElectronPath` is the full resolution order.
  */
 export const internals = {
+  electronDistCandidates,
+  electronDistExe,
+  electronExeBeside,
   isBareElectron,
   resolveElectronPath,
   resolveElectronPathImpl,