@orkestrel/browser 0.0.26 → 0.0.27

package/README.md

@@ -1,11 +1,10 @@
 # @orkestrel/browser
 
-> 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.
+> The browser runtime for the `@orkestrel` line: a `Browser` that finds, launches, or attaches
+> to Chromium; its contexts and pages; the elements and readings a page yields; and the toolset
+> and journeys that hand a page to an agent.
 
-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 whole captured page as Markdown or plain text 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.
+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 whole captured page as Markdown or plain text in bounded slices, and hand the whole vocabulary to an agent as `@orkestrel/tool` tools with `createBrowserToolset`. Inside a page, `createBrowserToolset(createBrowserDOMView(options))` 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 seven journey tools, or compile it with `compileBrowserJourney` into a module a developer runs and customizes. Part of the `@orkestrel` line.
 
 ## Install
 
@@ -32,7 +31,12 @@ import { createBrowser } from '@orkestrel/browser/server'
 
 const browser = createBrowser({ headless: true })
 await browser.connect()
-const page = await browser.create({ url: 'https://example.com' })
+const url =
+	'data:text/html,' +
+	encodeURIComponent(
+		'<label>Email<input aria-label="Email"></label><button onclick="document.body.append(&quot;Saved&quot;)">Save</button>',
+	)
+const page = await browser.create({ url })
 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')
@@ -54,9 +58,13 @@ import { createToolManager } from '@orkestrel/tool'
 
 const toolset = createBrowserToolset(page, { tools: createToolManager() })
 await toolset.start()
-await toolset.tools.execute({ id: '1', name: 'look', arguments: { search: 'Email' } })
-await toolset.tools.execute({ id: '2', name: 'read', arguments: { search: 'delivery' } })
-await toolset.tools.execute({ id: '3', name: 'plain', arguments: { search: 'confirmation' } })
+await toolset.tools.execute({ id: '1', name: 'read', arguments: { from: 1, search: 'Email' } })
+await toolset.tools.execute({ id: '2', name: 'read', arguments: { from: 1, search: 'delivery' } })
+await toolset.tools.execute({
+	id: '3',
+	name: 'read',
+	arguments: { from: 1, search: 'confirmation' },
+})
 await toolset.destroy()
 ```
 
@@ -71,9 +79,11 @@ const result = await client.send('Page.navigate', { url: 'https://example.com' }
 await client.close()
 ```
 
+Context wrapping uses `BrowserContextOptions`; `browser.isolate` uses `BrowserIsolateOptions` and assigns the context id. The stable `page.recorder` reports `active` and starts explicitly. Network `apply` retains omitted or undefined settings; `clear()` resets headers, offline mode, and credentials. Cookie `remove` requires a nonempty filter; `clear()` removes all cookies.
+
 ## Browse binary
 
-The package ships the `browse` binary, which serves the browser vocabulary and the journey tools over MCP on stdio and starts Chromium when the server starts, before the client's first request, 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`, `BROWSE_READONLY`, and `BROWSE_POOL` 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, the startup and recovery behavior, and a recorded exchange.
+The package ships the `browse` binary, which serves the browser vocabulary and the journey tools over MCP on stdio and starts Chromium when the server starts, before the client's first request, 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`, `BROWSE_READONLY`, and `BROWSE_POOL` 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, the startup and recovery behavior, and an illustrative exchange.
 
 ## Guide
 
@@ -83,9 +93,9 @@ For the full surface of the three faces, the method tables, the toolset vocabula
 
 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 core: context and page contracts, elements and readings, the toolset, recorder, replay, memory stores, journey compiler, and their factories. Owners construct pages, frames, elements, input devices, and managers and return their public interfaces; `createBrowserContext` constructs a context over an injected CDP client.
+- `./browser`, the in-page face: `BrowserDOMView`, `BrowserDOMWait`, `SocketCDPTransport`, `createBrowserDOMView`, and `createSocketCDPTransport`. Compose the view with the core's `createBrowserToolset`.
+- `./server`, the Node runtime: `Browser`, `WebSocketCDPTransport`, `FileBrowserWriter`, the file journey and run stores, `BrowserMCPServer`, and the factories `createBrowser`, `createWebSocketCDPTransport`, `createFileBrowserWriter`, `createFileBrowserJourneyStore`, `createFileBrowserRunStore`, and `createBrowserMCPServer`.
 
 The `bin` field names `browse`, which runs `dist/bin/main.js`.
 

package/dist/bin/main.js

@@ -21,32 +21,34 @@ try {
 		"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", {
+	]]) if (value !== void 0 && value !== "" && parsed === void 0) throw new BrowserError("SERVER_ENVIRONMENT", `${name} must be true, false, 1, or 0, not ${JSON.stringify(value)}`, {
 		name,
 		value
 	});
-	if (BROWSE_POOL !== void 0 && BROWSE_POOL !== "" && size === void 0) throw new BrowserError(`BROWSE_POOL must be an integer, not ${JSON.stringify(BROWSE_POOL)}`, "BROWSER_SERVER_ENVIRONMENT", {
+	if (BROWSE_POOL !== void 0 && BROWSE_POOL !== "" && size === void 0) throw new BrowserError("SERVER_ENVIRONMENT", `BROWSE_POOL must be an integer, not ${JSON.stringify(BROWSE_POOL)}`, {
 		name: "BROWSE_POOL",
 		value: BROWSE_POOL
 	});
-	if (BROWSE_VIEWPORT !== void 0 && BROWSE_VIEWPORT !== "" && viewport === void 0) throw new BrowserError(`BROWSE_VIEWPORT must be positive integers in WIDTHxHEIGHT form, not ${JSON.stringify(BROWSE_VIEWPORT)}`, "BROWSER_SERVER_ENVIRONMENT", {
+	if (BROWSE_VIEWPORT !== void 0 && BROWSE_VIEWPORT !== "" && viewport === void 0) throw new BrowserError("SERVER_ENVIRONMENT", `BROWSE_VIEWPORT must be positive integers in WIDTHxHEIGHT form, not ${JSON.stringify(BROWSE_VIEWPORT)}`, {
 		name: "BROWSE_VIEWPORT",
 		value: BROWSE_VIEWPORT
 	});
-	if (BROWSE_CONTEXTS !== void 0 && BROWSE_CONTEXTS !== "" && contexts === void 0) throw new BrowserError(`BROWSE_CONTEXTS must be an integer, not ${JSON.stringify(BROWSE_CONTEXTS)}`, "BROWSER_SERVER_ENVIRONMENT", {
+	if (BROWSE_CONTEXTS !== void 0 && BROWSE_CONTEXTS !== "" && contexts === void 0) throw new BrowserError("SERVER_ENVIRONMENT", `BROWSE_CONTEXTS must be an integer, not ${JSON.stringify(BROWSE_CONTEXTS)}`, {
 		name: "BROWSE_CONTEXTS",
 		value: BROWSE_CONTEXTS
 	});
 	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 },
+		browser: {
+			...headless === void 0 ? {} : { headless },
+			...BROWSE_EXECUTABLE === void 0 || BROWSE_EXECUTABLE === "" ? {} : { executable: BROWSE_EXECUTABLE },
+			...viewport === void 0 ? {} : { viewport }
+		},
+		journeys: { ...readonly === void 0 ? {} : { readonly } },
 		pool: {
 			...size === void 0 ? {} : { size },
 			...contexts === void 0 ? {} : { contexts }
-		},
-		...viewport === void 0 ? {} : { viewport }
+		}
 	}).start();
 } catch (error) {
 	if (!isBrowserError(error)) throw error;

package/dist/bin/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","names":[],"sources":["../../src/bin/main.ts"],"sourcesContent":["import { parseBoolean, parseInteger } from '@orkestrel/contract'\nimport { BrowserError, isBrowserError } from '@src/core'\nimport { createBrowserMCPServer, parseBrowserViewport } from '@src/server'\n\n// The entry owns stderr; a closed reader must not interrupt the server's teardown barrier.\nprocess.stderr.on('error', () => {\n\tprocess.exitCode = 1\n})\n\ntry {\n\tconst {\n\t\tBROWSE_ROOT,\n\t\tBROWSE_HEADLESS,\n\t\tBROWSE_EXECUTABLE,\n\t\tBROWSE_READONLY,\n\t\tBROWSE_POOL,\n\t\tBROWSE_CONTEXTS,\n\t\tBROWSE_VIEWPORT,\n\t} = process.env\n\tconst headless = parseBoolean(BROWSE_HEADLESS)\n\tconst readonly = parseBoolean(BROWSE_READONLY)\n\tconst size = parseInteger(BROWSE_POOL)\n\tconst contexts = parseInteger(BROWSE_CONTEXTS)\n\tconst viewport = parseBrowserViewport(BROWSE_VIEWPORT)\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\tif (BROWSE_POOL !== undefined && BROWSE_POOL !== '' && size === undefined)\n\t\tthrow new BrowserError(\n\t\t\t`BROWSE_POOL must be an integer, not ${JSON.stringify(BROWSE_POOL)}`,\n\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t{ name: 'BROWSE_POOL', value: BROWSE_POOL },\n\t\t)\n\tif (BROWSE_VIEWPORT !== undefined && BROWSE_VIEWPORT !== '' && viewport === undefined)\n\t\tthrow new BrowserError(\n\t\t\t`BROWSE_VIEWPORT must be positive integers in WIDTHxHEIGHT form, not ${JSON.stringify(BROWSE_VIEWPORT)}`,\n\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t{ name: 'BROWSE_VIEWPORT', value: BROWSE_VIEWPORT },\n\t\t)\n\tif (BROWSE_CONTEXTS !== undefined && BROWSE_CONTEXTS !== '' && contexts === undefined)\n\t\tthrow new BrowserError(\n\t\t\t`BROWSE_CONTEXTS must be an integer, not ${JSON.stringify(BROWSE_CONTEXTS)}`,\n\t\t\t'BROWSER_SERVER_ENVIRONMENT',\n\t\t\t{ name: 'BROWSE_CONTEXTS', value: BROWSE_CONTEXTS },\n\t\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\tpool: {\n\t\t\t...(size === undefined ? {} : { size }),\n\t\t\t...(contexts === undefined ? {} : { contexts }),\n\t\t},\n\t\t...(viewport === undefined ? {} : { viewport }),\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":";;;;;AAKA,QAAQ,OAAO,GAAG,eAAe;CAChC,QAAQ,WAAW;AACpB,CAAC;AAED,IAAI;CACH,MAAM,EACL,aACA,iBACA,mBACA,iBACA,aACA,iBACA,oBACG,QAAQ;CACZ,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,OAAO,aAAa,WAAW;CACrC,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,WAAW,qBAAqB,eAAe;CAErD,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,IAAI,gBAAgB,KAAA,KAAa,gBAAgB,MAAM,SAAS,KAAA,GAC/D,MAAM,IAAI,aACT,uCAAuC,KAAK,UAAU,WAAW,KACjE,8BACA;EAAE,MAAM;EAAe,OAAO;CAAY,CAC3C;CACD,IAAI,oBAAoB,KAAA,KAAa,oBAAoB,MAAM,aAAa,KAAA,GAC3E,MAAM,IAAI,aACT,uEAAuE,KAAK,UAAU,eAAe,KACrG,8BACA;EAAE,MAAM;EAAmB,OAAO;CAAgB,CACnD;CACD,IAAI,oBAAoB,KAAA,KAAa,oBAAoB,MAAM,aAAa,KAAA,GAC3E,MAAM,IAAI,aACT,2CAA2C,KAAK,UAAU,eAAe,KACzE,8BACA;EAAE,MAAM;EAAmB,OAAO;CAAgB,CACnD;CACD,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;EAC7C,MAAM;GACL,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;GACrC,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC9C;EACA,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"}
+{"version":3,"file":"main.js","names":[],"sources":["../../src/bin/main.ts"],"sourcesContent":["import { parseBoolean, parseInteger } from '@orkestrel/contract'\nimport { BrowserError, isBrowserError } from '@src/core'\nimport { createBrowserMCPServer, parseBrowserViewport } from '@src/server'\n\n// The entry owns stderr; a closed reader must not interrupt the server's teardown barrier.\nprocess.stderr.on('error', () => {\n\tprocess.exitCode = 1\n})\n\ntry {\n\tconst {\n\t\tBROWSE_ROOT,\n\t\tBROWSE_HEADLESS,\n\t\tBROWSE_EXECUTABLE,\n\t\tBROWSE_READONLY,\n\t\tBROWSE_POOL,\n\t\tBROWSE_CONTEXTS,\n\t\tBROWSE_VIEWPORT,\n\t} = process.env\n\tconst headless = parseBoolean(BROWSE_HEADLESS)\n\tconst readonly = parseBoolean(BROWSE_READONLY)\n\tconst size = parseInteger(BROWSE_POOL)\n\tconst contexts = parseInteger(BROWSE_CONTEXTS)\n\tconst viewport = parseBrowserViewport(BROWSE_VIEWPORT)\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'SERVER_ENVIRONMENT',\n\t\t\t\t`${name} must be true, false, 1, or 0, not ${JSON.stringify(value)}`,\n\t\t\t\t{ name, value },\n\t\t\t)\n\t\t}\n\t}\n\tif (BROWSE_POOL !== undefined && BROWSE_POOL !== '' && size === undefined)\n\t\tthrow new BrowserError(\n\t\t\t'SERVER_ENVIRONMENT',\n\t\t\t`BROWSE_POOL must be an integer, not ${JSON.stringify(BROWSE_POOL)}`,\n\t\t\t{ name: 'BROWSE_POOL', value: BROWSE_POOL },\n\t\t)\n\tif (BROWSE_VIEWPORT !== undefined && BROWSE_VIEWPORT !== '' && viewport === undefined)\n\t\tthrow new BrowserError(\n\t\t\t'SERVER_ENVIRONMENT',\n\t\t\t`BROWSE_VIEWPORT must be positive integers in WIDTHxHEIGHT form, not ${JSON.stringify(BROWSE_VIEWPORT)}`,\n\t\t\t{ name: 'BROWSE_VIEWPORT', value: BROWSE_VIEWPORT },\n\t\t)\n\tif (BROWSE_CONTEXTS !== undefined && BROWSE_CONTEXTS !== '' && contexts === undefined)\n\t\tthrow new BrowserError(\n\t\t\t'SERVER_ENVIRONMENT',\n\t\t\t`BROWSE_CONTEXTS must be an integer, not ${JSON.stringify(BROWSE_CONTEXTS)}`,\n\t\t\t{ name: 'BROWSE_CONTEXTS', value: BROWSE_CONTEXTS },\n\t\t)\n\tawait createBrowserMCPServer({\n\t\t...(BROWSE_ROOT === undefined || BROWSE_ROOT === '' ? {} : { root: BROWSE_ROOT }),\n\t\tbrowser: {\n\t\t\t...(headless === undefined ? {} : { headless }),\n\t\t\t...(BROWSE_EXECUTABLE === undefined || BROWSE_EXECUTABLE === ''\n\t\t\t\t? {}\n\t\t\t\t: { executable: BROWSE_EXECUTABLE }),\n\t\t\t...(viewport === undefined ? {} : { viewport }),\n\t\t},\n\t\tjourneys: { ...(readonly === undefined ? {} : { readonly }) },\n\t\tpool: {\n\t\t\t...(size === undefined ? {} : { size }),\n\t\t\t...(contexts === undefined ? {} : { contexts }),\n\t\t},\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":";;;;;AAKA,QAAQ,OAAO,GAAG,eAAe;CAChC,QAAQ,WAAW;AACpB,CAAC;AAED,IAAI;CACH,MAAM,EACL,aACA,iBACA,mBACA,iBACA,aACA,iBACA,oBACG,QAAQ;CACZ,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,OAAO,aAAa,WAAW;CACrC,MAAM,WAAW,aAAa,eAAe;CAC7C,MAAM,WAAW,qBAAqB,eAAe;CAErD,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,sBACA,GAAG,KAAK,qCAAqC,KAAK,UAAU,KAAK,KACjE;EAAE;EAAM;CAAM,CACf;CAGF,IAAI,gBAAgB,KAAA,KAAa,gBAAgB,MAAM,SAAS,KAAA,GAC/D,MAAM,IAAI,aACT,sBACA,uCAAuC,KAAK,UAAU,WAAW,KACjE;EAAE,MAAM;EAAe,OAAO;CAAY,CAC3C;CACD,IAAI,oBAAoB,KAAA,KAAa,oBAAoB,MAAM,aAAa,KAAA,GAC3E,MAAM,IAAI,aACT,sBACA,uEAAuE,KAAK,UAAU,eAAe,KACrG;EAAE,MAAM;EAAmB,OAAO;CAAgB,CACnD;CACD,IAAI,oBAAoB,KAAA,KAAa,oBAAoB,MAAM,aAAa,KAAA,GAC3E,MAAM,IAAI,aACT,sBACA,2CAA2C,KAAK,UAAU,eAAe,KACzE;EAAE,MAAM;EAAmB,OAAO;CAAgB,CACnD;CACD,MAAM,uBAAuB;EAC5B,GAAI,gBAAgB,KAAA,KAAa,gBAAgB,KAAK,CAAC,IAAI,EAAE,MAAM,YAAY;EAC/E,SAAS;GACR,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;GAC7C,GAAI,sBAAsB,KAAA,KAAa,sBAAsB,KAC1D,CAAC,IACD,EAAE,YAAY,kBAAkB;GACnC,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC9C;EACA,UAAU,EAAE,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS,EAAG;EAC5D,MAAM;GACL,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;GACrC,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;EAC9C;CACD,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"}

package/dist/src/browser/index.d.ts

@@ -1,14 +1,8 @@
 import type { BrowserCallOptions } from '@orkestrel/browser';
 import type { BrowserElementInterface } from '@orkestrel/browser';
 import type { BrowserElementManagerInterface } from '@orkestrel/browser';
-import type { BrowserElementQuery } from '@orkestrel/browser';
-import type { BrowserEpochFunction } from '@orkestrel/browser';
-import type { BrowserOutline } from '@orkestrel/browser';
-import type { BrowserOutlineOptions } from '@orkestrel/browser';
 import type { BrowserReadingInput } from '@orkestrel/browser';
 import type { BrowserReadingInterface } from '@orkestrel/browser';
-import type { BrowserToolsetInterface } from '@orkestrel/browser';
-import type { BrowserToolsetOptions } from '@orkestrel/browser';
 import type { BrowserViewInterface } from '@orkestrel/browser';
 import type { BrowserWaitOptions } from '@orkestrel/browser';
 import type { CDPTransportEventMap } from '@orkestrel/browser';
@@ -77,82 +71,6 @@ export declare const BROWSER_SELECTED_ROLES: ReadonlySet<string>;
 /** Names the `input` type states whose value an untrusted `fill` sets as typed text. */
 export declare const BROWSER_TYPED_INPUTS: ReadonlySet<string>;
 
-/**
- * Configures a toolset that drives one browser document.
- *
- * @remarks
- * - `document` and `own` — the driven document and the admission of the realm's own document, as
- *   {@link BrowserDOMViewOptions} describes them
- * - `source` — a source of page tools, such as `@orkestrel/mcp`'s model context bridge; the
- *   toolset adopts its tools and re-adopts on its `change`. Default: no page tools
- * - `tools`, `limit`, `journeys`, `on`, and `error` — as {@link BrowserToolsetOptions}
- *   describes them
- */
-export declare interface BrowserDocumentToolsetOptions extends BrowserDOMViewOptions, Pick<BrowserToolsetOptions, 'on' | 'error' | 'tools' | 'source' | 'limit' | 'journeys'> {
-}
-
-/**
- * Drives a referenced element of a DOM document without trusted input.
- *
- * @remarks
- * `click` runs `HTMLElement.click()`; `fill` and `select` set the control through its native
- * prototype setter and dispatch `input` and `change`, and `fill` refuses `UNKNOWN` an element
- * that is not a text control and a read-only one; `submit` runs `form.requestSubmit()` and
- * observes the outcome through a `submit` listener registered across the call. Each action
- * refuses with a `BrowserElementError` naming the reason: `DISABLED` for a disabled control,
- * `HIDDEN` for an element that does not render, and `UNTRUSTED` for what an untrusted event
- * cannot do, which is a click or submission that opens another browsing context, a click that
- * opens a file chooser, and typing into a contenteditable element. A click that activates a
- * `label`, on the label itself or on a descendant that `matchesBrowserActivation` admits, is
- * judged by the label's control as well: a disabled control refuses `DISABLED`, and a file input
- * refuses `UNTRUSTED` as a direct click on it does. A click on an interactive descendant of a
- * label keeps only its own checks. `role` and `name` read the description the latest outline or
- * query that encountered the element captured, so a change to the element shows after the next
- * capture, and a dropped reference keeps its last capture. Every action on an element removed
- * from its document, collected, or held across a navigation reports `GONE`.
- *
- * @example
- * ```ts
- * const view = createBrowserDOMView({ document: frame.contentDocument })
- * await view.elements.outline()
- * await view.elements.element('e1')?.click()
- * ```
- */
-export declare class BrowserDOMElement implements BrowserDOMElementInterface {
-    #private;
-    constructor(input: BrowserDOMElementInput);
-    get reference(): string;
-    get role(): string;
-    get name(): string;
-    click(options?: BrowserCallOptions): Promise<void>;
-    fill(value: string, options?: BrowserCallOptions): Promise<void>;
-    select(values: readonly string[], options?: BrowserCallOptions): Promise<void>;
-    focus(options?: BrowserCallOptions): Promise<void>;
-    read(options?: BrowserCallOptions): Promise<BrowserReadingInterface>;
-    submit(options?: BrowserCallOptions): Promise<void>;
-}
-
-/**
- * Binds a DOM element to its reference and the manager that minted it.
- *
- * @remarks
- * - `reference` — the reference the manager minted for the element
- * - `description` — returns the role and accessible name the latest capture that encountered
- *   the element recorded; after the manager drops the reference it keeps returning that capture
- * - `node` — a weak reference to the element the reference names, so a removed element can be
- *   collected; an element that no longer dereferences reports `GONE`
- * - `current` — true while the manager still holds the reference; false otherwise
- * - `navigation` — reads the epoch of the element's own document, which every reading records;
- *   it advances when that document or the view's document navigates
- */
-export declare interface BrowserDOMElementInput {
-    readonly reference: string;
-    readonly description: () => Pick<BrowserElementInterface, 'role' | 'name'>;
-    readonly node: WeakRef<Element>;
-    readonly current: () => boolean;
-    readonly navigation: BrowserEpochFunction;
-}
-
 /**
  * Provides DOM actions through a stable element reference, without trusted input.
  *
@@ -165,71 +83,6 @@ export declare interface BrowserDOMElementInput {
 export declare interface BrowserDOMElementInterface extends BrowserElementInterface {
 }
 
-/**
- * Outlines a DOM document from its elements and binds stable references to the interactive ones.
- *
- * @remarks
- * Rows come in document order from a `TreeWalker` over the flat tree: an open shadow root
- * contributes its rows in place of its host's children, a `slot` its assigned nodes, and a
- * same-origin `iframe` its document's rows, while a cross-origin one renders
- * `iframe "NAME" (cross-origin, not readable)`. An element that `matchesBrowserHidden` reports is
- * omitted with its subtree, a scope root in such a subtree yields no row, and an element that
- * `matchesBrowserInvisible` reports yields no row of its own. An element whose role
- * `BROWSER_INTERACTIVE_ROLES` names receives a reference bound through a `WeakRef`, which never
- * changes while the manager holds it, and a reference number is never reused. Every outline or
- * query that encounters a bound element records its role and name afresh, and the element's
- * wrapper reports that latest capture, also after the manager drops the reference. A reference
- * and a reading from any walked document record that document's epoch, which advances on its own
- * navigation events and on the view's; that document's `pagehide` drops its references. A form
- * carrying a `toolname` attribute renders `[tool=NAME]` after its role and name. A row carries
- * `focused` when its element is the active element of its own document or shadow root. Rows carry
- * pressed, expanded, and selected states through the Chromium mapping in `readBrowserStates`.
- * A `select` row is followed by one `option` row per option, named by its label. Whitespace between two texts of
- * one block renders as one space, as a rendered `br` between them does, and texts with neither
- * between them stay joined. A CSS query
- * searches the document the view drives, not its child documents or shadow trees. After the
- * input's `signal` aborts, `outline`, `find`, and `wait` reject with its reason.
- *
- * `wait` parks a `BrowserDOMWait` bound to the view's lifetime over every root that
- * `collectBrowserRoots` reaches from its scope, reconciled at every observed mutation and frame
- * `load`. A shadow root attached after the wait began is a declared limit: the wait discovers it
- * at the next observed mutation or `load`, so a match inserted there with no other observed
- * change is not seen before the deadline.
- *
- * @example
- * ```ts
- * const view = createBrowserDOMView({ document: frame.contentDocument })
- * const outline = await view.elements.outline()
- * const [save] = await view.elements.find({ role: 'button', name: 'save' })
- * ```
- */
-export declare class BrowserDOMElementManager implements BrowserElementManagerInterface<BrowserDOMElementInterface> {
-    #private;
-    constructor(input: BrowserDOMElementManagerInput);
-    outline(options?: BrowserOutlineOptions): Promise<BrowserOutline>;
-    find(query: BrowserElementQuery, options?: BrowserCallOptions): Promise<readonly BrowserDOMElementInterface[]>;
-    wait(query: BrowserElementQuery, options?: BrowserWaitOptions): Promise<readonly BrowserDOMElementInterface[]>;
-    element(reference: string): BrowserDOMElementInterface | undefined;
-    elements(): readonly BrowserDOMElementInterface[];
-    clear(): void;
-}
-
-/**
- * Binds a DOM element manager to the view that owns it.
- *
- * @remarks
- * - `document` — returns the document the view drives at the moment of the call
- * - `navigation` — reads the view's navigation epoch, which every reading records
- * - `signal` — the view's lifetime; it aborts when the view is destroyed, every wait and
- *   navigation listener the manager starts ends with it, and after it aborts `outline`, `find`,
- *   and `wait` reject with its reason
- */
-export declare interface BrowserDOMElementManagerInput {
-    readonly document: () => Document;
-    readonly navigation: BrowserEpochFunction;
-    readonly signal: AbortSignal;
-}
-
 /**
  * Reads and drives a DOM document from a realm that can reach it, without trusted input.
  *
@@ -242,7 +95,7 @@ export declare interface BrowserDOMElementManagerInput {
  * fires none of those events, so a reading there stays current across it. A cross-document
  * navigation also clears every element reference. `destroy()` releases the listeners and every
  * reference, and fails every pending wait with a `BrowserError` coded
- * `BROWSER_DOCUMENT_DESTROYED`; after it, `title()`, `read()`, `wait()`, and the element manager's
+ * `DOCUMENT_DESTROYED`; after it, `title()`, `read()`, `wait()`, and the element manager's
  * `outline()`, `find()`, and `wait()` reject with that error, and a second `destroy()` does
  * nothing more. `trusted` is `false`: no action grants user activation, and
  * every event the view's actions dispatch themselves carries `isTrusted` `false`. The `submit`
@@ -302,7 +155,7 @@ export declare interface BrowserDOMViewOptions {
  * again after every subscription, and no check runs once the deadline, counted from `start`, has
  * passed, which the wait reads again after `roots` returns. The wait settles one time: on the
  * check's first value, on the signal's abort with its reason, at the deadline with
- * `BROWSER_WAIT_TIMEOUT`, on a `pagehide` in the first root's window with `GONE`, or with whatever
+ * `TIMEOUT`, on a `pagehide` in the first root's window with `GONE`, or with whatever
  * the check or the roots function throws. A signal that aborts while `check` or `roots` runs
  * settles the wait with its reason, and wins over a value that same check returns. Settlement
  * disconnects every observer and removes every listener synchronously, so a mutation queued
@@ -506,8 +359,8 @@ export declare function computeBrowserText(root: Element | ShadowRoot, context?:
  * @param options - The driven document, and `own` to admit the realm's own document
  * @returns A {@link BrowserDOMViewInterface} over the document's window
  * @throws Thrown when `document` is not a document attached to a window, with the code
- * `BROWSER_DOCUMENT`, and when it is `globalThis.document` without `own: true`, with the code
- * `BROWSER_DOCUMENT_OWN`.
+ * `DOCUMENT`, and when it is `globalThis.document` without `own: true`, with the code
+ * `DOCUMENT_OWN`.
  *
  * @example
  * ```ts
@@ -519,37 +372,6 @@ export declare function computeBrowserText(root: Element | ShadowRoot, context?:
  */
 export declare function createBrowserDOMView(options: BrowserDOMViewOptions): BrowserDOMViewInterface;
 
-/**
- * Creates a `BrowserToolsetInterface` that publishes the five view tools over a DOM document and
- * adopts a source's page tools beside them.
- *
- * @remarks
- * The toolset runs over a view {@link createBrowserDOMView} creates for `document`, so it
- * advertises `look`, `read`, `plain`, `click`, `type`, and `wait`, and a click or type receipt ends with
- * ` (untrusted event)`. `source` supplies page tools, which the toolset adopts during `start()`
- * and again on every `change`; `toolset.native` never includes them, so publishing it to a
- * registry leaves that registry's own tools alone. The view belongs to the toolset: `destroy()`
- * removes the toolset's tools, then destroys the view, which releases its listeners and fails
- * its pending waits, and a construction that throws destroys the view before it rethrows.
- * `journeys` adds `record`, `save`, `journeys`, `edit`, and `replay` at construction; a replay
- * runs the steps the document placement executes.
- *
- * @param options - The driven document, `own`, the page-tool source, the manager, the bound, the
- * journey stores, and the emitter hooks
- * @returns A {@link BrowserToolsetInterface} whose `view` drives the document
- * @throws Thrown when `document` is not a document attached to a window, with the code
- * `BROWSER_DOCUMENT`, when it is `globalThis.document` without `own: true`, with the code
- * `BROWSER_DOCUMENT_OWN`, and when `limit` is not a positive integer.
- *
- * @example
- * ```ts
- * const toolset = createDocumentToolset({ document: frame.contentDocument, source: bridge })
- * await toolset.start()
- * await toolset.tools.execute({ id: '1', name: 'look', arguments: { search: 'form' } })
- * ```
- */
-export declare function createDocumentToolset(options: BrowserDocumentToolsetOptions): BrowserToolsetInterface;
-
 /**
  * Creates a CDP transport over the browser's native `WebSocket`.
  *
@@ -752,7 +574,7 @@ export declare function readBrowserBlock(element: Element | null, root: Node): N
  * @param node - The root whose rendered markup is captured; its owner document supplies `URL`
  * and `title`
  * @returns The capture's `url`, `title`, and `html`
- * @throws Thrown as a `BrowserResultLimitError` when the serialized capture is longer than
+ * @throws Thrown as a `BrowserError` when the serialized capture is longer than
  * `BROWSER_RESULT_LIMIT` characters, with `length` and `limit` in its context.
  */
 export declare function readBrowserCapture(node: Element): BrowserReadingInput;
@@ -855,7 +677,7 @@ export declare function skipBrowserSubtree(walker: TreeWalker): Node | null;
  * Provides a raw CDP text transport over the browser's native `WebSocket`.
  *
  * @remarks
- * `start()` resolves on the socket's `open` event and rejects with a `BrowserConnectionError`
+ * `start()` resolves on the socket's `open` event and rejects with a `BrowserError`
  * carrying `url` for a URL whose scheme is not `ws:` or `wss:`, for a URL the `WebSocket`
  * constructor refuses (one with a fragment), for a socket that fails or closes before it opens,
  * and at the `timeout` deadline. Concurrent and repeated `start()` and `close()`