summrise-agent 1.2.510 → 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,18 +1,24 @@
 {
   "name": "summrise-agent",
-  "version": "1.2.510",
-  "description": "Summrise Agent \u2014 Windows device MCP server (terminal/SSH/serial) + panel. Self-hosted npm distribution.",
-  "//build": "\u552f\u4e00\u6784\u5efa\u8def\u5f84\uff1a\u5728\u672c\u76ee\u5f55\u6267\u884c npm run build\u3002\u5b83\u662f\u81ea\u5305\u542b\u7684\uff1a\u7ecf npm exec \u6309\u9700\u62c9\u53d6 typescript@5\uff0c\u65e0\u9700\u9884\u88c5\u4efb\u4f55 node_modules\uff08\u5e72\u51c0\u68c0\u51fa\u53ef\u8dd1\uff1b\u65e7\u811a\u672c\u5f15\u7528 ../summrise-desktop-electron/node_modules/.bin/tsc\uff0c\u5e72\u51c0\u68c0\u51fa\u5fc5 ENOENT\uff09\u3002\u5fc5\u987b\u7528 npm exec --package \u2026 -- tsc \u7684\u5f62\u5f0f\uff1anpx \u4f1a\u5403\u6389\u4f20\u7ed9 tsc \u7684 -p/--outDir \u7b49\u53c2\u6570\uff08round-435\uff1anpx \u5199\u6cd5\u4ece\u672a\u771f\u6b63\u8dd1\u901a\u8fc7\uff09\u3002\u5148\u7f16 electron TS\uff08--noCheck \u7eaf emit\uff0c\u4e0e release.yml \u4e00\u81f4\uff09\u540c\u6b65\u4e24\u5904 src/*.js\uff0c\u518d\u7f16 src/summrise.ts \u5230 bin/summrise.js \u5e76\u6821\u9a8c round-298 \u6807\u8bb0\uff08\u5f31 oracle\uff0c\u53ea\u8bc1\u67d0\u6b21\u6784\u5efa\u53d1\u751f\uff0c\u65b0\u9c9c\u6027\u7531 publish-release.sh \u7684 tsc \u91cd\u7f16 + cmp \u95e8\u4fdd\u8bc1\uff09\u3002",
+  "version": "1.2.512",
+  "description": "Summrise Agent — Windows device MCP server (terminal/SSH/serial) + panel. Self-hosted npm distribution.",
+  "//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.js"
+    "summrise": "bin/summrise.exe"
   },
   "files": [
     "README.md",
-    "bin/",
+    "bin/summrise.exe",
     "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/url-policy.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/icon.png",
     "summrise-desktop-electron/icon.ico"
   ],
@@ -24,7 +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 /tmp/summrise-electron-fresh/url-policy.js ../summrise-desktop-electron/src/url-policy.js && cp ../summrise-desktop-electron/src/main.js ../summrise-desktop-electron/src/preload.js ../summrise-desktop-electron/src/url-policy.js ./summrise-desktop-electron/src/ && npm exec --yes --package typescript@5.9.3 -- tsc -p tsconfig.json --outDir /tmp/summrise-fresh-bin && cp /tmp/summrise-fresh-bin/summrise.js bin/summrise.js && grep -q \"summrise-release\" bin/summrise.js && rm -rf /tmp/summrise-electron-fresh /tmp/summrise-fresh-bin",
-    "test": "node --test"
+    "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;
+}