dsh-builtin-browser 0.4.2 → 0.4.6

package/client.js

@@ -19,7 +19,7 @@ window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) =>
 
   const react = require("react")
   const h = react.createElement
-  const { useCallback, useEffect, useState } = react
+  const { useCallback, useEffect, useRef, useState } = react
 
   const name = "dsh-builtin-browser"
   const inject = ["slots", "locale"]
@@ -58,7 +58,8 @@ window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) =>
     "credentials.allowRead": "允许 Agent 读取 cookies / 导出登录状态",
     "browser.title": "浏览器载体",
     "browser.channel": "使用哪个浏览器",
-    "browser.bundled": "内置 Electron(随插件提供,无需安装)",
+    "browser.sidebar": "侧栏浏览器(在 DSH 窗口右侧打开,不额外拉窗口)",
+  "browser.bundled": "内置 Electron(随插件提供,无需安装)",
     "browser.chrome": "本机 Chrome",
     "browser.edge": "本机 Edge",
     "browser.auto": "自动(优先 Chrome,其次 Edge)",
@@ -105,7 +106,8 @@ window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) =>
     "credentials.allowRead": "Allow the agent to read cookies / export login state",
     "browser.title": "Browser",
     "browser.channel": "Which browser to use",
-    "browser.bundled": "Bundled Electron (ships with the plugin, nothing to install)",
+  "browser.sidebar": "Sidebar browser (opens in the DSH window right pane; no extra window)",
+  "browser.bundled": "Bundled Electron (ships with the plugin, nothing to install)",
     "browser.chrome": "Installed Chrome",
     "browser.edge": "Installed Edge",
     "browser.auto": "Automatic (Chrome first, then Edge)",
@@ -137,26 +139,219 @@ window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) =>
     return data
   }
 
+  /**
+   * The panel's own stylesheet.
+   *
+   * Inline styles cannot express `:hover`, and the rows need one — an interactive row with no
+   * feedback reads as decoration. The colours come from DSH's own design tokens
+   * (`--dsw-alias-*`, the same ones the host's settings rows use) so this follows the active
+   * theme instead of guessing at it; each has a literal fallback because a token may be absent
+   * under a third-party theme, and an unstyled row is worse than a slightly-off one.
+   */
+  const CSS = `
+.dsh-bb-row {
+  border-radius: 8px;
+  padding: 7px 9px;
+  color: var(--dsw-alias-label-primary, inherit);
+  transition: background-color .12s ease;
+}
+/* No resting background: a permanent grey block behind every row reads as a set of buttons
+   rather than a list of settings. The highlight belongs to the pointer, not to the row. */
+.dsh-bb-row:hover {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.15));
+}
+.dsh-bb-row:active {
+  background: var(--dsw-alias-interactive-bg-active, rgba(128,128,128,.22));
+}
+.dsh-bb-row:focus-within {
+  border-color: var(--dsw-alias-border-l2, rgba(128,128,128,.4));
+}
+/* The dropdown is drawn here rather than by the OS.
+   A native <select> paints its popup with system colours on Windows: the highlight overrides
+   whatever the option sets (white text on a white bar), and the list carries a border no CSS
+   can remove. Only the collapsed control is styleable, so a panel that matches its theme
+   everywhere else ends up with one control that does not. Everything below is ours: the
+   surface, the highlight, and the absence of that line. */
+.dsh-bb-dd {
+  position: relative;
+  display: inline-block;
+  margin-top: 4px;
+}
+.dsh-bb-dd-btn {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  max-width: 100%;
+  padding: 4px 8px 4px 9px;
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.4));
+  border-radius: 6px;
+  background: var(--dsw-alias-bg-layer-2, rgba(128,128,128,.12));
+  color: var(--dsw-alias-label-primary, inherit);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+.dsh-bb-dd-btn:hover:not(:disabled) {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.18));
+}
+.dsh-bb-dd-btn:disabled { opacity: .55; cursor: default; }
+.dsh-bb-dd-caret { opacity: .6; font-size: 10px; line-height: 1; }
+.dsh-bb-dd-list {
+  position: absolute;
+  z-index: 20;
+  top: calc(100% + 4px);
+  left: 0;
+  min-width: 100%;
+  max-width: 340px;
+  padding: 4px;
+  border: 1px solid var(--dsw-alias-border-l2, rgba(128,128,128,.4));
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-layer-2, #2f2f2f);
+  box-shadow: 0 6px 20px rgba(0,0,0,.28);
+}
+.dsh-bb-dd-opt {
+  display: block;
+  width: 100%;
+  padding: 6px 9px;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary, inherit);
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+/* The same ellipse the rows use, so the panel reads as one surface — and it is ours to draw,
+   which is the whole reason this control exists. */
+.dsh-bb-dd-opt:hover,
+.dsh-bb-dd-opt[data-active="true"] {
+  background: var(--dsw-alias-interactive-bg-hover, rgba(128,128,128,.18));
+}
+.dsh-bb-dd-opt[aria-selected="true"] { font-weight: 600; }
+`
+
+  /** Install the stylesheet once, however many times the panel is mounted. */
+  function installStyles() {
+    if (typeof document === "undefined") return
+    if (document.getElementById("dsh-builtin-browser-styles") !== null) return
+    const tag = document.createElement("style")
+    tag.id = "dsh-builtin-browser-styles"
+    tag.textContent = CSS
+    document.head.appendChild(tag)
+  }
+
   const styles = {
     wrap: { display: "flex", flexDirection: "column", gap: "14px", padding: "4px 2px", fontSize: "13px" },
     lead: { opacity: 0.75, lineHeight: 1.6, margin: 0 },
     group: { border: "1px solid rgba(128,128,128,.28)", borderRadius: "8px", padding: "10px 12px" },
     groupTitle: { margin: "0 0 8px", fontSize: "13px", fontWeight: 600 },
-    row: { display: "flex", gap: "10px", alignItems: "flex-start", padding: "5px 0" },
+    row: { display: "flex", gap: "10px", alignItems: "flex-start" },
     box: { marginTop: "2px" },
     label: { display: "flex", flexDirection: "column", gap: "2px", cursor: "pointer" },
     hint: { opacity: 0.68, lineHeight: 1.5 },
-    select: { marginTop: "4px", padding: "4px 6px", borderRadius: "6px", background: "transparent", color: "inherit", border: "1px solid rgba(128,128,128,.4)" },
     status: { opacity: 0.7, minHeight: "18px" },
     error: { color: "#e5534b" },
     pathLine: { opacity: 0.6, wordBreak: "break-all", lineHeight: 1.5 },
     button: { padding: "3px 10px", borderRadius: "6px", border: "1px solid rgba(128,128,128,.4)", background: "transparent", color: "inherit", cursor: "pointer" },
   }
 
+  /**
+   * A dropdown drawn by this panel rather than by the operating system.
+   *
+   * Replaces a native `<select>`, whose popup Windows paints with system colours: the hover
+   * highlight overrode the option's background (white text on a white bar) and the list carried
+   * a border no CSS could remove. Both are unfixable from outside the control, and this panel's
+   * two dropdowns were the only places it did not match its own theme.
+   *
+   * Keyboard and assistive-technology behaviour is reimplemented rather than inherited, which is
+   * the cost of owning the rendering: Up/Down move, Enter/Space commit, Escape closes and
+   * returns focus, Home/End jump, clicking outside closes.
+   */
+  function Dropdown(props) {
+    const [open, setOpen] = useState(false)
+    // Index the keyboard has moved to; -1 means "the selected value, unless the user moved".
+    const [active, setActive] = useState(-1)
+    const rootRef = useRef(null)
+    const buttonRef = useRef(null)
+
+    const selected = props.options.findIndex(option => option.value === props.value)
+    const current = props.options[selected] ?? props.options[0]
+
+    useEffect(() => {
+      if (!open) return undefined
+      const away = event => {
+        if (rootRef.current !== null && !rootRef.current.contains(event.target)) setOpen(false)
+      }
+      document.addEventListener("mousedown", away)
+      return () => document.removeEventListener("mousedown", away)
+    }, [open])
+
+    const commit = index => {
+      const option = props.options[index]
+      if (option === undefined) return
+      setOpen(false)
+      setActive(-1)
+      buttonRef.current?.focus()
+      if (option.value !== props.value) props.onChange(option.value)
+    }
+
+    const onKeyDown = event => {
+      if (event.key === "Escape") {
+        if (open) { event.preventDefault(); setOpen(false); buttonRef.current?.focus() }
+        return
+      }
+      if (!open && (event.key === "Enter" || event.key === " " || event.key === "ArrowDown")) {
+        event.preventDefault()
+        setOpen(true)
+        setActive(selected >= 0 ? selected : 0)
+        return
+      }
+      if (!open) return
+      const last = props.options.length - 1
+      if (event.key === "ArrowDown") { event.preventDefault(); setActive(a => Math.min(last, (a < 0 ? selected : a) + 1)) }
+      else if (event.key === "ArrowUp") { event.preventDefault(); setActive(a => Math.max(0, (a < 0 ? selected : a) - 1)) }
+      else if (event.key === "Home") { event.preventDefault(); setActive(0) }
+      else if (event.key === "End") { event.preventDefault(); setActive(last) }
+      else if (event.key === "Enter" || event.key === " ") { event.preventDefault(); commit(active < 0 ? selected : active) }
+    }
+
+    return h("div", { key: "s", className: "dsh-bb-dd", ref: rootRef }, [
+      h("button", {
+        key: "b",
+        type: "button",
+        ref: buttonRef,
+        className: "dsh-bb-dd-btn",
+        disabled: props.disabled,
+        "aria-haspopup": "listbox",
+        "aria-expanded": open ? "true" : "false",
+        onClick: () => { setOpen(o => !o); setActive(-1) },
+        onKeyDown,
+      }, [
+        h("span", { key: "v" }, current === undefined ? "" : current.label),
+        h("span", { key: "c", className: "dsh-bb-dd-caret", "aria-hidden": "true" }, "\\u25be"),
+      ]),
+      open ? h("div", {
+        key: "l",
+        className: "dsh-bb-dd-list",
+        role: "listbox",
+        "aria-label": props.label,
+      }, props.options.map((option, index) => h("button", {
+        key: option.value,
+        type: "button",
+        className: "dsh-bb-dd-opt",
+        role: "option",
+        "aria-selected": option.value === props.value ? "true" : "false",
+        "data-active": index === active ? "true" : "false",
+        onMouseEnter: () => setActive(index),
+        onClick: () => commit(index),
+      }, option.label))) : null,
+    ])
+  }
+
   /** One boolean switch bound to a settings path. */
   function Toggle(props) {
     const t = translate
-    return h("div", { style: styles.row }, [
+    return h("div", { style: styles.row, className: "dsh-bb-row" }, [
       h("input", {
         key: "i",
         type: "checkbox",
@@ -277,40 +472,43 @@ window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) =>
       ]),
 
       section("vision.title", [
-        h("div", { key: "row", style: styles.row }, [
+        h("div", { key: "row", style: styles.row, className: "dsh-bb-row" }, [
           h("label", { key: "l", style: styles.label }, [
             h("span", { key: "t" }, t("vision.strategy")),
-            h("select", {
+            h(Dropdown, {
               key: "s",
-              style: styles.select,
+              label: t("vision.strategy"),
               value: settings.vision.strategy,
               disabled: busy,
-              onChange: event => patch({ vision: { strategy: event.target.value } }),
-            }, [
-              h("option", { key: "auto", value: "auto" }, t("vision.auto")),
-              h("option", { key: "nonVisual", value: "nonVisual" }, t("vision.nonVisual")),
-            ]),
+              onChange: value => patch({ vision: { strategy: value } }),
+              options: [
+                { value: "auto", label: t("vision.auto") },
+                { value: "nonVisual", label: t("vision.nonVisual") },
+              ],
+            }),
             h("span", { key: "h", style: styles.hint }, t("vision.hint")),
           ]),
         ]),
       ]),
 
       section("browser.title", [
-        h("div", { key: "row", style: styles.row }, [
+        h("div", { key: "row", style: styles.row, className: "dsh-bb-row" }, [
           h("label", { key: "l", style: styles.label }, [
             h("span", { key: "t" }, t("browser.channel")),
-            h("select", {
+            h(Dropdown, {
               key: "s",
-              style: styles.select,
+              label: t("browser.channel"),
               value: settings.browser.channel,
               disabled: busy,
-              onChange: event => patch({ browser: { channel: event.target.value } }),
-            }, [
-              h("option", { key: "bundled", value: "bundled" }, t("browser.bundled")),
-              h("option", { key: "auto", value: "auto" }, t("browser.auto")),
-              h("option", { key: "chrome", value: "chrome" }, t("browser.chrome")),
-              h("option", { key: "edge", value: "edge" }, t("browser.edge")),
-            ]),
+              onChange: value => patch({ browser: { channel: value } }),
+              options: [
+                { value: "sidebar", label: t("browser.sidebar") },
+                { value: "bundled", label: t("browser.bundled") },
+                { value: "auto", label: t("browser.auto") },
+                { value: "chrome", label: t("browser.chrome") },
+                { value: "edge", label: t("browser.edge") },
+              ],
+            }),
             h("span", { key: "h", style: styles.hint }, t("browser.hint")),
           ]),
         ]),
@@ -365,7 +563,218 @@ window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) =>
     ])
   }
 
+  // ===========================================================================
+  // Conversation panel service: the one place a sidebar panel is opened.
+  //
+  // The shell mounts one right sidebar per conversation, and DSH's own sidebar
+  // browser keeps that conversation's tabs and its webview guest inside it.
+  // `ctx.sidebarRight.openTab` acts on the conversation the shell is SHOWING
+  // (`mounted`), so every path that simulated a shortcut or clicked a card put
+  // the page into whichever conversation the human happened to be reading —
+  // that is the cross-conversation bleed, and it is a property of the path, not
+  // an accident of it.
+  //
+  // `openTabIn(sessionId, …)` is the same navigation aimed at a NAMED
+  // conversation, and it works for one that is not on screen. This service is
+  // the only caller; the plugin's host half reaches it by evaluating
+  // `globalThis.__dshBuiltinBrowser.openPanel(...)` inside the shell window, so
+  // no input event, no key dispatch and no element click is involved.
+  //
+  // Guest identity is read from the panel's own `<webview>` and only inside the
+  // subtree found for THAT conversation — never from the first match in the
+  // document, which belongs to somebody else's panel.
+  // ===========================================================================
+
+  /** The conversation a sidebar element belongs to, read off its React fiber. */
+  function sessionIdOfElement(element) {
+    const key = Object.keys(element).find(
+      name => name.startsWith("__reactFiber$") || name.startsWith("__reactInternalInstance$"),
+    )
+    if (key === undefined) return null
+    let fiber = element[key]
+    let depth = 0
+    while (fiber !== null && fiber !== undefined && depth < 60) {
+      const props = fiber.memoizedProps
+      if (props !== null && typeof props === "object" && typeof props.sessionId === "string") return props.sessionId
+      fiber = fiber.return
+      depth += 1
+    }
+    return null
+  }
+
+  /**
+   * This conversation's own sidebar strip, or null when the shell has not mounted it.
+   *
+   * Its presence is the precondition `openTabIn` needs: it is minted together with the
+   * conversation's surface store, and a call for a conversation whose store was never
+   * minted silently does nothing. Detecting it here turns that silence into a reason
+   * the caller can report, instead of a page that never appears.
+   */
+  function tabStripFor(sessionId) {
+    for (const strip of Array.from(document.querySelectorAll("[class*=_tabStrip]"))) {
+      if (sessionIdOfElement(strip) === sessionId) return strip
+    }
+    return null
+  }
+
+  /**
+   * Every live `<webview>` guest inside this conversation's panel subtree.
+   *
+   * The walk up stops the moment an ancestor carries ANOTHER conversation's sidebar, and that stop
+   * condition is the whole point of this function. The shell mounts every conversation's panel in
+   * the same document — hidden ones included — so one step too far lands on a subtree that holds
+   * all of them, and the first guest found there belongs to whichever conversation the shell
+   * happens to render first. Measured: a GitHub login page opened in a different conversation was
+   * reported as this one's guest, which is the cross-conversation bleed this service exists to
+   * prevent. A sibling strip is the exact, class-name-independent signature of having stepped
+   * outside; a conversation may legitimately own more than one strip of its own, so the test is
+   * "is there one that is NOT mine", never a count.
+   */
+  function guestsInPanel(sessionId) {
+    const strip = tabStripFor(sessionId)
+    if (strip === null) return []
+    // Start at the strip itself: it is by construction this conversation's own, so the foreign test
+    // below cannot trip on it, and a shell that renders the guest as a sibling of the strip is
+    // still reached.
+    let node = strip
+    while (node !== null && node !== undefined && node !== document.body) {
+      const foreign = Array.from(node.querySelectorAll("[class*=_tabStrip]"))
+        .some(el => sessionIdOfElement(el) !== sessionId)
+      if (foreign) break
+      const found = Array.from(node.querySelectorAll("webview")).filter(view => {
+        try { return typeof view.getWebContentsId === "function" && view.getWebContentsId() > 0 }
+        catch (error) { return false }
+      })
+      if (found.length > 0) return found
+      node = node.parentElement
+    }
+    return []
+  }
+
+  /** Read this conversation's current guest, preferring the one actually drawn. */
+  function guestStateFor(sessionId) {
+    const strip = tabStripFor(sessionId)
+    if (strip === null) return { panel: false, guestId: null, url: "" }
+    const guests = guestsInPanel(sessionId)
+    if (guests.length === 0) return { panel: true, guestId: null, url: "" }
+    // A sidebar keeps every tab mounted (`keepMounted`), so a background tab's guest is
+    // in the tree too. Prefer the one with a drawn box; fall back to the newest.
+    const drawn = guests.find(view => {
+      const rect = view.getBoundingClientRect()
+      return rect.width > 0 && rect.height > 0
+    })
+    const chosen = drawn === undefined ? guests[guests.length - 1] : drawn
+    let url = ""
+    try { url = String(chosen.getURL ? chosen.getURL() : "") } catch (error) { url = "" }
+    try { return { panel: true, guestId: chosen.getWebContentsId(), url } }
+    catch (error) { return { panel: true, guestId: null, url: "" } }
+  }
+
+  /**
+   * Publish the service every host-side panel request goes through.
+   *
+   * The binding is separate from the publication so the API exists from the first
+   * apply — a request arriving before `sidebarRight` is ready gets a named reason
+   * rather than a missing global, which is indistinguishable from a bridge that
+   * never loaded.
+   */
+  function installPanelService(ctx) {
+    let sidebarRight = null
+    // `inject` is how a client plugin waits for a service to appear. A host that does not offer it
+    // — an older composition, or a harness that mounted this bundle for its settings panel alone —
+    // must still get the panel, so the wait is skipped and the published API names the missing
+    // service when it is called. Failing the whole apply here would take the settings panel down
+    // with it, which is exactly the shape of regression this file has been bitten by before.
+    if (typeof ctx.inject === "function") {
+      ctx.inject(["sidebarRight"], (scope) => {
+        sidebarRight = scope.sidebarRight
+        scope.effect(() => () => {
+          if (sidebarRight === scope.sidebarRight) sidebarRight = null
+        }, "dsh-builtin-browser: conversation panel binding")
+      })
+    }
+    const api = {
+      /** @returns what happened: an existing guest, a newly opened tab, or a named refusal. */
+      openPanel(sessionId, url) {
+        const wanted = typeof sessionId === "string" ? sessionId : ""
+        if (!/^session-/.test(wanted)) {
+          return { ok: false, reason: "not a conversation id: " + JSON.stringify(sessionId), panel: false, guestId: null }
+        }
+        if (sidebarRight === null || typeof sidebarRight.openTabIn !== "function") {
+          return { ok: false, reason: "the shell's sidebar service is not available", panel: false, guestId: null }
+        }
+        const state = guestStateFor(wanted)
+        if (state.guestId !== null) {
+          return { ok: true, created: false, panel: true, guestId: state.guestId, url: state.url }
+        }
+        // A mounted panel is NOT required to place a tab.
+        //
+        // `openTabIn` acts on the conversation's own surface store, and the sidebar-right service
+        // keeps one for every conversation the shell has shown — "reaches any session's store by
+        // id … on screen or not". What a DISPLAYED conversation adds is the DOM to read the guest
+        // back out of, which is a separate question. So the tab is placed either way, and `tabsIn`
+        // (a public method) is what says whether it actually landed: `openTabIn` SILENTLY ignores a
+        // conversation whose store was never minted, and a silent no-op must never be reported as
+        // success.
+        let before = 0
+        try { before = sidebarRight.tabsIn(wanted).length } catch (error) { before = 0 }
+        try {
+          sidebarRight.openTabIn(wanted, "browser", url ? { params: { url: String(url) } } : {})
+        } catch (error) {
+          return { ok: false, reason: String((error && error.message) || error), panel: state.panel, guestId: null }
+        }
+        let placed = 0
+        try { placed = sidebarRight.tabsIn(wanted).length } catch (error) { placed = before }
+        // `openTabIn` DEDUPLICATES, so "the count grew" is the wrong test for "is this
+        // conversation's surface mounted".
+        //
+        // Placing a page kind the conversation already holds leaves the count unchanged — the shell
+        // reveals the tab it has. Testing for growth therefore reported a conversation that already
+        // held the page as UNMOUNTED, and refused to drive a page that was right there: that is the
+        // "it will not reopen what it already opened" behaviour, and it bites hardest on the second
+        // open of an address, which is exactly when a human expects a fast answer.
+        //
+        // A count that started at zero and stayed there is the real signature of a surface the
+        // shell has never minted, because that is the only case where `openTabIn` is a silent no-op.
+        if (placed <= before && before === 0) {
+          // Name what was FOUND, not just what was missing: "no panel" has two very different
+          // causes — the shell has mounted no sidebar for this conversation (nothing this side can
+          // do), or it writes its session id somewhere this lookup does not read (fixable) — and a
+          // refusal that says only "not mounted" cannot tell them apart.
+          const strips = Array.from(document.querySelectorAll("[class*=_tabStrip]"))
+          return {
+            ok: false,
+            reason: "this conversation's sidebar is not mounted, so a panel cannot be opened in it",
+            panel: state.panel,
+            guestId: null,
+            found: {
+              wanted: wanted,
+              strips: strips.length,
+              owners: strips.slice(0, 8).map(strip => sessionIdOfElement(strip)),
+              reactKeys: strips.length === 0 ? [] : Object.keys(strips[0]).filter(key => key.startsWith("__react")).slice(0, 4),
+            },
+          }
+        }
+        return { ok: true, created: placed > before, panel: state.panel, guestId: null, tabs: placed }
+      },
+      /** Read-only: this conversation's current guest, if it has one. */
+      panelGuest(sessionId) {
+        return guestStateFor(typeof sessionId === "string" ? sessionId : "")
+      },
+    }
+    ctx.effect(() => {
+      globalThis.__dshBuiltinBrowser = api
+      return () => {
+        if (globalThis.__dshBuiltinBrowser === api) delete globalThis.__dshBuiltinBrowser
+      }
+    }, "dsh-builtin-browser: conversation panel service")
+  }
+
   function apply(ctx) {
+    // Before anything renders: the rows need a hover state, and inline styles cannot express
+    // one. Idempotent, so a re-apply does not stack copies.
+    installStyles()
+    installPanelService(ctx)
     ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-builtin-browser: dictionaries")
     const t = ctx.locale.bind(NS)
     translate = t

package/desktop-bridge/install.mjs

@@ -106,11 +106,31 @@ ${MARKER} pages.
 // Installed by apps/desktop/bridge/install.mjs — re-run it after a desktop upgrade.
 // A bridge failure is never fatal to the shell.
 app.whenReady().then(async () => {
+	const bridgeUrl = new URL("./plugin-browser-bridge.js", import.meta.url);
+	const loadBridge = async (why) => {
+		try {
+			// A plain import is cached for the process lifetime, so an edited bridge
+			// would need a shell restart. The stamp makes every load read the current
+			// bytes; start() itself stops the previous instance, so this reloads in place.
+			const bridge = await import(bridgeUrl.href + "?v=" + Date.now());
+			bridge.start();
+			console.log("[dsh-browser-bridge] started" + (why ? " (" + why + ")" : ""));
+		} catch (error) {
+			console.error("[dsh-browser-bridge] start failed:", error);
+		}
+	};
+	await loadBridge();
+	// Watch the module so an edit reloads it in place instead of forcing a shell
+	// restart. Debounced; a failure here is never fatal to the shell.
 	try {
-		const bridge = await import("./plugin-browser-bridge.js");
-		bridge.start();
+		const { watch } = await import("node:fs");
+		let timer = null;
+		watch(bridgeUrl, { persistent: false }, () => {
+			if (timer) clearTimeout(timer);
+			timer = setTimeout(() => void loadBridge("file changed"), 300);
+		});
 	} catch (error) {
-		console.error("[dsh-browser-bridge] start failed:", error);
+		console.error("[dsh-browser-bridge] watch failed:", error);
 	}
 });
 `
@@ -273,9 +293,49 @@ if (revert) {
     reverted = true
   }
   if (existsSync(backupPath)) {
-    copyFileSync(backupPath, mainPath)
-    console.log(`restored ${mainPath} from ${backupPath}`)
-    reverted = true
+    // Refuse when the backup no longer matches the tree it would overwrite.
+    //
+    // The backup is taken once and then kept, so after a desktop upgrade it holds the PREVIOUS
+    // build's main.js. Restoring it would silently roll the app back to that build's code — and
+    // it would also discard any patch another tool applied in the meantime, which is not a
+    // hypothetical here: `dsh-purge` patches this same file, so a blind revert erases its work
+    // while reporting success. A matching current file is the only case where the restore is
+    // unambiguously right; anything else needs a human to decide.
+    let backedUp
+    let current
+    try {
+      backedUp = readFileSync(backupPath)
+      current = readFileSync(mainPath)
+    } catch {
+      backedUp = undefined
+      current = undefined
+    }
+    const identical = backedUp !== undefined && current !== undefined && backedUp.equals(current)
+    const stillHasOurMarker = current !== undefined && current.includes(MARKER)
+    // A backup taken BEFORE the file was patched by anything else is not a clean restore
+    // point: reverting to it discards those patches. The marker test alone does not catch
+    // this, because the current file legitimately carries our marker — that is exactly what
+    // this script put there — while the backup predates a patch by another tool.
+    // `dsh-purge` patches this same file, so on this machine that is not hypothetical.
+    const backupHasOurMarker = backedUp !== undefined && backedUp.includes(MARKER)
+    if (!identical && stillHasOurMarker && !backupHasOurMarker) {
+      console.error(`WARNING: ${backupPath} predates the bridge patch, so it is not a clean`)
+      console.error(`  restore point for ${mainPath}. Reverting would also discard anything`)
+      console.error('  patched in between (dsh-purge patches this same file). Refreshing the')
+      console.error('  backup from the current file instead, so a later --revert is safe.')
+      writeFileSync(backupPath, current ?? Buffer.alloc(0))
+      reverted = true
+    } else if (!identical && !stillHasOurMarker) {
+      console.error(`WARNING: ${mainPath} has changed since the backup was taken, and it does`)
+      console.error('  not contain the bridge import either — something else has edited it')
+      console.error('  (a desktop upgrade, or another patch tool). Restoring the backup would')
+      console.error(`  discard that. The backup is at ${backupPath}; restore it by hand if that`)
+      console.error('  is what you want. Skipping this file.')
+    } else {
+      copyFileSync(backupPath, mainPath)
+      console.log(`restored ${mainPath} from ${backupPath}`)
+      reverted = true
+    }
   }
   if (existsSync(cliShimBackup)) {
     copyFileSync(cliShimBackup, cliShimPath)