summrise-agent 1.2.511 → 1.2.512

package/README.md

@@ -22,6 +22,14 @@ npm i -g https://agent.saisi.online/summrise-agent/summrise-agent-latest.tgz
 summrise setup --reg-key <key-from-console>   # --reg-key is optional (local mode works without it)
 ```
 
+**ON A DEVICE THE INSTALLER SET UP, A HAND INSTALL MUST PASS `--prefix`.** `agent/deploy/summrise-online-setup.ps1`
+does exactly that — `npm install -g --prefix $NpmGlobal $tgz`, where `$NpmGlobal` is `<install dir>\components\npm-global`
+("Layout v2"; it was `tools\npm-global` before that) — and puts that directory on `PATH`. **A bare `npm i -g` lands in
+npm's DEFAULT global prefix instead**, which is not where the running agent looks, so the install succeeds and nothing
+changes. The layout is the one thing to keep in step, and `summrise update` prints the right prefix for an existing
+device rather than making anyone derive it.
+
+
 **Run `setup` from an elevated PowerShell.** The install directory is under `Program Files` and the registry key is
 `HKLM`, so a normal shell fails with `EPERM: operation not permitted, mkdir 'C:\Program Files\Summrise\scripts'` —
 a stack trace where the useful sentence is "run it as administrator".
@@ -47,6 +55,11 @@ npm i -g --prefix (Split-Path (Get-Command summrise).Source) https://agent.saisi
 summrise update
 ```
 
+**YOU DO NOT HAVE TO COMPUTE THAT PREFIX — THE CLI PRINTS IT.** When `summrise update` refuses because the running
+CLI is older than the release channel, it answers with the exact command for THIS device, prefix included, computed from
+where the CLI is running (`Split-Path (Get-Command summrise).Source`, asked of the process that IS that binary). The
+`--prefix` in the block above is what it prints; the paragraph below is why it matters.
+
 **The `--prefix` is not optional on a device that is already set up.** Plain
 `npm i -g <url>` installs into npm's DEFAULT global prefix, which is not where
 `summrise` lives when the agent runs as SYSTEM. On a real device the two prefixes

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "summrise-agent",
-  "version": "1.2.511",
+  "version": "1.2.512",
   "description": "Summrise Agent — Windows device MCP server (terminal/SSH/serial) + panel. Self-hosted npm distribution.",
-  "//build": "唯一构建路径：在本目录执行 npm run build。它是自包含的：经 npm exec 按需拉取 typescript@5，无需预装任何 node_modules（干净检出可跑；旧脚本引用 ../summrise-desktop-electron/node_modules/.bin/tsc，干净检出必 ENOENT）。必须用 npm exec --package … -- tsc 的形式：npx 会吃掉传给 tsc 的 -p/--outDir 等参数（round-435：npx 写法从未真正跑通过）。 LANDING 4b: the CLI IS A RUST BINARY NOW (bin/summrise.exe, built by `cargo xwin build -p summrise-cli` and staged by scripts/build.sh) — nothing here compiles it, and src/summrise.ts + bin/summrise.js are DELETED. This script therefore only compiles the electron TS (--noCheck pure emit, same as release.yml) and syncs both src/*.js copies. LANDING 6: the desktop shell's URL/certificate policy is Rust compiled to wasm. summrise_url_policy.js and summrise_url_policy_bg.wasm are NOT built here — agent/summrise-url-policy/build.sh produces them (wasm-pack) and they are committed — this script only COPIES the committed pair into the package's own summrise-desktop-electron/src/, the way it does for main.js/preload.js, so that npm pack carries what the shell requires.",
+  "//build": "THE ONLY BUILD PATH: run npm run build in this directory. It is self-contained: it pulls typescript@5 on demand through npm exec, with no preinstalled node_modules (so it runs in a clean checkout; the old script referenced ../summrise-desktop-electron/node_modules/.bin/tsc, which is always ENOENT in a clean checkout). It MUST use the `npm exec --package … -- tsc` form: npx swallows the -p/--outDir arguments passed to tsc (round-435: the npx form never actually ran). LANDING 4b: the CLI IS A RUST BINARY NOW (bin/summrise.exe, built by `cargo xwin build -p summrise-cli` and staged by scripts/build.sh) — nothing here compiles it, and src/summrise.ts + bin/summrise.js are DELETED. This script therefore only compiles the electron TS (--noCheck pure emit, same as release.yml) and syncs both src/*.js copies. LANDING 6: the desktop shell's URL/certificate policy is Rust compiled to wasm. summrise_url_policy.js and summrise_url_policy_bg.wasm are NOT built here — agent/summrise-url-policy/build.sh produces them (wasm-pack) and they are committed — this script only COPIES the committed pair into the package's own summrise-desktop-electron/src/, the way it does for main.js/preload.js, so that npm pack carries what the shell requires.",
   "bin": {
     "summrise": "bin/summrise.exe"
   },
@@ -12,6 +12,8 @@
     "summrise-agent.exe",
     "summrise-launch.exe",
     "summrise-desktop-electron/src/main.js",
+    "summrise-desktop-electron/src/embedded-slot.js",
+    "summrise-desktop-electron/src/browser-sessions.js",
     "summrise-desktop-electron/src/preload.js",
     "summrise-desktop-electron/src/summrise_url_policy.js",
     "summrise-desktop-electron/src/summrise_url_policy_bg.wasm",
@@ -28,6 +30,6 @@
   ],
   "license": "MIT",
   "scripts": {
-    "build": "npm exec --yes --package typescript@5.9.3 -- tsc -p ../summrise-desktop-electron/tsconfig.json --outDir /tmp/summrise-electron-fresh --noCheck && cp /tmp/summrise-electron-fresh/main.js ../summrise-desktop-electron/src/main.js && cp /tmp/summrise-electron-fresh/preload.js ../summrise-desktop-electron/src/preload.js && cp ../summrise-desktop-electron/src/main.js ../summrise-desktop-electron/src/preload.js ../summrise-desktop-electron/src/summrise_url_policy.js ../summrise-desktop-electron/src/summrise_url_policy_bg.wasm ../summrise-desktop-electron/src/summrise_shell_policy.js ../summrise-desktop-electron/src/summrise_shell_policy_bg.wasm ./summrise-desktop-electron/src/ && rm -rf /tmp/summrise-electron-fresh"
+    "build": "npm exec --yes --package typescript@5.9.3 -- tsc -p ../summrise-desktop-electron/tsconfig.json --outDir /tmp/summrise-electron-fresh --noCheck && cp /tmp/summrise-electron-fresh/main.js ../summrise-desktop-electron/src/main.js && cp /tmp/summrise-electron-fresh/embedded-slot.js ../summrise-desktop-electron/src/embedded-slot.js && cp /tmp/summrise-electron-fresh/browser-sessions.js ../summrise-desktop-electron/src/browser-sessions.js && cp /tmp/summrise-electron-fresh/preload.js ../summrise-desktop-electron/src/preload.js && cp ../summrise-desktop-electron/src/main.js ../summrise-desktop-electron/src/embedded-slot.js ../summrise-desktop-electron/src/browser-sessions.js ../summrise-desktop-electron/src/preload.js ../summrise-desktop-electron/src/summrise_url_policy.js ../summrise-desktop-electron/src/summrise_url_policy_bg.wasm ../summrise-desktop-electron/src/summrise_shell_policy.js ../summrise-desktop-electron/src/summrise_shell_policy_bg.wasm ./summrise-desktop-electron/src/ && rm -rf /tmp/summrise-electron-fresh"
   }
 }

package/summrise-desktop-electron/src/browser-sessions.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserSessionsBind = browserSessionsBind;
+exports.browserOpen = browserOpen;
+exports.browserClose = browserClose;
+exports.browserList = browserList;
+exports.browserCloseAll = browserCloseAll;
+// ── Browser-session windows: the cluster that owns them (round-247) ────────────────────────────
+// `main.ts`'s browser-session section, moved out whole: the three operations an AI drives over IPC or
+// the loopback control server (`browserOpen`, `browserClose`, `browserList`), the session table they
+// read and write, and the shutdown sweep that closes it. What those operations DECIDE is not here, and
+// never was: the reuse/evict plan is `agent/summrise-shell-policy`'s (`planBrowserOpen`), the window id
+// is its `browserId`, the CDP endpoint they advertise is its `cdpEndpoint`, and the cap is its
+// `MAX_BROWSER_WINDOWS`. This file applies those answers to real `BrowserWindow`s.
+//
+// ── WHY THIS IS A FILE OF ITS OWN, AND THE THREE THINGS IT DOES NOT OWN ────────────────────────
+// The survey that found it measured that nothing here touches `tray`, `Tray`, `Menu`, `mainWindow`,
+// `ipcMain` or the `win` variable — and it also measured what a survey of NAMES misses: the section has
+// THREE dependencies on `main.ts`, and they are why this file takes a seam rather than an import.
+//   * the ONE load door (`loadTarget`) — `main.ts`'s single call site of the URL policy's
+//     `sanitizeBrowserUrl`. Every URL a session window opens must go through it, never around it.
+//   * the window icon (`windowIcon`) — the shell's own resolution of `windowIconName()` against the
+//     install tree, which is `main.ts`'s business (it records what it resolved for
+//     `/api/shell/icon-status`) and is shared with the main window.
+//   * the window cap (`maxBrowserWindows`) — `K.MAX_BROWSER_WINDOWS`, the boot table `main.ts` parses
+//     once from the policy crate. One number, fixed at boot: a VALUE, not a getter.
+// Importing any of the three from `main.ts` would make `main.ts` require this module and this module
+// require `main.ts`: a cycle whose failure mode is a half-initialised module rather than an error. So
+// `main.ts` binds all three ONCE (`browserSessionsBind`) and this module reads them through `deps()`.
+//
+// THE IPC REGISTRATIONS DELIBERATELY DID NOT MOVE WITH IT. They go through `main.ts`'s ONE door
+// (`ipcHandle`, which applies the frame check and is the file's only `ipcMain.handle` call), and the
+// channel set is pinned against the preload's by `test/ipc-door.test.mjs`. A handler registered here
+// would be a second door, so `main.ts` keeps the three `ipcHandle("browser-session:…")` lines and calls
+// in — and with them the THREE other call sites the section always had: the loopback control server's
+// `browser-open`/`browser-close`/`browser-list` routes (the SPA in a plain browser) and the main
+// window's `setWindowOpenHandler`, which routes a `target=_blank` from the panel to a sandboxed session
+// instead of a preload-bearing window.
+const electron_1 = require("electron");
+const summrise_shell_policy_1 = require("./summrise_shell_policy");
+/** The CDP port every session window is advertised on. Read from the SAME boot table `main.ts` parses,
+ *  rather than bound: it is a policy constant, not host state — `main.ts` does not own 9333, it passes
+ *  it to `--remote-debugging-port` and `agent/summrise-shell-policy`'s `boot.rs` defines it. Bound state
+ *  is for what the host OWNS; a second reader of the crate's table is not a second decision. */
+const CDP_PORT = JSON.parse((0, summrise_shell_policy_1.shellConstants)()).CDP_PORT;
+let bound = null;
+/** Called ONCE by `main.ts`, before any `browser-session:*` channel can be invoked. */
+function browserSessionsBind(host) { bound = host; }
+function deps() {
+    // LOUD, not silent: an unbound host would otherwise open a window on a fallback URL, with no icon and
+    // no cap — the failures a reader would have to reconstruct from a browser that went to the wrong page.
+    if (!bound)
+        throw new Error("browser-sessions: browserSessionsBind() was never called — main.ts binds the shell's load door, its window icon and its session cap at startup");
+    return bound;
+}
+const browserSessions = new Map();
+/** Initial target per browser window — reuse matching uses this instead of
+ *  webContents.getURL() (which lags during navigation; stage-n). */
+const browserTargets = new Map();
+/** Open a browser-session window on a decided load target (loadTarget() is the
+ *  ONE load door — the scheme policy lives there). */
+function browserOpen(url) {
+    const target = deps().loadTarget(url);
+    // stage-n: reuse an existing window on the same URL instead of stacking duplicates (AI-driven
+    // browsing opens/closes sessions repeatedly). Match against the window's INITIAL target (stored at
+    // open) — webContents.getURL() lags during navigation (returns about:blank while loading), so a
+    // same-URL reopen right after the first open would otherwise miss the reuse and stack a duplicate.
+    //
+    // THE PLAN IS THE POLICY CRATE'S, in one call: which window to reuse (first non-destroyed match, in
+    // INSERTION order), and — when the cap is reached — which one to evict (the OLDEST, not the least
+    // recently used). This file only reads the session table and applies the answer. The `destroyed` flag
+    // travels with the row because a destroyed window is skipped for reuse while still COUNTING against
+    // the cap, which is what `browserSessions.size` did.
+    const plan = JSON.parse((0, summrise_shell_policy_1.planBrowserOpen)(JSON.stringify([...browserSessions].map(([id, bw]) => ({ id, target: browserTargets.get(id) ?? "", destroyed: bw.isDestroyed() }))), target, deps().maxBrowserWindows));
+    if (plan.reuse) {
+        const existing = browserSessions.get(plan.reuse);
+        if (existing) {
+            if (existing.isMinimized())
+                existing.restore();
+            existing.show();
+            existing.focus();
+            return { ok: true, id: plan.reuse, url: target, cdp: (0, summrise_shell_policy_1.cdpEndpoint)(CDP_PORT) };
+        }
+    }
+    if (plan.evict)
+        browserClose(plan.evict);
+    const id = (0, summrise_shell_policy_1.browserId)(Date.now());
+    const bw = new electron_1.BrowserWindow({
+        width: 1100, height: 750, title: `Summrise Browser — ${target}`,
+        ...(deps().windowIcon() ? { icon: deps().windowIcon() } : {}),
+        // review #6/#7: these windows load ARBITRARY internet pages. contextIsolation
+        // on + nodeIntegration off + NO preload = zero Node/bridge surface (the
+        // default; made explicit). Popups are denied (they would otherwise spawn
+        // unmanaged windows outside the MAX_BROWSER_WINDOWS cap).
+        webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
+    });
+    bw.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
+    bw.loadURL(target);
+    bw.on("closed", () => { browserSessions.delete(id); browserTargets.delete(id); });
+    // stage-n: the window title starts as "Summrise Browser — <target>" but a
+    // site's own <title> is more useful after load (and after in-page
+    // navigation); follow it so window managers/taskbar show the real page.
+    bw.webContents.on("page-title-updated", (_e, title) => {
+        if (!bw.isDestroyed() && title)
+            bw.setTitle(`Summrise Browser — ${title}`);
+    });
+    browserSessions.set(id, bw);
+    browserTargets.set(id, target);
+    return { ok: true, id, url: target, cdp: (0, summrise_shell_policy_1.cdpEndpoint)(CDP_PORT) };
+}
+function browserClose(id) {
+    const bw = browserSessions.get(id || "");
+    // review #g: close() is vetoable by a page's beforeunload — an arbitrary
+    // remote page could refuse eviction, so the MAX_BROWSER_WINDOWS cap never
+    // freed and browserOpen stalled. destroy() is unconditional (these are
+    // disposable, headless-driven windows).
+    if (bw) {
+        bw.destroy();
+        browserSessions.delete(id || "");
+        browserTargets.delete(id || "");
+    }
+    return { ok: true };
+}
+function browserList() {
+    const list = [...browserSessions.entries()].map(([id, bw]) => ({ id, url: bw.webContents.getURL() }));
+    return { ok: true, sessions: list, cdp: (0, summrise_shell_policy_1.cdpEndpoint)(CDP_PORT) };
+}
+/** stage-n: close every browser-session window explicitly — app.quit()
+ *  tears down the main window but independent BrowserWindows with pending
+ *  beforeunload handlers can stall or leak on exit. The table is THIS file's state, so the sweep over it
+ *  is too: `main.ts`'s `before-quit` handler calls in, the way it calls the three operations above. */
+function browserCloseAll() {
+    for (const [id, bw] of browserSessions) {
+        if (!bw.isDestroyed())
+            bw.destroy();
+        browserSessions.delete(id);
+        browserTargets.delete(id);
+    }
+}

package/summrise-desktop-electron/src/embedded-slot.js

@@ -0,0 +1,347 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embeddedSlot = embeddedSlot;
+// ── ONE EMBEDDED SLOT, INSTANTIATED TWICE ──────────────────────────────────────────────────────
+// The shell embeds TWO native `WebContentsView`s over the SPA's placeholders: the real-render BROWSER
+// view (an internet browser an AI also drives over CDP) and the DSH view (the operator's own harness on
+// loopback). They arrived here as two modules — `embedded-view.ts` and `dsh-view.ts` — that a
+// function-by-function comparison (`docs/agents/ideas.md`, round 111) measured to be near-copies of one
+// pattern: the same eight twinned operations (`bind`/`deps`/`ensure`/`place`/`navigate`/`reload`/
+// `recover`/`state`), the same three slot-state bindings, and ELEVEN occurrences of
+// `setVisible`/`setBounds`/`addChildView`/`removeChildView` on each side. This file is that pattern,
+// ONCE, as a factory: `embeddedSlot(config)` returns one slot's functions, and `main.ts` builds both
+// instances from it.
+//
+// ── WHAT IS A PARAMETER, AND WHY EACH ONE CANNOT BE MERGED AWAY ────────────────────────────────
+//   * `door` — the ONE load door for this slot: `loadTarget` (the url policy's `sanitizeBrowserUrl`,
+//     admitting any http/https) for the browser, `dshTargetFor` (its own loopback origin, or nothing)
+//     for the DSH. Forced by the crate split: the two policy crates must not depend on each other, so
+//     shell-policy takes the ANSWER of url-policy's predicate. Merging them would either expose the
+//     internet to the DSH's `window.open` or confine the browser view to loopback.
+//   * `popupTarget` — the `target=_blank` decision, over the same split as `door`:
+//     `embeddedPopupTarget(door(raw))` for the browser (its argument is the DECIDED target, and a
+//     refusal is DROPPED rather than collapsed to `about:blank`, so a refused link cannot erase the page
+//     being read) against `dshPopupTarget(raw, isDshUrl(raw))` for the DSH.
+//   * `recoverUrl(lastDecided)` — what a crashed view is reloaded with: the browser's `embeddedRecoverUrl`
+//     (the last DECIDED url, `about:blank` as the fallback, because "recovering a crashed view must not
+//     make a request to a search engine to do it") against the DSH's `dshHome(base)` ("a crash recovery
+//     that lands somewhere other than the harness is a view the operator did not ask for").
+//   * `stateUrl(live, lastDecided)` — the `url` field of `state()`. The browser's address bar must never
+//     go blank, so it answers the last decided url when its view cannot (`shownUrl`); the DSH's record
+//     must not report a dead object's last url, so it answers "" (`shownUrl(live, "")`). This is a
+//     FINDING rather than one of the four load-bearing differences above: the two modules differed here
+//     by accident of their callers, and merging it either way would change one pane's contract.
+//   * `goneChannel` — `embedded-browser:gone` / `embedded-dsh:gone`. The signal is the same on both
+//     sides (a renderer that died must not leave the pane saying "starting…" forever); only the channel
+//     name differs, and the names are pinned by the preload/panel fixtures.
+//   * `navChannel?` — present ONLY for the browser: it brings the three navigation pushes
+//     (`did-navigate`, `did-navigate-in-page`, `page-title-updated`), the `canBack`/`canFwd` fields of
+//     `state()`, and the `go`/`zoom` operations. The DSH has no history surface, so adding them there
+//     would be uncalled surface (and a channel the preload does not expose would fail the channel-set
+//     equality in `test/ipc-door.test.mjs`).
+//
+// ── WHAT IS DELIBERATELY NOT A PARAMETER, AND WHY ──────────────────────────────────────────────
+// THE LIFECYCLE AND THE STARTUP NAVIGATION ARE CALLER BEHAVIOURS. The browser slot is created EAGERLY at
+// startup, hidden, and never navigated (an attached AI always has an `about:blank` CDP target; it used
+// to load `bing.com` on every launch) — `main.ts` calls `ensure()` from `app.whenReady()`. The DSH slot
+// is created LAZILY by the pane's `open()` and navigated home — `main.ts`'s `dshOpen()` is
+// `slot.navigate(dshHome(dshBase()))`, and `navigate()` is what creates the view. Neither belongs in a
+// parameter of `ensure()`: a flag here would let one caller ask for the other's lifecycle by accident.
+// `main.ts` also keeps `bootDshPort`, `dshTargetFor`, `loadHarnessDoors`, `dshOpen` and EVERY
+// `ipcHandle(...)` registration, because the shell holds the ONE `ipcMain.handle` door.
+//
+// A POLICY THAT IS THE SAME FOR BOTH SLOTS STAYS AN IMPORT, not a parameter: the minimum slot
+// (`slotTooSmall`), the visible conjunction (`viewVisible`), the history sign (`goBackwards`) and the
+// zoom clamp (`zoomFactor`) are the shell policy crate's answers and are identical for the two views.
+// Only what DIFFERS travels as a parameter.
+//
+// ── FIVE THINGS THE TWO IMPLEMENTATIONS DISAGREED ABOUT THAT WERE NOT IN THE LIST ABOVE ────────
+// Each was decided here explicitly rather than inherited from whichever side happened to be copied:
+//   1. THE RE-SHOW AFTER A CRASH. Both `recover()`s contained a "re-show if the slot is live" block that
+//      could never run: `ensure()` — which recovery has just called to build the fresh view — clears the
+//      visible flag first. It is FIXED here rather than deleted: the block's own comment states its
+//      purpose ("kept so a renderer-crash recovery can re-show the fresh view at the same spot without
+//      waiting for the SPA"), the retained bounds exist for exactly that, and the fix makes the slot's
+//      record agree with its screen (the flag is restored, so `state().visible` is true when the fresh
+//      view is shown). It is not a new always-on behaviour: after a REAL crash the `gone` handler has
+//      already cleared the flag, so the SPA's next `place()` still shows the view — this only covers a
+//      recovery invoked without that event (an explicit recover, or a stalled renderer).
+//   2. `ensure()` WAS EXPORTED BY ONE MODULE AND PRIVATE IN THE OTHER. The slot exposes it for both: it
+//      is the browser's eager-creation hook, and the difference is which CALLER calls it, not what it
+//      does. The DSH's instance is simply never asked.
+//   3. THE PERMISSION HANDLERS. The browser's `ensure()` installed deny-by-default request/check
+//      handlers on the session; the DSH's installed none. Both instances install them now: the DSH is
+//      still a whole web application on loopback, and the DSH's own suite already called the posture it
+//      lacked "the browser view's security posture". The calls are idempotent and inside the same
+//      try/catch, so a session that refuses them is non-fatal on both sides.
+//   4. THE `gone` HANDLER'S ORDER. The browser checked the window FIRST and returned — leaving a dead
+//      renderer's view visible — where the DSH hid the view first and only the PUSH depended on the
+//      window. The DSH's order is the rule here, on both slots: a renderer that died never repaints, the
+//      hide needs nothing from the host, and the window (which `main.ts` re-creates and nulls) is read
+//      only where it is genuinely required.
+//   5. `state()`'s `visible` FIELD reached the crate on one side (`viewVisible`) and was spelled
+//      `dshVisible && !!wc` on the other. The two are the same answer, so both go through the crate —
+//      the decision belongs to the policy, not to one call site.
+const electron_1 = require("electron");
+const summrise_shell_policy_1 = require("./summrise_shell_policy");
+function embeddedSlot(config) {
+    if (!config || typeof config !== "object") {
+        throw new Error("embedded-slot: a slot is built from its host config (win, door, popupTarget, recoverUrl, stateUrl, " +
+            "goneChannel, and navChannel for a slot with a history surface) — there is no such thing as a default one");
+    }
+    const REQUIRED = ["win", "door", "popupTarget", "recoverUrl", "stateUrl"];
+    for (const name of REQUIRED) {
+        if (typeof config[name] !== "function") {
+            throw new Error(`embedded-slot: ${name} is not a function — a slot is built with its host (main.ts lends both ` +
+                `instances the shell's window getter, one load door, and the policy answers only that slot may use)`);
+        }
+    }
+    if (typeof config.goneChannel !== "string" || !config.goneChannel) {
+        throw new Error("embedded-slot: goneChannel is missing — a crashed renderer pushes `gone` so the pane can show a " +
+            "recovery state instead of 'starting…' forever, and a slot that cannot push it must not be built");
+    }
+    if (config.navChannel !== undefined && (typeof config.navChannel !== "string" || !config.navChannel)) {
+        throw new Error("embedded-slot: navChannel is present but is not a channel name — omit it for a slot with no history surface");
+    }
+    const { win, door, popupTarget, recoverUrl, stateUrl, goneChannel, navChannel } = config;
+    // ── THE PER-INSTANCE STATE, AND IT IS THE INSTANCE'S ─────────────────────────────────────────
+    // Four bindings, closed over rather than module-level, which is what makes two slots independent: the
+    // two modules this replaces each held their state at module scope, so a second instance was not
+    // merely unused, it was unrepresentable. (`embeddedUrl` is the fourth rather than the third: the
+    // browser's module held view/visible/bounds AND the last url its door decided, which recovery and
+    // `state()` both read. The DSH's recover ignores it and its `stateUrl` does too.)
+    let view = null;
+    let visible = false;
+    let bounds = null;
+    let lastDecided = "about:blank";
+    function ensure() {
+        if (view && !view.webContents.isDestroyed())
+            return view;
+        // ── THE HOST IS READ BEFORE ANYTHING IS BUILT, AND BEFORE ANY STATE IS SET ─────────────────────
+        // An UNBOUND slot is one whose window getter refuses (`deps().win()` on a host whose `bind()` never
+        // ran), and a refusal must leave the slot exactly as it was: nothing built, nothing assigned, no
+        // handler wired. The read used to sit AFTER `view = built` — the order BOTH modules had before the
+        // unification — so the loud throw left a fully built view in the slot's state that no window ever
+        // showed: its crash handler was live, a later `state()`/`reload()` answered about it, and a second
+        // `ensure()` returned it without reading the window again. Nothing below needs the window to BUILD a
+        // view; the read is only about WHERE to attach one, so it happens first and a refusal creates
+        // nothing. This is a deliberate behaviour change on the UNBOUND path only: a bound host's getter
+        // returns exactly what it returned before, and reads it exactly once.
+        const w = win();
+        const built = new electron_1.WebContentsView({
+            webPreferences: {
+                contextIsolation: true,
+                nodeIntegration: false,
+                sandbox: true,
+                // NO `preload` KEY, on either slot: zero Node surface in a renderer. The browser view renders
+                // arbitrary internet pages; the DSH is a whole web application on loopback. A `preload` added
+                // here would be added to BOTH views at once, which is why it is written down.
+            },
+        });
+        built.setVisible(false);
+        visible = false;
+        // ── `target=_blank`, ONE DECISION PER SLOT ─────────────────────────────────────────────────
+        // Real sites open every external link in a new window (Baidu's, the harness's docs), and this is a
+        // single-tab pane: the popup itself is always DENIED and the SAME view moves instead. WHICH targets
+        // qualify is the `popupTarget` parameter's — through the slot's own door, so a refused scheme is
+        // dropped rather than navigated to `about:blank`.
+        built.webContents.setWindowOpenHandler(({ url }) => {
+            const decided = popupTarget(url);
+            if (decided !== undefined)
+                navigateDecided(decided);
+            return { action: "deny" };
+        });
+        if (navChannel) {
+            // Event-driven (no polling): the SPA's address bar and back/fwd buttons track the ACTUAL page, so
+            // an in-page (hash) navigation and a title-only update are changes it has to see too.
+            const push = () => {
+                const w = win();
+                if (!w || w.isDestroyed())
+                    return;
+                const s = stateWithHistory();
+                w.webContents.send(navChannel, { url: s.url, canBack: s.canBack, canFwd: s.canFwd, title: s.title });
+            };
+            built.webContents.on("did-navigate", push);
+            built.webContents.on("did-navigate-in-page", push);
+            built.webContents.on("page-title-updated", push);
+        }
+        // A renderer that crashed (process-gone) or hung mid-load never paints again. The dead view is HIDDEN
+        // first — that needs nothing from the host — so the pane's recovery banner, which paints under the
+        // native view, becomes visible in the slot; only the PUSH needs a live window, which `main.ts`
+        // re-creates and nulls (a destroyed window's `send` throws in Electron).
+        built.webContents.on("render-process-gone", (_e, details) => {
+            try {
+                built.setVisible(false);
+            }
+            catch { /* already gone */ }
+            visible = false;
+            const w = win();
+            if (w && !w.isDestroyed()) {
+                w.webContents.send(goneChannel, { reason: details.reason, exitCode: details.exitCode });
+            }
+        });
+        try {
+            electron_1.session.defaultSession.setPermissionRequestHandler((_wc, _perm, cb) => cb(false));
+            electron_1.session.defaultSession.setPermissionCheckHandler(() => false);
+        }
+        catch { /* non-fatal (already set at app ready, or a session that does not exist) */ }
+        view = built;
+        // Attach to the main window's content view once the window exists — THE WINDOW READ AT THE TOP of
+        // this function, not a second read: the same one getter call, moved ahead of the build. The view is
+        // added HIDDEN and only shown when the SPA's page is active and reports its placeholder bounds.
+        if (w)
+            w.contentView.addChildView(built);
+        return built;
+    }
+    /** Place the view over the SPA's slot (CSS px in the window's content coordinate space). Empty bounds
+     *  hide it. */
+    function place(next) {
+        const v = ensure();
+        const w = win();
+        if (!w)
+            return;
+        if ((0, summrise_shell_policy_1.slotTooSmall)(next)) {
+            v.setVisible(false);
+            visible = false;
+            return;
+        }
+        bounds = next;
+        v.setBounds(next);
+        v.setVisible(true);
+        visible = true;
+        // Keep it above the SPA content (the SPA's placeholder is an empty div).
+        w.contentView.addChildView(v);
+    }
+    /** Load an ALREADY DECIDED url. The one path that does not open the door again: the popup decision and
+     *  `recover()` both hand this a target their own policy has decided, and re-deciding it would be a
+     *  second call the caller did not ask for. */
+    function navigateDecided(url) {
+        const v = ensure();
+        lastDecided = url;
+        v.webContents.loadURL(url).catch(() => { });
+    }
+    function navigate(raw) {
+        // Every raw url the SPA or the AI hands this slot is decided by the ONE load door before it reaches
+        // loadURL — and it is recorded FIRST, so the record is the door's answer and never the raw string.
+        const url = door(raw);
+        navigateDecided(url);
+        return { ok: true, url };
+    }
+    function reload() {
+        const v = view;
+        if (!v || v.webContents.isDestroyed())
+            return { ok: false };
+        try {
+            v.webContents.reload();
+            return { ok: true };
+        }
+        catch {
+            return { ok: false };
+        }
+    }
+    /** The record WITHOUT a history surface: exactly the four keys the DSH's pane reads. */
+    function stateRecord() {
+        const v = view;
+        const wc = v && !v.webContents.isDestroyed() ? v.webContents : null;
+        return {
+            ok: true,
+            url: stateUrl(wc ? wc.getURL() : undefined, lastDecided),
+            title: wc ? wc.getTitle() : "",
+            visible: (0, summrise_shell_policy_1.viewVisible)(visible, !!wc),
+        };
+    }
+    /** ...and the same record WITH the two history fields, which only the browser's slot has. */
+    function stateWithHistory() {
+        const v = view;
+        const wc = v && !v.webContents.isDestroyed() ? v.webContents : null;
+        return {
+            ...stateRecord(),
+            canBack: !!wc && wc.navigationHistory.canGoBack(),
+            canFwd: !!wc && wc.navigationHistory.canGoForward(),
+        };
+    }
+    /** Recover after a renderer crash: a dead webContents never recovers, so re-create the view. */
+    function recover() {
+        // THE SLOT'S PLACEMENT IS READ BEFORE THE RE-CREATE. `ensure()` clears the visible flag for the view
+        // it builds, so a re-show block that reads the flag afterwards can never run — which is exactly the
+        // defect both modules carried. Reading it here is what makes the re-show below reachable, and the
+        // bounds are retained on every hide for the same reason (they are the SPA's last placement).
+        const wasVisible = visible;
+        const lastBounds = bounds;
+        try {
+            if (view && !view.webContents.isDestroyed()) {
+                view.webContents.close({ waitForBeforeUnload: false });
+            }
+            if (view) {
+                try {
+                    win()?.contentView.removeChildView(view);
+                }
+                catch { /* already gone */ }
+                view = null;
+            }
+        }
+        catch { /* fall through to ensure() */ }
+        const fresh = ensure();
+        if (!fresh || fresh.webContents.isDestroyed())
+            return { ok: false };
+        // The recovery target is the parameter's, and it is ALREADY A DECISION: the browser's re-loads the
+        // last url its door decided (never a third-party home page a crash would fetch), the DSH's is its
+        // own home (`dshHome`), because a recovery that lands anywhere else is a view nobody asked for.
+        fresh.webContents.loadURL(recoverUrl(lastDecided)).catch(() => { });
+        // Re-show at the same spot if the slot was live when the renderer died — and restore the flag, so the
+        // record the pane reads agrees with what is on screen. A slot that was hidden (never placed, or the
+        // SPA cleared its placeholder) stays hidden: the SPA's next place() is what shows it.
+        if (wasVisible && lastBounds) {
+            const w = win();
+            if (w) {
+                fresh.setBounds(lastBounds);
+                fresh.setVisible(true);
+                visible = true;
+                w.contentView.addChildView(fresh);
+            }
+        }
+        return { ok: true };
+    }
+    const slot = { ensure, place, navigate, reload, recover, state: stateRecord };
+    if (!navChannel)
+        return slot;
+    // THE HISTORY SURFACE, only for the slot that declared a nav channel. A pane with no address bar and no
+    // back/fwd buttons has no use for these, and a channel nothing invokes is a channel the preload does not
+    // expose — which `test/ipc-door.test.mjs` fails on.
+    const nav = {
+        ...slot,
+        state: stateWithHistory,
+        /** Back/forward through the REAL webContents history; the direction sign is the crate's. */
+        go: (delta) => {
+            const v = view;
+            if (!v || v.webContents.isDestroyed())
+                return { ok: false };
+            try {
+                if ((0, summrise_shell_policy_1.goBackwards)(delta))
+                    v.webContents.goBack();
+                else
+                    v.webContents.goForward();
+                return { ok: true };
+            }
+            catch {
+                return { ok: false };
+            }
+        },
+        /** Zoom the REAL view (webContents.setZoomFactor — the native browser zooms, not a CSS scale). The
+         *  clamp AND the falsy test are the crate's, because `zoomFactor(0)` is 100% and not 50%. */
+        zoom: (factor) => {
+            const v = view;
+            if (!v || v.webContents.isDestroyed())
+                return { ok: false };
+            const f = (0, summrise_shell_policy_1.zoomFactor)(factor);
+            try {
+                v.webContents.setZoomFactor(f);
+                return { ok: true, factor: f };
+            }
+            catch {
+                return { ok: false };
+            }
+        },
+    };
+    return nav;
+}

package/summrise-desktop-electron/src/main.js

@@ -82,6 +82,21 @@ const http = __importStar(require("http"));
 // this file, which holds exactly one instance of each glue, evaluates it.
 const summrise_url_policy_1 = require("./summrise_url_policy");
 const summrise_shell_policy_1 = require("./summrise_shell_policy");
+// THE TWO EMBEDDED VIEWS ARE ONE MODULE NOW. `embedded-slot.ts` holds the pattern the browser's view and
+// the DSH's view each used to spell out (`embedded-view.ts` and `dsh-view.ts`, near-copies that a
+// function-by-function comparison measured), and this file builds BOTH instances from it — one slot per
+// view, with the differences that are load-bearing (the load door, the popup decision, the recovery
+// target, the state's url fallback, the `gone` channel, and the browser-only nav channel) passed in as
+// configuration. Every `ipcHandle` registration stays HERE (see the block below "THE EMBEDDED VIEW'S IPC"),
+// because this file holds the ONE `ipcMain.handle` door.
+const embedded_slot_1 = require("./embedded-slot");
+// THE BROWSER-SESSION WINDOWS ARE THEIR OWN MODULE TOO. It owns the session table and the three
+// operations an AI drives; this file owns the load door every one of them opens through, the window
+// icon they share with the main window, and the cap's number — lent to it in one `browserSessionsBind`
+// call below. The IPC registrations and the three other call sites stay HERE: this file holds the ONE
+// `ipcMain.handle` door, and the loopback control server and the panel's `target=_blank` handler are
+// this file's routers, not the module's.
+const browser_sessions_1 = require("./browser-sessions");
 const K = JSON.parse((0, summrise_shell_policy_1.shellConstants)());
 // The handful the shell reads often enough that `K.` at every use site would be noise. They are still the
 // table's values — destructuring a copy of the parse, not a second declaration.
@@ -235,13 +250,6 @@ let win = null;
 let tray = null;
 /** Whether the hide-to-tray notification has been shown (once per launch). */
 let hideNotified = false;
-const browserSessions = new Map();
-/** Initial target per browser window — reuse matching uses this instead of
- *  webContents.getURL() (which lags during navigation; stage-n). */
-const browserTargets = new Map();
-/** Cap on concurrent browser-session windows — an AI loop opening sessions
- *  repeatedly must not pile up windows on the desktop (stage-n). The number is `K.MAX_BROWSER_WINDOWS`;
- *  the PLAN that applies it (reuse by initial target, then evict the oldest) is the policy crate's. */
 // stage-m: SINGLE-INSTANCE LOCK — a second Summrise window exits immediately.
 // (The agent itself also enforces single-instance via bind-failure exit.)
 const gotTheLock = electron_1.app.requestSingleInstanceLock();
@@ -373,322 +381,60 @@ function buildMenu() {
  *  cannot quietly reach for a weaker policy of its own.
  *
  *  Callers keep their own about:blank semantics: browserOpen() opens a blank
- *  window, embeddedNavigate() loads it, and the embedded view's window-open
+ *  window, the browser slot's navigate() loads it, and that slot's window-open
  *  handler REFUSES it (an external link must not blank the page being read). */
 function loadTarget(raw) {
     return (0, summrise_url_policy_1.sanitizeBrowserUrl)(raw);
 }
-/** Open a browser-session window on a decided load target (loadTarget() is the
- *  ONE load door — the scheme policy lives there). */
-function browserOpen(url) {
-    const target = loadTarget(url);
-    // stage-n: reuse an existing window on the same URL instead of stacking duplicates (AI-driven
-    // browsing opens/closes sessions repeatedly). Match against the window's INITIAL target (stored at
-    // open) — webContents.getURL() lags during navigation (returns about:blank while loading), so a
-    // same-URL reopen right after the first open would otherwise miss the reuse and stack a duplicate.
-    //
-    // THE PLAN IS THE POLICY CRATE'S, in one call: which window to reuse (first non-destroyed match, in
-    // INSERTION order), and — when the cap is reached — which one to evict (the OLDEST, not the least
-    // recently used). This file only reads the session table and applies the answer. The `destroyed` flag
-    // travels with the row because a destroyed window is skipped for reuse while still COUNTING against
-    // the cap, which is what `browserSessions.size` did.
-    const plan = JSON.parse((0, summrise_shell_policy_1.planBrowserOpen)(JSON.stringify([...browserSessions].map(([id, bw]) => ({ id, target: browserTargets.get(id) ?? "", destroyed: bw.isDestroyed() }))), target, K.MAX_BROWSER_WINDOWS));
-    if (plan.reuse) {
-        const existing = browserSessions.get(plan.reuse);
-        if (existing) {
-            if (existing.isMinimized())
-                existing.restore();
-            existing.show();
-            existing.focus();
-            return { ok: true, id: plan.reuse, url: target, cdp: (0, summrise_shell_policy_1.cdpEndpoint)(K.CDP_PORT) };
-        }
-    }
-    if (plan.evict)
-        browserClose(plan.evict);
-    const id = (0, summrise_shell_policy_1.browserId)(Date.now());
-    const bw = new electron_1.BrowserWindow({
-        width: 1100, height: 750, title: `Summrise Browser — ${target}`,
-        ...(windowIcon() ? { icon: windowIcon() } : {}),
-        // review #6/#7: these windows load ARBITRARY internet pages. contextIsolation
-        // on + nodeIntegration off + NO preload = zero Node/bridge surface (the
-        // default; made explicit). Popups are denied (they would otherwise spawn
-        // unmanaged windows outside the MAX_BROWSER_WINDOWS cap).
-        webPreferences: { contextIsolation: true, nodeIntegration: false, sandbox: true },
-    });
-    bw.webContents.setWindowOpenHandler(() => ({ action: "deny" }));
-    bw.loadURL(target);
-    bw.on("closed", () => { browserSessions.delete(id); browserTargets.delete(id); });
-    // stage-n: the window title starts as "Summrise Browser — <target>" but a
-    // site's own <title> is more useful after load (and after in-page
-    // navigation); follow it so window managers/taskbar show the real page.
-    bw.webContents.on("page-title-updated", (_e, title) => {
-        if (!bw.isDestroyed() && title)
-            bw.setTitle(`Summrise Browser — ${title}`);
-    });
-    browserSessions.set(id, bw);
-    browserTargets.set(id, target);
-    return { ok: true, id, url: target, cdp: (0, summrise_shell_policy_1.cdpEndpoint)(K.CDP_PORT) };
-}
-function browserClose(id) {
-    const bw = browserSessions.get(id || "");
-    // review #g: close() is vetoable by a page's beforeunload — an arbitrary
-    // remote page could refuse eviction, so the MAX_BROWSER_WINDOWS cap never
-    // freed and browserOpen stalled. destroy() is unconditional (these are
-    // disposable, headless-driven windows).
-    if (bw) {
-        bw.destroy();
-        browserSessions.delete(id || "");
-        browserTargets.delete(id || "");
-    }
-    return { ok: true };
-}
-function browserList() {
-    const list = [...browserSessions.entries()].map(([id, bw]) => ({ id, url: bw.webContents.getURL() }));
-    return { ok: true, sessions: list, cdp: (0, summrise_shell_policy_1.cdpEndpoint)(K.CDP_PORT) };
-}
-ipcHandle("browser-session:open", (url) => browserOpen(url));
-ipcHandle("browser-session:close", (id) => browserClose(id));
-ipcHandle("browser-session:list", () => browserList());
-// ── Embedded real-render browser view (round-246) ──────────────────────────
-// The SPA's Browser page used to show the BRIDGE's headless-chromium as a
-// JPEG screencast (lossy q60-92 frames over a websocket) — never as sharp as
-// a real browser, and a SECOND browser instance alongside the desktop shell.
-// In the Electron shell we replace it with a REAL WebContentsView embedded
-// over the SPA's browser placeholder: GPU-composited, vector text, directly
-// interactive. Its webContents is a first-class CDP target on the SAME
-// :9333 endpoint, so AI (playwright connectOverCDP) drives EXACTLY the page
-// the user sees — one browser, zero JPEG.
-//
-// Security posture mirrors the browser-session windows: the view loads
-// arbitrary internet pages, so contextIsolation on, nodeIntegration off, NO
-// preload, sandbox on, popups denied, permissions denied by default.
-let embeddedView = null;
-let embeddedVisible = false;
-let embeddedUrl = "about:blank";
-// round-256: last placed bounds — kept so a renderer-crash recovery can
-// re-show the fresh view at the same spot without waiting for the SPA.
-let embeddedBounds = null;
-function embeddedViewEnsure() {
-    if (embeddedView && !embeddedView.webContents.isDestroyed())
-        return embeddedView;
-    const view = new electron_1.WebContentsView({
-        webPreferences: {
-            contextIsolation: true,
-            nodeIntegration: false,
-            sandbox: true,
-            // round-246 (review #6/#7 parity): no preload = zero Node surface.
-        },
-    });
-    view.setVisible(false);
-    embeddedVisible = false;
-    // round-248 (user report "浏览器超链接跳转不了"): `target=_blank` links
-    // (the norm on real sites — Baidu's every external link opens a new
-    // window) were DENIED, so clicking them did nothing. The embedded view is
-    // a single-tab browser: intercept window.open and navigate the SAME view
-    // to the requested URL instead (the address bar follows via the nav
-    // events). The scheme allow-list is loadTarget()'s (the ONE load door):
-    // anything it refuses (javascript:, file:, chrome:) must NOT blank the page
-    // the user is reading, so a refused target is dropped here instead.
-    view.webContents.setWindowOpenHandler(({ url }) => {
-        // THE DOOR DECIDES, THIS FILE APPLIES: `loadTarget` is the ONE load door (the URL policy's), and
-        // the DECISION to DROP a refused target rather than navigate to the blank page is the policy
-        // crate's — a refused `javascript:`/`file:`/`chrome:` link must not erase what the operator is
-        // reading, which is why a refusal is `undefined` here and not `"about:blank"`.
-        const decided = (0, summrise_shell_policy_1.embeddedPopupTarget)(loadTarget(url));
-        if (decided !== undefined) {
-            embeddedNavigate(decided);
-        }
-        return { action: "deny" };
-    });
-    // round-248: same-view navigation for window.name/target=_top style links
-    // that Chromium routes as renderer-initiated top navigations is already
-    // handled natively; this handler only covers the window.open path above.
-    // round-247: real-navigation events → SPA (URL/title/history tracking).
-    embeddedWireNavEvents(view);
-    try {
-        electron_1.session.defaultSession.setPermissionRequestHandler((_wc, _perm, cb) => cb(false));
-        electron_1.session.defaultSession.setPermissionCheckHandler(() => false);
-    }
-    catch { /* non-fatal (already set at app ready) */ }
-    embeddedView = view;
-    // Attach to the main window's content view once the window exists. The
-    // view is added hidden and only shown when the SPA's Browser page is
-    // active and reports its placeholder bounds.
-    if (win)
-        win.contentView.addChildView(view);
-    return view;
-}
-/** Place the embedded view over the SPA's browser placeholder (CSS px in the
- *  window's content coordinate space). Empty bounds hide it. */
-function embeddedViewPlace(bounds) {
-    const view = embeddedViewEnsure();
-    if (!win)
-        return;
-    // `K.MIN_SLOT_PX` AND ITS COMPARISON ARE ONE FUNCTION NOW: this view and the DSH view each spelled
-    // `bounds.width < 50 || bounds.height < 50` BEFORE the port, which is two copies of one policy — the
-    // place where the browser view and the DSH view would come to disagree about what "showing" means.
-    if ((0, summrise_shell_policy_1.slotTooSmall)(bounds)) {
-        view.setVisible(false);
-        embeddedVisible = false;
-        return;
-    }
-    embeddedBounds = bounds;
-    view.setBounds(bounds);
-    view.setVisible(true);
-    embeddedVisible = true;
-    // Keep it above the SPA content (the SPA placeholder is an empty div).
-    win.contentView.addChildView(view);
-}
-function embeddedNavigate(raw) {
-    // Every raw URL the SPA/AI hands the embedded view is decided by the ONE
-    // load door before it reaches loadURL.
-    const url = loadTarget(raw);
-    const view = embeddedViewEnsure();
-    embeddedUrl = url;
-    view.webContents.loadURL(url).catch(() => { });
-    return { ok: true, url };
-}
-/** round-247: nav controls on the embedded view (the SPA's toolbar mirrors a
- *  real browser: back/fwd/reload operate the actual webContents history). */
-function embeddedGo(delta) {
-    const view = embeddedView;
-    if (!view || view.webContents.isDestroyed())
-        return { ok: false };
-    try {
-        if ((0, summrise_shell_policy_1.goBackwards)(delta))
-            view.webContents.goBack();
-        else
-            view.webContents.goForward();
-        return { ok: true };
-    }
-    catch {
-        return { ok: false };
-    }
-}
-function embeddedReload() {
-    const view = embeddedView;
-    if (!view || view.webContents.isDestroyed())
-        return { ok: false };
-    try {
-        view.webContents.reload();
-        return { ok: true };
-    }
-    catch {
-        return { ok: false };
-    }
-}
-function embeddedState() {
-    const view = embeddedView;
-    const wc = view && !view.webContents.isDestroyed() ? view.webContents : null;
-    return {
-        ok: true,
-        // The FALLBACK is the policy crate's: a live `getURL()` that answers "" (not yet navigated) and no
-        // live contents at all are the same answer, and it is the last URL this view was sent to.
-        url: (0, summrise_shell_policy_1.shownUrl)(wc ? wc.getURL() : undefined, embeddedUrl),
-        canBack: !!wc && wc.navigationHistory.canGoBack(),
-        canFwd: !!wc && wc.navigationHistory.canGoForward(),
-        title: wc ? wc.getTitle() : "",
-        visible: (0, summrise_shell_policy_1.viewVisible)(embeddedVisible, !!wc),
-    };
-}
-/** round-247: push real navigation state (URL + title + history) to the SPA
- *  so its address bar and back/fwd buttons track the ACTUAL embedded page —
- *  event-driven (fires on navigation, no polling). */
-function embeddedWireNavEvents(view) {
-    const wc = view.webContents;
-    const push = () => {
-        if (!win || win.isDestroyed())
-            return;
-        const s = embeddedState();
-        win.webContents.send("embedded-browser:nav", { url: s.url, canBack: s.canBack, canFwd: s.canFwd, title: s.title });
-    };
-    wc.on("did-navigate", push);
-    wc.on("did-navigate-in-page", push);
-    wc.on("page-title-updated", push);
-    // round-256: the embedded view's RENDERER can crash (process-gone) or hang
-    // mid-load (did-fail-load). Push a `gone` event so the SPA shows a recovery
-    // state instead of "Starting…" forever; the SPA then offers a reload.
-    wc.on("render-process-gone", (_e, details) => {
-        if (!win || win.isDestroyed())
-            return;
-        // Hide the dead view so the SPA's recovery banner (which paints under
-        // the native view) becomes visible in the slot.
-        try {
-            view.setVisible(false);
-        }
-        catch { /* already gone */ }
-        embeddedVisible = false;
-        win.webContents.send("embedded-browser:gone", {
-            reason: details.reason,
-            exitCode: details.exitCode,
-        });
-    });
-}
-/** round-256: recover the embedded view after a RENDERER CRASH. A
- *  process-gone renderer usually leaves the webContents object alive but
- *  dead — loadURL on it never recovers, so force a full re-create: drop the
- *  old view (destroy + remove) and build a fresh one via embeddedViewEnsure,
- *  then navigate to the last URL (or a default). */
-function embeddedRecover() {
-    try {
-        if (embeddedView && !embeddedView.webContents.isDestroyed()) {
-            embeddedView.webContents.close({ waitForBeforeUnload: false });
-        }
-        if (embeddedView) {
-            try {
-                win?.contentView.removeChildView(embeddedView);
-            }
-            catch { /* already gone */ }
-            embeddedView = null;
-        }
-    }
-    catch { /* fall through to ensure() */ }
-    const view = embeddedViewEnsure();
-    if (!view || view.webContents.isDestroyed())
-        return { ok: false };
-    // Already decided by loadTarget() when embeddedUrl was set (the ONE load
-    // door) — recovery re-loads that decision, it does not re-open the policy.
-    // The fallback is about:blank, NOT a third-party home page: recovering a
-    // crashed view must not make a request to a search engine to do it. That
-    // rule is `embeddedRecoverUrl`'s, in the policy crate.
-    const url = (0, summrise_shell_policy_1.embeddedRecoverUrl)(embeddedUrl);
-    view.webContents.loadURL(url).catch(() => { });
-    // Re-show if the SPA slot is live (bounds were placed before the crash).
-    if (embeddedVisible && win && embeddedBounds) {
-        view.setBounds(embeddedBounds);
-        view.setVisible(true);
-        win.contentView.addChildView(view);
-    }
-    return { ok: true };
-}
-ipcHandle("embedded-browser:recover", () => embeddedRecover());
-ipcHandle("embedded-browser:navigate", (url) => embeddedNavigate(String(url || "")));
-ipcHandle("embedded-browser:back", () => embeddedGo(-1));
-ipcHandle("embedded-browser:fwd", () => embeddedGo(1));
-ipcHandle("embedded-browser:reload", () => embeddedReload());
-/** round-251: zoom the REAL embedded view (webContents.setZoomFactor — the
- *  native browser zooms, not a CSS scale). factor: 0.5-3.0. */
-ipcHandle("embedded-browser:zoom", (factor) => {
-    const view = embeddedView;
-    if (!view || view.webContents.isDestroyed())
-        return { ok: false };
-    // The clamp AND the `Number(factor) || 1` falsy test are the policy crate's, because `zoomFactor(0)`
-    // is 100% and not 50% — a boundary that a hand-written `Math.min/Math.max` here got right by
-    // accident and a rewrite would not.
-    const f = (0, summrise_shell_policy_1.zoomFactor)(factor);
-    try {
-        view.webContents.setZoomFactor(f);
-        return { ok: true, factor: f };
-    }
-    catch {
-        return { ok: false };
-    }
+// ── THE BROWSER SLOT: THE FIRST INSTANCE OF `embedded-slot.ts` ─────────────────────────────
+// Built ONCE here (module load), the way the bind call it replaces was. Everything the slot needs is
+// either a function object this file owns (the window getter and the ONE load door above) or a policy
+// answer only THIS view may use — and the two that must not be merged into the module are the popup
+// decision and the recovery target, because they are what keeps this view a general browser while the
+// DSH's is confined to its own loopback origin (see `embedded-slot.ts`'s header).
+const browserSlot = (0, embedded_slot_1.embeddedSlot)({
+    // A GETTER, not the value: the window does not exist yet and is nulled when it closes.
+    win: () => win,
+    door: loadTarget,
+    // `target=_blank` through the ONE load door: its argument is the DECIDED target, and a refused scheme
+    // answers `undefined` — DROPPED rather than collapsed to `about:blank`, so an external link cannot
+    // erase the page the operator is reading.
+    popupTarget: (raw) => (0, summrise_shell_policy_1.embeddedPopupTarget)(loadTarget(raw)),
+    // The last DECIDED url, or the crate's blank fallback: recovering a crashed view must not fetch a
+    // third-party home page to do it.
+    recoverUrl: (lastDecided) => (0, summrise_shell_policy_1.embeddedRecoverUrl)(lastDecided),
+    // This state feeds the SPA's ADDRESS BAR, which must never go blank: a view that cannot answer reports
+    // the last url the door decided for it. (The DSH's record does the opposite — see its instance below.)
+    stateUrl: (live, lastDecided) => (0, summrise_shell_policy_1.shownUrl)(live, lastDecided),
+    goneChannel: "embedded-browser:gone",
+    // THE BROWSER-ONLY SURFACE: nav pushes, canBack/canFwd, and go/zoom. The DSH instance has none of it.
+    navChannel: "embedded-browser:nav",
 });
+// The browser-session windows' seam, bound ONCE here (module load) and never re-bound. Three things
+// this file owns and the sessions do not: the ONE load door above (their every URL goes through it),
+// the window icon the main window also uses, and the cap's number from the boot table. `main.ts`
+// requiring the module and the module requiring `main.ts` would be a cycle, so they are lent instead,
+// and `browser-sessions.ts` reads them through its own `deps()`.
+(0, browser_sessions_1.browserSessionsBind)({ loadTarget, windowIcon, maxBrowserWindows: K.MAX_BROWSER_WINDOWS });
+ipcHandle("browser-session:open", (url) => (0, browser_sessions_1.browserOpen)(url));
+ipcHandle("browser-session:close", (id) => (0, browser_sessions_1.browserClose)(id));
+ipcHandle("browser-session:list", () => (0, browser_sessions_1.browserList)());
+// ── THE EMBEDDED VIEW'S IPC — THE REGISTRATIONS STAY HERE ──────────────────────────────────
+// The slot itself (its state and its operations) is `embedded-slot.ts`. These lines do NOT go with it:
+// this file holds the ONE `ipcMain.handle` door — `ipcHandle` applies the frame check — and
+// `test/ipc-door.test.mjs` pins the channels registered behind that door against the ones `preload.ts`
+// invokes. A handler registered in the module would be a second door.
+ipcHandle("embedded-browser:recover", () => browserSlot.recover());
+ipcHandle("embedded-browser:navigate", (url) => browserSlot.navigate(String(url || "")));
+ipcHandle("embedded-browser:back", () => browserSlot.go(-1));
+ipcHandle("embedded-browser:fwd", () => browserSlot.go(1));
+ipcHandle("embedded-browser:reload", () => browserSlot.reload());
+ipcHandle("embedded-browser:zoom", (factor) => browserSlot.zoom(factor));
 ipcHandle("embedded-browser:place", (bounds) => {
-    embeddedViewPlace(bounds);
+    browserSlot.place(bounds);
     return { ok: true };
 });
-ipcHandle("embedded-browser:state", () => embeddedState());
+ipcHandle("embedded-browser:state", () => browserSlot.state());
 // ── THE DSH VIEW: the harness's own UI, embedded in summrise ────────────────────────────────
 //
 // WHY LOOPBACK AND NOT THE PUBLIC HOSTNAME. The DSH runs on THIS machine (127.0.0.1:18081), and
@@ -701,9 +447,26 @@ ipcHandle("embedded-browser:state", () => embeddedState());
 //
 // A SECOND view, not a re-use of the browser one: the browser view is a single-tab internet
 // browser an AI drives over CDP, and navigating it to the DSH would throw that session away.
-let dshView = null;
-let dshVisible = false;
-let dshBounds = null;
+//
+// ── THE DSH SLOT IS THE SECOND INSTANCE OF THE SAME MODULE; THIS IS ITS HOST HALF ──────────
+// The view's state and its operations are `embedded-slot.ts` now, built from the same factory as the
+// browser's. What matters HERE is the three functions below it that DELIBERATELY DID NOT GO INTO IT,
+// because they belong to the boot and the host rather than to the view:
+//   * `bootDshPort` — the boot's port pin, the twin of `bootAgentPort` below: called once, from
+//     `app.whenReady()`, as the argument to `setDshPort`, which feeds the url policy's port state
+//     that this file owns. No operation of the view calls it.
+//   * `dshTargetFor` — the ONE load door for that view, and a door is the HOST's: this file owns
+//     the load door of every view it lends one to (`loadTarget` above is the same shape for the
+//     other two modules), and it is where this file evaluates the url-policy predicate
+//     `isDshUrl` — the rule the import block above states for both crates. It is LENT to the slot in
+//     the `embeddedSlot` call below, never re-declared there.
+//   * `loadHarnessDoors` — the boot's ONE read of the agent's harness table: it MUTATES the url
+//     policy's own port list (`addDshPort`), fetches with the device token (`authHeaders`) and is
+//     bounded by the boot table's `HARNESS_FETCH_MS`. The view never calls it, so lending this
+//     module a credential and a boot number for a caller it does not have would be dependency
+//     surface bought for nothing.
+// `WebContentsView` left this file's electron import with the view: nothing here names the type
+// any more, and a surface no reader can act on is the rule the child_process import above cites.
 /** The DSH's port. Env first (a deployment may move it), else the component's default — the range test
  *  and the fallback are the policy crate's, the env read is this file's. */
 function bootDshPort() {
@@ -749,133 +512,50 @@ function loadHarnessDoors() {
     })
         .finally(() => clearTimeout(timer));
 }
-function dshViewEnsure() {
-    if (dshView && !dshView.webContents.isDestroyed())
-        return dshView;
-    const view = new electron_1.WebContentsView({
-        webPreferences: {
-            contextIsolation: true,
-            nodeIntegration: false,
-            sandbox: true,
-            // No preload: the DSH SPA needs no Node surface, and a view that cannot reach one cannot
-            // be talked into using one.
-        },
-    });
-    view.setVisible(false);
-    dshVisible = false;
-    // The DSH opens links (docs, the operator's own pages) with target=_blank. Deny the POPUP but
-    // keep the click meaningful where the door allows it — and the door allows one origin, so in
-    // practice an external link is simply dropped rather than silently navigating this view away
-    // from the harness.
-    view.webContents.setWindowOpenHandler(({ url }) => {
-        const decided = (0, summrise_shell_policy_1.dshPopupTarget)(url, (0, summrise_url_policy_1.isDshUrl)(url));
-        if (decided !== undefined)
-            dshNavigate(decided);
-        return { action: "deny" };
-    });
-    view.webContents.on("render-process-gone", (_e, details) => {
-        try {
-            view.setVisible(false);
-        }
-        catch { /* already gone */ }
-        dshVisible = false;
-        // The SAME signal the browser view sends, for the same reason (round-256 there): without it
-        // the pane shows "starting…" forever over a view that will never paint, and the operator has
-        // no way to tell a slow load from a dead renderer.
-        if (win && !win.isDestroyed()) {
-            win.webContents.send("embedded-dsh:gone", { reason: details.reason, exitCode: details.exitCode });
-        }
-    });
-    dshView = view;
-    if (win)
-        win.contentView.addChildView(view);
-    return view;
-}
-function dshNavigate(url) {
-    const target = dshTargetFor(url);
-    const view = dshViewEnsure();
-    view.webContents.loadURL(target).catch(() => { });
-    return { ok: true, url: target };
-}
-/** Open (or re-focus) the DSH at its configured address. Idempotent.
- *
- *  `dshHome` is the policy crate's and it was spelled TWICE in this file before the port — here and in
- *  `dshRecover` — which is exactly the pair that must not drift: a crash recovery that lands somewhere
- *  other than the harness is a view the operator did not ask for. */
+// THE DSH INSTANCE, built ONCE here (module load) from the SAME factory as the browser slot. The window
+// is a getter because it does not exist yet and is nulled when it closes; `door` is the load door above;
+// and the DSH's own answers travel as FUNCTIONS rather than as values for the reason the crate's docs
+// give — "the BASE arrives from the host, which is the only thing that can read the configured DSH
+// port" — and because `setDshPort` runs at `whenReady`, so a snapshot taken here would pin the port list
+// before the agent's harness table has even been read.
+//
+// THE LIFECYCLE IS THE CALLER'S, NOT A PARAMETER: this slot is created LAZILY (nothing calls `ensure()`
+// until the pane's `open()` navigates), where the browser's is created eagerly at startup. `ensure` is on
+// the slot's surface for both instances; only the browser's caller asks for it early.
+const dshSlot = (0, embedded_slot_1.embeddedSlot)({
+    win: () => win,
+    door: dshTargetFor,
+    // The DSH's own popup decision: over its own door, and only the harness's origin is admitted — an
+    // external `target=_blank` link is dropped rather than navigating this pane away from the harness.
+    popupTarget: (raw) => (0, summrise_shell_policy_1.dshPopupTarget)(raw, (0, summrise_url_policy_1.isDshUrl)(raw)),
+    // Always the harness home: a crash recovery that lands somewhere other than the harness is a view the
+    // operator did not ask for.
+    recoverUrl: () => (0, summrise_shell_policy_1.dshHome)((0, summrise_url_policy_1.dshBase)()),
+    // This record describes the LIVE view and nothing else — a dead webContents reports blank rather than
+    // its last url (the browser slot's address bar is the opposite case; see its instance above).
+    stateUrl: (live) => (0, summrise_shell_policy_1.shownUrl)(live, ""),
+    goneChannel: "embedded-dsh:gone",
+    // NO navChannel: the DSH pane has no address bar and no back/fwd buttons.
+});
+/** Open (or re-focus) the DSH at its configured address. Idempotent — and the `open` OPERATION stays in
+ *  this file because the lifecycle is the caller's: this is the call that CREATES the DSH's view (the
+ *  slot builds it lazily inside `navigate`), and navigates it home through the ONE door above. */
 function dshOpen() {
-    return dshNavigate((0, summrise_shell_policy_1.dshHome)((0, summrise_url_policy_1.dshBase)()));
-}
-/** Place the view over the SPA's slot. Empty bounds hide it (the same contract as the browser). */
-function dshPlace(bounds) {
-    const view = dshViewEnsure();
-    if (!win)
-        return;
-    // The SAME predicate the browser view uses — one `MIN_SLOT_PX`, two call sites, before the port.
-    if ((0, summrise_shell_policy_1.slotTooSmall)(bounds)) {
-        view.setVisible(false);
-        dshVisible = false;
-        return;
-    }
-    dshBounds = bounds;
-    view.setBounds(bounds);
-    view.setVisible(true);
-    dshVisible = true;
-    win.contentView.addChildView(view);
-}
-function dshReload() {
-    const view = dshView;
-    if (!view || view.webContents.isDestroyed())
-        return { ok: false };
-    try {
-        view.webContents.reload();
-        return { ok: true };
-    }
-    catch {
-        return { ok: false };
-    }
-}
-/** Recover after a renderer crash: a dead webContents never recovers, so re-create the view. */
-function dshRecover() {
-    try {
-        if (dshView && !dshView.webContents.isDestroyed())
-            dshView.webContents.close({ waitForBeforeUnload: false });
-        if (dshView) {
-            try {
-                win?.contentView.removeChildView(dshView);
-            }
-            catch { /* already gone */ }
-            dshView = null;
-        }
-    }
-    catch { /* fall through to ensure() */ }
-    const view = dshViewEnsure();
-    if (!view || view.webContents.isDestroyed())
-        return { ok: false };
-    view.webContents.loadURL((0, summrise_shell_policy_1.dshHome)((0, summrise_url_policy_1.dshBase)())).catch(() => { });
-    if (dshVisible && win && dshBounds) {
-        view.setBounds(dshBounds);
-        view.setVisible(true);
-        win.contentView.addChildView(view);
-    }
-    return { ok: true };
-}
-function dshState() {
-    const view = dshView;
-    const wc = view && !view.webContents.isDestroyed() ? view.webContents : null;
-    return { ok: true, url: wc ? wc.getURL() : "", title: wc ? wc.getTitle() : "", visible: dshVisible && !!wc };
+    return dshSlot.navigate((0, summrise_shell_policy_1.dshHome)((0, summrise_url_policy_1.dshBase)()));
 }
 ipcHandle("embedded-dsh:open", () => dshOpen());
 ipcHandle("embedded-dsh:place", (bounds) => {
-    dshPlace(bounds);
+    dshSlot.place(bounds);
     return { ok: true };
 });
-ipcHandle("embedded-dsh:state", () => dshState());
-// SELECT A HOST: `dshNavigate` already refuses anything `isDshUrl` does not admit, so this channel can
-// only reach a door the agent configured — and it answers with the address it actually loaded, which for a
-// refusal is `about:blank`. The pane shows that rather than pretending the switch worked.
-ipcHandle("embedded-dsh:go", (url) => dshNavigate(String(url)));
-ipcHandle("embedded-dsh:reload", () => dshReload());
-ipcHandle("embedded-dsh:recover", () => dshRecover());
+ipcHandle("embedded-dsh:state", () => dshSlot.state());
+// SELECT A HOST: the slot's `navigate` already refuses anything `isDshUrl` does not admit, so this
+// channel can only reach a door the agent configured — and it answers with the address it actually
+// loaded, which for a refusal is `about:blank`. The pane shows that rather than pretending the switch
+// worked.
+ipcHandle("embedded-dsh:go", (url) => dshSlot.navigate(String(url)));
+ipcHandle("embedded-dsh:reload", () => dshSlot.reload());
+ipcHandle("embedded-dsh:recover", () => dshSlot.recover());
 // Desktop-app settings (auto-launch) — the Settings page toggles this. We
 // manage a per-user scheduled task ("SummriseDesktop", onlogon) instead of
 // Electron's setLoginItemSettings: in dev mode (electron .) the login-item
@@ -1070,9 +750,9 @@ const httpServer = http.createServer((req, res) => {
         // guard (a POST reaches the same reader), while `/open`, `/close` and `/start-agent` require POST and
         // a GET to one of them falls through to the 404.
         switch ((0, summrise_shell_policy_1.controlRoute)(req.method ?? "", pathname)) {
-            case "browser-open": return send(browserOpen((0, summrise_shell_policy_1.controlQuery)(req.url, "url") || K.ABOUT_BLANK));
-            case "browser-close": return send(browserClose((0, summrise_shell_policy_1.controlQuery)(req.url, "id") || ""));
-            case "browser-list": return send(browserList());
+            case "browser-open": return send((0, browser_sessions_1.browserOpen)((0, summrise_shell_policy_1.controlQuery)(req.url, "url") || K.ABOUT_BLANK));
+            case "browser-close": return send((0, browser_sessions_1.browserClose)((0, summrise_shell_policy_1.controlQuery)(req.url, "id") || ""));
+            case "browser-list": return send((0, browser_sessions_1.browserList)());
             case "start-agent": return (async () => send(await startAgentTask()))();
             case "agent-status": return (async () => send({ ok: true, running: await agentResponds(CONTROL_PROBE_MS) }))();
             case "icon-status": return send({ ok: true, icons: iconReport,
@@ -1227,7 +907,7 @@ if (gotTheLock) {
         // review #7: a target=_blank from the SPA must NOT get a preload-bearing
         // window; route it to a sandboxed browser session instead.
         win.webContents.setWindowOpenHandler(({ url }) => {
-            browserOpen(url);
+            (0, browser_sessions_1.browserOpen)(url);
             return { action: "deny" };
         });
         // stage-n: load /desktop/ only when the agent is actually listening.
@@ -1447,14 +1127,17 @@ if (gotTheLock) {
         // attached playwright/AI ALWAYS has its own dedicated page to drive —
         // without it, playwright grabbed the MAIN window (now tripwired) or the
         // user had to open the Browser page first. The view is hidden until the
-        // SPA's Browser page reports bounds (embeddedViewPlace shows it).
+        // SPA's Browser page reports bounds (the slot's place() shows it).
         // NO EAGER NAVIGATION: this used to loadURL("https://www.bing.com"), i.e. a
         // request to a third party on EVERY launch before anyone asked for a page.
         // The view is still created — about:blank is a first-class CDP target (the
         // reason it exists here is that a target be available, not that a page be
         // loaded), and the user/AI navigates it next (loadTarget is the one door).
+        // THIS CALL IS THE BROWSER SLOT'S LIFECYCLE AND IT LIVES HERE ON PURPOSE: the browser's view is
+        // created eagerly, the DSH's is created lazily by its pane's open() — a difference between two
+        // CALLERS, so it is these lines rather than a parameter of the shared slot.
         try {
-            embeddedViewEnsure();
+            browserSlot.ensure();
         }
         catch { /* non-fatal */ }
         console.log(`[summrise] CDP endpoint: ${(0, summrise_shell_policy_1.cdpEndpoint)(K.CDP_PORT)} (playwright connectOverCDP)`);
@@ -1609,11 +1292,7 @@ electron_1.app.on("before-quit", () => {
     electron_1.app.isQuitting = true;
     // stage-n: close every browser-session window explicitly — app.quit()
     // tears down the main window but independent BrowserWindows with pending
-    // beforeunload handlers can stall or leak on exit.
-    for (const [id, bw] of browserSessions) {
-        if (!bw.isDestroyed())
-            bw.destroy();
-        browserSessions.delete(id);
-        browserTargets.delete(id);
-    }
+    // beforeunload handlers can stall or leak on exit. The sweep itself lives with the
+    // table it walks (`browser-sessions.ts`), which is why this is a call and not a loop.
+    (0, browser_sessions_1.browserCloseAll)();
 });