dsh-builtin-browser 0.3.1 → 0.4.0

package/desktop-bridge/install.mjs

@@ -8,31 +8,92 @@
  * expressed as something replayable rather than as a one-off edit — re-run this
  * after every desktop upgrade.
  *
+ * TWO LAYOUTS
+ * DSH Desktop ships in two shapes, and they need different work:
+ *
+ *   unpacked  `<install>/resources/app/lib/main.js` is a real file. The
+ *             long-standing path: copy the module next to main.js and append a
+ *             guarded import to it.
+ *
+ *   packed    `<install>/resources/app.asar` holds the whole app (main.js is
+ *             inside the archive) and `resources/app.asar.unpacked` holds the
+ *             entries marked `unpacked`, i.e. the native modules. The official
+ *             Windows build is packed — where this script used to fail with
+ *             "not a DSH Desktop install" on a perfectly good installation,
+ *             because it only ever looked for the unpacked main.js.
+ *
+ * HOW THE PACKED LAYOUT IS HANDLED
+ * Electron loads `app.asar` in preference to `app/`, and a directory only wins
+ * once the archive is not there. Rewriting the archive in place is not an
+ * option either: the official build enables the
+ * `EnableEmbeddedAsarIntegrityValidation` fuse (measured: enabled), so a
+ * modified app.asar is a broken app. The archive is therefore never touched:
+ *
+ *   1. extract `app.asar` into `resources/app`, taking the real bytes of
+ *      `unpacked` entries from `resources/app.asar.unpacked` (a straight
+ *      archive walk would leave the native modules as empty stubs);
+ *   2. install the bridge into that tree exactly as in the unpacked layout;
+ *   3. rename `app.asar` to `app.asar.before-bridge`, so Electron falls back to
+ *      the directory that was just built.
+ *
+ * The trigger is the ARCHIVE's presence, not the directory's absence. A desktop
+ * update writes a new `app.asar` and leaves any earlier extraction lying around
+ * (the updater does not know about that directory), so keying off "the tree is
+ * missing" would patch the stale tree while Electron keeps loading the archive —
+ * a run that reports success with the bridge dead. Whenever the archive is
+ * there it is the app, so the tree is rebuilt from it.
+ *
+ * `--revert` moves the archive back and restores the pristine main.js. The
+ * extracted tree then becomes inert (the archive wins again) and can be deleted.
+ *
  * WHAT IT DOES (idempotent)
  *   1. copies `plugin-browser-bridge.js` next to the app's main bundle;
  *   2. appends a guarded import to `lib/main.js` that starts it after `whenReady`,
  *      keeping a pristine `main.js.before-bridge` backup the first time;
- *   3. does nothing if the import is already present.
+ *   3. does nothing if the import is already present;
+ *   4. keeps `dsh <args>` working: the Desktop CLI launcher and the CLI's own
+ *      runtime lookup both spell `app.asar` out loud and both break once the
+ *      archive is moved aside, so both are patched (each with its own
+ *      `.before-bridge` backup) and `--revert` restores them.
  *
  * USAGE
- *   node apps/desktop/bridge/install.mjs [path-to-DeepSeek-Harness-install]
+ *   node desktop-bridge/install.mjs [path-to-DeepSeek-Harness-install]
  * Default path: %LOCALAPPDATA%\Programs\DeepSeek Harness
- * Pass --revert to restore the pre-bridge main.js instead.
+ * Pass --revert to restore the pre-bridge state instead.
  */
-import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { copyFileSync, existsSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 const DEFAULT_INSTALL = join(process.env.LOCALAPPDATA ?? '', 'Programs', 'DeepSeek Harness')
 const args = process.argv.slice(2)
 const revert = args.includes('--revert')
 const installRoot = args.find(arg => !arg.startsWith('--')) ?? DEFAULT_INSTALL
 
-const appDir = join(installRoot, 'resources', 'app')
+const resourcesDir = join(installRoot, 'resources')
+const appDir = join(resourcesDir, 'app')
+const asarPath = join(resourcesDir, 'app.asar')
+const asarMoved = `${asarPath}.before-bridge`
 const mainPath = join(appDir, 'lib', 'main.js')
 const bridgeTarget = join(appDir, 'lib', 'plugin-browser-bridge.js')
 const bridgeSource = join(import.meta.dirname, 'plugin-browser-bridge.js')
 const backupPath = `${mainPath}.before-bridge`
 
+// Moving the archive aside breaks two more places that spell `app.asar` out
+// loud, and both are used by `dsh <args>` (the Desktop CLI launcher and the
+// plugin manager behind it), so they are patched here and restored by --revert:
+//
+//   runtime/cli/bin/dsh.cmd                    launches the CLI by that path
+//   dsh/.../dsh-desktop-host/lib/cli.js        locates `runtime` by that name
+//
+// Without them the CLI dies with MODULE_NOT_FOUND even though the app itself
+// runs fine (the shell resolves everything through app.getAppPath()).
+const cliShimPath = join(resourcesDir, 'runtime', 'cli', 'bin', 'dsh.cmd')
+const cliShimBackup = `${cliShimPath}.before-bridge`
+const hostCliPath = join(appDir, 'dsh', 'node_modules', '@deepseek-ai', 'dsh-desktop-host', 'lib', 'cli.js')
+const hostCliBackup = `${hostCliPath}.before-bridge`
+const CLI_SHIM_MARKER = 'dsh-builtin-browser: resolve the app directory'
+const HOST_CLI_MARKER = 'dsh-builtin-browser: recognize an unpacked `app` directory'
+
 /** The exact block appended to main.js. Keep it recognisable: idempotence and
  *  reverting both key off this marker. */
 const MARKER = '// dsh-builtin-browser: hand the plugin a way to drive the sidebar'
@@ -54,25 +115,225 @@ app.whenReady().then(async () => {
 });
 `
 
-if (!existsSync(mainPath)) {
-  console.error(`not a DSH Desktop install (no ${mainPath})`)
+/**
+ * Parse an asar header — a Chromium pickle holding
+ * `[payloadSize][jsonLength][json…]`, preceded by an 8-byte outer pickle.
+ * @param file - the archive path.
+ * @returns the parsed header tree plus the offset where file content starts.
+ */
+function readAsarHeader(file) {
+  const fd = openSync(file, 'r')
+  const sizeBuf = Buffer.alloc(8)
+  readSync(fd, sizeBuf, 0, 8, 0)
+  const headerSize = sizeBuf.readUInt32LE(4)
+  const headerBuf = Buffer.alloc(headerSize)
+  readSync(fd, headerBuf, 0, headerSize, 8)
+  const jsonLength = headerBuf.readUInt32LE(4)
+  const header = JSON.parse(headerBuf.toString('utf8', 8, 8 + jsonLength))
+  return { fd, header, contentBase: 8 + headerSize }
+}
+
+/**
+ * Write one asar tree to disk, taking `unpacked` entries from the sibling
+ * `.unpacked` directory — their bytes are not in the archive.
+ * @param asar - the archive path.
+ * @param outDir - directory to extract into.
+ * @returns file and byte counts, and how many entries came from `.unpacked`.
+ */
+function extractAsar(asar, outDir) {
+  const { fd, header, contentBase } = readAsarHeader(asar)
+  const unpackedRoot = `${asar}.unpacked`
+  let files = 0
+  let bytes = 0
+  let unpackedFiles = 0
+  const walk = (node, prefix) => {
+    for (const [name, entry] of Object.entries(node.files ?? {})) {
+      const relativePath = prefix === '' ? name : `${prefix}/${name}`
+      const target = join(outDir, ...relativePath.split('/'))
+      if (entry.files) {
+        mkdirSync(target, { recursive: true })
+        walk(entry, relativePath)
+        continue
+      }
+      mkdirSync(dirname(target), { recursive: true })
+      if (entry.unpacked) {
+        const source = join(unpackedRoot, ...relativePath.split('/'))
+        if (!existsSync(source)) throw new Error(`unpacked entry is missing: ${source}`)
+        copyFileSync(source, target)
+        unpackedFiles += 1
+      } else {
+        const buffer = Buffer.alloc(entry.size)
+        readSync(fd, buffer, 0, entry.size, contentBase + Number(entry.offset))
+        writeFileSync(target, buffer)
+      }
+      const actual = statSync(target).size
+      if (actual !== entry.size) throw new Error(`size mismatch for ${relativePath}: header ${entry.size}, wrote ${actual}`)
+      files += 1
+      bytes += actual
+    }
+  }
+  mkdirSync(outDir, { recursive: true })
+  walk(header, '')
+  return { files, bytes, unpackedFiles }
+}
+
+/**
+ * Make the Desktop CLI launcher resolve the app directory instead of spelling
+ * `app.asar` out loud.
+ *
+ * `resources/runtime/cli/bin/dsh.cmd` is what the `dsh` command on PATH calls,
+ * and it launches the CLI through an `app.asar\…` path. Once the archive is
+ * moved aside that path is gone, so `dsh <args>` dies with MODULE_NOT_FOUND
+ * while the app itself keeps working (the shell resolves everything through
+ * `app.getAppPath()`). The patch touches only the app-directory fragment: the
+ * launcher keeps its own spelling of everything else, including the executable
+ * name, so a build whose binary is named differently still works.
+ *
+ * @returns what happened, for the install log.
+ */
+function patchCliShim() {
+  if (!existsSync(cliShimPath)) return 'launcher not present (skipped)'
+  const text = readFileSync(cliShimPath, 'utf8')
+  if (text.includes(CLI_SHIM_MARKER)) return 'already patched'
+  if (!/%~dp0(?:\.\.\\)+app\.asar\\dsh\\/.test(text)) return 'unexpected launcher shape (skipped)'
+  if (!existsSync(cliShimBackup)) copyFileSync(cliShimPath, cliShimBackup)
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  const setLocal = /^.*setlocal.*$/m.exec(text)
+  const injection = [
+    `rem ${CLI_SHIM_MARKER} (resources\\app when the bridge is installed,`,
+    'rem resources\\app.asar on a stock installation).',
+    'set "DSH_APP=%~dp0..\\..\\..\\app"',
+    'if not exist "%DSH_APP%\\dsh\\node_modules\\@deepseek-ai\\dsh-desktop-host\\lib\\cli.js" set "DSH_APP=%~dp0..\\..\\..\\app.asar"',
+  ].join(eol)
+  const withVariables = setLocal === null
+    ? `${injection}${eol}${text}`
+    : text.replace(setLocal[0], `${setLocal[0]}${eol}${injection}`)
+  writeFileSync(cliShimPath, withVariables.replace(/%~dp0(?:\.\.\\)+app\.asar\\dsh\\/, '%DSH_APP%\\dsh\\'))
+  return 'patched'
+}
+
+/**
+ * Teach the Desktop CLI where its `runtime` directory is when the app is an
+ * unpacked `app` directory rather than `app.asar`.
+ *
+ * `dsh-desktop-host/lib/cli.js` derives the directory that holds pnpm as
+ * `dirname(runtimeArchivePath(runtimeDir) ?? runtimeDir)`, and
+ * `runtimeArchivePath` only recognises a parent literally named `app.asar`.
+ * With the app at `resources/app` that falls back to one level too few and
+ * resolves `resources/app/runtime`, which does not exist — so the plugin
+ * manager behind `dsh plugin …` cannot start.
+ *
+ * @returns what happened, for the install log.
+ */
+function patchHostCli() {
+  if (!existsSync(hostCliPath)) return 'cli.js not present (skipped)'
+  const text = readFileSync(hostCliPath, 'utf8')
+  if (text.includes(HOST_CLI_MARKER)) return 'already patched'
+  const before = '\tawait runDesktopCli(runtimeDir, join(dirname(runtimeArchivePath(runtimeDir) ?? runtimeDir), "runtime"));'
+  if (!text.includes(before)) return 'unexpected cli.js shape (skipped)'
+  if (!existsSync(hostCliBackup)) copyFileSync(hostCliPath, hostCliBackup)
+  const eol = text.includes('\r\n') ? '\r\n' : '\n'
+  const after = [
+    `\t// ${HOST_CLI_MARKER} as the app root,`,
+    '\t// so an installation whose app.asar was moved aside still finds its runtime.',
+    '\tconst cliOwnerDir = dirname(runtimeDir);',
+    '\tconst cliSupportRoot = basename(cliOwnerDir) === "app" || basename(cliOwnerDir) === "app.asar" ? dirname(cliOwnerDir) : cliOwnerDir;',
+    '\tawait runDesktopCli(runtimeDir, join(cliSupportRoot, "runtime"));',
+  ].join(eol)
+  writeFileSync(hostCliPath, text.replace(before, after))
+  return 'patched'
+}
+
+/** Apply both CLI compatibility patches and report them. */
+function installCliCompatibility() {
+  console.log(`  cli launcher:           ${patchCliShim()}`)
+  console.log(`  cli runtime resolution: ${patchHostCli()}`)
+}
+
+// The archive wins whenever it exists, so ITS presence — not the absence of the
+// directory — decides the layout. After a desktop update the archive is back
+// (a new build) while an older extraction is still lying around, and keying off
+// the directory would patch a tree that Electron never loads.
+const packedLayout = existsSync(asarPath)
+if (!existsSync(mainPath) && !existsSync(asarPath)) {
+  console.error('not a DSH Desktop install: neither')
+  console.error(`  ${mainPath}`)
+  console.error('nor')
+  console.error(`  ${asarPath}`)
+  console.error('exists. Pass the installation directory as the first argument.')
   process.exit(1)
 }
 
 if (revert) {
-  if (!existsSync(backupPath)) {
-    console.error(`nothing to revert: ${backupPath} does not exist`)
+  let reverted = false
+  if (existsSync(asarMoved)) {
+    if (existsSync(asarPath)) rmSync(asarPath, { force: true })
+    renameSync(asarMoved, asarPath)
+    console.log(`restored the app archive: app.asar.before-bridge -> app.asar`)
+    reverted = true
+  }
+  if (existsSync(backupPath)) {
+    copyFileSync(backupPath, mainPath)
+    console.log(`restored ${mainPath} from ${backupPath}`)
+    reverted = true
+  }
+  if (existsSync(cliShimBackup)) {
+    copyFileSync(cliShimBackup, cliShimPath)
+    console.log(`restored the CLI launcher: ${cliShimPath}`)
+    reverted = true
+  }
+  if (existsSync(hostCliBackup) && existsSync(dirname(hostCliPath))) {
+    copyFileSync(hostCliBackup, hostCliPath)
+    console.log(`restored the CLI runtime resolution: ${hostCliPath}`)
+    reverted = true
+  }
+  if (!reverted) {
+    console.error(`nothing to revert in ${installRoot}`)
     process.exit(1)
   }
-  copyFileSync(backupPath, mainPath)
-  console.log(`reverted ${mainPath} from ${backupPath}`)
+  console.log(`note: ${appDir} is inert while app.asar exists; delete it to reclaim ~350 MB`)
   process.exit(0)
 }
 
+if (packedLayout) {
+  const stale = existsSync(appDir)
+  const started = Date.now()
+  console.log(stale
+    ? `packed layout detected (${asarPath}); an earlier extraction is present and will be rebuilt`
+    : `packed layout detected (${asarPath})`)
+  if (stale) {
+    // Rebuild rather than merge: the tree has to describe THIS archive, and a
+    // merge would keep files the new build no longer ships. Removing it is safe
+    // here — the archive is present, so the app is not running from this
+    // directory, and a failure below leaves the archive in place and the
+    // installation working.
+    rmSync(appDir, { recursive: true, force: true })
+  }
+  console.log(`extracting into ${appDir} — this writes ~355 MB and can take a minute (measured: 8-55s)...`)
+  const result = extractAsar(asarPath, appDir)
+  const megabytes = (result.bytes / 1024 / 1024).toFixed(1)
+  const seconds = ((Date.now() - started) / 1000).toFixed(1)
+  console.log(`  extracted ${result.files} files / ${megabytes} MB` +
+    ` (${result.unpackedFiles} from app.asar.unpacked) in ${seconds}s`)
+  // A fresh extraction invalidates any earlier pristine copy: --revert has to be
+  // able to restore the main.js that belongs to THIS build.
+  copyFileSync(mainPath, backupPath)
+  try {
+    renameSync(asarPath, asarMoved)
+    console.log('moved the archive aside: app.asar -> app.asar.before-bridge')
+    console.log(`  Electron now loads ${appDir}; the archive is untouched, so the asar integrity fuse cannot trip`)
+  } catch (error) {
+    console.error(`could not move app.asar aside: ${String(error)}`)
+    console.error('close DSH Desktop completely and run this again.')
+    process.exit(1)
+  }
+}
+
 const current = readFileSync(mainPath, 'utf8')
 if (current.includes(MARKER)) {
   console.log('bridge already installed (main.js carries the marker); refreshing the module copy')
   copyFileSync(bridgeSource, bridgeTarget)
+  installCliCompatibility()
   process.exit(0)
 }
 
@@ -95,4 +356,5 @@ copyFileSync(bridgeSource, bridgeTarget)
 console.log(`installed bridge into ${appDir}`)
 console.log(`  module: ${bridgeTarget}`)
 console.log(`  patch:  ${mainPath} (+${SNIPPET.split('\n').length} lines)`)
+installCliCompatibility()
 console.log('restart DSH Desktop to activate it.')

package/desktop-bridge/plugin-browser-bridge.js

@@ -24,12 +24,24 @@
 import { createServer } from 'node:net'
 import { randomBytes } from 'node:crypto'
 import { writeFileSync, mkdirSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { app, webContents } from 'electron'
 
-/** Absolute path of the endpoint file the plugin reads. */
+/**
+ * Absolute path of the endpoint file the plugin reads.
+ *
+ * The fallback has to match the plugin's own (`process.env.DSH_HOME ??
+ * homedir()/.dsh`, see src/browser-electron/desktop-bridge-host.ts). With a
+ * bare `?? ''` an unset DSH_HOME resolves to the process CWD, so the endpoint
+ * landed beside the app — while the plugin looked in ~/.dsh and never found it.
+ * The failure is silent in both directions: discovery returns undefined and the
+ * plugin quietly falls back to a self-hosted window, with no error anywhere.
+ * Measured on DSH Desktop 0.2.0-rc.2, launched from a shortcut (no DSH_HOME in
+ * its environment).
+ */
 function endpointFile() {
-  const home = process.env.DSH_HOME ?? ''
+  const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
   return join(home, 'dsh-builtin-browser-bridge.json')
 }
 
@@ -128,10 +140,21 @@ async function handle(request) {
     //    b. otherwise type into the address field and submit with REAL key input
     //       (synthetic events do not move React's controlled input, and the field
     //       also loses focus to re-renders, so both halves are needed).
+    let submitVerdict = 'n/a'
     const restored = await sendCdp(shell.id, 'Runtime.evaluate', {
+      // Only real controls count, and only their OWN text does. Matching any
+      // node's `textContent` made a container that merely mentioned restoring a
+      // page report RESTORED — which skipped the address route below entirely
+      // and left the guest unmaterialized (measured on DSH 0.2.0-rc.2, where the
+      // sidebar shows no restore control at all).
       expression: `(() => {
         const nodes = Array.from(document.querySelectorAll('button,a,[role=button],div[role=link]'));
-        const hit = nodes.find(n => /恢复页面|恢复上次|上次打开/.test((n.textContent || '').trim()));
+        const hit = nodes.find(n => {
+          const own = (n.textContent || '').trim();
+          if (own.length > 24) return false;
+          return /^(恢复页面|恢复上次|恢复上次页面|上次打开)$/.test(own)
+            || /恢复|restore/i.test(n.getAttribute('aria-label') || n.getAttribute('title') || '');
+        });
         if (hit === undefined) return 'NO_RESTORE';
         hit.click();
         return 'RESTORED';
@@ -140,8 +163,15 @@ async function handle(request) {
     })
     if (restored?.result?.value !== 'RESTORED') {
       if (url !== '') {
-        // Set the value the way React accepts it, then submit with real input.
-        await sendCdp(shell.id, 'Runtime.evaluate', {
+        // Set the value the way React accepts it, then SUBMIT THE FORM.
+        //
+        // A dispatched Enter is not enough: the sidebar browser's toolbar is a
+        // `<form>` whose submission is wired to an explicit control (aria-label
+        // "前往" / "Go"), and implicit submission does not fire there — measured
+        // on DSH 0.2.0-rc.2, where Enter left the field filled and the guest
+        // uncreated. `requestSubmit()` goes through the same path the button
+        // does, so it works with React's onSubmit and needs no localized label.
+        const typed = await sendCdp(shell.id, 'Runtime.evaluate', {
           expression: `(() => {
             const inputs = Array.from(document.querySelectorAll('input')).filter(i => /HTTP|地址|url/i.test((i.placeholder || '') + (i.getAttribute('aria-label') || '')));
             if (inputs.length === 0) return 'NO_ADDRESS_BAR';
@@ -150,18 +180,28 @@ async function handle(request) {
             setter.call(input, ${JSON.stringify(String(request.url ?? ''))});
             input.dispatchEvent(new Event('input', { bubbles: true }));
             input.focus();
-            return 'TYPED';
+            const form = input.form ?? input.closest('form');
+            if (form) { form.requestSubmit(); return 'SUBMITTED_FORM'; }
+            const button = input.parentElement
+              ? input.parentElement.querySelector('button[type=submit],button')
+              : null;
+            if (button) { button.click(); return 'CLICKED_SUBMIT'; }
+            return 'TYPED_ONLY';
           })()`,
           returnByValue: true,
         })
-        for (const type of ['keyDown', 'keyUp']) {
-          await sendCdp(shell.id, 'Input.dispatchKeyEvent', {
-            type,
-            key: 'Enter',
-            code: 'Enter',
-            windowsVirtualKeyCode: 13,
-            nativeVirtualKeyCode: 13,
-          })
+        submitVerdict = String(typed?.result?.value ?? 'n/a')
+        // Enter stays as the last resort for sidebars without a form.
+        if (submitVerdict === 'TYPED_ONLY') {
+          for (const type of ['keyDown', 'keyUp']) {
+            await sendCdp(shell.id, 'Input.dispatchKeyEvent', {
+              type,
+              key: 'Enter',
+              code: 'Enter',
+              windowsVirtualKeyCode: 13,
+              nativeVirtualKeyCode: 13,
+            })
+          }
         }
       }
     }
@@ -177,7 +217,7 @@ async function handle(request) {
         return { ok: true, created: true, id: created[0].id, via: restored?.result?.value === 'RESTORED' ? 'restore' : 'address' }
       }
     }
-    throw new Error(`the sidebar did not create a browser guest (prepare=${String(verdict)}, restore=${String(restored?.result?.value)})`)
+    throw new Error(`the sidebar did not create a browser guest (prepare=${String(verdict)}, restore=${String(restored?.result?.value)}, submit=${submitVerdict})`)
   }
   if (op === 'ensureTabs') {
     // Grow the sidebar's browser tab strip to `count` tabs and report every guest.

package/lib/browser-electron/desktop-bridge-host.d.ts

@@ -35,7 +35,6 @@ export declare function bridgeEndpointPath(): string;
  * point is a single page both parties can see.
  */
 export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
-    private readonly endpoint;
     private readonly connection;
     private readonly views;
     /**
@@ -47,6 +46,16 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      * session gets its own page).
      */
     private readonly orphaned;
+    /**
+     * Registered by the provider, and deliberately never invoked on this carrier.
+     *
+     * The sidebar is the shell's own interface: a human clicking inside that page is an
+     * event the shell owns, and the bridge exposes no operation that reports it. The
+     * handler is stored anyway so the interface contract holds (a caller may register
+     * one and must not be surprised) and so a future bridge operation can deliver it
+     * without changing the provider. Consequently no user-action event is emitted while
+     * the desktop sidebar is the carrier — by design, not by omission.
+     */
     private userActionHandler;
     /**
      * @param endpoint - the shell's published bridge endpoint.

package/lib/browser-electron/desktop-bridge-host.js

@@ -50,7 +50,6 @@ function isGuestGone(error) {
  * point is a single page both parties can see.
  */
 export class DesktopBridgeViewHost {
-    endpoint;
     connection;
     views = new Map();
     /**
@@ -62,12 +61,21 @@ export class DesktopBridgeViewHost {
      * session gets its own page).
      */
     orphaned = new Set();
+    /**
+     * Registered by the provider, and deliberately never invoked on this carrier.
+     *
+     * The sidebar is the shell's own interface: a human clicking inside that page is an
+     * event the shell owns, and the bridge exposes no operation that reports it. The
+     * handler is stored anyway so the interface contract holds (a caller may register
+     * one and must not be surprised) and so a future bridge operation can deliver it
+     * without changing the provider. Consequently no user-action event is emitted while
+     * the desktop sidebar is the carrier — by design, not by omission.
+     */
     userActionHandler;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     constructor(endpoint) {
-        this.endpoint = endpoint;
         this.connection = new BridgeConnection(endpoint);
     }
     /**

package/lib/browser-electron/entry.js

@@ -16,7 +16,8 @@ import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js';
 import { DesktopBridgeViewHost } from './desktop-bridge-host.js';
-import { detectBrowser, SystemBrowserViewHost } from './system-browser.js';
+import { detectBrowser, searchSummary, SystemBrowserViewHost } from './system-browser.js';
+import { MissingSystemBrowserHost } from './missing-system-browser.js';
 import { SettingsStore } from './settings-store.js';
 export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.js';
 export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
@@ -96,10 +97,25 @@ export function apply(ctx, config) {
     // spawns a browser window. (An earlier version launched it here, which meant a
     // browser appeared the moment the plugin loaded — reported and fixed.)
     const channel = settings.get().browser.channel;
+    // Naming a browser is a decision about which one to use, so it also decides whether the
+    // desktop sidebar may take over. Skipping discovery for an explicit choice is what makes
+    // that choice real — otherwise a user who picked Chrome would silently get the sidebar,
+    // and a user who picked a browser that is not installed would never see the explanation
+    // written for exactly that case, because the sidebar would quietly replace it.
+    const explicitChoice = channel !== 'bundled' && channel !== 'auto';
     if (channel !== 'bundled') {
         const detected = detectBrowser(channel);
         if (detected === undefined) {
-            ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`);
+            // `auto` promises to take whatever is available, so falling back is what it
+            // asked for. Naming a browser is a specific request, and quietly satisfying it
+            // with a different one turns the real problem ("no Chrome here") into a
+            // confusing error about Electron later on. Report it instead.
+            if (channel === 'auto') {
+                ctx.logger?.warn?.('dsh-builtin-browser: no installed browser was found; using the bundled browser');
+            }
+            else {
+                adopt(new MissingSystemBrowserHost(channel, searchSummary(channel)), `the selected ${channel} is not installed — commands will explain how to fix it`);
+            }
         }
         else {
             const home = process.env.DSH_HOME ?? homedir();
@@ -114,6 +130,10 @@ export function apply(ctx, config) {
             adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir), `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
         }
     }
+    // An explicit choice was already adopted above; discovering the sidebar here would
+    // replace it, which is exactly what this guard prevents.
+    if (explicitChoice)
+        return;
     void DesktopBridgeViewHost.discover().then(sidebar => {
         // No bridge (plain `dsh web`, an older desktop build, or a shell that already
         // exited): keep self-hosting, which is what every surface has always done.

package/lib/browser-electron/history-store.js

@@ -137,7 +137,11 @@ export class HistoryStore {
             return [];
         }
         const pages = [];
-        for (const line of raw.split('\n')) {
+        // Strip a BOM first: trim() does not remove U+FEFF (it is not whitespace in
+        // ECMAScript), so a file written by Notepad or PowerShell made the first line fail to
+        // parse and be discarded as corrupt — silently losing one visit, or the whole file when
+        // it holds one. settings-store strips one for the same reason.
+        for (const line of raw.replace(/^\uFEFF/, '').split('\n')) {
             const trimmed = line.trim();
             if (trimmed === '')
                 continue;

package/lib/browser-electron/missing-system-browser.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A host that exists only to explain why the browser you asked for is not here.
+ *
+ * WHY THIS EXISTS
+ * When the browser setting names a browser explicitly (Chrome or Edge rather than
+ * "bundled" or "automatic"), the plugin used to log a warning and quietly fall back
+ * to its own Electron window. That is worse than failing: you asked for Chrome, you
+ * got an Electron window, and the error that eventually surfaced talked about
+ * Electron — pointing at something you never chose and never wanted to install. The
+ * actual problem ("no Chrome on this machine") never reached you.
+ *
+ * So the two choices are treated as the different requests they are:
+ *   - `auto` means "any browser will do", and falling back to the bundled one is the
+ *     behaviour it asks for;
+ *   - `chrome` / `edge` are explicit, and an explicit request that cannot be met is
+ *     reported as such, with the ways out of it.
+ *
+ * `available()` reports true on purpose. Reporting false would make the provider pick
+ * a different carrier and hide the problem again, which is exactly the bug.
+ */
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
+import type { BrowserChannel } from './system-browser.js';
+/**
+ * A carrier that cannot carry anything: every command explains the real problem.
+ *
+ * The message is written to be acted on, not just read: it says which browser was
+ * requested, where the plugin looked, and the three concrete ways to resolve it.
+ */
+export declare class MissingSystemBrowserHost implements ElectronBrowserViewHost {
+    private readonly kind;
+    private readonly searched;
+    /**
+     * @param kind - the browser the user asked for.
+     * @param searched - the names and locations that were checked, for the report.
+     */
+    constructor(kind: Exclude<BrowserChannel, 'bundled' | 'auto'>, searched: readonly string[]);
+    /** @returns always true: see the module comment — reporting false would hide this. */
+    available(): boolean;
+    /**
+     * The message every command fails with.
+     * @returns a multi-line explanation with the fixes.
+     */
+    private explain;
+    /**
+     * Create a handle whose every command fails with the explanation.
+     * @returns a handle that never reaches a page.
+     */
+    createView(): ElectronViewHandle;
+    /**
+     * Accept a handle for destruction. Nothing was created, so nothing is released.
+     * @param handle - the handle returned by {@link createView}.
+     */
+    destroyView(handle: ElectronViewHandle): void;
+}