dsh-builtin-browser 0.1.23 → 0.3.0

package/lib/browser-electron/system-browser.js

@@ -0,0 +1,322 @@
+/**
+ * Drive the browser the user already has (Chrome / Edge / any Chromium) instead of
+ * the Electron we ship — the same approach Codex Browser Use takes.
+ *
+ * WHY
+ * The bundled Electron is a private copy with its own profile, so it can never see
+ * the logins the user already has in Chrome, and on a managed machine the user may
+ * simply prefer their own browser. Launching their browser with a *separate*
+ * `--user-data-dir` gives us a real Chromium we can drive over CDP without touching
+ * their everyday profile, bookmarks or windows: nothing of theirs is opened, locked
+ * or modified, and closing us never closes them.
+ *
+ * HOW
+ * Chromium exposes CDP on `--remote-debugging-port=0`, and writes the port it chose
+ * into `<profile>/DevToolsActivePort`. That file is the discovery mechanism — no
+ * port guessing, no collisions. From there everything is CDP over one WebSocket:
+ * `Target.createTarget` makes a page, `Target.attachToTarget` (flattened) gives a
+ * session for it, and the plugin's commands ride that session. Node 22 ships a global
+ * `WebSocket`, so this needs no dependency at all.
+ *
+ * WHAT IT IMPLEMENTS
+ * The same `ElectronBrowserViewHost` seam as the self-hosted and sidebar hosts, so
+ * the provider, the tools, history, the cursor and teardown rules are unchanged —
+ * only the carrier differs.
+ * @module dsh-browser/browser-electron/system-browser
+ */
+import { readFileSync, rmSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+/**
+ * Where each Chromium product installs on Windows, plus the registry paths that
+ * survive a non-default install location. Only paths that exist are returned, so a
+ * caller can tell "not installed" from "installed elsewhere".
+ */
+const WINDOWS_LOCATIONS = {
+    chrome: [
+        String.raw `C:\Program Files\Google\Chrome\Application\chrome.exe`,
+        String.raw `C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+    ],
+    edge: [
+        String.raw `C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
+        String.raw `C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+    ],
+    brave: [
+        String.raw `C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
+        String.raw `C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+    ],
+};
+/**
+ * Find an installed Chromium browser.
+ *
+ * `auto` prefers Chrome, then Edge, then Brave — the order reflects how likely each
+ * is to be the browser a user actually chose rather than one Windows shipped.
+ * @param channel - the configured choice; `bundled` never resolves to a system browser.
+ * @param env - environment lookup, injected so tests need no real machine.
+ * @returns the detected browser, or undefined when the choice is unavailable.
+ */
+export function detectBrowser(channel, env = process.env) {
+    if (channel === 'bundled')
+        return undefined;
+    const order = channel === 'auto' ? ['chrome', 'edge', 'brave'] : [channel];
+    for (const kind of order) {
+        const fromEnv = (kind === 'chrome' ? env.DSH_BROWSER_CHROME_PATH : kind === 'edge' ? env.DSH_BROWSER_EDGE_PATH : undefined);
+        if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv))
+            return { kind, path: fromEnv };
+        for (const candidate of WINDOWS_LOCATIONS[kind] ?? []) {
+            if (existsSync(candidate))
+                return { kind, path: candidate };
+        }
+    }
+    return undefined;
+}
+/** One CDP connection to a browser-level WebSocket, with flattened sessions. */
+class CdpClient {
+    url;
+    nextId = 1;
+    pending = new Map();
+    ready;
+    /**
+     * @param url - the browser's `webSocketDebuggerUrl`.
+     */
+    constructor(url) {
+        this.url = url;
+        // Node 22 provides WebSocket globally; no dependency is added for this.
+        const socket = new WebSocket(url);
+        this.socket = socket;
+        this.ready = new Promise((resolve, reject) => {
+            socket.addEventListener('open', () => resolve());
+            socket.addEventListener('error', () => reject(new Error('dsh-builtin-browser: could not reach the browser over CDP')));
+        });
+        socket.addEventListener('message', event => this.onMessage(String(event.data)));
+        socket.addEventListener('close', () => this.fail(new Error('dsh-builtin-browser: the browser closed the CDP connection')));
+    }
+    socket;
+    /** Resolve once the socket is open. */
+    async whenReady() {
+        await this.ready;
+    }
+    /**
+     * Send one CDP command, optionally on an attached session.
+     * @param method - the CDP method.
+     * @param params - its parameters.
+     * @param sessionId - the flattened session to target, when this is a page command.
+     * @returns the CDP result.
+     */
+    async send(method, params, sessionId) {
+        await this.ready;
+        const id = this.nextId++;
+        const message = { id, method, ...params !== undefined ? { params } : {}, ...sessionId !== undefined ? { sessionId } : {} };
+        return await new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.socket.send(JSON.stringify(message));
+            setTimeout(() => {
+                if (this.pending.delete(id))
+                    reject(new Error(`dsh-builtin-browser: ${method} timed out`));
+            }, 30_000).unref?.();
+        });
+    }
+    /** Close the socket. */
+    close() {
+        try {
+            this.socket.close();
+        }
+        catch { /* already closed */ }
+    }
+    /** Route one CDP message to its waiter. */
+    onMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (message.id === undefined)
+            return;
+        const entry = this.pending.get(message.id);
+        if (entry === undefined)
+            return;
+        this.pending.delete(message.id);
+        if (message.error !== undefined)
+            entry.reject(new Error(`dsh-builtin-browser: CDP error: ${message.error.message ?? 'unknown'}`));
+        else
+            entry.resolve(message.result);
+    }
+    /** Fail everything in flight. */
+    fail(error) {
+        const pending = [...this.pending.values()];
+        this.pending.clear();
+        for (const entry of pending)
+            entry.reject(error);
+    }
+}
+/** A system browser driven over CDP, presented as a browser view host. */
+export class SystemBrowserViewHost {
+    child;
+    client;
+    kind;
+    ephemeralDir;
+    views = new Map();
+    disposed = false;
+    /**
+     * @param child - the launched browser process.
+     * @param client - the CDP connection to it.
+     * @param kind - which product this is (for diagnostics).
+     * @param ephemeralDir - a throwaway profile to remove on release, when the user
+     *   has turned persistence off and no login state should outlive the session.
+     */
+    constructor(child, client, kind, ephemeralDir) {
+        this.child = child;
+        this.client = client;
+        this.kind = kind;
+        this.ephemeralDir = ephemeralDir;
+    }
+    /**
+     * @param browser - the detected installation to launch.
+     * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
+     * @param extraArgs - additional Chromium switches.
+     * @param ephemeralDir - a directory to delete when the browser is released, used
+     *   when persistence is switched off so no login state outlives the session.
+     * @returns the host, or undefined when the browser refuses to come up.
+     */
+    static async launch(browser, profileDir, extraArgs = [], ephemeralDir) {
+        const args = [
+            '--remote-debugging-port=0',
+            `--user-data-dir=${profileDir}`,
+            // Behave like a fresh, unattended browser: no first-run UI, no default-browser
+            // prompt, no restore bubble, and no "Chrome is being controlled" infobar.
+            '--no-first-run',
+            '--no-default-browser-check',
+            '--disable-features=Translate,MediaRouter',
+            '--disable-session-crashed-bubble',
+            '--hide-crash-restore-bubble',
+            ...extraArgs,
+            'about:blank',
+        ];
+        const child = spawn(browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
+        const portFile = join(profileDir, 'DevToolsActivePort');
+        const deadline = Date.now() + 30_000;
+        for (;;) {
+            if (Date.now() > deadline) {
+                child.kill();
+                return undefined;
+            }
+            if (child.exitCode !== null)
+                return undefined;
+            if (existsSync(portFile)) {
+                try {
+                    const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '';
+                    if (port !== '') {
+                        const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json();
+                        if (typeof version.webSocketDebuggerUrl === 'string') {
+                            const client = new CdpClient(version.webSocketDebuggerUrl);
+                            await client.whenReady();
+                            return new SystemBrowserViewHost(child, client, browser.kind, ephemeralDir);
+                        }
+                    }
+                }
+                catch {
+                    // The file can exist a moment before the port answers; poll again.
+                }
+            }
+            await new Promise(resolve => setTimeout(resolve, 250));
+        }
+    }
+    /** Whether this host can back views: the CDP connection is live. */
+    available() {
+        return !this.disposed;
+    }
+    createView() {
+        const viewId = randomUUID();
+        return {
+            id: viewId,
+            sendCommand: async (method, params) => {
+                const session = this.views.get(viewId) ?? await this.ensureSession(viewId);
+                const result = await this.client.send(method, params, session);
+                return (result ?? {});
+            },
+        };
+    }
+    destroyView(handle) {
+        const session = this.views.get(handle.id);
+        this.views.delete(handle.id);
+        if (session === undefined)
+            return;
+        // A session id is not a target id: closing the page needs the target the session
+        // was attached to, which is why they are tracked separately.
+        const targetId = this.sessions.get(session);
+        this.sessions.delete(session);
+        if (targetId !== undefined) {
+            // Best-effort: a page that is already gone is not an error.
+            void this.client.send('Target.closeTarget', { targetId }).catch(() => undefined);
+        }
+    }
+    /** Nothing to show: the browser owns its own windows. */
+    showView() { }
+    /** Same as {@link showView}. */
+    async presentView() { }
+    /** The browser owns window grouping. */
+    groupView() { }
+    /**
+     * Bring the browser's window forward.
+     *
+     * The browser is a separate application, so there is no view to raise; focusing
+     * the process is the closest honest equivalent, and failing to do so (a minimized
+     * window, a locked session) is never worth an error.
+     */
+    async focus() {
+        try {
+            this.child.kill('SIGCONT');
+        }
+        catch { /* not supported on Windows; harmless */ }
+    }
+    /** The browser reports its own window lifecycle. */
+    onUserAction() { }
+    /** The browser reports its own window lifecycle. */
+    onViewClosed() { }
+    /** Close the browser we launched. The user's own windows are a different process. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.views.clear();
+        this.sessions.clear();
+        this.client.close();
+        try {
+            this.child.kill();
+        }
+        catch { /* already gone */ }
+        const ephemeral = this.ephemeralDir;
+        if (ephemeral !== undefined) {
+            // The browser flushes its profile while shutting down, so deleting later avoids
+            // racing it. Leftovers are only a stray temp directory, never a live credential.
+            setTimeout(() => { try {
+                rmSync(ephemeral, { recursive: true, force: true });
+            }
+            catch { /* best effort */ } }, 3_000).unref?.();
+        }
+    }
+    /** The flattened session for a view, creating its page on first use. */
+    async ensureSession(viewId) {
+        const existing = this.views.get(viewId);
+        if (existing !== undefined)
+            return existing;
+        const created = await this.client.send('Target.createTarget', { url: 'about:blank' });
+        const targetId = created?.targetId;
+        if (typeof targetId !== 'string')
+            throw new Error('dsh-builtin-browser: the browser did not create a page');
+        const attached = await this.client.send('Target.attachToTarget', { targetId, flatten: true });
+        const sessionId = attached?.sessionId;
+        if (typeof sessionId !== 'string')
+            throw new Error('dsh-builtin-browser: the browser did not attach to the new page');
+        // The session id is what page commands ride; the target id is what closes it.
+        this.sessions.set(sessionId, targetId);
+        this.views.set(viewId, sessionId);
+        return sessionId;
+    }
+    /** sessionId -> targetId, so a destroyed view can close the right page. */
+    sessions = new Map();
+}

package/lib/browser-electron/virtual-cursor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Synthetic pointer feedback for a human watching the tab: an overlay drawn
+ * INSIDE the page, never the real system pointer. Its presence is the "the agent
+ * has taken over this tab" signal, so it also covers DOM-level operations that
+ * move no pointer at all.
+ *
+ * Implementation notes that matter:
+ * - The overlay is `position: fixed` and positioned from viewport coordinates,
+ *   which is exactly what the element locator already computes and what
+ *   `Input.dispatchMouseEvent` consumes.
+ * - All styling is inline and the ripple uses the Web Animations API: a
+ *   `<style>` element would be subject to the page's `style-src` CSP, an
+ *   injected script is not. Injected page feedback must never be silently
+ *   dropped by a strict CSP.
+ * - Every call is best-effort: feedback is never allowed to fail an operation.
+ * @module dsh-browser/browser-electron/virtual-cursor
+ */
+/** What the pointer is doing at the reported point. */
+export type CursorAction = 'move' | 'click';
+/**
+ * Whether a paint at this position would change anything on screen.
+ * @param handle - the view the overlay belongs to.
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - the action being reported.
+ * @param force - paint even when unchanged (a click ripple must always fire).
+ * @returns true when the overlay should be painted.
+ */
+export declare function cursorNeedsPaint<TView>(handle: TView, x: number, y: number, action: CursorAction, force?: boolean): boolean;
+/**
+ * The in-page expression that materializes or moves the overlay. Idempotent: the
+ * first call creates the nodes, later calls only move them (and pulse).
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - whether to pulse a click ripple at the point.
+ * @param label - optional short description of the operation, shown beside the
+ *   pointer. The overlay is the only "the agent has taken over this tab" signal, so
+ *   saying *what* it is doing is what turns it from a decoration into an account of
+ *   the agent's actions that a human can follow without reading the tool log.
+ * @returns a self-contained expression that evaluates to `true`.
+ */
+export declare function cursorScript(x: number, y: number, action: CursorAction, label?: string): string;
+/**
+ * Forget the remembered position for a view.
+ *
+ * Called when the document is replaced: the overlay lived in the old document and
+ * went with it, so the cache would otherwise claim the pointer is already where it
+ * needs to be and skip every later paint — the pointer would simply never return
+ * after a navigation.
+ * @param handle - the view whose cache should be dropped.
+ */
+export declare function forgetCursor<TView>(handle: TView): void;
+/**
+ * Draw (or move) the pointer overlay on one view's page.
+ *
+ * Fire-and-forget: a page that is mid-navigation, cross-origin-blocked, or
+ * otherwise unable to answer must not turn a successful operation into a
+ * failure, and the navigation that just committed may still be replacing the
+ * document this call would have painted into.
+ * @param handle - the view to paint into.
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - whether to pulse a click ripple.
+ * @param evaluate - the provider's evaluate bridge (keeps the CDP coupling in one place).
+ * @param label - optional short description of the operation, shown beside the pointer.
+ */
+export declare function paintCursor<TView>(handle: TView, x: number, y: number, action: CursorAction, evaluate: (handle: TView, expression: string) => Promise<unknown>, label?: string, force?: boolean): void;

package/lib/browser-electron/virtual-cursor.js

@@ -0,0 +1,141 @@
+/**
+ * Synthetic pointer feedback for a human watching the tab: an overlay drawn
+ * INSIDE the page, never the real system pointer. Its presence is the "the agent
+ * has taken over this tab" signal, so it also covers DOM-level operations that
+ * move no pointer at all.
+ *
+ * Implementation notes that matter:
+ * - The overlay is `position: fixed` and positioned from viewport coordinates,
+ *   which is exactly what the element locator already computes and what
+ *   `Input.dispatchMouseEvent` consumes.
+ * - All styling is inline and the ripple uses the Web Animations API: a
+ *   `<style>` element would be subject to the page's `style-src` CSP, an
+ *   injected script is not. Injected page feedback must never be silently
+ *   dropped by a strict CSP.
+ * - Every call is best-effort: feedback is never allowed to fail an operation.
+ * @module dsh-browser/browser-electron/virtual-cursor
+ */
+/** Element id of the overlay root, stable so repeat calls update one node. */
+const CURSOR_ID = '__dsh_agent_cursor__';
+/**
+ * Where the overlay was last placed, so an unchanged position is not repainted.
+ *
+ * A single tool call issues several CDP commands (locate, click, cursor), and the
+ * cursor is repainted for each one that moves it. Repainting to the same pixel is a
+ * wasted round-trip *and* a visible flicker: the transition restarts from the same
+ * place, which reads as a stutter rather than as movement.
+ */
+const lastPlaced = new WeakMap();
+/**
+ * Whether a paint at this position would change anything on screen.
+ * @param handle - the view the overlay belongs to.
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - the action being reported.
+ * @param force - paint even when unchanged (a click ripple must always fire).
+ * @returns true when the overlay should be painted.
+ */
+export function cursorNeedsPaint(handle, x, y, action, force = false) {
+    if (force)
+        return true;
+    const key = handle;
+    if (key === null || typeof key !== 'object')
+        return true;
+    const previous = lastPlaced.get(key);
+    return previous === undefined || previous.x !== x || previous.y !== y || previous.action !== action;
+}
+/**
+ * The in-page expression that materializes or moves the overlay. Idempotent: the
+ * first call creates the nodes, later calls only move them (and pulse).
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - whether to pulse a click ripple at the point.
+ * @param label - optional short description of the operation, shown beside the
+ *   pointer. The overlay is the only "the agent has taken over this tab" signal, so
+ *   saying *what* it is doing is what turns it from a decoration into an account of
+ *   the agent's actions that a human can follow without reading the tool log.
+ * @returns a self-contained expression that evaluates to `true`.
+ */
+export function cursorScript(x, y, action, label) {
+    return `(() => {
+  const id = ${JSON.stringify(CURSOR_ID)}
+  let root = document.getElementById(id)
+  if (!root) {
+    root = document.createElement('div')
+    root.id = id
+    root.setAttribute('aria-hidden', 'true')
+    root.style.cssText = 'position:fixed;left:0;top:0;width:0;height:0;z-index:2147483647;pointer-events:none;transition:transform 190ms cubic-bezier(.22,.85,.24,1);will-change:transform'
+    const svg = '<svg width="22" height="22" viewBox="0 0 22 22" style="position:absolute;left:-2px;top:-2px;filter:drop-shadow(0 1px 2px rgba(0,0,0,.45))">'
+      + '<path d="M4 2 L4 18 L8.4 13.8 L11.2 19.6 L13.8 18.4 L11 12.8 L17 12.6 Z" fill="#ffffff" stroke="#111111" stroke-width="1.4" stroke-linejoin="round"/></svg>'
+    const ripple = '<span data-dsh-role="ripple" style="position:absolute;left:0;top:0;width:34px;height:34px;margin:-17px 0 0 -17px;border-radius:50%;border:2px solid rgba(64,160,255,.9);opacity:0"></span>'
+    // The bubble sits below-right of the pointer tip and is capped in width so a long
+    // label cannot cover the page it is describing.
+    const bubble = '<span data-dsh-role="bubble" style="position:absolute;left:18px;top:16px;max-width:280px;padding:3px 8px;border-radius:5px;background:rgba(17,17,17,.92);color:#fff;font:12px/1.45 -apple-system,Segoe UI,Roboto,sans-serif;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;opacity:0;box-shadow:0 1px 3px rgba(0,0,0,.4)"></span>'
+    root.innerHTML = svg + ripple + bubble
+    ;(document.body || document.documentElement).appendChild(root)
+  }
+  root.style.transform = 'translate(${x}px, ${y}px)'
+  ${action === 'click' ? `const ripple = root.querySelector('[data-dsh-role="ripple"]')
+  if (ripple && typeof ripple.animate === 'function') {
+    ripple.animate(
+      [{ transform: 'scale(.25)', opacity: 0.95 }, { transform: 'scale(1.6)', opacity: 0 }],
+      { duration: 550, easing: 'ease-out' },
+    )
+  }` : ''}
+  ${label !== undefined && label !== '' ? `const bubble = root.querySelector('[data-dsh-role="bubble"]')
+  if (bubble) {
+    bubble.textContent = ${JSON.stringify(label)}
+    if (typeof bubble.animate === 'function') {
+      // Fade in, hold, fade out: the label is a narration of the action, not a
+      // permanent caption, so a stale one never lingers over later work.
+      bubble.animate(
+        [{ opacity: 0, transform: 'translateY(-3px)' }, { opacity: 1, transform: 'translateY(0)' }, { opacity: 1, offset: 0.6 }, { opacity: 0 }],
+        { duration: 2200, easing: 'ease-out', fill: 'forwards' },
+      )
+    } else {
+      bubble.style.opacity = '1'
+    }
+  }` : ''}
+  return true
+})()`;
+}
+/**
+ * Forget the remembered position for a view.
+ *
+ * Called when the document is replaced: the overlay lived in the old document and
+ * went with it, so the cache would otherwise claim the pointer is already where it
+ * needs to be and skip every later paint — the pointer would simply never return
+ * after a navigation.
+ * @param handle - the view whose cache should be dropped.
+ */
+export function forgetCursor(handle) {
+    const key = handle;
+    if (key !== null && typeof key === 'object')
+        lastPlaced.delete(key);
+}
+/**
+ * Draw (or move) the pointer overlay on one view's page.
+ *
+ * Fire-and-forget: a page that is mid-navigation, cross-origin-blocked, or
+ * otherwise unable to answer must not turn a successful operation into a
+ * failure, and the navigation that just committed may still be replacing the
+ * document this call would have painted into.
+ * @param handle - the view to paint into.
+ * @param x - viewport x in CSS pixels.
+ * @param y - viewport y in CSS pixels.
+ * @param action - whether to pulse a click ripple.
+ * @param evaluate - the provider's evaluate bridge (keeps the CDP coupling in one place).
+ * @param label - optional short description of the operation, shown beside the pointer.
+ */
+export function paintCursor(handle, x, y, action, evaluate, label, force = false) {
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+        return;
+    const roundedX = Math.round(x);
+    const roundedY = Math.round(y);
+    if (!cursorNeedsPaint(handle, roundedX, roundedY, action, force))
+        return;
+    const key = handle;
+    if (key !== null && typeof key === 'object')
+        lastPlaced.set(key, { x: roundedX, y: roundedY, action });
+    void evaluate(handle, cursorScript(roundedX, roundedY, action, label)).catch(() => { });
+}

package/lib/index.d.ts

@@ -4,10 +4,24 @@
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
  *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
  *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
- * This root entry only re-exports for programmatic use; the loader rows are
- * the composition surface.
+ * The capability itself is composed by those rows; this root entry exists for
+ * programmatic imports AND because the host's client-module scan identifies a
+ * package's browser half through a loader row whose specifier resolves to the
+ * PACKAGE ROOT. A row named after a subpath (`dsh-builtin-browser/browser`) is
+ * not a package specifier and is skipped by design, which is why the patch also
+ * registers a row under the bare package name — see cordis.patch.yml.
  * @module dsh-builtin-browser
  */
+/** Plugin identity for the root row (the composition surface is the subpath rows). */
+export declare const name = "dsh-builtin-browser";
+/**
+ * Inert application for the root row: the browser seam, the Electron provider and
+ * the tools are mounted by the subpath rows, so this one only exists to give the
+ * package a loader row named after the package itself. Without it the host's
+ * client scan finds no row to resolve `dsh.client` from, and the settings panel
+ * never reaches the browser (the plugin works, its client half is invisible).
+ */
+export declare function apply(): void;
 export { BrowserError } from './browser/types.js';
 export type { BrowserA11yNode, BrowserA11yRequest, BrowserA11yResult, BrowserChallenge, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentFormat, BrowserContentRequest, BrowserContentResult, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillField, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserNavigateRequest, BrowserOpenRequest, BrowserProvider, BrowserScrapeField, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserScreenshotResult, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotElement, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, ExportedCookie, } from './browser/types.js';
 export { BrowserRuntime } from './browser/runtime.js';

package/lib/index.js

@@ -4,10 +4,26 @@
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
  *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
  *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
- * This root entry only re-exports for programmatic use; the loader rows are
- * the composition surface.
+ * The capability itself is composed by those rows; this root entry exists for
+ * programmatic imports AND because the host's client-module scan identifies a
+ * package's browser half through a loader row whose specifier resolves to the
+ * PACKAGE ROOT. A row named after a subpath (`dsh-builtin-browser/browser`) is
+ * not a package specifier and is skipped by design, which is why the patch also
+ * registers a row under the bare package name — see cordis.patch.yml.
  * @module dsh-builtin-browser
  */
+/** Plugin identity for the root row (the composition surface is the subpath rows). */
+export const name = 'dsh-builtin-browser';
+/**
+ * Inert application for the root row: the browser seam, the Electron provider and
+ * the tools are mounted by the subpath rows, so this one only exists to give the
+ * package a loader row named after the package itself. Without it the host's
+ * client scan finds no row to resolve `dsh.client` from, and the settings panel
+ * never reaches the browser (the plugin works, its client half is invisible).
+ */
+export function apply() {
+    // Intentionally empty: see the module comment above.
+}
 export { BrowserError } from './browser/types.js';
 export { BrowserRuntime } from './browser/runtime.js';
 export { ElectronBrowserProvider } from './browser-electron/provider.js';