@orkestrel/browser 0.0.18 → 0.0.20

package/README.md

@@ -1,14 +1,11 @@
 # @orkestrel/browser
 
-> A lightweight Chrome DevTools Protocol automation layer for Chromium-family
-> browsers: an environment-agnostic core that drives pages, frames, locators, and
-> DOM snapshots over an injected transport, and a Node runtime that finds,
-> launches, and connects to the browser itself.
+> A Chrome DevTools Protocol automation layer for Chromium-family browsers: an
+> environment-agnostic core that drives pages, elements, and readings over an injected transport
+> and publishes them as agent tools, an in-page face that drives a DOM document with native APIs,
+> and a Node runtime that finds, launches, and connects to the browser itself.
 
-Connect to a running browser or launch one with the `createBrowser` function, open a page in its
-default context, and drive that page through locators, trusted input, network control, and DOM
-snapshots. Inject your own `CDPTransportInterface` where the runtime is not Node. Part of the
-`@orkestrel` line.
+Connect to a running browser or launch one with the `createBrowser` function, open a page, and drive it through stable element references and trusted input. Read the page as Markdown in bounded slices, and hand the whole vocabulary to an agent as `@orkestrel/tool` tools with `createBrowserToolset`. Inside a page, `createDocumentToolset` drives a DOM document with native APIs, and `createSocketCDPTransport` carries the core client over the browser's own `WebSocket`. Record a journey, one user intent kept as JSON, from a model's tool calls or a person's gestures on a page, then list, edit, replay, and forget it through the six journey tools, or compile it with `compileBrowserJourney` into a module a developer runs and customizes. Part of the `@orkestrel` line.
 
 ## Install
 
@@ -18,30 +15,49 @@ npm install @orkestrel/browser
 
 ## Requirements
 
-- Node.js >= 22 for the server surface (the core surface is environment-agnostic)
-- ESM and CommonJS builds ship for both the core and server entry points
+The package runs under the following conditions.
+
+- Node.js 22.12.0 or later for the server face; the core runs in any JavaScript environment, and the browser face in a page, a worker, or an extension page.
+- A Chromium-family browser on the host for the server face: Chrome, Chromium, or Microsoft Edge. The package downloads no browser.
+- For `createSocketCDPTransport`, a browser launched with `--remote-allow-origins` naming the caller's origin; the browser refuses the handshake otherwise.
+- For `page.registry`, a browser that exposes the experimental `WebMCP` protocol domain. The configuration reference of Chrome DevTools MCP 1.10.1, read on 2026-09-29, states that its WebMCP tools need Chrome 150 or later launched with `--enable-features=WebMCP`; see [the Chrome DevTools MCP configuration reference](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/configuration.md). Chromium 141 answers `WebMCP.enable` with `-32601`, and `registry.start()` resolves `false` there.
+- ESM and CommonJS builds ship for the core and server entry points, and an ESM build for the browser entry point.
 
 ## Usage
 
-Launch or connect to a browser and drive a page from Node:
+The following fence launches or connects to a browser and drives a page from Node.
 
 ```ts
 import { createBrowser } from '@orkestrel/browser/server'
 
-const browser = createBrowser()
+const browser = createBrowser({ headless: true })
 await browser.connect()
 const page = await browser.create({ url: 'https://example.com' })
-await page.click('#submit')
-const frame = await page.frame('checkout')
-await frame?.fill('[name=email]', 'ada@example.com')
-const snapshot = await page.snapshot({ styles: ['display'] })
-const article = await page.article() // reader-facing prose, boilerplate pruned
+const outline = await page.elements.outline() // the page's text and elements, with references such as e4
+const [email] = await page.elements.find({ role: 'textbox', name: 'Email' })
+await email?.fill('sam@example.test')
+const [save] = await page.elements.find({ role: 'button', name: 'Save' })
+await save?.click()
+await page.wait('Saved')
+const reading = await page.read()
+reading.markdown({ limit: 4_000 }) // { text, offset, total }
 await page.screenshot({ path: 'example.png' })
 await browser.destroy()
 ```
 
-Drive the same protocol from any environment by injecting your own transport
-over the environment-agnostic core:
+The following fence publishes the same page to an agent as tools.
+
+```ts
+import { createBrowserToolset } from '@orkestrel/browser'
+import { createToolManager } from '@orkestrel/tool'
+
+const toolset = createBrowserToolset(page, { tools: createToolManager() })
+await toolset.start()
+await toolset.tools.execute({ id: '1', name: 'look', arguments: { what: 'the form' } })
+await toolset.destroy()
+```
+
+The following fence drives the same protocol from any environment over a transport you inject.
 
 ```ts
 import { createCDPClient } from '@orkestrel/browser'
@@ -52,20 +68,23 @@ const result = await client.send('Page.navigate', { url: 'https://example.com' }
 await client.close()
 ```
 
+## Browse binary
+
+The package ships the `browse` binary, which serves the browser vocabulary and the journey tools over MCP on stdio and launches Chromium on the first tool call, keeping journeys and runs under `tmp/browsers`. Register it for a checkout with `claude mcp add --scope project browse -- node node_modules/@orkestrel/browser/dist/bin/main.js`, which writes the `browse` entry of the project's `.mcp.json`, then start `claude` in the checkout and approve the server; `BROWSE_ROOT`, `BROWSE_HEADLESS`, `BROWSE_EXECUTABLE`, and `BROWSE_READONLY` configure it. See [Register the browse binary with Claude Code](guides/browser.md#register-the-browse-binary-with-claude-code) for the entry, the approval, and a recorded exchange.
+
 ## Guide
 
-For the full surface — the CDP dispatch core, the `BrowserContext`,
-`BrowserPage`, and `BrowserCodegen` classes, the server transports, and usage
-patterns — see [`guides/browser.md`](guides/browser.md).
+For the full surface of the three faces, the method tables, the toolset vocabulary, the journeys, the relation to WebMCP, and the contract, see [`guides/browser.md`](guides/browser.md).
 
 ## Package
 
-Published with the entry points the `exports` field in `package.json` names:
-the environment-agnostic core (`.`) — `CDPClient`, `BrowserContext`,
-`BrowserPage`, `BrowserFrame`, DOM snapshot traversal helpers,
-`BrowserCodegen`, `createCDPClient`, `CDPTransportInterface` —
-and the Node-only server surface (`./server`) — `Browser`, `createBrowser`,
-`createCDPTransport`, `createBrowserWriter`, `WebSocketCDPTransport`.
+The `exports` field in `package.json` names three entry points:
+
+- `.`, the environment-agnostic core: `CDPClient`, `BrowserContext`, `BrowserPage`, `BrowserFrame`, `BrowserNavigationManager`, the element managers, `BrowserPageElement`, `BrowserReading`, `BrowserToolset`, `BrowserSnapshot`, `BrowserCodegen`, `BrowserRecorder`, `BrowserReplay`, `BrowserJourneyToolset`, the memory journey and run stores, `compileBrowserJourney`, and the factories `createCDPClient`, `createBrowserReading`, `createBrowserSnapshot`, `createBrowserToolset`, `createBrowserRecorder`, `createBrowserReplay`, `createMemoryBrowserJourneyStore`, and `createMemoryBrowserRunStore`;
+- `./browser`, the in-page face: `BrowserDOMView`, `BrowserDOMElement`, `BrowserDOMElementManager`, `SocketCDPTransport`, and the factories `createBrowserDOMView`, `createDocumentToolset`, and `createSocketCDPTransport`;
+- `./server`, the Node runtime: `Browser`, `WebSocketCDPTransport`, `FileBrowserWriter`, the file journey and run stores, `BrowserMCPServer`, and the factories `createBrowser`, `createCDPTransport`, `createBrowserWriter`, `createFileBrowserJourneyStore`, `createFileBrowserRunStore`, and `createBrowserMCPServer`.
+
+The `bin` field names `browse`, which runs `dist/bin/main.js`.
 
 ## License
 

package/dist/bin/main.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { parseBoolean } from "@orkestrel/contract";
+import { BrowserError, isBrowserError } from "../src/core/index.js";
+import { createBrowserMCPServer } from "../src/server/index.js";
+//#region src/bin/main.ts
+try {
+	const { BROWSE_ROOT, BROWSE_HEADLESS, BROWSE_EXECUTABLE, BROWSE_READONLY } = process.env;
+	const headless = parseBoolean(BROWSE_HEADLESS);
+	const readonly = parseBoolean(BROWSE_READONLY);
+	for (const [name, value, parsed] of [[
+		"BROWSE_HEADLESS",
+		BROWSE_HEADLESS,
+		headless
+	], [
+		"BROWSE_READONLY",
+		BROWSE_READONLY,
+		readonly
+	]]) if (value !== void 0 && value !== "" && parsed === void 0) throw new BrowserError(`${name} must be true, false, 1, or 0, not ${JSON.stringify(value)}`, "BROWSER_SERVER_ENVIRONMENT", {
+		name,
+		value
+	});
+	await createBrowserMCPServer({
+		...BROWSE_ROOT === void 0 || BROWSE_ROOT === "" ? {} : { root: BROWSE_ROOT },
+		...headless === void 0 ? {} : { headless },
+		...BROWSE_EXECUTABLE === void 0 || BROWSE_EXECUTABLE === "" ? {} : { executable: BROWSE_EXECUTABLE },
+		...readonly === void 0 ? {} : { readonly }
+	}).start();
+} catch (error) {
+	if (!isBrowserError(error)) throw error;
+	console.error(`browse: ${error.code}: ${error.message.split(/\r\n|\n/u).join(" ")}`);
+	process.exitCode = 1;
+}
+//#endregion
+
+//# sourceMappingURL=main.js.map

package/dist/bin/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","names":[],"sources":["../../src/bin/main.ts"],"sourcesContent":["import { parseBoolean } from '@orkestrel/contract'\nimport { BrowserError, isBrowserError } from '@src/core'\nimport { createBrowserMCPServer } from '@src/server'\n\ntry {\n\tconst { BROWSE_ROOT, BROWSE_HEADLESS, BROWSE_EXECUTABLE, BROWSE_READONLY } = process.env\n\tconst headless = parseBoolean(BROWSE_HEADLESS)\n\tconst readonly = parseBoolean(BROWSE_READONLY)\n\t// An empty variable counts as unset, as a shell's `NAME=` leaves it.\n\tfor (const [name, value, parsed] of [\n\t\t['BROWSE_HEADLESS', BROWSE_HEADLESS, headless],\n\t\t['BROWSE_READONLY', BROWSE_READONLY, readonly],\n\t] as const) {\n\t\tif (value !== undefined && value !== '' && parsed === undefined) {\n\t\t\tthrow new BrowserError(\n\t\t\t\t`${name} must be true, false, 1, or 0, not ${JSON.stringify(value)}`,\n\t\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t\t{ name, value },\n\t\t\t)\n\t\t}\n\t}\n\tawait createBrowserMCPServer({\n\t\t...(BROWSE_ROOT === undefined || BROWSE_ROOT === '' ? {} : { root: BROWSE_ROOT }),\n\t\t...(headless === undefined ? {} : { headless }),\n\t\t...(BROWSE_EXECUTABLE === undefined || BROWSE_EXECUTABLE === ''\n\t\t\t? {}\n\t\t\t: { executable: BROWSE_EXECUTABLE }),\n\t\t...(readonly === undefined ? {} : { readonly }),\n\t}).start()\n} catch (error) {\n\tif (!isBrowserError(error)) throw error\n\tconsole.error(`browse: ${error.code}: ${error.message.split(/\\r\\n|\\n/u).join(' ')}`)\n\tprocess.exitCode = 1\n}\n"],"mappings":";;;;;AAIA,IAAI;CACH,MAAM,EAAE,aAAa,iBAAiB,mBAAmB,oBAAoB,QAAQ;CACrF,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,WAAW,aAAa,eAAe;CAE7C,KAAK,MAAM,CAAC,MAAM,OAAO,WAAW,CACnC;EAAC;EAAmB;EAAiB;CAAQ,GAC7C;EAAC;EAAmB;EAAiB;CAAQ,CAC9C,GACC,IAAI,UAAU,KAAA,KAAa,UAAU,MAAM,WAAW,KAAA,GACrD,MAAM,IAAI,aACT,GAAG,KAAK,qCAAqC,KAAK,UAAU,KAAK,KACjE,8BACA;EAAE;EAAM;CAAM,CACf;CAGF,MAAM,uBAAuB;EAC5B,GAAI,gBAAgB,KAAA,KAAa,gBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,YAAY;EAC/E,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC7C,GAAI,sBAAsB,KAAA,KAAa,sBAAsB,KAC1D,CAAC,IACD,EAAE,YAAY,kBAAkB;EACnC,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;CAC9C,CAAC,CAAC,CAAC,MAAM;AACV,SAAS,OAAO;CACf,IAAI,CAAC,eAAe,KAAK,GAAG,MAAM;CAClC,QAAQ,MAAM,WAAW,MAAM,KAAK,IAAI,MAAM,QAAQ,MAAM,UAAU,CAAC,CAAC,KAAK,GAAG,GAAG;CACnF,QAAQ,WAAW;AACpB"}