dsh-builtin-browser 0.1.23 → 0.3.0

package/lib/browser-electron/entry.js

@@ -11,7 +11,13 @@
  */
 import z from '@deepseek-ai/schemastery';
 import { ElectronBrowserProvider } from './provider.js';
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js';
+import { DesktopBridgeViewHost } from './desktop-bridge-host.js';
+import { detectBrowser, SystemBrowserViewHost } from './system-browser.js';
+import { SettingsStore } from './settings-store.js';
 export { ELECTRON_BROWSER_PROVIDER_ID, ElectronBrowserProvider, } from './provider.js';
 export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
 /** Cordis plugin name used by loader diagnostics. */
@@ -28,23 +34,201 @@ export const Config = z.object({
 });
 /** Register the Electron browser provider with `ctx.browser`. */
 export function apply(ctx, config) {
-    // External host (desktop shell) wins; otherwise self-host. The self-hosted
-    // child is disposed with the fiber, mirroring the shell's lifetime.
-    const host = config.viewHost ?? new RemoteElectronViewHost(defaultHostMainPath());
-    // Own the disposer on THIS plugin's fiber: registerBrowserProvider's effect
-    // 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, {
+    // One settings document per plugin instance: the settings panel writes it, the
+    // provider reads it live, and both ends agree on the same file.
+    const settings = new SettingsStore();
+    installSettingsRoute(ctx, settings);
+    const providerConfig = {
         httpOnly: config.httpOnly,
         downloadDir: config.downloadDir,
         snapshotMaxElements: config.snapshotMaxElements,
         contentMaxChars: config.contentMaxChars,
-    }));
+        settings: () => settings.get(),
+    };
+    // A host supplied by the composition (the desktop shell's own seam) wins and is
+    // synchronous, so registration stays synchronous on that path.
+    if (config.viewHost !== undefined) {
+        const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost, providerConfig));
+        ctx.effect(() => () => { external(); });
+        return;
+    }
+    // Otherwise start self-hosted — a working browser from the first call, on every
+    // surface — and upgrade to the desktop sidebar if this machine has one. The
+    // upgrade is deliberately a swap of the whole provider: the two carriers own
+    // different lifetimes (a spawned child vs. the shell's view), and pretending
+    // otherwise would leave a stray window behind.
+    const selfHosted = new RemoteElectronViewHost(defaultHostMainPath());
+    let unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(selfHosted, providerConfig));
+    let upgraded = false;
     ctx.effect(() => () => {
         unregister();
-        if (config.viewHost === undefined && host instanceof RemoteElectronViewHost) {
-            host.dispose();
+        selfHosted.dispose();
+    });
+    /**
+     * Swap the provider to another carrier, releasing the previous one.
+     * @param host - the carrier to adopt.
+     * @param note - a one-line description for the log.
+     */
+    const adopt = (host, note) => {
+        if (upgraded) {
+            host.dispose?.();
+            return;
+        }
+        upgraded = true;
+        try {
+            unregister();
+            unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, providerConfig));
+            selfHosted.dispose();
+            ctx.logger?.info?.(`dsh-builtin-browser: ${note}`);
+        }
+        catch (error) {
+            // Never leave the surface without a provider.
+            unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(new RemoteElectronViewHost(defaultHostMainPath()), providerConfig));
+            ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`);
+        }
+    };
+    // A browser the user explicitly asked for outranks every automatic choice: the
+    // whole point of the setting is that they know which browser they want. It is
+    // launched with a plugin-owned profile, so their own windows are untouched.
+    void (async () => {
+        const channel = settings.get().browser.channel;
+        if (channel === 'bundled')
+            return;
+        const detected = detectBrowser(channel);
+        if (detected === undefined) {
+            ctx.logger?.warn?.(`dsh-builtin-browser: ${channel} was requested but no installation was found; using the bundled browser`);
+            return;
+        }
+        const home = process.env.DSH_HOME ?? homedir();
+        // Login state lives in the browser profile, so the cookies setting decides where
+        // that profile goes: a stable directory keeps the user signed in across restarts
+        // (the point of using their own browser), while turning persistence off gets a
+        // throwaway directory that is removed when the browser is released.
+        const persist = settings.get().cookies.persist;
+        const profileDir = persist
+            ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
+            : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`);
+        const host = await SystemBrowserViewHost.launch(detected, profileDir, [], persist ? undefined : profileDir);
+        if (host === undefined) {
+            ctx.logger?.warn?.(`dsh-builtin-browser: ${detected.kind} did not start; using the bundled browser`);
+            return;
         }
+        adopt(host, `driving the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`);
+    })().catch(() => { });
+    void DesktopBridgeViewHost.discover().then(sidebar => {
+        // No bridge (plain `dsh web`, an older desktop build, or a shell that already
+        // exited): keep self-hosting, which is what every surface has always done.
+        if (sidebar === undefined)
+            return;
+        adopt(sidebar, 'driving the desktop sidebar browser');
+    }).catch(() => { });
+}
+/** Route the settings panel reads and writes. */
+const SETTINGS_ROUTE = '/dsh-builtin-browser/settings';
+/**
+ * Expose the settings document over the host's web server, which is how the
+ * settings panel reads and writes it. A host without that service (headless /
+ * CLI surfaces) simply skips this: the panel is then unreachable and the file
+ * stays hand-editable — never a plugin-startup failure.
+ * @param ctx - the plugin context.
+ * @param settings - the settings document to expose.
+ */
+function installSettingsRoute(ctx, settings) {
+    const inject = ctx.inject;
+    if (typeof inject !== 'function')
+        return;
+    try {
+        inject(['webServer'], (host) => {
+            host.effect(() => host.webServer.register({
+                kind: 'exact',
+                path: SETTINGS_ROUTE,
+                handler: (request, response) => handleSettingsRequest(request, response, settings),
+            }, 'dsh-builtin-browser: settings'));
+        });
+    }
+    catch {
+        // No web server on this surface: the settings file remains the interface.
+    }
+}
+/**
+ * Same-origin guard. Settings are machine-local configuration, so a page loaded
+ * elsewhere must not be able to read or rewrite them.
+ * @param request - the incoming request.
+ * @returns whether the request may touch the settings document.
+ */
+function sameOrigin(request) {
+    const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase();
+    if (site === 'cross-site')
+        return false;
+    const origin = String(request.headers.origin ?? '').trim();
+    if (origin === 'null')
+        return false;
+    if (origin === '')
+        return true;
+    try {
+        return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One settings round-trip: `GET` reads the document, `PUT`/`POST` merges a
+ * partial patch into it.
+ * @param request - the incoming request.
+ * @param response - the response to write.
+ * @param settings - the settings document.
+ */
+async function handleSettingsRequest(request, response, settings) {
+    const json = (status, body) => {
+        response.writeHead(status, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+        });
+        response.end(JSON.stringify(body));
+    };
+    if (!sameOrigin(request)) {
+        json(403, { ok: false, error: 'cross-origin request refused' });
+        return;
+    }
+    const method = request.method ?? 'GET';
+    if (method === 'GET') {
+        json(200, { ok: true, settings: settings.get(), path: settings.path() });
+        return;
+    }
+    if (method !== 'PUT' && method !== 'POST') {
+        response.writeHead(405, { allow: 'GET, PUT' });
+        response.end();
+        return;
+    }
+    try {
+        const body = await readBody(request);
+        const patch = body.trim() === '' ? {} : JSON.parse(body);
+        json(200, { ok: true, settings: settings.update(patch) });
+    }
+    catch (error) {
+        json(400, { ok: false, error: `invalid settings patch: ${String(error)}` });
+    }
+}
+/**
+ * Read a request body with a hard cap (the settings patch is tiny, and an
+ * unbounded read would let any same-origin caller exhaust memory).
+ * @param request - the incoming request.
+ * @param limit - maximum accepted characters.
+ * @returns the body text.
+ */
+function readBody(request, limit = 64 * 1024) {
+    return new Promise((resolve, reject) => {
+        let text = '';
+        request.setEncoding('utf8');
+        request.on('data', chunk => {
+            text += String(chunk);
+            if (text.length > limit) {
+                request.destroy();
+                reject(new Error('settings patch too large'));
+            }
+        });
+        request.on('end', () => resolve(text));
+        request.on('error', reject);
     });
 }

package/lib/browser-electron/history-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Persistent browsing history: which pages the shared browser actually visited,
+ * kept independently from any session's operation log (`browser_history`) and
+ * from the browser process's lifetime.
+ *
+ * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/
+ * history.jsonl`), so it follows the same persistence rules as the login state:
+ * closing the interface releases the process, never the record.
+ *
+ * Format: one JSON object per line, append-only. Appending stays cheap for a
+ * long session, and a half-written tail (crash, power loss) is dropped on read
+ * instead of poisoning the whole file.
+ * @module dsh-browser/browser-electron/history-store
+ */
+import type { VisitedPage } from '../browser/types.js';
+export type { VisitedPage };
+/** Retention limits; whichever is hit first starts trimming. */
+export interface HistoryLimits {
+    /** Maximum retained entries. Default 5000. */
+    readonly maxEntries?: number;
+    /** Maximum age in days. Default 90. */
+    readonly maxAgeDays?: number;
+}
+/**
+ * Absolute path of the browsing-history file, beside the browser profile so the
+ * record shares the login state's persistence rules.
+ * @returns the history file path.
+ */
+export declare function visitedHistoryPath(): string;
+/**
+ * Append-only browsing history with bounded retention. Every method tolerates a
+ * missing or damaged file: recording a visit must never fail a navigation, and
+ * a corrupted line must never hide the rest of the history.
+ */
+export declare class HistoryStore {
+    private readonly file;
+    private readonly maxEntries;
+    private readonly maxAgeMs;
+    /**
+     * @param file - absolute path of the JSONL history file.
+     * @param limits - retention overrides (entry count and age).
+     */
+    constructor(file?: string, limits?: HistoryLimits);
+    /** Whether the history file exists yet (diagnostics and tests). */
+    exists(): boolean;
+    /**
+     * Record one visit. Failures are swallowed by design: history is a
+     * convenience, and losing an entry must never break the tool call that
+     * produced it.
+     * @param page - the visited page.
+     */
+    append(page: VisitedPage): void;
+    /**
+     * Read visits, newest first. Unparseable lines are skipped; entries older
+     * than the age limit are filtered out but left on disk until the next prune.
+     * @param options - optional result cap plus three filters: `domain` (hostname),
+     *   `query` (substring of the URL or title) and `session` (the task that visited
+     *   it). Filters compose, so "the pages THIS task opened on that host" is one call.
+     * @returns the matching visits, newest first.
+     */
+    list(options?: {
+        readonly limit?: number;
+        readonly domain?: string;
+        readonly query?: string;
+        readonly session?: string;
+    }): VisitedPage[];
+    /**
+     * Enforce retention: drop entries past the age limit, then the oldest beyond
+     * the count cap. Cheap no-op until the file grows past the cap, so callers can
+     * run it after every append.
+     */
+    prune(): void;
+    /** Parse the whole file, skipping blank and damaged lines. */
+    private readAll;
+}

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

@@ -0,0 +1,162 @@
+/**
+ * Persistent browsing history: which pages the shared browser actually visited,
+ * kept independently from any session's operation log (`browser_history`) and
+ * from the browser process's lifetime.
+ *
+ * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/
+ * history.jsonl`), so it follows the same persistence rules as the login state:
+ * closing the interface releases the process, never the record.
+ *
+ * Format: one JSON object per line, append-only. Appending stays cheap for a
+ * long session, and a half-written tail (crash, power loss) is dropped on read
+ * instead of poisoning the whole file.
+ * @module dsh-browser/browser-electron/history-store
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Default entry cap — mirrors the documented retention rule. */
+const DEFAULT_MAX_ENTRIES = 5_000;
+/** Default age cap in days. */
+const DEFAULT_MAX_AGE_DAYS = 90;
+/** Rewrite the file only once it has grown this far past the cap. */
+const PRUNE_SLACK = 500;
+/**
+ * Absolute path of the browsing-history file, beside the browser profile so the
+ * record shares the login state's persistence rules.
+ * @returns the history file path.
+ */
+export function visitedHistoryPath() {
+    const home = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(home, 'dsh-builtin-browser-host', 'history.jsonl');
+}
+/**
+ * Append-only browsing history with bounded retention. Every method tolerates a
+ * missing or damaged file: recording a visit must never fail a navigation, and
+ * a corrupted line must never hide the rest of the history.
+ */
+export class HistoryStore {
+    file;
+    maxEntries;
+    maxAgeMs;
+    /**
+     * @param file - absolute path of the JSONL history file.
+     * @param limits - retention overrides (entry count and age).
+     */
+    constructor(file = visitedHistoryPath(), limits = {}) {
+        this.file = file;
+        this.maxEntries = limits.maxEntries ?? DEFAULT_MAX_ENTRIES;
+        this.maxAgeMs = (limits.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS) * 24 * 60 * 60 * 1000;
+    }
+    /** Whether the history file exists yet (diagnostics and tests). */
+    exists() {
+        return existsSync(this.file);
+    }
+    /**
+     * Record one visit. Failures are swallowed by design: history is a
+     * convenience, and losing an entry must never break the tool call that
+     * produced it.
+     * @param page - the visited page.
+     */
+    append(page) {
+        try {
+            mkdirSync(dirname(this.file), { recursive: true });
+            appendFileSync(this.file, `${JSON.stringify(page)}\n`);
+        }
+        catch {
+            // Best-effort: history is not worth failing a navigation over.
+        }
+    }
+    /**
+     * Read visits, newest first. Unparseable lines are skipped; entries older
+     * than the age limit are filtered out but left on disk until the next prune.
+     * @param options - optional result cap plus three filters: `domain` (hostname),
+     *   `query` (substring of the URL or title) and `session` (the task that visited
+     *   it). Filters compose, so "the pages THIS task opened on that host" is one call.
+     * @returns the matching visits, newest first.
+     */
+    list(options = {}) {
+        const all = this.readAll();
+        const cutoff = Date.now() - this.maxAgeMs;
+        const domain = options.domain?.toLowerCase();
+        const query = options.query?.toLowerCase();
+        const session = options.session;
+        const matches = all.filter(page => {
+            if (page.at < cutoff)
+                return false;
+            if (session !== undefined && page.session !== session)
+                return false;
+            if (query !== undefined) {
+                const haystack = `${page.url}\n${page.title ?? ''}`.toLowerCase();
+                if (!haystack.includes(query))
+                    return false;
+            }
+            if (domain === undefined)
+                return true;
+            try {
+                return new URL(page.url).hostname.toLowerCase().includes(domain);
+            }
+            catch {
+                return page.url.toLowerCase().includes(domain);
+            }
+        });
+        matches.reverse();
+        return options.limit === undefined ? matches : matches.slice(0, Math.max(0, options.limit));
+    }
+    /**
+     * Enforce retention: drop entries past the age limit, then the oldest beyond
+     * the count cap. Cheap no-op until the file grows past the cap, so callers can
+     * run it after every append.
+     */
+    prune() {
+        const all = this.readAll();
+        const cutoff = Date.now() - this.maxAgeMs;
+        const fresh = all.filter(page => page.at >= cutoff);
+        const kept = fresh.length > this.maxEntries ? fresh.slice(fresh.length - this.maxEntries) : fresh;
+        // Only rewrite when something actually fell off, and only once the excess
+        // is worth a full rewrite.
+        if (kept.length === all.length)
+            return;
+        if (all.length - kept.length < PRUNE_SLACK && fresh.length <= this.maxEntries)
+            return;
+        try {
+            const body = kept.map(page => `${JSON.stringify(page)}\n`).join('');
+            writeFileSync(this.file, body);
+        }
+        catch {
+            // Best-effort: an unpruned file still reads correctly.
+        }
+    }
+    /** Parse the whole file, skipping blank and damaged lines. */
+    readAll() {
+        let raw;
+        try {
+            raw = readFileSync(this.file, 'utf8');
+        }
+        catch {
+            return [];
+        }
+        const pages = [];
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed === '')
+                continue;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (typeof parsed.at !== 'number' || typeof parsed.url !== 'string')
+                    continue;
+                pages.push({
+                    at: parsed.at,
+                    url: parsed.url,
+                    ...typeof parsed.title === 'string' && parsed.title !== '' ? { title: parsed.title } : {},
+                    ...typeof parsed.session === 'string' && parsed.session !== '' ? { session: parsed.session } : {},
+                });
+            }
+            catch {
+                // A damaged line (typically a truncated tail) must not hide the rest.
+                continue;
+            }
+        }
+        return pages;
+    }
+}

package/lib/browser-electron/host-main.js

@@ -338,7 +338,34 @@ function windowFor(windowId) {
     if (existing !== undefined)
         return existing;
     const w = new BrowserWindow({ width: 1400, height: 900, show: true, title: 'dsh-browser' });
-    w.on('closed', () => { windows.delete(key); });
+    w.on('closed', () => {
+        const closing = windows.get(key);
+        windows.delete(key);
+        // A BrowserWindow does not destroy its child views: their webContents (the
+        // renderer process, its timers and audio) outlive the window unless closed
+        // explicitly, so release them here instead of leaking a renderer per window.
+        if (closing !== undefined) {
+            for (const view of closing.views.values()) {
+                try {
+                    view.webContentsView.webContents.close();
+                }
+                catch {
+                    // Already destroyed along with the window.
+                }
+            }
+            closing.views.clear();
+        }
+        // The interface is gone for good. Report it, so the plugin ends that session
+        // instead of holding one whose window the human already closed. Browsing
+        // history and login state live on disk, so the next open starts a clean
+        // session rather than resurrecting this one.
+        try {
+            rpcSocket?.write(JSON.stringify({ id: 0, op: 'viewClosed', windowId: key }) + '\n');
+        }
+        catch {
+            // Socket already gone (parent shutting down): nothing left to report to.
+        }
+    });
     const win = { windowId: key, window: w, toolbarView: undefined, views: new Map(), visibleViewId: undefined, lastFocusedViewId: undefined, closeTimer: undefined };
     // Keep every view (and the toolbar) filling the window as the human
     // resizes it; otherwise pages stay at their original size and break.

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

@@ -6,6 +6,8 @@
  * shell that owns the `BrowserWindow`.
  * @module dsh-browser/browser-electron
  */
+import { type VisitedPage } from './history-store.js';
+import type { BrowserSettings } from './settings-store.js';
 import type { BrowserA11yRequest, BrowserA11yResult, BrowserChallenge, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserHistoryEntry, BrowserOpenRequest, BrowserProvider, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, ExportedCookie } from '../browser/types.js';
 /** Stable provider id registered with `ctx.browser`. */
 export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
@@ -78,6 +80,38 @@ export interface ElectronBrowserViewHost {
      * @param handler - called for every user action; must not throw.
      */
     onUserAction?(handler: (action: BrowserUserAction) => void): void;
+    /**
+     * Optional: receive notice that the human closed a browser window. Closing the
+     * interface ends the session it showed — the next call opens a clean one —
+     * while browsing history and login state survive on disk.
+     * @param handler - called with the group (session) key; must not throw.
+     */
+    onViewClosed?(handler: (windowId: string) => void): void;
+    /**
+     * Release the service's page(s) without ending the plugin's own lifetime.
+     *
+     * Only carriers that outlive a browser session need this. A self-hosted window
+     * dies with its view, but the desktop shell's sidebar keeps running no matter
+     * what the plugin does — so "release the browser when the session ends"
+     * (settings: ui.closeWithSession) has to be asked for explicitly there.
+     * @returns a promise that settles once the release was attempted.
+     */
+    releasePage?(): Promise<void>;
+    /**
+     * Fold the carrier's presentation away while keeping the page alive.
+     *
+     * The desktop sidebar keeps running regardless of the plugin, so "do not take
+     * over the screen" (settings: ui.autoExpandOnce = false) can only be honoured by
+     * asking the shell to fold it. A self-hosted window has no such state and simply
+     * does not implement this.
+     * @returns a promise that settles once the fold was attempted.
+     */
+    collapse?(): Promise<void>;
+    /**
+     * Release everything the carrier owns (a spawned browser, a socket, a child).
+     * Called when the plugin stops using it, never while it is still in service.
+     */
+    dispose?(): void;
 }
 /**
  * A user-initiated browser action from the host's own UI (toolbar). The
@@ -137,6 +171,28 @@ export interface ElectronViewHandle {
 export interface ElectronBrowserProviderConfig {
     /** Allow navigation only to HTTP(S) URLs; reject anything else. Default true. */
     readonly httpOnly?: boolean;
+    /**
+     * Persistent browsing history (visited pages), independent of session
+     * lifetime. `enabled: false` keeps the browser working but records nothing;
+     * the retained limits ride along so a user's choice from the settings panel
+     * reaches the store without a second configuration path.
+     */
+    readonly history?: {
+        readonly enabled?: boolean;
+        readonly maxEntries?: number;
+        readonly maxAgeDays?: number;
+        /**
+         * Explicit history file path. Default: beside the browser profile
+         * (`$DSH_HOME/dsh-builtin-browser-host/history.jsonl`).
+         */
+        readonly file?: string;
+    };
+    /**
+     * Live settings source (the settings panel's document). When present it wins
+     * over the static `history` config, so a switch flipped in the UI takes effect
+     * without restarting DSH.
+     */
+    readonly settings?: () => BrowserSettings;
     /** Maximum snapshot elements before truncation. Default 60. */
     readonly snapshotMaxElements?: number;
     /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
@@ -208,6 +264,13 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private readonly snapshotMaxElements;
     private readonly contentMaxChars;
     private readonly downloadDir;
+    /**
+     * Persistent browsing history, or `undefined` when the user turned it off.
+     * Sessions come and go; this record outlives all of them.
+     */
+    private readonly historyStore;
+    /** Live settings source; absent when nothing owns a settings document. */
+    private readonly settingsSource;
     constructor(host: ElectronBrowserViewHost, config?: ElectronBrowserProviderConfig);
     /**
      * Usable when the host says it can back views (the self-hosted host probes
@@ -447,6 +510,39 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private record;
     /** Return the session's chronological operation log (newest last). */
     history(session: BrowserSessionId): Promise<readonly BrowserHistoryEntry[]>;
+    /**
+     * Record one page visit in the persistent browsing history. Fire-and-forget by
+     * design: a visit must never delay or fail the navigation that produced it,
+     * and the title is only worth reading once the document has settled.
+     * @param s - the session that drove the visit.
+     * @param handle - the view whose document just loaded.
+     */
+    private recordVisit;
+    /**
+     * List persisted visits, newest first — what `browser_visited` reads back.
+     * @param options - result cap and an optional hostname filter.
+     * @returns the matching visits, or an empty list when history is disabled.
+     */
+    visited(options?: {
+        readonly limit?: number;
+        readonly domain?: string;
+        readonly query?: string;
+        readonly session?: string;
+    }): readonly VisitedPage[];
+    /**
+     * Show the synthetic pointer on a view, unless the user switched it off. The
+     * cursor is the "the agent has taken over this tab" signal, so it is painted
+     * for every operation that has a landing point — including DOM-level ones that
+     * move no real pointer.
+     * @param handle - the view to paint into.
+     * @param x - viewport x in CSS pixels.
+     * @param y - viewport y in CSS pixels.
+     * @param action - click pulses a ripple; move only relocates.
+     * @param label - short description of the operation, shown beside the pointer.
+     * @param force - paint even when the pointer is already there (a click ripple must
+     *   always play; a bare move need not repeat).
+     */
+    private showCursor;
     /**
      * Replay one recorded operation by sequence number. Navigate/click/type are
      * re-issued against the current page; execute re-runs its script. The
@@ -465,6 +561,20 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private newTab;
     /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
     private tabByViewId;
+    /**
+     * Whether a session is still live. The human closing a window ends its session
+     * (see {@link handleViewClosed}), so callers that cache ids must ask first.
+     * @param session - the session id to test.
+     */
+    exists(session: BrowserSessionId): boolean;
+    /**
+     * The human closed a browser window: the session that window showed is over.
+     * Ending it here is what makes the next call a clean start rather than a
+     * resurrection of an invisible window. Browsing history and login state live
+     * on disk, so nothing the human cares about is lost with it.
+     * @param windowId - the group key the host reported, which is the session id.
+     */
+    private handleViewClosed;
     /**
      * Route a user-initiated action from the host's UI into the session model.
      * Fire-and-forget by design: a user action failing (e.g. an unreachable
@@ -472,7 +582,18 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * is reported to the host (toolbar) when the host supports it, else logged.
      */
     private handleUserAction;
-    /** Report a failed user action to the host UI (toolbar), when supported. */
+    /**
+     * Report a failed user action to the host UI (toolbar), when supported.
+     *
+     * Two properties matter here, because this runs inside the catch of an async
+     * handler (issue #16):
+     *  - the receiver must be preserved. Reading the method off the host and calling
+     *    it unbound runs the host's implementation with `this === undefined`, so its
+     *    very first statement (`void this.ready()`) throws, the throw escapes the
+     *    async catch as an unhandled rejection, and the whole DSH host exits;
+     *  - this method must be incapable of throwing. Reporting a failed action is
+     *    diagnostics: it can never be allowed to become the failure.
+     */
     private notifyUserActionError;
     /** Ask the host to show the active tab's view, carrying the session label. */
     private showActive;