dsh-builtin-browser 0.4.2 → 0.4.5

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

@@ -36,6 +36,22 @@ import { join } from 'node:path';
  * exited, and that exit was reported as a bad browser path.
  */
 const EXIT_GRACE_MS = 3_000;
+/**
+ * Ceiling on one attempt to ask a discovered CDP port who it is.
+ *
+ * The launch loop below polls: it reads `DevToolsActivePort`, tries `/json/version` on the port
+ * inside it, and waits 250 ms between attempts under a 30 s deadline. An unbounded fetch can
+ * park inside one iteration for the whole budget, so a bound is needed — but it has to be
+ * small enough that the loop still behaves like a loop.
+ *
+ * The usual case is NOT a slow answer, it is NO answer: a browser that has written the file but
+ * is not listening yet refuses the connection instantly, and that immediacy is what lets the
+ * loop spin. Any timeout added here is paid on every iteration in which the port is not ready,
+ * so an earlier attempt at this used 2000 ms — eight times the poll interval — and cut the
+ * attempts available in the budget from roughly 120 to 15. This value is the same size as the
+ * interval, so a worst-case iteration costs 500 ms and the budget still affords ~60 attempts.
+ */
+const PORT_PROBE_MS = 250;
 /** The real launcher: spawn a detached-free child with pipes closed. */
 const defaultLauncher = (path, args) => spawn(path, [...args], { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
 import { spawn } from 'node:child_process';
@@ -441,6 +457,18 @@ export class SystemBrowserViewHost {
             return false;
         }
     }
+    /**
+     * Forget which browser issued what, after that browser is gone.
+     *
+     * The two maps must move together: `views` maps a view id to a session id and `sessions`
+     * maps a session id to a target id, so clearing one alone leaves a mapping the next command
+     * will act on. Every path that abandons a browser calls this rather than spelling the pair
+     * out — four separate copies is how the third one came to be missing.
+     */
+    forgetBrowserState() {
+        this.views.clear();
+        this.sessions.clear();
+    }
     async ensureClient() {
         // A disposed host must never start a browser: doing so would spawn a process
         // nobody owns and nobody will kill.
@@ -469,8 +497,7 @@ export class SystemBrowserViewHost {
             // child left to kill: the process already exited, its exit listener already set
             // `this.child` to undefined, so start() skips that branch and publishes a new browser
             // while the views still point at the dead one. That is the state that never recovers.
-            this.views.clear();
-            this.sessions.clear();
+            this.forgetBrowserState();
         }
         // Concurrent first calls share one startup rather than racing two browsers.
         this.starting ??= this.start().finally(() => { this.starting = undefined; });
@@ -514,8 +541,7 @@ export class SystemBrowserViewHost {
             // heard of them — the "Session with given id not found" loop, which never clears.
             this.client?.close();
             this.client = undefined;
-            this.views.clear();
-            this.sessions.clear();
+            this.forgetBrowserState();
             // Wait for it to actually die. kill() only sends the signal: on Windows it is
             // TerminateProcess, which is asynchronous, and the browser may still hold this profile's
             // singleton lock for a while. Spawning immediately meant the replacement saw an existing
@@ -585,8 +611,7 @@ export class SystemBrowserViewHost {
             // The pages this client opened belong to the process that just died; keeping their
             // session ids means every later command is sent to a browser that never issued them.
             // Clearing these is what makes the restart usable rather than merely alive.
-            this.views.clear();
-            this.sessions.clear();
+            this.forgetBrowserState();
         });
         const portFile = join(this.profileDir, 'DevToolsActivePort');
         /**
@@ -643,7 +668,11 @@ export class SystemBrowserViewHost {
                 stopped = 'timeout';
                 break;
             }
-            if (child.exitCode !== null) {
+            // signalCode too: a browser killed by a signal never sets exitCode, so checking exitCode
+            // alone made a killed browser look alive and the launch run out its full 30s deadline
+            // before reporting "did not expose CDP" — a timeout for something that died at once.
+            // The sibling check on the release path already looked at both.
+            if (child.exitCode !== null || child.signalCode !== null) {
                 if (this.child === child)
                     this.child = undefined;
                 stopped = 'exited';
@@ -654,9 +683,19 @@ export class SystemBrowserViewHost {
             const port = freshPort();
             if (port !== undefined) {
                 try {
-                    const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json();
+                    const version = await (await fetch(`http://127.0.0.1:${port}/json/version`, {
+                        // Bounded: an unanswered loopback request would otherwise park inside this
+                        // iteration for the rest of the budget, and the deadline above is only re-checked
+                        // between iterations. Deliberately no larger than the 250 ms sleep — see
+                        // PORT_PROBE_MS.
+                        signal: AbortSignal.timeout(PORT_PROBE_MS),
+                    })).json();
                     if (typeof version.webSocketDebuggerUrl === 'string') {
                         const client = new CdpClient(version.webSocketDebuggerUrl);
+                        // `whenReady` has its own 30 s ceiling, and it is reached only after the port
+                        // answered above — so the browser is listening and this is a handshake, not a
+                        // discovery. A handshake that outlives the launch is reported as the timeout it
+                        // is, by the same deadline that governs everything else here.
                         await client.whenReady();
                         // Still wanted? A dispose() during the handshake has already killed the
                         // process, so publishing the client would leave a dangling connection.
@@ -682,14 +721,22 @@ export class SystemBrowserViewHost {
             throw new Error(`dsh-builtin-browser: could not launch ${target}: ${launchError?.message ?? 'unknown error'}`);
         }
         if (stopped === 'exited') {
-            // Exit code 0 is the whole story here: the browser decided to hand the request to an
-            // instance that already owns this profile directory and quit, rather than failing. That is
-            // what a leftover browser from a previous run (or a second DSH on the same profile) looks
-            // like. "Check that the path is a runnable browser" pointed at the one cause that is almost
-            // never it, and sent people looking for a broken install that was not there.
-            throw new Error(`dsh-builtin-browser: ${target} exited immediately after launch (exit code ${child.exitCode}). `
-                + 'That exit code means it handed the request to an instance already using this profile '
-                + 'directory and quit — look for a leftover browser process from an earlier run, then retry.');
+            // Only exit code 0 is the hand-off story. A non-zero code or a signal means the browser
+            // died on its own — a crash, a missing library, a sandbox refusal — and asserting the
+            // profile story for those sent people looking for a leftover process that was not there,
+            // which is the same mistake this message was written to correct, pointing the other way.
+            const code = child.exitCode;
+            const signal = child.signalCode;
+            const clean = code === 0 && signal === null;
+            throw new Error(clean
+                ? `dsh-builtin-browser: ${target} exited immediately after launch (exit code 0). `
+                    + 'That means it handed the request to an instance already using this profile '
+                    + 'directory and quit — look for a leftover browser process from an earlier run, then retry.'
+                : `dsh-builtin-browser: ${target} exited immediately after launch `
+                    + `(${signal !== null ? `killed by ${signal}` : `exit code ${String(code)}`}), so it did not `
+                    + 'hand the request anywhere — the browser failed to start rather than deferring to another '
+                    + 'instance. Check that it can run at all: run it by hand, and look for a crash or a missing '
+                    + 'dependency rather than a leftover process.');
         }
         if (stopped === 'released') {
             throw new Error(`dsh-builtin-browser: ${target} was released while it was starting`);
@@ -755,8 +802,17 @@ export class SystemBrowserViewHost {
                     if (!client.isAlive()) {
                         // Only THIS call's client. Under concurrency the field may already hold a
                         // connection another call just published, and closing that would kill a healthy one.
-                        if (this.client === client)
+                        if (this.client === client) {
                             this.client = undefined;
+                            // This is the third of the three paths that discard a client, and it was the one
+                            // that did not retire what the client had issued. A view holding a session id
+                            // from the dead browser kept handing it to the replacement, which had never heard
+                            // of it: every page command then failed with "Session with given id not found"
+                            // and no later call could clear it, because the cached session was returned
+                            // unconditionally. Gated on the same identity check as the field itself, so a
+                            // concurrent call that just published a healthy client does not lose its maps.
+                            this.forgetBrowserState();
+                        }
                         client.close();
                     }
                     throw error;
@@ -782,10 +838,31 @@ export class SystemBrowserViewHost {
     }
     /** Nothing to show: the browser owns its own windows. */
     showView() { }
-    /** Same as {@link showView}. */
-    async presentView() { }
-    /** The browser owns window grouping. */
-    groupView() { }
+    /**
+     * Bring the target's page to the front, then report success.
+     *
+     * The comment on `focus` below used to say this was impossible — that raising the page needs
+     * `Page.bringToFront` on a target session, which is a view-level concern the host cannot
+     * reach. The handle this method is handed IS that view, and it can send commands, so the
+     * capability was here all along; it just was not used. Without it `presentView` was an empty
+     * async method, so the provider's whole presentation barrier — the one that stops
+     * `Input.*` from being silently dropped for a view with no display surface, and reports
+     * `BROWSER_VIEW_NOT_PRESENTED` when it cannot present — never ran on this carrier.
+     *
+     * A failure is swallowed rather than propagated: a real Chrome window that refuses to come
+     * forward is not a reason to refuse the click that follows. The barrier exists to order the
+     * two, and the order is honoured either way.
+     * @param handle - the view to present.
+     */
+    async presentView(handle) {
+        try {
+            await handle.sendCommand('Page.bringToFront');
+        }
+        catch {
+            // Backgrounded, minimised, or a target that went away between the snapshot and the
+            // click. The command that called this will report its own failure if the page is gone.
+        }
+    }
     /**
      * Best effort at bringing the browser's window forward.
      *
@@ -804,10 +881,6 @@ export class SystemBrowserViewHost {
         }
         catch { /* Windows has no SIGCONT; nothing to do */ }
     }
-    /** The browser reports its own window lifecycle. */
-    onUserAction() { }
-    /** The browser reports its own window lifecycle. */
-    onViewClosed() { }
     /**
      * Close the browser we launched, if we ever launched one.
      *
@@ -819,8 +892,7 @@ export class SystemBrowserViewHost {
         if (this.disposed)
             return;
         this.disposed = true;
-        this.views.clear();
-        this.sessions.clear();
+        this.forgetBrowserState();
         this.client?.close();
         try {
             this.child?.kill();
@@ -869,6 +941,21 @@ export class SystemBrowserViewHost {
      * a second copy of that rule.
      */
     async ensureSession(viewId) {
+        // One target per view, even when two commands arrive together. The two CDP round trips
+        // below are awaits, so without this a second caller entering during the first's flight saw
+        // no session in `views` and created its own target — leaving an orphan page that nothing
+        // closes, because only the last id survives in the map.
+        const inFlight = this.sessionBuilding.get(viewId);
+        if (inFlight !== undefined)
+            return await inFlight;
+        const building = this.buildSession(viewId).finally(() => {
+            this.sessionBuilding.delete(viewId);
+        });
+        this.sessionBuilding.set(viewId, building);
+        return await building;
+    }
+    /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
+    async buildSession(viewId) {
         const client = await this.ensureClient();
         const created = await client.send('Target.createTarget', { url: 'about:blank' });
         const targetId = created?.targetId;
@@ -883,6 +970,8 @@ export class SystemBrowserViewHost {
         this.views.set(viewId, { session: sessionId, client });
         return sessionId;
     }
+    /** Views whose session is being created right now, so a second caller waits for the first. */
+    sessionBuilding = new Map();
     /** sessionId -> targetId, so a destroyed view can close the right page. */
     sessions = new Map();
 }

package/lib/index.js

@@ -22,7 +22,6 @@ export const name = 'dsh-builtin-browser';
  * 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';

package/lib/tool-browser/element-fields.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The element and node field sets, declared once.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * The same field set used to be written out in four places: the page script produced an
+ * object, `types.ts` declared its shape, a tool's `execute` rebuilt it as an explicit list,
+ * and the tool's `output.schema` declared the properties. Nothing connected them, and the
+ * result is this project's most repeatable bug:
+ *
+ *   - `browser_a11y`'s `selector` — computed by the provider, declared by the schema,
+ *     printed by the renderer, and dropped by the projection. 134 tests stayed green.
+ *   - `browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
+ *     schema, and dropped by the projection. 172 tests stayed green. It was found a round
+ *     later, by reading the three places that agree and noticing the fourth did not.
+ *
+ * A hand-written allow-list is invisible to the type checker (it is an object literal) and to
+ * the tests (nothing ran a tool). The fix is not a careful list; it is one list. Both the
+ * schema fragment and the projection are derived from the tables below, so a field cannot be
+ * present in one and absent from the other.
+ *
+ * The schema is the dangerous half: `additionalProperties: false` means a field the schema
+ * does NOT declare causes the ENTIRE result to be rejected at run time, while a field the
+ * projection forgets is silently dropped. One table cannot get either wrong on its own.
+ */
+/**
+ * The `elements` item schema for browser_snapshot and browser_open.
+ *
+ * Written as a literal rather than generated, because `defineTool` validates the output schema
+ * against its own `ValueSchemaSpec` and a generated `Record<string, …>` is too wide to satisfy
+ * it. The field table above remains the single source of truth: `tests/element-fields.test.mjs`
+ * asserts that these properties and `projectElement`'s output are exactly the table's keys, so
+ * the two cannot drift even though one is typed by hand.
+ */
+export declare const ELEMENT_ITEM_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly ref: {
+            readonly type: "number";
+            readonly required: true;
+        };
+        readonly kind: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly label: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly selector: {
+            readonly type: "string";
+        };
+        readonly x: {
+            readonly type: "number";
+            readonly required: true;
+        };
+        readonly y: {
+            readonly type: "number";
+            readonly required: true;
+        };
+        readonly frame: {
+            readonly type: "boolean";
+        };
+    };
+};
+/**
+ * The `nodes` item schema for browser_a11y.
+ *
+ * Same reasoning as {@link ELEMENT_ITEM_SCHEMA}: literal for the type checker, table-backed by
+ * test.
+ */
+export declare const NODE_ITEM_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly ref: {
+            readonly type: "number";
+            readonly required: true;
+        };
+        readonly role: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly name: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly value: {
+            readonly type: "string";
+        };
+        readonly states: {
+            readonly type: "array";
+            readonly required: true;
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly depth: {
+            readonly type: "number";
+            readonly required: true;
+        };
+        readonly tag: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly selector: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly x: {
+            readonly type: "number";
+            readonly required: true;
+        };
+        readonly y: {
+            readonly type: "number";
+            readonly required: true;
+        };
+        readonly frame: {
+            readonly type: "boolean";
+        };
+    };
+};
+/**
+ * Project one snapshot element into the shape the schema declares.
+ *
+ * Generic in the source type so the caller keeps the precise shape `defineTool` inferred from
+ * the schema: the projection decides which fields survive at run time, and the field table is
+ * what guarantees that set matches the schema. Widening the return type here would only move
+ * the mismatch to the call site.
+ * @param element - the element as the provider produced it.
+ * @returns exactly the declared fields.
+ */
+export declare function projectElement<T extends object>(element: T): T;
+/**
+ * Project one accessibility node into the shape the schema declares.
+ * @param node - the node as the provider produced it.
+ * @returns exactly the declared fields.
+ */
+export declare function projectNode<T extends object>(node: T): T;
+/** The field names each table declares, for tests that check the two stay in step. */
+export declare const DECLARED_FIELDS: {
+    readonly element: string[];
+    readonly node: string[];
+};

package/lib/tool-browser/element-fields.js

@@ -0,0 +1,152 @@
+/**
+ * The element and node field sets, declared once.
+ *
+ * WHY THIS FILE EXISTS
+ *
+ * The same field set used to be written out in four places: the page script produced an
+ * object, `types.ts` declared its shape, a tool's `execute` rebuilt it as an explicit list,
+ * and the tool's `output.schema` declared the properties. Nothing connected them, and the
+ * result is this project's most repeatable bug:
+ *
+ *   - `browser_a11y`'s `selector` — computed by the provider, declared by the schema,
+ *     printed by the renderer, and dropped by the projection. 134 tests stayed green.
+ *   - `browser_screenshot`'s `width`/`height` — measured by the provider, declared by the
+ *     schema, and dropped by the projection. 172 tests stayed green. It was found a round
+ *     later, by reading the three places that agree and noticing the fourth did not.
+ *
+ * A hand-written allow-list is invisible to the type checker (it is an object literal) and to
+ * the tests (nothing ran a tool). The fix is not a careful list; it is one list. Both the
+ * schema fragment and the projection are derived from the tables below, so a field cannot be
+ * present in one and absent from the other.
+ *
+ * The schema is the dangerous half: `additionalProperties: false` means a field the schema
+ * does NOT declare causes the ENTIRE result to be rejected at run time, while a field the
+ * projection forgets is silently dropped. One table cannot get either wrong on its own.
+ */
+/**
+ * The fields of one entry in `browser_snapshot` / `browser_open`'s `elements`.
+ *
+ * `selector` is the reason this file exists; see the header. It was added to the schema and
+ * the projection separately, and only one of them landed.
+ */
+const ELEMENT_FIELDS = {
+    ref: { schema: { type: 'number' }, required: true },
+    kind: { schema: { type: 'string' }, required: true },
+    label: { schema: { type: 'string' }, required: true },
+    selector: { schema: { type: 'string' } },
+    x: { schema: { type: 'number' }, required: true },
+    y: { schema: { type: 'number' }, required: true },
+    frame: { schema: { type: 'boolean' } },
+};
+/**
+ * The fields of one entry in `browser_a11y`'s `nodes`.
+ *
+ * Different shape from an element on purpose: a role and an accessible name carry meaning a
+ * tag and a label string do not, and `depth` is what renders the tree.
+ */
+const NODE_FIELDS = {
+    ref: { schema: { type: 'number' }, required: true },
+    role: { schema: { type: 'string' }, required: true },
+    name: { schema: { type: 'string' }, required: true },
+    value: { schema: { type: 'string' } },
+    states: { schema: { type: 'array', items: { type: 'string' } }, required: true },
+    depth: { schema: { type: 'number' }, required: true },
+    tag: { schema: { type: 'string' }, required: true },
+    // Always present: the provider derives it for every node and yields an empty string when the
+    // element has neither an id nor a name. Declaring it optional described a shape the provider
+    // never produced, and the type said required — the same disagreement, one level down.
+    selector: { schema: { type: 'string' }, required: true },
+    x: { schema: { type: 'number' }, required: true },
+    y: { schema: { type: 'number' }, required: true },
+    frame: { schema: { type: 'boolean' } },
+};
+/**
+ * Copy the declared fields out of a source value.
+ *
+ * Reads the table rather than naming fields, so anything the provider produces that the table
+ * declares is carried through, and anything the table does not declare is left out — which is
+ * what keeps the result and the schema in agreement in both directions.
+ * @param fields - the field table to project through.
+ * @param source - the value the provider produced.
+ * @returns a new object holding exactly the declared fields that are present.
+ */
+function project(fields, source) {
+    const out = {};
+    for (const name of Object.keys(fields)) {
+        const value = source[name];
+        if (value !== undefined && value !== null)
+            out[name] = value;
+    }
+    return out;
+}
+/**
+ * The `elements` item schema for browser_snapshot and browser_open.
+ *
+ * Written as a literal rather than generated, because `defineTool` validates the output schema
+ * against its own `ValueSchemaSpec` and a generated `Record<string, …>` is too wide to satisfy
+ * it. The field table above remains the single source of truth: `tests/element-fields.test.mjs`
+ * asserts that these properties and `projectElement`'s output are exactly the table's keys, so
+ * the two cannot drift even though one is typed by hand.
+ */
+export const ELEMENT_ITEM_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ref: { type: 'number', required: true },
+        kind: { type: 'string', required: true },
+        label: { type: 'string', required: true },
+        selector: { type: 'string' },
+        x: { type: 'number', required: true },
+        y: { type: 'number', required: true },
+        frame: { type: 'boolean' },
+    },
+};
+/**
+ * The `nodes` item schema for browser_a11y.
+ *
+ * Same reasoning as {@link ELEMENT_ITEM_SCHEMA}: literal for the type checker, table-backed by
+ * test.
+ */
+export const NODE_ITEM_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ref: { type: 'number', required: true },
+        role: { type: 'string', required: true },
+        name: { type: 'string', required: true },
+        value: { type: 'string' },
+        states: { type: 'array', required: true, items: { type: 'string' } },
+        depth: { type: 'number', required: true },
+        tag: { type: 'string', required: true },
+        selector: { type: 'string', required: true },
+        x: { type: 'number', required: true },
+        y: { type: 'number', required: true },
+        frame: { type: 'boolean' },
+    },
+};
+/**
+ * Project one snapshot element into the shape the schema declares.
+ *
+ * Generic in the source type so the caller keeps the precise shape `defineTool` inferred from
+ * the schema: the projection decides which fields survive at run time, and the field table is
+ * what guarantees that set matches the schema. Widening the return type here would only move
+ * the mismatch to the call site.
+ * @param element - the element as the provider produced it.
+ * @returns exactly the declared fields.
+ */
+export function projectElement(element) {
+    return project(ELEMENT_FIELDS, element);
+}
+/**
+ * Project one accessibility node into the shape the schema declares.
+ * @param node - the node as the provider produced it.
+ * @returns exactly the declared fields.
+ */
+export function projectNode(node) {
+    return project(NODE_FIELDS, node);
+}
+/** The field names each table declares, for tests that check the two stay in step. */
+export const DECLARED_FIELDS = {
+    element: Object.keys(ELEMENT_FIELDS),
+    node: Object.keys(NODE_FIELDS),
+};