dsh-builtin-browser 0.1.14 → 0.1.16

package/lib/browser/runtime.js

@@ -8,8 +8,8 @@
  */
 import { Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import { BrowserError } from "./types.js";
-export { BrowserError, } from "./types.js";
+import { BrowserError } from './types.js';
+export { BrowserError, } from './types.js';
 /**
  * The browser access service. Registered as `ctx.browser` (one instance per
  * context).
@@ -79,8 +79,8 @@ export class BrowserRuntime extends Service {
         return single;
     }
     /** Open a new browser session through the selected provider. */
-    async open() {
-        return this.resolveProvider().open();
+    async open(label) {
+        return this.resolveProvider().open(label);
     }
     /** Open a URL through the selected provider, optionally in a new tab. */
     async openUrl(session, request, signal) {
@@ -110,26 +110,78 @@ export class BrowserRuntime extends Service {
     async execute(session, request, signal) {
         return this.resolveProvider().execute(session, request, signal);
     }
+    /** Wait until the session's page is ready (and optional URL/selector match). */
+    async waitFor(session, request, signal) {
+        return this.resolveProvider().waitFor(session, request, signal);
+    }
     /** Produce an AI-friendly snapshot of the session's page. */
     async snapshot(session, signal) {
         return this.resolveProvider().snapshot(session, signal);
     }
+    /** Read the session's page accessibility tree through the selected provider. */
+    async a11y(session, request, signal) {
+        return this.resolveProvider().a11y(session, request, signal);
+    }
+    /** Reload the session's active tab through the selected provider. */
+    async reload(session, signal) {
+        return this.resolveProvider().reload(session, signal);
+    }
     /** Fetch page content in a requested format. */
     async content(session, request, signal) {
         return this.resolveProvider().content(session, request, signal);
     }
-    /** Click at viewport coordinates through the selected provider. */
+    /** Click at viewport coordinates (or a located element) through the selected provider. */
     async click(session, request, signal) {
         return this.resolveProvider().click(session, request, signal);
     }
-    /** Type into the focused element through the selected provider. */
+    /** Type into the focused element (or a located one) through the selected provider. */
     async type(session, request, signal) {
         return this.resolveProvider().type(session, request, signal);
     }
+    /** Scroll the session's page through the selected provider. */
+    async scroll(session, request, signal) {
+        return this.resolveProvider().scroll(session, request, signal);
+    }
+    /** Go back in the session's page history through the selected provider. */
+    async back(session, signal) {
+        return this.resolveProvider().back(session, signal);
+    }
+    /** Go forward in the session's page history through the selected provider. */
+    async forward(session, signal) {
+        return this.resolveProvider().forward(session, signal);
+    }
+    /** Press one named key through the selected provider. */
+    async key(session, request, signal) {
+        return this.resolveProvider().key(session, request, signal);
+    }
     /** Fill a form's fields in one batch through the selected provider. */
     async fillForm(session, request, signal) {
         return this.resolveProvider().fillForm(session, request, signal);
     }
+    /** Set one element's value through the selected provider. */
+    async setValue(session, request, signal) {
+        return this.resolveProvider().setValue(session, request, signal);
+    }
+    /** Check or uncheck one checkbox/radio through the selected provider. */
+    async check(session, request, signal) {
+        return this.resolveProvider().check(session, request, signal);
+    }
+    /** Select one option of a `<select>` through the selected provider. */
+    async selectOption(session, request, signal) {
+        return this.resolveProvider().selectOption(session, request, signal);
+    }
+    /** Clear one element through the selected provider. */
+    async clearField(session, request, signal) {
+        return this.resolveProvider().clearField(session, request, signal);
+    }
+    /** Read one element's value through the selected provider. */
+    async getValue(session, request, signal) {
+        return this.resolveProvider().getValue(session, request, signal);
+    }
+    /** Extract structured data through the selected provider. */
+    async scrape(session, request, signal) {
+        return this.resolveProvider().scrape(session, request, signal);
+    }
     /** Capture the current page through the selected provider. */
     async screenshot(session, request, signal) {
         return this.resolveProvider().screenshot(session, request, signal);

package/lib/browser/types.d.ts

@@ -20,7 +20,11 @@ export type BrowserSessionId = string;
  * minimal so a provider swap never changes how the model asks.
  */
 export interface BrowserNavigateRequest {
-    /** The URL to open. Admission (HTTP(S) only, no credentials/private targets) is provider-owned. */
+    /**
+     * The URL to open. Admission (HTTP(S) only) is provider-owned; the seam
+     * itself does not police credentials or private/localhost targets — a
+     * shared real browser legitimately reaches local dev servers.
+     */
     readonly url: string;
 }
 /**
@@ -39,6 +43,132 @@ export interface BrowserTypeRequest {
     /** The text to insert. */
     readonly text: string;
 }
+/** Scroll the page: by pixel deltas, to an element, or to top/bottom. */
+export interface BrowserScrollRequest {
+    /** Horizontal delta in CSS pixels. */
+    readonly deltaX?: number;
+    /** Vertical delta in CSS pixels. */
+    readonly deltaY?: number;
+    /** Scroll the given selector's element into view (top document; same-origin iframes reachable via execute). */
+    readonly selector?: string;
+    /** Scroll to the top of the page. */
+    readonly toTop?: boolean;
+    /** Scroll to the bottom of the page. */
+    readonly toBottom?: boolean;
+}
+/** Press one named key (Enter, Tab, arrows, …). */
+export interface BrowserKeyRequest {
+    /** Key name from the supported set (see the browser_key tool). */
+    readonly key: string;
+}
+/**
+ * How to find one element for a targeted interaction (form controls, clicks,
+ * typing). `text` matches an element's own visible text — exact first, then
+ * contains, deepest element preferred (so a button inside a card wins over
+ * the card itself).
+ */
+export interface BrowserElementTarget {
+    /** Locator kind. */
+    readonly by: 'css' | 'text' | 'xpath';
+    /** The CSS selector / visible text / XPath expression. */
+    readonly value: string;
+    /** 0-based index of the match to use. Default 0. */
+    readonly index?: number;
+}
+/** Set the value of one input/textarea/select/contenteditable. */
+export interface BrowserSetValueRequest {
+    /** The element to set (css/text/xpath). */
+    readonly target: BrowserElementTarget;
+    /** The value to set (string, number, or boolean). */
+    readonly value: string | number | boolean;
+    /** Element-lookup budget in ms. Default 5000. */
+    readonly timeoutMs?: number;
+}
+/** Result of a single setValue. */
+export interface BrowserSetValueResult {
+    /** How the value was applied: input | textarea | select | contenteditable. */
+    readonly method: string;
+    /** The value as applied. */
+    readonly value: string;
+}
+/** Check/uncheck one checkbox or radio. */
+export interface BrowserCheckRequest {
+    /** The element to toggle (css/text/xpath). */
+    readonly target: BrowserElementTarget;
+    /** Desired state. Default true (check). */
+    readonly checked?: boolean;
+    /** Element-lookup budget in ms. Default 5000. */
+    readonly timeoutMs?: number;
+}
+/** Select one option of a `<select>`, by value, visible text, or index. */
+export interface BrowserSelectRequest {
+    /** The `<select>` element (css/text/xpath). */
+    readonly target: BrowserElementTarget;
+    /** Match the option by its value attribute. */
+    readonly optionValue?: string;
+    /** Match the option by its visible text. */
+    readonly optionText?: string;
+    /** Match the option by its 0-based index. */
+    readonly optionIndex?: number;
+    /** Element-lookup budget in ms. Default 5000. */
+    readonly timeoutMs?: number;
+}
+/** Result of a single select. */
+export interface BrowserSelectResult {
+    /** The selected option's value attribute. */
+    readonly value: string;
+    /** The selected option's visible text. */
+    readonly text: string;
+}
+/** Clear one input/textarea/contenteditable (or uncheck a checkbox/radio). */
+export interface BrowserClearRequest {
+    /** The element to clear (css/text/xpath). */
+    readonly target: BrowserElementTarget;
+    /** Element-lookup budget in ms. Default 5000. */
+    readonly timeoutMs?: number;
+}
+/** Read one element's current value (for verification). */
+export interface BrowserGetValueRequest {
+    /** The element to read (css/text/xpath). */
+    readonly target: BrowserElementTarget;
+    /** Element-lookup budget in ms. Default 5000. */
+    readonly timeoutMs?: number;
+}
+/** Result of a getValue. */
+export interface BrowserGetValueResult {
+    /** The element's value; null when the element has none (e.g. a checkbox). */
+    readonly value: string | null;
+    /** For checkbox/radio: the checked state. */
+    readonly checked?: boolean;
+    /** For `<select>`: the selected option's visible text. */
+    readonly selectedText?: string;
+}
+/** One field of a scrape: a name plus a selector (optionally `selector@attr`). */
+export interface BrowserScrapeField {
+    /** Output key. */
+    readonly name: string;
+    /**
+     * CSS selector relative to each item; append `@attr` to take an attribute
+     * instead of text (`a@href` returns an absolute URL for links).
+     */
+    readonly selector: string;
+}
+/** Extract structured data from repeated DOM items (static, CSP-safe). */
+export interface BrowserScrapeRequest {
+    /** Required: CSS selector of each result container (e.g. `div.card`). */
+    readonly item: string;
+    /** Field map: name -> selector[@attr]. */
+    readonly fields: readonly BrowserScrapeField[];
+    /** Wait budget for the item selector to appear. Default 5000. */
+    readonly timeoutMs?: number;
+}
+/** Structured extraction result. */
+export interface BrowserScrapeResult {
+    /** Number of items extracted. */
+    readonly count: number;
+    /** One object per item; missing fields are null. */
+    readonly items: readonly Record<string, string | null>[];
+}
 /** One field of a batch form fill. Match by selector, or by name/label/placeholder. */
 export interface BrowserFillField {
     /** CSS selector; when present, candidates are scoped to it. */
@@ -81,6 +211,27 @@ export interface BrowserFillResult {
     /** Whether the containing form was submitted. */
     readonly submitted: boolean;
 }
+/** Wait request: poll until the page is ready (and optional URL/selector). */
+export interface BrowserWaitRequest {
+    /** Maximum wait in ms. Default 30000. */
+    readonly timeoutMs?: number;
+    /**
+     * Optional URL the top document must show (exact or prefix match). Pass the
+     * URL you navigated to — this distinguishes the NEW document from the old
+     * one still on screen while navigation is in flight.
+     */
+    readonly url?: string;
+    /** Optional CSS selector that must exist (top document or same-origin frames). */
+    readonly selector?: string;
+    /** Wait for the page load (readyState complete). Default true. */
+    readonly loaded?: boolean;
+}
+/** Outcome of a wait: whether the condition was met before the budget ran out. */
+export interface BrowserWaitResult {
+    readonly ready: boolean;
+    /** Why the wait ended: 'condition met' or a short explanation of the miss. */
+    readonly reason: string;
+}
 /**
  * A screenshot of the current page state. `dataUrl` is a base64 data URL the
  * tool layer renders directly; the live view itself never crosses the wire
@@ -92,12 +243,24 @@ export interface BrowserScreenshotResult {
     /** File path the capture was also saved to, when the request asked for it. */
     readonly path?: string;
 }
-/** Screenshot capture options. PNG only (CDP JPEG hangs on Electron 43). */
+/** Screenshot capture options. */
 export interface BrowserScreenshotRequest {
     /** Capture the full scrollable page instead of the viewport. Default false. */
     readonly fullPage?: boolean;
-    /** Absolute file path to also save the PNG to (for vision-tool reads). */
+    /** Absolute file path to also save the image to (for vision-tool reads). */
     readonly savePath?: string;
+    /**
+     * Image format. Default 'png'. JPEG is only available on the self-hosted
+     * native capture path; the desktop-shell CDP fallback always returns PNG
+     * (CDP JPEG hangs on Electron 43 — a documented platform defect).
+     */
+    readonly format?: 'png' | 'jpeg';
+    /** JPEG quality 1-100 (default 80); ignored for PNG. */
+    readonly quality?: number;
+    /** Downscale to fit within this width (aspect preserved). */
+    readonly maxWidth?: number;
+    /** Downscale to fit within this height (aspect preserved). */
+    readonly maxHeight?: number;
 }
 /** Download options: fetch a URL into a local file, keeping the session's cookies. */
 export interface BrowserDownloadRequest {
@@ -159,6 +322,12 @@ export interface BrowserSnapshotElement {
     /** Viewport-relative center, for coordinate fallbacks. */
     readonly x: number;
     readonly y: number;
+    /**
+     * True when the element lives inside an (same-origin) iframe: coordinates
+     * are still top-document, but DOM selectors are frame-scoped — reach the
+     * element via `iframe.contentDocument` in browser_execute.
+     */
+    readonly frame?: boolean;
 }
 /**
  * AI-friendly page snapshot: a compact, numbered inventory of interactive
@@ -176,6 +345,53 @@ export interface BrowserSnapshotResult {
     /** Human-verification challenge blocking the page, when one is detected. */
     readonly challenge?: BrowserChallenge;
 }
+/**
+ * One node of the accessibility tree, with a stable reference number the
+ * model can cite. Roles/names prefer Chrome's `computedRole`/`computedName`
+ * with tag/attribute inference as fallback; coordinates are top-document
+ * viewport-relative so the node can also be driven by click/type.
+ */
+export interface BrowserA11yNode {
+    /** 1-based reference number, stable for the lifetime of one a11y call. */
+    readonly ref: number;
+    /** ARIA role: button | link | textbox | checkbox | radio | combobox | … */
+    readonly role: string;
+    /** Accessible name (aria-label, label text, placeholder, own text, …). */
+    readonly name: string;
+    /** Current value of input-like nodes (null when not applicable). */
+    readonly value: string | null;
+    /** ARIA/DOM states: enabled/disabled/checked/unchecked/expanded/… */
+    readonly states: readonly string[];
+    /** DOM depth (within its document), for reconstructing the tree. */
+    readonly depth: number;
+    /** Element tag name (lowercase). */
+    readonly tag: string;
+    /** Viewport-relative center, for coordinate fallbacks. */
+    readonly x: number;
+    readonly y: number;
+    /** True when the node lives inside a same-origin iframe. */
+    readonly frame?: boolean;
+}
+/** A11y tree request: what to include and how many nodes to return. */
+export interface BrowserA11yRequest {
+    /** Include hidden elements (display:none, hidden, aria-hidden). Default false. */
+    readonly includeHidden?: boolean;
+    /** Maximum nodes returned. Default 500; clamped to 10-5000. */
+    readonly maxNodes?: number;
+}
+/** The page's accessibility tree, flattened into a numbered node list. */
+export interface BrowserA11yResult {
+    /** Final page URL. */
+    readonly url: string;
+    /** Page title, if any. */
+    readonly title?: string;
+    /** Number of nodes returned. */
+    readonly count: number;
+    /** Flattened a11y nodes (depth restores the tree). */
+    readonly nodes: readonly BrowserA11yNode[];
+    /** True when the result was truncated (maxNodes reached). */
+    readonly truncated: boolean;
+}
 /**
  * A detected human-verification (bot-detection / CAPTCHA) challenge blocking
  * the page. Detection is best-effort and marker-based; a clean result is not a
@@ -245,8 +461,11 @@ export interface BrowserProvider {
      * Open a new session. The provider mints the session id and prepares its
      * backing surface (a view, a headless page, and so on). Sessions are isolated from
      * each other; a session must not be visible to any other session's caller.
+     * @param label - optional human-readable label (e.g. the calling DSH task
+     * id) the provider may surface on the visible surface (window title) so a
+     * human can tell which task's page is currently shown.
      */
-    open(): Promise<BrowserSessionId>;
+    open(label?: string): Promise<BrowserSessionId>;
     /** Open a URL, optionally in a new tab. Honor `signal` for cancellation. */
     openUrl(session: BrowserSessionId, request: BrowserOpenRequest, signal?: AbortSignal): Promise<void>;
     /** List the session's tabs. */
@@ -261,16 +480,56 @@ export interface BrowserProvider {
     navigate(session: BrowserSessionId, request: BrowserNavigateRequest, signal?: AbortSignal): Promise<void>;
     /** Execute JS in the active tab's page context. */
     execute(session: BrowserSessionId, request: BrowserExecuteRequest, signal?: AbortSignal): Promise<BrowserExecuteResult>;
+    /** Wait until the page is ready (and optional URL/selector match). Honor `signal` for cancellation. */
+    waitFor(session: BrowserSessionId, request: BrowserWaitRequest, signal?: AbortSignal): Promise<BrowserWaitResult>;
     /** Produce an AI-friendly snapshot of the active tab. */
     snapshot(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserSnapshotResult>;
+    /** Read the active tab's accessibility tree (semantic, interactive nodes). */
+    a11y(session: BrowserSessionId, request: BrowserA11yRequest, signal?: AbortSignal): Promise<BrowserA11yResult>;
+    /** Reload the active tab. Honor `signal` for cancellation. */
+    reload(session: BrowserSessionId, signal?: AbortSignal): Promise<void>;
     /** Check whether a human-verification challenge is blocking the active tab. */
     detectChallenge(session: BrowserSessionId, signal?: AbortSignal): Promise<BrowserChallenge>;
     /** Fetch page content in a requested format. */
     content(session: BrowserSessionId, request: BrowserContentRequest, signal?: AbortSignal): Promise<BrowserContentResult>;
-    /** Click at viewport coordinates (fallback path; execute is preferred). Honor `signal` for cancellation. */
-    click(session: BrowserSessionId, request: BrowserClickRequest, signal?: AbortSignal): Promise<void>;
-    /** Type into the focused element (fallback path). Honor `signal` for cancellation. */
-    type(session: BrowserSessionId, request: BrowserTypeRequest, signal?: AbortSignal): Promise<void>;
+    /**
+     * Click at viewport coordinates, or at a located element's center when the
+     * request carries a `target`. Honor `signal` for cancellation.
+     */
+    click(session: BrowserSessionId, request: BrowserClickRequest | {
+        readonly target: BrowserElementTarget;
+    }, signal?: AbortSignal): Promise<void>;
+    /**
+     * Type into the focused element, or focus a located element first when the
+     * request carries a `target`. Honor `signal` for cancellation.
+     */
+    type(session: BrowserSessionId, request: BrowserTypeRequest | {
+        readonly target: BrowserElementTarget;
+    }, signal?: AbortSignal): Promise<void>;
+    /** Set one element's value (native setter + input/change events). */
+    setValue(session: BrowserSessionId, request: BrowserSetValueRequest, signal?: AbortSignal): Promise<BrowserSetValueResult>;
+    /** Check or uncheck one checkbox/radio. */
+    check(session: BrowserSessionId, request: BrowserCheckRequest, signal?: AbortSignal): Promise<{
+        readonly checked: boolean;
+    }>;
+    /** Select one option of a `<select>`. */
+    selectOption(session: BrowserSessionId, request: BrowserSelectRequest, signal?: AbortSignal): Promise<BrowserSelectResult>;
+    /** Clear one input/textarea/contenteditable (or uncheck). */
+    clearField(session: BrowserSessionId, request: BrowserClearRequest, signal?: AbortSignal): Promise<{
+        readonly cleared: boolean;
+    }>;
+    /** Read one element's current value (for verification). */
+    getValue(session: BrowserSessionId, request: BrowserGetValueRequest, signal?: AbortSignal): Promise<BrowserGetValueResult>;
+    /** Extract structured data from repeated DOM items (static CSS, CSP-safe). */
+    scrape(session: BrowserSessionId, request: BrowserScrapeRequest, signal?: AbortSignal): Promise<BrowserScrapeResult>;
+    /** Scroll the active tab. Honor `signal` for cancellation. */
+    scroll(session: BrowserSessionId, request: BrowserScrollRequest, signal?: AbortSignal): Promise<void>;
+    /** Go back in the active tab's history. Honor `signal` for cancellation. */
+    back(session: BrowserSessionId, signal?: AbortSignal): Promise<void>;
+    /** Go forward in the active tab's history. Honor `signal` for cancellation. */
+    forward(session: BrowserSessionId, signal?: AbortSignal): Promise<void>;
+    /** Press one named key (Enter/Tab/arrows/…). Honor `signal` for cancellation. */
+    key(session: BrowserSessionId, request: BrowserKeyRequest, signal?: AbortSignal): Promise<void>;
     /** Fill a form's fields in one batch. Honor `signal` for cancellation. */
     fillForm(session: BrowserSessionId, request: BrowserFillRequest, signal?: AbortSignal): Promise<BrowserFillResult>;
     /** Capture the current page. Honor `signal` for cancellation. */

package/lib/browser-electron/entry.d.ts

@@ -11,11 +11,11 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import type { BrowserRuntime } from '../browser/runtime.ts';
-import type { ElectronBrowserViewHost } from './provider.ts';
-export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.ts';
-export type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.ts';
-export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.ts';
+import type { BrowserRuntime } from '../browser/runtime.js';
+import type { ElectronBrowserViewHost } from './provider.js';
+export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.js';
+export type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
+export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "browser-electron";
 /** The browser seam this provider registers into. */
@@ -26,6 +26,16 @@ export interface Config {
     readonly viewHost?: ElectronBrowserViewHost;
     /** Allow navigation only to HTTP(S) URLs. Default true. */
     readonly httpOnly?: boolean;
+    /**
+     * Directory `browser_download` save paths must resolve inside (prevents a
+     * prompt-injected agent from writing arbitrary machine paths). Default:
+     * the user's Downloads folder; override to confine downloads elsewhere.
+     */
+    readonly downloadDir?: string;
+    /** Maximum snapshot elements before truncation. Default 60. */
+    readonly snapshotMaxElements?: number;
+    /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
+    readonly contentMaxChars?: number;
 }
 export declare const Config: z<Config>;
 /** Register the Electron browser provider with `ctx.browser`. */

package/lib/browser-electron/entry.js

@@ -10,10 +10,10 @@
  * @module dsh-browser/browser-electron
  */
 import z from '@deepseek-ai/schemastery';
-import { ElectronBrowserProvider } from "./provider.js";
-import { defaultHostMainPath, RemoteElectronViewHost } from "./remote-host.js";
-export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from "./provider.js";
-export { RemoteElectronViewHost, defaultHostMainPath } from "./remote-host.js";
+import { ElectronBrowserProvider } from './provider.js';
+import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js';
+export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.js';
+export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'browser-electron';
 /** The browser seam this provider registers into. */
@@ -22,6 +22,9 @@ export const Config = z.object({
     // Absent on surfaces without a desktop shell; the plugin self-hosts then.
     viewHost: z.any(),
     httpOnly: z.boolean().default(true),
+    downloadDir: z.string(),
+    snapshotMaxElements: z.number(),
+    contentMaxChars: z.number(),
 });
 /** Register the Electron browser provider with `ctx.browser`. */
 export function apply(ctx, config) {
@@ -32,7 +35,12 @@ export function apply(ctx, config) {
     // is bound to the seam's own fiber (the browser row), so a reload of this
     // row would otherwise collide with the still-registered provider
     // (BROWSER_DUPLICATE_PROVIDER) or leave a stale provider behind.
-    const unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, { httpOnly: config.httpOnly }));
+    const unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, {
+        httpOnly: config.httpOnly,
+        downloadDir: config.downloadDir,
+        snapshotMaxElements: config.snapshotMaxElements,
+        contentMaxChars: config.contentMaxChars,
+    }));
     ctx.effect(() => () => {
         unregister();
         if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {

package/lib/browser-electron/host-main.d.ts

@@ -1,14 +1,23 @@
 /**
  * Self-hosted Electron browser host (child side): the Electron main process
- * spawned by {@link RemoteElectronViewHost}. Owns one `BrowserWindow` plus
- * `WebContentsView`s and their `webContents.debugger` (CDP), and answers
- * line-delimited JSON-RPC on stdio.
+ * spawned by {@link RemoteElectronViewHost}. Owns one `BrowserWindow` PER
+ * SESSION (each session's views live in their own window) plus a browser
+ * toolbar (address bar, back/forward/reload, tab strip) that makes the
+ * built-in browser usable as a real browser by the human — every window has
+ * its own toolbar. Views are `WebContentsView`s driven over
+ * `webContents.debugger` (CDP); user toolbar actions are routed back to the
+ * parent so the agent and the human always share one tab/navigation model.
  *
  * Protocol (one JSON object per line, both directions):
  *   <- { id, op: 'ping' } | { id, op: 'createView', viewId } |
  *      { id, op: 'destroyView', viewId } | { id, op: 'showView', viewId } |
- *      { id, op: 'command', viewId, method, params }
+ *      { id, op: 'groupView', viewId, windowId, label? } |
+ *      { id, op: 'command', viewId, method, params } |
+ *      { id, op: 'userActionError', windowId, message }
+ *   -> { id: 0, op: 'hello', token } (our FIRST message — proves we know the
+ *      parent's stdin token; the parent refuses the connection otherwise)
  *   -> { id, ok: true, result? } | { id, ok: false, err }
+ *   -> { id: 0, op: 'userAction', action } (fire-and-forget; no reply)
  *
  * The parent never parses stderr, so diagnostics may go there freely.
  * @module dsh-browser/browser-electron/host-main