@orkestrel/scaffold 0.0.91 → 0.0.92

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/dist/agents/templates/brief.md +2 -0
  2. package/dist/bin/main.js +3 -3
  3. package/dist/bin/main.js.map +1 -1
  4. package/dist/host/AGENTS.md +2 -2
  5. package/dist/host/agents/orchestration.md +1 -1
  6. package/dist/host/agents/skills/orkestrel-falsify/SKILL.md +3 -3
  7. package/dist/host/agents/skills/orkestrel-publish/references/window.md +3 -4
  8. package/dist/host/agents/skills/orkestrel-scout/SKILL.md +1 -1
  9. package/dist/host/agents/templates/brief.md +2 -0
  10. package/dist/host/agents/transports/cursor.md +1 -1
  11. package/dist/host/claude/agents/analyst.md +1 -1
  12. package/dist/host/claude/agents/grok.md +1 -1
  13. package/dist/host/claude/agents/orkestrel.md +8 -8
  14. package/dist/host/claude/agents/planner.md +1 -1
  15. package/dist/host/claude/agents/researcher.md +1 -1
  16. package/dist/host/claude/agents/scout.md +1 -1
  17. package/dist/host/claude/rules/names.md +1 -1
  18. package/dist/host/claude/rules/patterns.md +1 -1
  19. package/dist/host/claude/rules/quality.md +11 -0
  20. package/dist/host/claude/rules/tests.md +7 -8
  21. package/dist/host/claude/rules/writing.md +2 -1
  22. package/dist/host/codex/agents/researcher.toml +2 -2
  23. package/dist/host/codex/agents/scout.toml +1 -1
  24. package/dist/host/guides/browser.md +413 -346
  25. package/dist/host/guides/pool.md +154 -58
  26. package/dist/host/manifest.json +23 -23
  27. package/dist/src/core/index.cjs +3 -3
  28. package/dist/src/core/index.cjs.map +1 -1
  29. package/dist/src/core/index.js +3 -3
  30. package/dist/src/core/index.js.map +1 -1
  31. package/package.json +3 -3
package/dist/host/guides/browser.md CHANGED
@@ -7,7 +7,7 @@
7
7
 
8
8
  The package has three library faces, each with one import specifier, and the `browse` binary.
9
9
 
10
- - The core, `@orkestrel/browser`, compiles against `ESNext` and `WebWorker` with no DOM and no Node. `CDPClient` frames CDP messages over an injected `CDPTransportInterface`; `BrowserContext`, `BrowserPage`, and `BrowserFrame` model a browser context, its tabs, and their documents; `page.elements` outlines a page from its accessibility tree and acts on stable element references with trusted input; `frame.read()` captures a document as a `BrowserReadingInterface` value; `page.registry` mirrors the experimental `WebMCP` protocol domain; and `BrowserToolset` publishes all of it as `@orkestrel/tool` tools that an agent calls. The core also records, edits, replays, and compiles journeys, which [Journeys](#journeys) describes: `BrowserRecorder` and `page.codegen()` record steps, `BrowserReplay` replays them, `BrowserJourneyToolset` gives a model the six journey tools, `compileBrowserJourney` emits a module a developer runs, and two memory stores keep journeys and runs.
10
+ - The core, `@orkestrel/browser`, compiles against `ESNext` and `WebWorker` with no DOM and no Node. `CDPClient` frames CDP messages over an injected `CDPTransportInterface`; `BrowserContext`, `BrowserPage`, and `BrowserFrame` model a browser context, its tabs, and their documents; `page.elements` outlines a page from its accessibility tree and acts on stable element references with trusted input; `frame.read()` captures a document as a `BrowserReadingInterface` value; `page.registry` mirrors the experimental `WebMCP` protocol domain; and `BrowserToolset` publishes all of it as `@orkestrel/tool` tools that an agent calls. The core also records, edits, replays, and compiles journeys, which [Journeys](#journeys) describes: `BrowserRecorder` and `page.codegen()` record steps, `BrowserReplay` replays them, `BrowserJourneyToolset` gives a model the journey tools, `compileBrowserJourney` emits a module a developer runs, and two memory stores keep journeys and runs.
11
11
  - The in-page face, `@orkestrel/browser/browser`, adds the DOM. `BrowserDOMView` drives a document with `HTMLElement.click()`, native value setters, `form.requestSubmit()`, and `MutationObserver`, and reports what an untrusted event cannot do. `createDocumentToolset` publishes the same vocabulary over that view, and `SocketCDPTransport` carries the core client over the browser's own `WebSocket`, so a worker or an extension page drives a browser over CDP.
12
12
  - The Node runtime, `@orkestrel/browser/server`, adds `Browser`, which discovers a browser listening on a CDP port, attaches to it, or launches one and reads its endpoint from standard error; `WebSocketCDPTransport`; a filesystem-backed browser writer; the file journey and run stores; and `BrowserMCPServer`, which serves the vocabulary and the journey tools over MCP on stdio.
13
13
  - The `browse` binary, `src/bin`, reads its environment variables and starts a `BrowserMCPServer`, which starts Chromium before the client's first request; see [Register the browse binary with Claude Code](#register-the-browse-binary-with-claude-code) for its hookup.
@@ -140,43 +140,43 @@ const run = await createBrowserReplay(toolset, { journey }, { runs }).execute()
140
140
 
141
141
  The following table lists the core classes. Each implements the behavioral interface of the same name plus `Interface`, which [Methods](#methods) documents.
142
142
 
143
- | API | Kind | Summary |
144
- | --------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
145
- | `BrowserAccessibility` | class | Captures Chromium Accessibility-domain snapshots for one page. |
146
- | `BrowserClock` | class | Controls the Chromium virtual-time budget for deterministic page timers. |
147
- | `BrowserCodegen` | class | Records semantic page gestures and compiles them into a journey module. |
148
- | `BrowserContext` | class | Owns pages and shared state inside one Chromium browser context. |
149
- | `BrowserCookieManager` | class | Performs cookie operations isolated to one browser context. |
150
- | `BrowserCoverage` | class | Collects JavaScript precise coverage and CSS rule usage for one page target. |
151
- | `BrowserDiagnostics` | class | Groups the tracing, coverage, performance, and profiler classes beneath one page. |
152
- | `BrowserEmulationManager` | class | Applies rendering, identity, location, and network emulation for context pages. |
153
- | `BrowserFrame` | class | Represents one attached document frame, evaluated through its own CDP execution world. |
154
- | `BrowserHARManager` | class | Records and replays HTTP archives over one page network manager. |
155
- | `BrowserKeyboard` | class | Sends trusted keyboard input through Chromium's CDP Input domain. |
156
- | `BrowserMouse` | class | Sends trusted mouse input through Chromium's CDP Input domain. |
157
- | `BrowserNavigationManager` | class | Parks URL-pattern and network-idle waits on page events and abort signals, and opens the records that settle the navigation an input starts. |
158
- | `BrowserNetworkManager` | class | Drives the page-scoped Network and Fetch domain lifecycle. |
159
- | `BrowserPage` | class | Represents a top-level browser page, including its target lifecycle and child frames. |
160
- | `BrowserPerformance` | class | Reads Performance-domain metrics for one frame. |
161
- | `BrowserPermissionManager` | class | Applies permission overrides isolated to one browser context. |
162
- | `BrowserProfiler` | class | Records sampled JavaScript CPU profiles over one frame's Profiler domain. |
163
- | `BrowserReading` | class | Represents one captured document, parsed one time and projected to Markdown or plain text in bounded slices. |
164
- | `BrowserScriptManager` | class | Installs new-document scripts and promise-based host functions for one page. |
165
- | `BrowserSnapshot` | class | Represents a navigable, serializable browser DOM snapshot. |
166
- | `BrowserStorageManager` | class | Imports, exports, and clears cookie and web-storage state for one browser context. |
167
- | `BrowserToolset` | class | Publishes the browser vocabulary as `@orkestrel/tool` tools over one view and adopts the view's own tools beside them. |
168
- | `BrowserTouch` | class | Sends trusted touch input through Chromium's CDP Input domain. |
169
- | `BrowserTracing` | class | Captures Chromium traces streamed through the IO domain. |
170
- | `BrowserTransition` | class | Runs one asynchronous transition at a time, shared by every caller that joins it. |
171
- | `BrowserWebSocket` | class | Represents an observable WebSocket connection reconstructed from Network-domain events. |
172
- | `CDPClient` | class | Provides a lightweight Chrome DevTools Protocol client over a `CDPTransportInterface`. |
173
- | `BrowserPageElement` | class | Drives a referenced DOM element through its document's isolated world and the page input stream. |
174
- | `BrowserElementManager` | class | Captures accessibility trees and binds stable references to their owning frame sessions. |
175
- | `BrowserRecorder` | class | Records semantic steps from completed toolset actions and omits refused or timed-out actions. |
176
- | `BrowserReplay` | class | Prepares and replays a journey under a toolset hold, retaining its executed prefix. |
177
- | `BrowserJourneyToolset` | class | Registers the journey tools `record`, `save`, `journeys`, `edit`, `replay`, and `forget` over a toolset and owns the recording and the active replay. |
178
- | `MemoryBrowserJourneyStore` | class | Keeps owned journey snapshots and revision counters across deletion. |
179
- | `MemoryBrowserRunStore` | class | Keeps owned runs under their journey names and producer ids without directories. |
143
+ | API | Kind | Summary |
144
+ | --------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
145
+ | `BrowserAccessibility` | class | Captures Chromium Accessibility-domain snapshots for one page. |
146
+ | `BrowserClock` | class | Controls the Chromium virtual-time budget for deterministic page timers. |
147
+ | `BrowserCodegen` | class | Records semantic page gestures and compiles them into a journey module. |
148
+ | `BrowserContext` | class | Owns pages and shared state inside one Chromium browser context. |
149
+ | `BrowserCookieManager` | class | Performs cookie operations isolated to one browser context. |
150
+ | `BrowserCoverage` | class | Collects JavaScript precise coverage and CSS rule usage for one page target. |
151
+ | `BrowserDiagnostics` | class | Groups the tracing, coverage, performance, and profiler classes beneath one page. |
152
+ | `BrowserEmulationManager` | class | Applies rendering, identity, location, and network emulation for context pages. |
153
+ | `BrowserFrame` | class | Represents one attached document frame, evaluated through its own CDP execution world. |
154
+ | `BrowserHARManager` | class | Records and replays HTTP archives over one page network manager. |
155
+ | `BrowserKeyboard` | class | Sends trusted keyboard input through Chromium's CDP Input domain. |
156
+ | `BrowserMouse` | class | Sends trusted mouse input through Chromium's CDP Input domain. |
157
+ | `BrowserNavigationManager` | class | Parks URL-pattern and network-idle waits on page events and abort signals, and opens the records that settle the navigation an input starts. |
158
+ | `BrowserNetworkManager` | class | Drives the page-scoped Network and Fetch domain lifecycle. |
159
+ | `BrowserPage` | class | Represents a top-level browser page, including its target lifecycle and child frames. |
160
+ | `BrowserPerformance` | class | Reads Performance-domain metrics for one frame. |
161
+ | `BrowserPermissionManager` | class | Applies permission overrides isolated to one browser context. |
162
+ | `BrowserProfiler` | class | Records sampled JavaScript CPU profiles over one frame's Profiler domain. |
163
+ | `BrowserReading` | class | Represents one captured document, parsed one time and projected to Markdown or plain text in bounded slices. |
164
+ | `BrowserScriptManager` | class | Installs new-document scripts and promise-based host functions for one page. |
165
+ | `BrowserSnapshot` | class | Represents a navigable, serializable browser DOM snapshot. |
166
+ | `BrowserStorageManager` | class | Imports, exports, and clears cookie and web-storage state for one browser context. |
167
+ | `BrowserToolset` | class | Publishes the browser vocabulary as `@orkestrel/tool` tools over one view and adopts the view's own tools beside them. |
168
+ | `BrowserTouch` | class | Sends trusted touch input through Chromium's CDP Input domain. |
169
+ | `BrowserTracing` | class | Captures Chromium traces streamed through the IO domain. |
170
+ | `BrowserTransition` | class | Runs one asynchronous transition at a time, shared by every caller that joins it. |
171
+ | `BrowserWebSocket` | class | Represents an observable WebSocket connection reconstructed from Network-domain events. |
172
+ | `CDPClient` | class | Provides a lightweight Chrome DevTools Protocol client over a `CDPTransportInterface`. |
173
+ | `BrowserPageElement` | class | Drives a referenced DOM element through its document's isolated world and the page input stream. |
174
+ | `BrowserElementManager` | class | Captures accessibility trees and binds stable references to their owning frame sessions. |
175
+ | `BrowserRecorder` | class | Records semantic steps from completed toolset actions and omits refused or timed-out actions. |
176
+ | `BrowserReplay` | class | Prepares and replays a journey under a toolset hold, retaining its executed prefix. |
177
+ | `BrowserJourneyToolset` | class | Registers the journey tools `record`, `save`, `journeys`, `edit`, `replay`, `forget`, and `capture` over a toolset and owns the recording and the active replay. |
178
+ | `MemoryBrowserJourneyStore` | class | Keeps owned journey snapshots and revision counters across deletion. |
179
+ | `MemoryBrowserRunStore` | class | Keeps owned runs under their journey names and producer ids without directories. |
180
180
 
181
181
  #### Constants
182
182
 
@@ -232,7 +232,7 @@ The following table lists the core constants.
232
232
  | `BROWSER_TOOL_NAME_PATTERN` | const | Matches a page tool name the toolset can advertise: 1 to 64 ASCII letters, digits, underscores, and hyphens. |
233
233
  | `BROWSER_SCHEMES` | const | Names the URL schemes the `navigate` tool accepts by default: `http:` and `https:`. |
234
234
  | `BROWSER_TOOL_COPY` | const | Holds the advertised definition of each reserved tool: its description, its JSON Schema parameters, and its annotations. |
235
- | `BROWSER_JOURNEY_TOOL_NAMES` | const | Names the journey tools a toolset constructed with `journeys` registers and reserves: `record`, `save`, `journeys`, `edit`, `replay`, and `forget`. |
235
+ | `BROWSER_JOURNEY_TOOL_NAMES` | const | Names the journey tools a toolset constructed with `journeys` registers and reserves: `record`, `save`, `journeys`, `edit`, `replay`, `forget`, and `capture`. |
236
236
  | `BROWSER_JOURNEY_ACTIONS` | const | Names the native actions a journey step can hold: `click`, `type`, `press`, `navigate`, `wait`, `dialog`, and `switch`. |
237
237
  | `BROWSER_ACTION_OUTCOMES` | const | Lists every outcome a `BrowserAction` and a run step carry: `done`, `refused`, `timeout`, and `interrupted`. |
238
238
  | `BROWSER_ACTION_STAGES` | const | Lists every navigation stage a `BrowserAction` and a run step carry: `requested`, `committed`, and `loaded`. |
@@ -320,6 +320,8 @@ An error names its refusal in `code`. The following table lists every code that
320
320
  | `BROWSER_JOURNEY_LOCKED` | `BrowserError` | the file journey store's `set` and `delete`, the file run store's `open` and `clear`, `save`, `edit`, and `forget` | Another write holds the journey's `journey.lock`; the store refuses at once and never waits. |
321
321
  | `BROWSER_JOURNEY_FILE` | `BrowserError` | the file stores' `get` and `list`, `save`, `edit`, and `forget` for a store failure with no code, and a replay's run write | A stored file is empty, truncated, malformed, or names another journey or run, or the run write passed its bound. |
322
322
  | `BROWSER_JOURNEY_ACCESS` | `BrowserError` | the file stores | The filesystem refused permission; the message names the path. |
323
+ | `BROWSER_CAPTURE_UNTRUSTED` | `BrowserError` | `capture` | The current view is untrusted. |
324
+ | `BROWSER_CAPTURE_UNAVAILABLE` | `BrowserError` | `capture` | The view has no screenshot capability, or the runs store has no standalone file storage. |
323
325
  | `BROWSER_JOURNEY_PATH` | `BrowserError` | the file stores and their constructors, the memory stores' name checks, and the memory run store's `capture` | A journey name is invalid, an id or path escapes the root, a path component is a symbolic link, the root is missing, or a capture names a slot the store did not open. |
324
326
  | `BROWSER_JOURNEY_ARGUMENT` | `BrowserError` | the stores' `list`, the file stores' constructors, `BrowserJourneyToolset` construction, and `journeys` | A listing limit is not a positive safe integer, or an offset is not a nonnegative integer; store page offsets must also be safe integers. |
325
327
  | `BROWSER_JOURNEY_READONLY` | `BrowserError` | `record`, `save`, `edit`, and `forget` | The toolset was constructed with `journeys.readonly`. |
@@ -903,258 +905,258 @@ validateBrowserViewport({ width: 1280, height: 720 })
903
905
 
904
906
  The following table lists the core types.
905
907
 
906
- | API | Kind | Summary |
907
- | ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
908
- | `CDPTransportEventMap` | type | Maps the events emitted by a `CDPTransportInterface` — the raw text pipe a `CDPClientInterface` sends and receives JSON-RPC frames over. |
909
- | `CDPTransportInterface` | interface | Represents the text pipe a `CDPClient` sends and receives JSON-RPC frames over. |
910
- | `CDPClientEventMap` | type | Maps the events a `CDPClientInterface` emits. |
911
- | `CDPClientOptions` | interface | Describes the options for creating a `CDPClient` instance. |
912
- | `CDPSendOptions` | interface | Describes the options for one CDP method call. |
913
- | `CDPHandler` | type | Receives a subscribed CDP event with its params record. |
914
- | `CDPTarget` | interface | Represents one entry of the CDP `Target.getTargets` result. |
915
- | `CDPClientInterface` | interface | Provides a lightweight Chrome DevTools Protocol client over a `CDPTransportInterface`. |
916
- | `BrowserTransitionFunction` | type | Runs the work one `BrowserTransitionInterface` transition performs. |
917
- | `BrowserTransitionInterface` | interface | Represents one asynchronous transition shared by every caller that arrives while it runs. |
918
- | `BrowserWriterInterface` | interface | Provides a pluggable sink for persisting captured browser bytes to a path. |
919
- | `BrowserViewport` | interface | Describes the viewport dimensions for a browser page. |
920
- | `BrowserWaitUntil` | type | Names the page load condition for navigation — the CDP load event awaited by `navigate()`. |
921
- | `BrowserPageOptions` | interface | Describes the options for creating a `BrowserPage` instance. |
922
- | `BrowserNavigationOptions` | interface | Describes the options for page navigation. |
923
- | `BrowserNavigationResult` | interface | Describes the outcome of a top-level navigation command. |
924
- | `BrowserNavigationWatch` | interface | Holds the state retained while correlating navigation with Network events. |
925
- | `BrowserNavigationWait` | interface | Represents one pending navigation or network-idle wait. |
926
- | `BrowserLoaderFunction` | type | Reads the loader id of the page's current document, undefined before the first commit. |
927
- | `BrowserNavigationManagerInterface` | interface | Provides URL and network-idle waits associated with one page. |
928
- | `BrowserNavigationRecordInterface` | interface | Settles the navigation an input into one frame started, from the steps the page accepted after the record opened. |
929
- | `BrowserPopupManagerInterface` | interface | Opens the records that settle the popups an input into a page opens. |
930
- | `BrowserPopupRecordInterface` | interface | Settles the popups an input opened, from the `Page.windowOpen` reports the page's own session sends after the record opened. |
931
- | `BrowserDestinationRelationship` | type | Names the frame a submission targets relative to the frame whose document submitted, mirroring the HTML `_self`, `_parent`, and `_top` keywords. |
932
- | `BrowserDestination` | interface | Pairs a document that recorded a surviving submission with the submission's destination. |
933
- | `BrowserSettlementOptions` | interface | Configures a record's settlement. |
934
- | `BrowserNavigationStage` | type | Names how far a settled navigation got: requested, committed, or loaded. |
935
- | `BrowserNavigationReason` | type | Names why a frame requested a navigation, mirroring the CDP `Page.ClientNavigationReason` values that `Page.frameRequestedNavigation` carries as of Chromium 141. |
936
- | `BrowserSettlementResult` | interface | Describes the navigation a record settled. |
937
- | `BrowserNavigationEventMap` | type | Maps the navigation steps a page accepts from the session that owns each frame, which it hands to its navigation and element managers. |
938
- | `BrowserInputOptions` | interface | Describes the options shared by every trusted input operation. |
939
- | `BrowserClickOptions` | interface | Describes the options for a trusted mouse click. |
940
- | `BrowserDragOptions` | interface | Describes the options for a trusted mouse drag. |
941
- | `BrowserScreenshotOptions` | interface | Describes the options for taking a page screenshot. |
942
- | `BrowserScreenshotResult` | interface | Describes the result of a page screenshot. |
943
- | `BrowserTeardownFunction` | type | Runs one teardown step to settlement while the first failure is retained. |
944
- | `BrowserHandleInterface` | interface | Represents a remote JavaScript object retained in one frame execution context. |
945
- | `BrowserBindingHandler` | type | Runs a host function exposed into page JavaScript. |
946
- | `BrowserBindingCall` | interface | Describes a decoded page-to-host binding call. |
947
- | `BrowserScriptManagerInterface` | interface | Manages initialization scripts and host bindings for one page. |
948
- | `BrowserScriptEntry` | interface | Represents one installed new-document script and its optional host binding owner. |
949
- | `BrowserAXNode` | interface | Represents one decoded Chromium accessibility node. |
950
- | `BrowserAccessibilitySnapshot` | interface | Describes a serializable accessibility-tree snapshot. |
951
- | `BrowserAccessibilityOptions` | interface | Describes the options for an accessibility snapshot. |
952
- | `BrowserAccessibilityInterface` | interface | Inspects the accessibility tree. |
953
- | `BrowserTracingOptions` | interface | Describes the options for a Chromium trace capture. |
954
- | `BrowserTracingResult` | interface | Describes the result of a trace capture. |
955
- | `BrowserStreamChunk` | interface | Represents one decoded IO stream read. |
956
- | `BrowserTracingInterface` | interface | Drives the trace capture lifecycle. |
957
- | `BrowserCoverageRange` | interface | Describes a source range reported by JavaScript or CSS coverage. |
958
- | `BrowserFunctionCoverage` | interface | Describes function coverage inside one script. |
959
- | `BrowserScriptCoverage` | interface | Describes JavaScript script coverage. |
960
- | `BrowserStyleCoverage` | interface | Describes CSS stylesheet coverage. |
961
- | `BrowserCoverageOptions` | interface | Describes the options for a coverage capture. |
962
- | `BrowserCoverageResult` | interface | Describes combined JavaScript and CSS usage. |
963
- | `BrowserCoverageInterface` | interface | Drives the coverage capture lifecycle. |
964
- | `BrowserMetric` | interface | Represents one Performance-domain metric. |
965
- | `BrowserProfileFrame` | interface | Describes a JavaScript call frame from a CPU profile. |
966
- | `BrowserProfileNode` | interface | Represents one node in a sampled CPU profile. |
967
- | `BrowserProfile` | interface | Describes a sampled CPU profile. |
968
- | `BrowserPerformanceInterface` | interface | Reads Performance-domain metrics. |
969
- | `BrowserProfilerInterface` | interface | Drives the sampled CPU profile lifecycle. |
970
- | `BrowserDiagnosticsInterface` | interface | Groups the diagnostics by capability. |
971
- | `BrowserClockInterface` | interface | Controls Chromium virtual time for deterministic page timers. |
972
- | `BrowserPoint` | interface | Describes a point in viewport CSS pixels. |
973
- | `BrowserMouseButton` | type | Names a mouse button understood by Chromium's Input domain. |
974
- | `BrowserScreenshotScale` | type | Names a screenshot coordinate scale. |
975
- | `BrowserKey` | interface | Describes normalized CDP keyboard key data. |
976
- | `BrowserChord` | interface | Describes a parsed keyboard chord. |
977
- | `BrowserOperationOptions` | type | Collects every option a trusted-input operation can carry. |
978
- | `BrowserKeyboardInterface` | interface | Provides keyboard input operations bound to one frame target session. |
979
- | `BrowserMouseInterface` | interface | Provides mouse input operations bound to one frame target session. |
980
- | `BrowserTouchInterface` | interface | Provides touch input operations bound to one frame target session. |
981
- | `BrowserActionabilityOptions` | interface | Describes the actionability checks performed before element input. |
982
- | `BrowserQuad` | interface | Describes a decoded content quad and its actionable center. |
983
- | `BrowserMargin` | interface | Describes the paper margin lengths accepted by Chromium print-to-PDF. |
984
- | `BrowserPDFOptions` | interface | Describes the options for printing a Chromium page to PDF. |
985
- | `BrowserPDFResult` | interface | Describes the result of printing a page to PDF. |
986
- | `BrowserDialogCategory` | type | Names a JavaScript dialog category reported by Chromium. |
987
- | `BrowserDialogInterface` | interface | Represents one active JavaScript dialog. |
988
- | `BrowserFileChooserInterface` | interface | Represents one intercepted file chooser. |
989
- | `BrowserDownloadStatus` | type | Names a download lifecycle phase. |
990
- | `BrowserDownloadEventMap` | type | Maps the download progress events. |
991
- | `BrowserDownloadProgress` | interface | Describes a protocol-neutral download progress update. |
992
- | `BrowserDownloadStart` | interface | Describes a decoded `Browser.downloadWillBegin` event. |
993
- | `BrowserDownloadInterface` | interface | Represents one context download tracked through Chromium's Browser domain. |
994
- | `BrowserConsoleMessage` | interface | Represents one console API call. |
995
- | `BrowserStackFrame` | interface | Represents one browser-side stack frame. |
996
- | `BrowserPageError` | interface | Represents one uncaught page exception. |
997
- | `BrowserWorkerCategory` | type | Names a worker target category. |
998
- | `BrowserWorkerInterface` | interface | Represents a script worker attached to a page target. |
999
- | `BrowserPageEventMap` | type | Maps the typed page, frame, target, and user-visible browser events. |
1000
- | `BrowserRequest` | interface | Represents one observed browser request. |
1001
- | `BrowserSecurity` | interface | Describes the TLS details supplied with a browser response. |
1002
- | `BrowserTimingRange` | interface | Describes the start/end pair for one network timing phase. |
1003
- | `BrowserTiming` | interface | Holds network timing values in milliseconds relative to request time. |
1004
- | `BrowserResponse` | interface | Represents one observed browser response. |
1005
- | `BrowserRequestFailure` | interface | Represents one failed browser request. |
1006
- | `BrowserWebSocketFrame` | interface | Describes a WebSocket frame payload. |
1007
- | `BrowserWebSocketEventMap` | type | Maps the WebSocket lifecycle events. |
1008
- | `BrowserWebSocketInterface` | interface | Represents one observed WebSocket connection. |
1009
- | `BrowserNetworkEventMap` | type | Maps the network events a page's network manager emits. |
1010
- | `BrowserRouteQuery` | interface | Describes route matching criteria. Omitted fields match all values. |
1011
- | `BrowserRouteContinueOptions` | interface | Describes the overrides supplied when continuing an intercepted request. |
1012
- | `BrowserRouteFulfillOptions` | interface | Describes the synthetic response supplied when fulfilling an intercepted request. |
1013
- | `BrowserRouteInterface` | interface | Represents one paused Fetch-domain request. |
1014
- | `BrowserRouteHandler` | type | Runs for a matching intercepted request. |
1015
- | `BrowserRouteDefinition` | interface | Represents one installed network route. |
1016
- | `BrowserHAROptions` | interface | Describes the options for a HAR recording. |
1017
- | `BrowserHARValue` | interface | Represents one name/value pair in an HTTP archive. |
1018
- | `BrowserHARCookie` | interface | Represents one cookie in an HTTP archive. |
1019
- | `BrowserHARPost` | interface | Describes request body metadata in an HTTP archive. |
1020
- | `BrowserHARContent` | interface | Describes response body metadata in an HTTP archive. |
1021
- | `BrowserHARRequest` | interface | Describes a HAR 1.2 request entry. |
1022
- | `BrowserHARResponse` | interface | Describes a HAR 1.2 response entry. |
1023
- | `BrowserHARTimings` | interface | Holds HAR 1.2 phase timings in milliseconds. |
1024
- | `BrowserHAREntry` | interface | Represents one completed HTTP exchange in a HAR recording. |
1025
- | `BrowserHARPending` | interface | Holds recording state until a request finishes; a new value replaces it on each update. |
1026
- | `BrowserHARCreator` | interface | Describes the tool identity embedded in an HTTP archive. |
1027
- | `BrowserHARLog` | interface | Describes the HAR 1.2 log object. |
1028
- | `BrowserHAR` | interface | Describes the standards-shaped HAR 1.2 document produced by the network manager. |
1029
- | `BrowserHARReplayOptions` | interface | Describes HAR replay behavior. |
1030
- | `BrowserHARManagerInterface` | interface | Provides HAR recording and replay operations. |
1031
- | `BrowserNetworkManagerInterface` | interface | Provides page-scoped network observation and interception. |
1032
- | `BrowserSameSite` | type | Names a cookie same-site policy understood by Chromium. |
1033
- | `BrowserCookiePartition` | interface | Describes a cookie partition key used by CHIPS-partitioned cookies. |
1034
- | `BrowserCookie` | interface | Represents one cookie returned from a browser context. |
1035
- | `BrowserCookieInput` | interface | Describes the input used to create or replace a browser cookie. |
1036
- | `BrowserCookieFilter` | interface | Describes optional narrowing criteria for clearing context cookies. |
1037
- | `BrowserCookieManagerInterface` | interface | Provides cookie operations scoped to one browser context. |
1038
- | `BrowserPermissionManagerInterface` | interface | Provides permission override operations scoped to one browser context. |
1039
- | `BrowserStorageEntry` | interface | Represents one key/value pair from web storage. |
1040
- | `BrowserStorageOrigin` | interface | Describes an origin-scoped local and session storage snapshot. |
1041
- | `BrowserStorageState` | interface | Describes a portable browser authentication and storage snapshot. |
1042
- | `BrowserStorageOptions` | interface | Describes the options for collecting storage state from selected origins. |
1043
- | `BrowserStorageManagerInterface` | interface | Provides storage-state import, export, and clearing operations. |
1044
- | `BrowserCredentials` | interface | Describes the HTTP basic-auth credentials applied to context pages. |
1045
- | `BrowserGeolocation` | interface | Describes a geographic location override. |
1046
- | `BrowserMedia` | interface | Describes browser color and media feature overrides. |
1047
- | `BrowserUserAgent` | interface | Describes user-agent metadata accepted by Chromium emulation. |
1048
- | `BrowserEmulationOptions` | interface | Describes network and rendering overrides inherited by context pages. |
1049
- | `BrowserPagesFunction` | type | Returns the context's live pages at call time. |
1050
- | `BrowserEmulationManagerInterface` | interface | Configures context-scoped emulation. |
1051
- | `BrowserProxy` | interface | Describes proxy settings used when creating an isolated browser context. |
1052
- | `BrowserDownloadOptions` | interface | Describes the download policy for a browser context. |
1053
- | `BrowserContextOptions` | interface | Describes the options for creating and configuring an isolated browser context. |
1054
- | `BrowserContextEventMap` | type | Maps the browser-context lifecycle events. |
1055
- | `BrowserJourneyBinding` | type | Binds a native action's string argument to a literal or to one declared parameter by name. |
1056
- | `BrowserJourneyParameter` | interface | Declares one parameter a journey takes: its default, or none when it is a secret. |
1057
- | `BrowserJourneyTarget` | interface | Names the element an acting step acts on the way a receipt names it, with the record-time evidence a developer reads when a resolution is refused. |
1058
- | `BrowserJourneyTab` | interface | Names the tab a `switch` step moves to, portably. |
1059
- | `BrowserJourneyStepInput` | interface | Describes one step before it holds an id: a call of a toolset tool with its element or tab named as data. |
1060
- | `BrowserJourneyStep` | interface | Describes a step with its identity: `s` followed by a positive integer, stable across edits and never reused. |
1061
- | `BrowserJourney` | interface | Describes one user intent as data; `next` is the number the next added step takes. |
1062
- | `BrowserJourneyRevision` | interface | Carries a journey with the revision the store assigned; `revision` is absent for a journey the store never held. |
1063
- | `BrowserJourneyEdit` | type | Describes one change to a journey; `editBrowserJourney` applies a batch to a copy, in order, and refuses it whole on the first invalid edit. |
1064
- | `BrowserJourneyEditRequest` | type | Describes an edit as the `edit` tool receives it over the wire: an added or updated step can name `ref` instead of a target, converted from the current view before the pure editor runs. |
1065
- | `BrowserRecorderEventMap` | type | Maps the events a recorder emits. |
1066
- | `BrowserRecorderInterface` | interface | Records the steps of a journey from one source as they happen and turns them into a journey. |
1067
- | `BrowserRecorderOptions` | interface | Configures a recorder. |
1068
- | `BrowserAction` | interface | Describes what became of one action the toolset performed. |
1069
- | `BrowserStepOutcome` | type | Names how one step ended. |
1070
- | `BrowserRunOutcome` | type | Names how a run ended. |
1071
- | `BrowserToolsetResult` | interface | Carries a performed call's tool result beside its structured action, present when the call reached a handler, and the value a failed handler threw. |
1072
- | `BrowserHoldInterface` | interface | Owns the toolset while a replay runs; `destroy` releases it. |
1073
- | `BrowserRunStep` | interface | Describes one replayed step; `action`, `trigger`, and `result` carry the meaning of the skill's `JournalStep` fields. |
1074
- | `BrowserRun` | interface | Describes one run of a journey; `inputs` omits secret values; `fault` carries the run file's write failure. |
1075
- | `BrowserReplayOptions` | interface | Configures one replay. |
1076
- | `BrowserReplayEventMap` | type | Maps the events a replay emits. |
1077
- | `BrowserReplayInterface` | interface | Replays one journey over a toolset. |
1078
- | `BrowserStoreOptions` | interface | Carries the signal a store call honours. |
1079
- | `BrowserJourneyValidationContext` | interface | Identifies the parameter binding that failed journey validation. |
1080
- | `BrowserStoreFault` | interface | Names one entry a listing could not read. |
1081
- | `BrowserStorePage` | interface | Carries one page of a listing with the entries it could not read. |
1082
- | `BrowserJourneyStoreInterface` | interface | Keeps journeys by name with a revision per write. |
1083
- | `BrowserRunSlot` | interface | Names the run directory a store opened, as data. |
1084
- | `BrowserRunStoreInterface` | interface | Keeps runs by the journey name and run id the run carries. |
1085
- | `BrowserJourneyOptions` | interface | Configures the journey toolset a toolset constructs. |
1086
- | `BrowserJourneyToolsetInterface` | interface | Registers the six journey tools over a toolset and owns the recording and the active replay. |
1087
- | `BrowserCodegenLanguage` | type | Names the target language for a compiled codegen script. |
1088
- | `BrowserCodegenInterface` | interface | Records semantic page gestures and compiles the resulting journey. |
1089
- | `BrowserCodegenScript` | interface | Carries the module `compileBrowserJourney` emits with the gap steps that refuse it. |
1090
- | `BrowserCodegenGesture` | interface | Carries a sanitized gesture from the page listener without password values. |
1091
- | `BrowserReadOptions` | interface | Describes the options for one slice of a reading's Markdown or plain-text projection. |
1092
- | `BrowserReadResult` | interface | Describes one slice of a reading's projection. |
1093
- | `BrowserReadMatch` | interface | Describes a matching line and its character offset in a reading's projection. |
1094
- | `BrowserEpochFunction` | type | Reads the navigation epoch of the frame a reading was captured from. |
1095
- | `BrowserReadingInput` | interface | Describes the captured document a reading is built from. |
1096
- | `BrowserReadingInterface` | interface | Represents one captured document, parsed one time and projected to Markdown or plain text in bounded slices. |
1097
- | `BrowserSessionFunction` | type | Resolves the current CDP session for a frame id. |
1098
- | `BrowserWorldFunction` | type | Resolves the isolated-world execution context a page caches for one frame document, creating the world on the given session when none is cached. |
1099
- | `BrowserElementQuery` | interface | Describes an accessibility or CSS query within an optional element reference. |
1100
- | `BrowserWaitOptions` | interface | Configures a text or element wait, including whether absence satisfies it. |
1101
- | `BrowserOutlineOptions` | interface | Configures an outline's element limit, optional subtree, and search. |
1102
- | `BrowserOutline` | interface | Carries a document-order outline and its included and available element counts. |
1103
- | `BrowserOutlineNode` | interface | Associates an outline row with its frame, session, and optional actionable reference. |
1104
- | `BrowserElementGeometry` | interface | Retains both session-local and page-composed element geometry. |
1105
- | `BrowserElementSubject` | interface | Identifies a manager failure without inventing an element reference. |
1106
- | `BrowserElementReason` | type | Identifies the refusal an element action reports. |
1107
- | `BrowserElementRefusal` | interface | Describes how an element action reports one refusal its compiled in-page check throws: the reason, and the detail that follows the element's name, or `undefined` for the reason's own wording. |
1108
- | `BrowserReferenceFunction` | type | Allocates the next reference from the owning browser context. |
1109
- | `BrowserElementWorldFunction` | type | Resolves the page-owned isolated world for a particular frame and session. |
1110
- | `BrowserReadinessFunction` | type | Waits for the current document's DOM readiness. |
1111
- | `BrowserElementPointFunction` | type | Composes a frame-local point into page coordinates. |
1112
- | `BrowserElementManagerInput` | interface | Provides the protocol and ownership boundaries used by a page element manager. |
1113
- | `BrowserElementInput` | interface | Binds an element to its document identity and the page's shared protocol resources. |
1114
- | `BrowserReadinessWait` | interface | Holds the resources of one lifecycle-event readiness wait. |
1115
- | `BrowserElementInterface` | interface | Provides actions and reading through a stable document element reference. |
1116
- | `BrowserPageElementInterface` | interface | Provides trusted page input and capture for a referenced element. |
1117
- | `BrowserElementManagerInterface` | interface | Captures, queries, and retains references to a view's elements. |
1118
- | `BrowserViewEventMap` | type | Maps the `console` and `error` events of a view that observes its document's output. |
1119
- | `BrowserViewInterface` | interface | Provides the document operations shared by remote and DOM-native views. |
1120
- | `BrowserCallOptions` | interface | Describes the options every asynchronous page, frame, handle, and worker call accepts. |
1121
- | `BrowserToolAnnotation` | interface | Transliterates the WebMCP protocol's `Annotation` type, retaining its wire spelling. |
1122
- | `BrowserTool` | interface | Describes a registered WebMCP tool and its owning document. |
1123
- | `BrowserToolRemoval` | interface | Identifies a removed WebMCP tool by document and name. |
1124
- | `BrowserInvocation` | interface | Describes a WebMCP invocation observed on the protocol. |
1125
- | `BrowserInvocationResult` | interface | Carries a terminal WebMCP status and its untrusted output or error. |
1126
- | `BrowserRegistryEventMap` | type | Maps registry changes and observed WebMCP invocation events. |
1127
- | `BrowserRegistryOptions` | interface | Configures registry listeners and listener-error handling. |
1128
- | `BrowserRegistryInterface` | interface | Mirrors the experimental WebMCP protocol domain for a page. |
1129
- | `BrowserRegistryPending` | interface | Holds one unsettled registry execution and its resource cleanup. |
1130
- | `BrowserToolName` | type | Names a tool the browser toolset reserves: the generic tools, the staged `dialog`, the opt-in `tabs` and `switch`, and the journey tools `record`, `save`, `journeys`, `edit`, `replay`, and `forget`, which a toolset constructed with `journeys` reserves. |
1131
- | `BrowserToolsetReason` | type | Names why a toolset declined a page tool. |
1132
- | `BrowserToolSourceEventMap` | type | Maps the signal a tool source emits when its page's tools change. |
1133
- | `BrowserToolSourceInterface` | interface | Supplies page-registered tools to a toolset through a contract free of protocol types. |
1134
- | `BrowserToolsetEventMap` | type | Maps the events a toolset emits. |
1135
- | `BrowserToolsetOptions` | interface | Configures a browser toolset. |
1136
- | `BrowserFollowOptions` | interface | Configures one step a toolset follows. |
1137
- | `BrowserTab` | interface | Describes one open tab of a toolset's context, which the `tabs` tool lists one per line. |
1138
- | `BrowserToolsetInterface` | interface | Publishes the browser vocabulary as tools over one current view and adopts the page's own tools beside them. |
1139
- | `BrowserToolsetHandler` | type | Runs one toolset tool inside the toolset's boundary. |
1140
- | `BrowserToolsetWatch` | interface | Holds the listeners a toolset attaches to one followed page. |
1141
- | `BrowserReceipt` | interface | Describes one tool receipt before rendering. |
1142
- | `BrowserFrameInfo` | interface | Describes serializable frame metadata decoded from CDP `Page.getFrameTree`. |
1143
- | `BrowserFrameInterface` | interface | Provides the operations shared by a top-level page and an iframe document. |
1144
- | `BrowserRect` | type | Represents a rectangle in CSS pixels: x, y, width, height. |
1145
- | `BrowserLayout` | interface | Describes layout data associated with one captured DOM node. |
1146
- | `BrowserNode` | interface | Represents one serializable DOM node decoded from a CDP DOM snapshot. |
1147
- | `BrowserDocument` | interface | Represents one document captured in a CDP DOM snapshot. |
1148
- | `BrowserSnapshotInput` | interface | Describes the serializable input for a navigable browser snapshot — the form a `BrowserSnapshot` is built from and serializes back to. |
1149
- | `BrowserWalkOrder` | type | Names the structural ordering for a browser snapshot walk. |
1150
- | `BrowserWalkOptions` | interface | Describes the options for walking a browser snapshot. |
1151
- | `BrowserSiblingRelation` | type | Names a structural sibling relationship relative to a browser node. |
1152
- | `BrowserSnapshotInterface` | interface | Represents a navigable, serializable snapshot of every document attached to a page, extending `BrowserSnapshotInput` with walking, structural relationships, search, and path derivation over plain `BrowserNode` values. |
1153
- | `BrowserSnapshotOptions` | interface | Describes the options configuring capture through `BrowserPageInterface` `snapshot()`. The snapshot entity's creation input is `BrowserSnapshotInput`. |
1154
- | `BrowserNodePredicate` | type | Names the predicate form accepted by `BrowserSnapshotInterface` find, filter, and closest methods. |
1155
- | `BrowserNodeQuery` | interface | Describes a declarative browser-node matcher used by `matchesBrowserNode`. |
1156
- | `BrowserPageInterface` | interface | Abstracts a single top-level browser page, extending `BrowserFrameInterface` with navigation, screenshots, frame discovery, DOM snapshots, codegen, and target teardown. |
1157
- | `BrowserContextInterface` | interface | Represents an isolated browser session over a CDP browser context. |
908
+ | API | Kind | Summary |
909
+ | ----------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
910
+ | `CDPTransportEventMap` | type | Maps the events emitted by a `CDPTransportInterface` — the raw text pipe a `CDPClientInterface` sends and receives JSON-RPC frames over. |
911
+ | `CDPTransportInterface` | interface | Represents the text pipe a `CDPClient` sends and receives JSON-RPC frames over. |
912
+ | `CDPClientEventMap` | type | Maps the events a `CDPClientInterface` emits. |
913
+ | `CDPClientOptions` | interface | Describes the options for creating a `CDPClient` instance. |
914
+ | `CDPSendOptions` | interface | Describes the options for one CDP method call. |
915
+ | `CDPHandler` | type | Receives a subscribed CDP event with its params record. |
916
+ | `CDPTarget` | interface | Represents one entry of the CDP `Target.getTargets` result. |
917
+ | `CDPClientInterface` | interface | Provides a lightweight Chrome DevTools Protocol client over a `CDPTransportInterface`. |
918
+ | `BrowserTransitionFunction` | type | Runs the work one `BrowserTransitionInterface` transition performs. |
919
+ | `BrowserTransitionInterface` | interface | Represents one asynchronous transition shared by every caller that arrives while it runs. |
920
+ | `BrowserWriterInterface` | interface | Provides a pluggable sink for persisting captured browser bytes to a path. |
921
+ | `BrowserViewport` | interface | Describes the viewport dimensions for a browser page. |
922
+ | `BrowserWaitUntil` | type | Names the page load condition for navigation — the CDP load event awaited by `navigate()`. |
923
+ | `BrowserPageOptions` | interface | Describes the options for creating a `BrowserPage` instance. |
924
+ | `BrowserNavigationOptions` | interface | Describes the options for page navigation. |
925
+ | `BrowserNavigationResult` | interface | Describes the outcome of a top-level navigation command. |
926
+ | `BrowserNavigationWatch` | interface | Holds the state retained while correlating navigation with Network events. |
927
+ | `BrowserNavigationWait` | interface | Represents one pending navigation or network-idle wait. |
928
+ | `BrowserLoaderFunction` | type | Reads the loader id of the page's current document, undefined before the first commit. |
929
+ | `BrowserNavigationManagerInterface` | interface | Provides URL and network-idle waits associated with one page. |
930
+ | `BrowserNavigationRecordInterface` | interface | Settles the navigation an input into one frame started, from the steps the page accepted after the record opened. |
931
+ | `BrowserPopupManagerInterface` | interface | Opens the records that settle the popups an input into a page opens. |
932
+ | `BrowserPopupRecordInterface` | interface | Settles the popups an input opened, from the `Page.windowOpen` reports the page's own session sends after the record opened. |
933
+ | `BrowserDestinationRelationship` | type | Names the frame a submission targets relative to the frame whose document submitted, mirroring the HTML `_self`, `_parent`, and `_top` keywords. |
934
+ | `BrowserDestination` | interface | Pairs a document that recorded a surviving submission with the submission's destination. |
935
+ | `BrowserSettlementOptions` | interface | Configures a record's settlement. |
936
+ | `BrowserNavigationStage` | type | Names how far a settled navigation got: requested, committed, or loaded. |
937
+ | `BrowserNavigationReason` | type | Names why a frame requested a navigation, mirroring the CDP `Page.ClientNavigationReason` values that `Page.frameRequestedNavigation` carries as of Chromium 141. |
938
+ | `BrowserSettlementResult` | interface | Describes the navigation a record settled. |
939
+ | `BrowserNavigationEventMap` | type | Maps the navigation steps a page accepts from the session that owns each frame, which it hands to its navigation and element managers. |
940
+ | `BrowserInputOptions` | interface | Describes the options shared by every trusted input operation. |
941
+ | `BrowserClickOptions` | interface | Describes the options for a trusted mouse click. |
942
+ | `BrowserDragOptions` | interface | Describes the options for a trusted mouse drag. |
943
+ | `BrowserScreenshotOptions` | interface | Describes the options for taking a page screenshot. |
944
+ | `BrowserScreenshotResult` | interface | Describes the result of a page screenshot. |
945
+ | `BrowserTeardownFunction` | type | Runs one teardown step to settlement while the first failure is retained. |
946
+ | `BrowserHandleInterface` | interface | Represents a remote JavaScript object retained in one frame execution context. |
947
+ | `BrowserBindingHandler` | type | Runs a host function exposed into page JavaScript. |
948
+ | `BrowserBindingCall` | interface | Describes a decoded page-to-host binding call. |
949
+ | `BrowserScriptManagerInterface` | interface | Manages initialization scripts and host bindings for one page. |
950
+ | `BrowserScriptEntry` | interface | Represents one installed new-document script and its optional host binding owner. |
951
+ | `BrowserAXNode` | interface | Represents one decoded Chromium accessibility node. |
952
+ | `BrowserAccessibilitySnapshot` | interface | Describes a serializable accessibility-tree snapshot. |
953
+ | `BrowserAccessibilityOptions` | interface | Describes the options for an accessibility snapshot. |
954
+ | `BrowserAccessibilityInterface` | interface | Inspects the accessibility tree. |
955
+ | `BrowserTracingOptions` | interface | Describes the options for a Chromium trace capture. |
956
+ | `BrowserTracingResult` | interface | Describes the result of a trace capture. |
957
+ | `BrowserStreamChunk` | interface | Represents one decoded IO stream read. |
958
+ | `BrowserTracingInterface` | interface | Drives the trace capture lifecycle. |
959
+ | `BrowserCoverageRange` | interface | Describes a source range reported by JavaScript or CSS coverage. |
960
+ | `BrowserFunctionCoverage` | interface | Describes function coverage inside one script. |
961
+ | `BrowserScriptCoverage` | interface | Describes JavaScript script coverage. |
962
+ | `BrowserStyleCoverage` | interface | Describes CSS stylesheet coverage. |
963
+ | `BrowserCoverageOptions` | interface | Describes the options for a coverage capture. |
964
+ | `BrowserCoverageResult` | interface | Describes combined JavaScript and CSS usage. |
965
+ | `BrowserCoverageInterface` | interface | Drives the coverage capture lifecycle. |
966
+ | `BrowserMetric` | interface | Represents one Performance-domain metric. |
967
+ | `BrowserProfileFrame` | interface | Describes a JavaScript call frame from a CPU profile. |
968
+ | `BrowserProfileNode` | interface | Represents one node in a sampled CPU profile. |
969
+ | `BrowserProfile` | interface | Describes a sampled CPU profile. |
970
+ | `BrowserPerformanceInterface` | interface | Reads Performance-domain metrics. |
971
+ | `BrowserProfilerInterface` | interface | Drives the sampled CPU profile lifecycle. |
972
+ | `BrowserDiagnosticsInterface` | interface | Groups the diagnostics by capability. |
973
+ | `BrowserClockInterface` | interface | Controls Chromium virtual time for deterministic page timers. |
974
+ | `BrowserPoint` | interface | Describes a point in viewport CSS pixels. |
975
+ | `BrowserMouseButton` | type | Names a mouse button understood by Chromium's Input domain. |
976
+ | `BrowserScreenshotScale` | type | Names a screenshot coordinate scale. |
977
+ | `BrowserKey` | interface | Describes normalized CDP keyboard key data. |
978
+ | `BrowserChord` | interface | Describes a parsed keyboard chord. |
979
+ | `BrowserOperationOptions` | type | Collects every option a trusted-input operation can carry. |
980
+ | `BrowserKeyboardInterface` | interface | Provides keyboard input operations bound to one frame target session. |
981
+ | `BrowserMouseInterface` | interface | Provides mouse input operations bound to one frame target session. |
982
+ | `BrowserTouchInterface` | interface | Provides touch input operations bound to one frame target session. |
983
+ | `BrowserActionabilityOptions` | interface | Describes the actionability checks performed before element input. |
984
+ | `BrowserQuad` | interface | Describes a decoded content quad and its actionable center. |
985
+ | `BrowserMargin` | interface | Describes the paper margin lengths accepted by Chromium print-to-PDF. |
986
+ | `BrowserPDFOptions` | interface | Describes the options for printing a Chromium page to PDF. |
987
+ | `BrowserPDFResult` | interface | Describes the result of printing a page to PDF. |
988
+ | `BrowserDialogCategory` | type | Names a JavaScript dialog category reported by Chromium. |
989
+ | `BrowserDialogInterface` | interface | Represents one active JavaScript dialog. |
990
+ | `BrowserFileChooserInterface` | interface | Represents one intercepted file chooser. |
991
+ | `BrowserDownloadStatus` | type | Names a download lifecycle phase. |
992
+ | `BrowserDownloadEventMap` | type | Maps the download progress events. |
993
+ | `BrowserDownloadProgress` | interface | Describes a protocol-neutral download progress update. |
994
+ | `BrowserDownloadStart` | interface | Describes a decoded `Browser.downloadWillBegin` event. |
995
+ | `BrowserDownloadInterface` | interface | Represents one context download tracked through Chromium's Browser domain. |
996
+ | `BrowserConsoleMessage` | interface | Represents one console API call. |
997
+ | `BrowserStackFrame` | interface | Represents one browser-side stack frame. |
998
+ | `BrowserPageError` | interface | Represents one uncaught page exception. |
999
+ | `BrowserWorkerCategory` | type | Names a worker target category. |
1000
+ | `BrowserWorkerInterface` | interface | Represents a script worker attached to a page target. |
1001
+ | `BrowserPageEventMap` | type | Maps the typed page, frame, target, and user-visible browser events. |
1002
+ | `BrowserRequest` | interface | Represents one observed browser request. |
1003
+ | `BrowserSecurity` | interface | Describes the TLS details supplied with a browser response. |
1004
+ | `BrowserTimingRange` | interface | Describes the start/end pair for one network timing phase. |
1005
+ | `BrowserTiming` | interface | Holds network timing values in milliseconds relative to request time. |
1006
+ | `BrowserResponse` | interface | Represents one observed browser response. |
1007
+ | `BrowserRequestFailure` | interface | Represents one failed browser request. |
1008
+ | `BrowserWebSocketFrame` | interface | Describes a WebSocket frame payload. |
1009
+ | `BrowserWebSocketEventMap` | type | Maps the WebSocket lifecycle events. |
1010
+ | `BrowserWebSocketInterface` | interface | Represents one observed WebSocket connection. |
1011
+ | `BrowserNetworkEventMap` | type | Maps the network events a page's network manager emits. |
1012
+ | `BrowserRouteQuery` | interface | Describes route matching criteria. Omitted fields match all values. |
1013
+ | `BrowserRouteContinueOptions` | interface | Describes the overrides supplied when continuing an intercepted request. |
1014
+ | `BrowserRouteFulfillOptions` | interface | Describes the synthetic response supplied when fulfilling an intercepted request. |
1015
+ | `BrowserRouteInterface` | interface | Represents one paused Fetch-domain request. |
1016
+ | `BrowserRouteHandler` | type | Runs for a matching intercepted request. |
1017
+ | `BrowserRouteDefinition` | interface | Represents one installed network route. |
1018
+ | `BrowserHAROptions` | interface | Describes the options for a HAR recording. |
1019
+ | `BrowserHARValue` | interface | Represents one name/value pair in an HTTP archive. |
1020
+ | `BrowserHARCookie` | interface | Represents one cookie in an HTTP archive. |
1021
+ | `BrowserHARPost` | interface | Describes request body metadata in an HTTP archive. |
1022
+ | `BrowserHARContent` | interface | Describes response body metadata in an HTTP archive. |
1023
+ | `BrowserHARRequest` | interface | Describes a HAR 1.2 request entry. |
1024
+ | `BrowserHARResponse` | interface | Describes a HAR 1.2 response entry. |
1025
+ | `BrowserHARTimings` | interface | Holds HAR 1.2 phase timings in milliseconds. |
1026
+ | `BrowserHAREntry` | interface | Represents one completed HTTP exchange in a HAR recording. |
1027
+ | `BrowserHARPending` | interface | Holds recording state until a request finishes; a new value replaces it on each update. |
1028
+ | `BrowserHARCreator` | interface | Describes the tool identity embedded in an HTTP archive. |
1029
+ | `BrowserHARLog` | interface | Describes the HAR 1.2 log object. |
1030
+ | `BrowserHAR` | interface | Describes the standards-shaped HAR 1.2 document produced by the network manager. |
1031
+ | `BrowserHARReplayOptions` | interface | Describes HAR replay behavior. |
1032
+ | `BrowserHARManagerInterface` | interface | Provides HAR recording and replay operations. |
1033
+ | `BrowserNetworkManagerInterface` | interface | Provides page-scoped network observation and interception. |
1034
+ | `BrowserSameSite` | type | Names a cookie same-site policy understood by Chromium. |
1035
+ | `BrowserCookiePartition` | interface | Describes a cookie partition key used by CHIPS-partitioned cookies. |
1036
+ | `BrowserCookie` | interface | Represents one cookie returned from a browser context. |
1037
+ | `BrowserCookieInput` | interface | Describes the input used to create or replace a browser cookie. |
1038
+ | `BrowserCookieFilter` | interface | Describes optional narrowing criteria for clearing context cookies. |
1039
+ | `BrowserCookieManagerInterface` | interface | Provides cookie operations scoped to one browser context. |
1040
+ | `BrowserPermissionManagerInterface` | interface | Provides permission override operations scoped to one browser context. |
1041
+ | `BrowserStorageEntry` | interface | Represents one key/value pair from web storage. |
1042
+ | `BrowserStorageOrigin` | interface | Describes an origin-scoped local and session storage snapshot. |
1043
+ | `BrowserStorageState` | interface | Describes a portable browser authentication and storage snapshot. |
1044
+ | `BrowserStorageOptions` | interface | Describes the options for collecting storage state from selected origins. |
1045
+ | `BrowserStorageManagerInterface` | interface | Provides storage-state import, export, and clearing operations. |
1046
+ | `BrowserCredentials` | interface | Describes the HTTP basic-auth credentials applied to context pages. |
1047
+ | `BrowserGeolocation` | interface | Describes a geographic location override. |
1048
+ | `BrowserMedia` | interface | Describes browser color and media feature overrides. |
1049
+ | `BrowserUserAgent` | interface | Describes user-agent metadata accepted by Chromium emulation. |
1050
+ | `BrowserEmulationOptions` | interface | Describes network and rendering overrides inherited by context pages. |
1051
+ | `BrowserPagesFunction` | type | Returns the context's live pages at call time. |
1052
+ | `BrowserEmulationManagerInterface` | interface | Configures context-scoped emulation. |
1053
+ | `BrowserProxy` | interface | Describes proxy settings used when creating an isolated browser context. |
1054
+ | `BrowserDownloadOptions` | interface | Describes the download policy for a browser context. |
1055
+ | `BrowserContextOptions` | interface | Describes the options for creating and configuring an isolated browser context. |
1056
+ | `BrowserContextEventMap` | type | Maps the browser-context lifecycle events. |
1057
+ | `BrowserJourneyBinding` | type | Binds a native action's string argument to a literal or to one declared parameter by name. |
1058
+ | `BrowserJourneyParameter` | interface | Declares one parameter a journey takes: its default, or none when it is a secret. |
1059
+ | `BrowserJourneyTarget` | interface | Names the element an acting step acts on the way a receipt names it, with the record-time evidence a developer reads when a resolution is refused. |
1060
+ | `BrowserJourneyTab` | interface | Names the tab a `switch` step moves to, portably. |
1061
+ | `BrowserJourneyStepInput` | interface | Describes one step before it holds an id: a call of a toolset tool with its element or tab named as data. |
1062
+ | `BrowserJourneyStep` | interface | Describes a step with its identity: `s` followed by a positive integer, stable across edits and never reused. |
1063
+ | `BrowserJourney` | interface | Describes one user intent as data; `next` is the number the next added step takes. |
1064
+ | `BrowserJourneyRevision` | interface | Carries a journey with the revision the store assigned; `revision` is absent for a journey the store never held. |
1065
+ | `BrowserJourneyEdit` | type | Describes one change to a journey; `editBrowserJourney` applies a batch to a copy, in order, and refuses it whole on the first invalid edit. |
1066
+ | `BrowserJourneyEditRequest` | type | Describes an edit as the `edit` tool receives it over the wire: an added or updated step can name `ref` instead of a target, converted from the current view before the pure editor runs. |
1067
+ | `BrowserRecorderEventMap` | type | Maps the events a recorder emits. |
1068
+ | `BrowserRecorderInterface` | interface | Records the steps of a journey from one source as they happen and turns them into a journey. |
1069
+ | `BrowserRecorderOptions` | interface | Configures a recorder. |
1070
+ | `BrowserAction` | interface | Describes what became of one action the toolset performed. |
1071
+ | `BrowserStepOutcome` | type | Names how one step ended. |
1072
+ | `BrowserRunOutcome` | type | Names how a run ended. |
1073
+ | `BrowserToolsetResult` | interface | Carries a performed call's tool result beside its structured action, present when the call reached a handler, and the value a failed handler threw. |
1074
+ | `BrowserHoldInterface` | interface | Owns the toolset while a replay runs; `destroy` releases it. |
1075
+ | `BrowserRunStep` | interface | Describes one replayed step; `action`, `trigger`, and `result` carry the meaning of the skill's `JournalStep` fields. |
1076
+ | `BrowserRun` | interface | Describes one run of a journey; `inputs` omits secret values; `fault` carries the run file's write failure. |
1077
+ | `BrowserReplayOptions` | interface | Configures one replay. |
1078
+ | `BrowserReplayEventMap` | type | Maps the events a replay emits. |
1079
+ | `BrowserReplayInterface` | interface | Replays one journey over a toolset. |
1080
+ | `BrowserStoreOptions` | interface | Carries the signal a store call honours. |
1081
+ | `BrowserJourneyValidationContext` | interface | Identifies the parameter binding that failed journey validation. |
1082
+ | `BrowserStoreFault` | interface | Names one entry a listing could not read. |
1083
+ | `BrowserStorePage` | interface | Carries one page of a listing with the entries it could not read. |
1084
+ | `BrowserJourneyStoreInterface` | interface | Keeps journeys by name with a revision per write. |
1085
+ | `BrowserRunSlot` | interface | Names the run directory a store opened, as data. |
1086
+ | `BrowserRunStoreInterface` | interface | Keeps runs by the journey name and run id the run carries. |
1087
+ | `BrowserJourneyOptions` | interface | Configures the journey toolset a toolset constructs. |
1088
+ | `BrowserJourneyToolsetInterface` | interface | Registers the journey tools over a toolset and owns the recording and the active replay. |
1089
+ | `BrowserCodegenLanguage` | type | Names the target language for a compiled codegen script. |
1090
+ | `BrowserCodegenInterface` | interface | Records semantic page gestures and compiles the resulting journey. |
1091
+ | `BrowserCodegenScript` | interface | Carries the module `compileBrowserJourney` emits with the gap steps that refuse it. |
1092
+ | `BrowserCodegenGesture` | interface | Carries a sanitized gesture from the page listener without password values. |
1093
+ | `BrowserReadOptions` | interface | Describes the options for one slice of a reading's Markdown or plain-text projection. |
1094
+ | `BrowserReadResult` | interface | Describes one slice of a reading's projection. |
1095
+ | `BrowserReadMatch` | interface | Describes a matching line and its character offset in a reading's projection. |
1096
+ | `BrowserEpochFunction` | type | Reads the navigation epoch of the frame a reading was captured from. |
1097
+ | `BrowserReadingInput` | interface | Describes the captured document a reading is built from. |
1098
+ | `BrowserReadingInterface` | interface | Represents one captured document, parsed one time and projected to Markdown or plain text in bounded slices. |
1099
+ | `BrowserSessionFunction` | type | Resolves the current CDP session for a frame id. |
1100
+ | `BrowserWorldFunction` | type | Resolves the isolated-world execution context a page caches for one frame document, creating the world on the given session when none is cached. |
1101
+ | `BrowserElementQuery` | interface | Describes an accessibility or CSS query within an optional element reference. |
1102
+ | `BrowserWaitOptions` | interface | Configures a text or element wait, including whether absence satisfies it. |
1103
+ | `BrowserOutlineOptions` | interface | Configures an outline's element limit, optional subtree, and search. |
1104
+ | `BrowserOutline` | interface | Carries a document-order outline and its included and available element counts. |
1105
+ | `BrowserOutlineNode` | interface | Associates an outline row with its frame, session, and optional actionable reference. |
1106
+ | `BrowserElementGeometry` | interface | Retains both session-local and page-composed element geometry. |
1107
+ | `BrowserElementSubject` | interface | Identifies a manager failure without inventing an element reference. |
1108
+ | `BrowserElementReason` | type | Identifies the refusal an element action reports. |
1109
+ | `BrowserElementRefusal` | interface | Describes how an element action reports one refusal its compiled in-page check throws: the reason, and the detail that follows the element's name, or `undefined` for the reason's own wording. |
1110
+ | `BrowserReferenceFunction` | type | Allocates the next reference from the owning browser context. |
1111
+ | `BrowserElementWorldFunction` | type | Resolves the page-owned isolated world for a particular frame and session. |
1112
+ | `BrowserReadinessFunction` | type | Waits for the current document's DOM readiness. |
1113
+ | `BrowserElementPointFunction` | type | Composes a frame-local point into page coordinates. |
1114
+ | `BrowserElementManagerInput` | interface | Provides the protocol and ownership boundaries used by a page element manager. |
1115
+ | `BrowserElementInput` | interface | Binds an element to its document identity and the page's shared protocol resources. |
1116
+ | `BrowserReadinessWait` | interface | Holds the resources of one lifecycle-event readiness wait. |
1117
+ | `BrowserElementInterface` | interface | Provides actions and reading through a stable document element reference. |
1118
+ | `BrowserPageElementInterface` | interface | Provides trusted page input and capture for a referenced element. |
1119
+ | `BrowserElementManagerInterface` | interface | Captures, queries, and retains references to a view's elements. |
1120
+ | `BrowserViewEventMap` | type | Maps the `console` and `error` events of a view that observes its document's output. |
1121
+ | `BrowserViewInterface` | interface | Provides the document operations shared by remote and DOM-native views. |
1122
+ | `BrowserCallOptions` | interface | Describes the options every asynchronous page, frame, handle, and worker call accepts. |
1123
+ | `BrowserToolAnnotation` | interface | Transliterates the WebMCP protocol's `Annotation` type, retaining its wire spelling. |
1124
+ | `BrowserTool` | interface | Describes a registered WebMCP tool and its owning document. |
1125
+ | `BrowserToolRemoval` | interface | Identifies a removed WebMCP tool by document and name. |
1126
+ | `BrowserInvocation` | interface | Describes a WebMCP invocation observed on the protocol. |
1127
+ | `BrowserInvocationResult` | interface | Carries a terminal WebMCP status and its untrusted output or error. |
1128
+ | `BrowserRegistryEventMap` | type | Maps registry changes and observed WebMCP invocation events. |
1129
+ | `BrowserRegistryOptions` | interface | Configures registry listeners and listener-error handling. |
1130
+ | `BrowserRegistryInterface` | interface | Mirrors the experimental WebMCP protocol domain for a page. |
1131
+ | `BrowserRegistryPending` | interface | Holds one unsettled registry execution and its resource cleanup. |
1132
+ | `BrowserToolName` | type | Names a tool the browser toolset reserves: the generic tools, the staged `dialog`, the opt-in `tabs` and `switch`, and the journey tools `record`, `save`, `journeys`, `edit`, `replay`, `forget`, and `capture`, which a toolset constructed with `journeys` reserves. |
1133
+ | `BrowserToolsetReason` | type | Names why a toolset declined a page tool. |
1134
+ | `BrowserToolSourceEventMap` | type | Maps the signal a tool source emits when its page's tools change. |
1135
+ | `BrowserToolSourceInterface` | interface | Supplies page-registered tools to a toolset through a contract free of protocol types. |
1136
+ | `BrowserToolsetEventMap` | type | Maps the events a toolset emits. |
1137
+ | `BrowserToolsetOptions` | interface | Configures a browser toolset. |
1138
+ | `BrowserFollowOptions` | interface | Configures one step a toolset follows. |
1139
+ | `BrowserTab` | interface | Describes one open tab of a toolset's context, which the `tabs` tool lists one per line. |
1140
+ | `BrowserToolsetInterface` | interface | Publishes the browser vocabulary as tools over one current view and adopts the page's own tools beside them. |
1141
+ | `BrowserToolsetHandler` | type | Runs one toolset tool inside the toolset's boundary. |
1142
+ | `BrowserToolsetWatch` | interface | Holds the listeners a toolset attaches to one followed page. |
1143
+ | `BrowserReceipt` | interface | Describes one tool receipt before rendering. |
1144
+ | `BrowserFrameInfo` | interface | Describes serializable frame metadata decoded from CDP `Page.getFrameTree`. |
1145
+ | `BrowserFrameInterface` | interface | Provides the operations shared by a top-level page and an iframe document. |
1146
+ | `BrowserRect` | type | Represents a rectangle in CSS pixels: x, y, width, height. |
1147
+ | `BrowserLayout` | interface | Describes layout data associated with one captured DOM node. |
1148
+ | `BrowserNode` | interface | Represents one serializable DOM node decoded from a CDP DOM snapshot. |
1149
+ | `BrowserDocument` | interface | Represents one document captured in a CDP DOM snapshot. |
1150
+ | `BrowserSnapshotInput` | interface | Describes the serializable input for a navigable browser snapshot — the form a `BrowserSnapshot` is built from and serializes back to. |
1151
+ | `BrowserWalkOrder` | type | Names the structural ordering for a browser snapshot walk. |
1152
+ | `BrowserWalkOptions` | interface | Describes the options for walking a browser snapshot. |
1153
+ | `BrowserSiblingRelation` | type | Names a structural sibling relationship relative to a browser node. |
1154
+ | `BrowserSnapshotInterface` | interface | Represents a navigable, serializable snapshot of every document attached to a page, extending `BrowserSnapshotInput` with walking, structural relationships, search, and path derivation over plain `BrowserNode` values. |
1155
+ | `BrowserSnapshotOptions` | interface | Describes the options configuring capture through `BrowserPageInterface` `snapshot()`. The snapshot entity's creation input is `BrowserSnapshotInput`. |
1156
+ | `BrowserNodePredicate` | type | Names the predicate form accepted by `BrowserSnapshotInterface` find, filter, and closest methods. |
1157
+ | `BrowserNodeQuery` | interface | Describes a declarative browser-node matcher used by `matchesBrowserNode`. |
1158
+ | `BrowserPageInterface` | interface | Abstracts a single top-level browser page, extending `BrowserFrameInterface` with navigation, screenshots, frame discovery, DOM snapshots, codegen, and target teardown. |
1159
+ | `BrowserContextInterface` | interface | Represents an isolated browser session over a CDP browser context. |
1158
1160
 
1159
1161
  A page hands the navigation steps it accepts, typed by `BrowserNavigationEventMap`, to its element manager as `BrowserElementManagerInput.steps`, and the manager drops a child frame's references on that frame's cross-document `commit` and on its `detach`. The input’s `recover` callback discards cached DOM readiness after context loss and parks until the destination document is ready. The same emitter reaches the navigation manager through its constructor; see [`BrowserNavigationManagerInterface`](#browsernavigationmanagerinterface). `BrowserToolsetWatch` holds a toolset's `dialog`, `popup`, `close`, and `closed` listeners and no navigation listener, because a toolset follows a navigation through the page's record.
1160
1162
 
@@ -1258,6 +1260,9 @@ The following table lists the server constants.
1258
1260
  | `BROWSER_SERVER_UNAVAILABLE` | const | Names the refusal when no browser can serve a call. |
1259
1261
  | `BROWSER_SERVER_CRASH` | const | Names the notice that a browser and its session state were lost. |
1260
1262
  | `BROWSER_SERVER_UNRESOLVED` | const | Names an interrupted call whose outcome is unknown. |
1263
+ | `BROWSER_SERVER_BUSY` | const | Names the refusal when every browser is admitted to a holder. |
1264
+ | `BROWSER_SERVER_HOLDER` | const | Names the refusal for an unknown or ended holder. |
1265
+ | `BROWSER_SERVER_COPY` | const | Defines the holder tools independently of the shared browser's vocabulary. |
1261
1266
  | `BROWSER_FILE_STORE_LIMIT` | const | Bounds a file-store listing page by default. |
1262
1267
 
1263
1268
  #### Errors
@@ -1297,6 +1302,7 @@ The following table lists the server helpers.
1297
1302
  | `formatBrowserLockEntry` | function | Formats a process identifier and UUID token as a lock entry name. |
1298
1303
  | `probeProcess` | function | Probes whether a process has not been confirmed absent. |
1299
1304
  | `parseBrowserProfileRecord` | function | Parses a profile record naming a positive process identifier and a loopback DevTools endpoint. |
1305
+ | `parseBrowserViewport` | function | Parses positive integer viewport dimensions in WIDTHxHEIGHT form. |
1300
1306
  | `describeBrowserServerLoss` | function | Describes a browser loss with its code, cause, and the session state it invalidates. |
1301
1307
  | `parseBrowserLockEntry` | function | Parses the holder process identifier from a lock entry name. |
1302
1308
  | `parseBrowserEngine` | function | Classifies an executable path/name into a `BrowserEngine` by case-insensitive hint, checked in the order edge → chromium → chrome. |
@@ -1391,6 +1397,10 @@ The following table lists the server types.
1391
1397
  | `BrowserSlot` | interface | Holds one warm browser a browse server owns: the browser, its profile, its isolated context, and its started toolset. |
1392
1398
  | `BrowserSlotWatch` | interface | Holds the listeners and resolver of one browser slot's loss watch. |
1393
1399
  | `BrowserMCPServerOptions` | interface | Configures the browse server. |
1400
+ | `BrowserServerToolName` | type | Names the server tools that manage independent browser holders. |
1401
+ | `BrowserServerHolder` | interface | Identifies one admitted browser lifetime independently of its current pool token. |
1402
+ | `BrowserServerCatalog` | interface | Describes the JSON catalog returned by the holder tools. |
1403
+ | `BrowserServerMirror` | interface | Binds shared catalog subscriptions to the exact token that published them. |
1394
1404
  | `BrowserMCPServerInterface` | interface | Serves the browser vocabulary and the journey tools over MCP on stdio. |
1395
1405
 
1396
1406
  ### Browser
@@ -1827,7 +1837,7 @@ requests `stable: true`, so a hidden tab does not suspend a check that needs no
1827
1837
  Pointer actions activate their owning page before sampling stability, because Chromium suspends
1828
1838
  animation frames in hidden tabs. The stability check still uses real animation frames.
1829
1839
 
1830
- One referenced element of a page, acted on through trusted input on the page session. `frame` is a Surface data member: the id of the frame whose document holds the element, which a toolset passes to `page.navigation.record`. A click scrolls the element into view, checks that it is visible, enabled, and stable across two animation frames, reads its content quad on its own session, hit-tests the quad center, and dispatches a pressed and released mouse event; each step refuses with a coded `BrowserElementError` whose `context.reason` is `GONE`, `HIDDEN`, `OCCLUDED`, `DISABLED`, `UNTRUSTED`, or `UNKNOWN`, and whose one-line message carries that reason and, for `GONE`, the refresh directive `; call look for fresh refs.` For an element inside an out-of-process frame the point is composed through each frame's content box.
1840
+ One referenced element of a page, acted on through trusted input on the page session. `frame` is a Surface data member: the id of the frame whose document holds the element, which a toolset passes to `page.navigation.record`. A click scrolls the element into view, checks that it is visible, enabled, and stable across two animation frames, waits for consecutive rendering frames to report equal document scroll offsets, reads its content quad on its own session, hit-tests the quad center, and dispatches a pressed and released mouse event; each step refuses with a coded `BrowserElementError` whose `context.reason` is `GONE`, `HIDDEN`, `OCCLUDED`, `DISABLED`, `UNTRUSTED`, or `UNKNOWN`, and whose one-line message carries that reason and, for `GONE`, the refresh directive `; call look for fresh refs.` The scroll wait shares the actionability call's timeout and signal and uses no polling timer. Hover and the drag source share this wait. A protocol hit-test refusal because the location held no node reports `OCCLUDED`. For an element inside an out-of-process frame the point is composed through each frame's content box.
1831
1841
 
1832
1842
  | Method | Returns | Summary |
1833
1843
  | ------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1992,7 +2002,7 @@ A `click`, a `type` with `submit`, or a `press` of Enter also opens `page.popups
1992
2002
 
1993
2003
  `follow` performs one recorded step on the current view through `perform`. A `click` or `type` step with a target resolves the one element that carries the target's role and exact accessible name and sends its reference as `ref`, and a stored `reference` or `css` is never read; a `switch` step on a toolset with `context` resolves the one tab `tabs()` lists with the step's URL and title and sends the tab's id as `tab`; every other step sends its arguments unchanged, a page tool's included. Before any input, a missing target or tab refuses with `BROWSER_JOURNEY_TARGET`, several refuse with `BROWSER_JOURNEY_AMBIGUOUS`, and a target name that binds a parameter refuses with `BROWSER_JOURNEY_INPUT`, each naming the step. `follow` returns the `BrowserAction` of a `done` action and of an `interrupted` one, whose dialog a following `dialog` step answers, and throws a `BrowserStepError` whose `action` is the performed action for any other outcome and for a navigation that stopped at `requested` or `committed`. Its `caller` option carries a hold's token, and its `secret` option withholds a `type` step's text. A replay and the module `compileBrowserJourney` emits run every step through it.
1994
2004
 
1995
- `perform` runs the handler a manager call runs and returns the `BrowserAction` beside the tool result, and the toolset emits the same action as `action`; `tools.execute` and `perform` share one path, so a receipt is the same through either, including a secret call whose signal was aborted before the handler ran. A failed `perform` also returns the value its handler threw as `fault`, so a copy of the result keeps a coded `BrowserError`, and a tool's own `execute` rejects with that same value. `hold` takes a queue turn for a replay: until the hold is destroyed, an action whose `context.caller` is not the hold's `token` is refused at admission with `BROWSER_TOOLSET_BUSY`, `dialog` and adopted page tools included, while `look`, `read`, `plain`, `tabs`, and `wait` pass; the toolset emits `hold` and `release` with the journey's name. With the `journeys` option, the toolset constructs a `BrowserJourneyToolset` that adds the six journey tools to the same manager, and destroys it first; see [Journeys](#journeys).
2005
+ `perform` runs the handler a manager call runs and returns the `BrowserAction` beside the tool result, and the toolset emits the same action as `action`; `tools.execute` and `perform` share one path, so a receipt is the same through either, including a secret call whose signal was aborted before the handler ran. A failed `perform` also returns the value its handler threw as `fault`, so a copy of the result keeps a coded `BrowserError`, and a tool's own `execute` rejects with that same value. `hold` takes a queue turn for a replay: until the hold is destroyed, an action whose `context.caller` is not the hold's `token` is refused at admission with `BROWSER_TOOLSET_BUSY`, `dialog` and adopted page tools included, while `look`, `read`, `plain`, `tabs`, and `wait` pass; the toolset emits `hold` and `release` with the journey's name. With the `journeys` option, the toolset constructs a `BrowserJourneyToolset` that adds the journey tools to the same manager, and destroys it first; see [Journeys](#journeys).
1996
2006
 
1997
2007
  | Method | Returns | Summary |
1998
2008
  | --------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -2232,15 +2242,18 @@ await store.delete('add-kettle')
2232
2242
 
2233
2243
  Keeps runs by the journey name and run id the run carries. A run id is the ISO time with `-` for `:`, followed by `-` and 4 hexadecimal digits, such as `2026-10-01T03-07-06.041Z-6d7e`. `FileBrowserRunStore` creates `ROOT/NAME/runs/ID/` exclusively in `open`, retrying with a fresh id on a collision, writes `run.json` there, and writes a capture only into a directory it opened, refusing a slot it did not open, a name outside `sN.png`, and a directory that is missing or a link; it creates no directory for a capture. `MemoryBrowserRunStore` has no directories: `open` mints an id, and `capture` resolves `undefined`, so a step carries no `capture`.
2234
2244
 
2235
- | Method | Returns | Summary |
2236
- | --------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2237
- | `open` | `Promise<BrowserRunSlot>` | Mints a run id for the journey and creates its run directory exclusively. |
2238
- | `get` | `Promise<BrowserRun \| undefined>` | Returns the run stored under the journey name and id, or `undefined` when none is stored. |
2239
- | `set` | `Promise<void>` | Writes the run under the journey name and the run id it carries. |
2240
- | `capture` | `Promise<string \| undefined>` | Writes capture bytes under the name into the run directory `open` created for the slot. |
2241
- | `delete` | `Promise<void>` | Removes the run stored under the journey name and id; a missing run is a no-op. |
2242
- | `clear` | `Promise<number>` | Removes every run and opened slot of a journey and returns their count, including unsaved slots; a missing name returns zero. File stores exclude concurrent allocation with the journey lock and refuse a held lock with `BROWSER_JOURNEY_LOCKED`. |
2243
- | `list` | `Promise<BrowserStorePage<BrowserRun>>` | Returns one page of the journey's runs, starting at `offset` and holding at most `limit` entries, with the entries it could not read in `faults`. |
2245
+ | Method | Returns | Summary |
2246
+ | ---------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2247
+ | `open` | `Promise<BrowserRunSlot>` | Mints a run id for the journey and creates its run directory exclusively. |
2248
+ | `get` | `Promise<BrowserRun \| undefined>` | Returns the run stored under the journey name and id, or `undefined` when none is stored. |
2249
+ | `set` | `Promise<void>` | Writes the run under the journey name and the run id it carries. |
2250
+ | `capture` | `Promise<string \| undefined>` | Writes capture bytes under the name into the run directory `open` created for the slot. |
2251
+ | `delete` | `Promise<void>` | Removes the run stored under the journey name and id; a missing run is a no-op. |
2252
+ | `clear` | `Promise<number>` | Removes every run and opened slot of a journey and returns their count, including unsaved slots; a missing name returns zero. File stores exclude concurrent allocation with the journey lock and refuse a held lock with `BROWSER_JOURNEY_LOCKED`. |
2253
+ | `list` | `Promise<BrowserStorePage<BrowserRun>>` | Returns one page of the journey's runs, starting at `offset` and holding at most `limit` entries, with the entries it could not read in `faults`. |
2254
+ | `snapshot` | `Promise<string>` | Saves a standalone PNG under the runs root without replacing an existing file. |
2255
+
2256
+ The optional `snapshot` method is implemented by `FileBrowserRunStore`. It allocates `ROOT/runs/ID/view.png` independently of a journey and returns its absolute path. It copies the input bytes before allocation and writes the file exclusively. Stores without standalone file storage omit it.
2244
2257
 
2245
2258
  The following fence opens a run slot, writes a capture and the run, and reads them back.
2246
2259
 
@@ -2256,11 +2269,11 @@ await runs.delete('add-kettle', slot.id)
2256
2269
 
2257
2270
  #### `BrowserJourneyToolsetInterface`
2258
2271
 
2259
- Registers the six journey tools on the toolset's manager and owns the recording and the active replay. `BrowserToolset` constructs it when given `journeys` and destroys it before its own teardown; it refuses construction with `BROWSER_TOOLSET_RESERVED` when the manager already holds a journey tool's name. See [Journeys](#journeys) for the tools.
2272
+ Registers the journey tools on the toolset's manager and owns the recording and the active replay. `BrowserToolset` constructs it when given `journeys` and destroys it before its own teardown; it refuses construction with `BROWSER_TOOLSET_RESERVED` when the manager already holds a journey tool's name. See [Journeys](#journeys) for the tools.
2260
2273
 
2261
- | Method | Returns | Summary |
2262
- | --------- | --------------- | ---------------------------------------------------------------------------- |
2263
- | `destroy` | `Promise<void>` | Aborts the active replay and removes the six journey tools from the manager. |
2274
+ | Method | Returns | Summary |
2275
+ | --------- | --------------- | ------------------------------------------------------------------------ |
2276
+ | `destroy` | `Promise<void>` | Aborts the active replay and removes the journey tools from the manager. |
2264
2277
 
2265
2278
  The following fence constructs the journey toolset through `BrowserToolset`, starts a recording, and destroys both.
2266
2279
 
@@ -2328,16 +2341,22 @@ await browser.destroy() // terminates and awaits the owned process
2328
2341
 
2329
2342
  #### `BrowserMCPServerInterface`
2330
2343
 
2331
- Serves the browser vocabulary and the journey tools over MCP on stdio. The server warms its pool at start and holds one validated lease. Initialization and tool calls await setup; a lost lease is replaced within the pool's restart bound. Each launch creates an exclusive `ROOT/.profiles/PID-UUID/` profile and an isolated context. `tools/list` answers while warming. Adopted page tools are mirrored until withdrawn or their lease is lost.
2344
+ Serves the browser vocabulary and the journey tools over MCP on stdio. The server warms its pool at start and holds one validated lease for the shared browser and one for each holder `acquire` admits. Initialization and tool calls await setup; a lost lease is replaced within the pool's restart bound. Each launch creates an exclusive `ROOT/.profiles/PID-UUID/` profile and an isolated context. `tools/list` answers while warming. Adopted page tools are mirrored until withdrawn or their lease is lost.
2332
2345
 
2333
2346
  A disconnect or a crash of the current page retires its slot; a background-page crash leaves the lease intact. Hand-out, per-call, and post-failure pings detect browsers that stopped answering. An interrupted failure answers `BROWSER_SERVER_UNRESOLVED`, a known success remains successful, and pending loss notes prefix the next string outcome on a successor or a refusal. Every pending loss is reported. Calls are never repeated, and replacement pages start at `about:blank`.
2334
2347
 
2335
2348
  The end of input, `SIGINT`, and `SIGTERM` stop admission and destroy the pool. Teardown releases watch listeners, destroys each toolset before its browser, and rechecks recorded folders. Unconfirmed termination retains its slot; a stranded launch prevents further launches. A timed-out ping forces termination before teardown. On Linux, a root process launches with `--no-sandbox`; other launches keep the sandbox.
2336
2349
 
2337
- | Method | Returns | Summary |
2338
- | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2339
- | `start` | `Promise<void>` | Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the session leases a warm browser; the legacy handshake and every tool call await the same setup. Rejects with `BROWSER_SERVER_UNAVAILABLE` when no browser can serve and with `BROWSER_TOOLSET_ENDED` after `destroy()`, and resolves when `destroy()` interrupts setup. |
2340
- | `destroy` | `Promise<void>` | Stops admission, tears down every browser, its toolset, and its profile, then rechecks the folders it answers for. |
2350
+ | Method | Returns | Summary |
2351
+ | --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2352
+ | `start` | `Promise<void>` | Serves stdio, sweeps the profiles ended servers left, warms the pool, and resolves after the shared holder leases a warm browser; the legacy handshake and every tool call await the same setup. Rejects with `BROWSER_SERVER_UNAVAILABLE` when no browser can serve and with `BROWSER_TOOLSET_ENDED` after `destroy()`, and resolves when `destroy()` interrupts setup. |
2353
+ | `destroy` | `Promise<void>` | Stops admission, tears down every browser, its toolset, and its profile, then rechecks the folders it answers for. |
2354
+
2355
+ The viewport option applies to every warmed browser, including spares and refills, and to every page and popup in its isolated context.
2356
+
2357
+ | Option | Type | Default | Behavior |
2358
+ | ---------- | ----------------- | ---------------------------- | -------------------------------------------------------------------------------------------- |
2359
+ | `viewport` | `BrowserViewport` | The browser's launch default | Sets the isolated context's page dimensions and emulation through `BrowserMCPServerOptions`. |
2341
2360
 
2342
2361
  The following fence serves the vocabulary on the process's standard streams, with the journeys under `tmp/browsers`.
2343
2362
 
@@ -2936,28 +2955,29 @@ This section holds the words a model reads: the tools a toolset advertises and t
2936
2955
 
2937
2956
  ### Tools
2938
2957
 
2939
- A page-backed toolset advertises `look`, `read`, `plain`, `click`, `type`, `press`, `navigate`, and `wait`, stages `dialog` while a dialog is open, and advertises `tabs` and `switch` when it is given a `context`; a view-backed toolset over a DOM document advertises `look`, `read`, `plain`, `click`, `type`, and `wait`. Either toolset advertises `record`, `save`, `journeys`, `edit`, `replay`, and `forget` when it is given `journeys`. Every tool declares at least one required parameter, because the streamed tool-call parser of Ollama 0.34.4 rejects a call to a tool that declares no parameter. The following table lists each tool with its advertised description.
2940
-
2941
- | Tool | Parameters | Annotations | Placements | Description |
2942
- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
2943
- | `look` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM | `Shows the page's text and the elements you can act on, each with a reference like e4. Call it first and after the page changes.` |
2944
- | `read` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM | `Reads the page as Markdown, with headings, tables, and link addresses. Call it to learn a fact; continue with the offset a cut result names.` |
2945
- | `plain` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM | `Reads the page as plain text, without Markdown, link addresses, or image text. Call it for words to pass to wait or type.` |
2946
- | `click` | `ref` (string, required) | none | CDP and DOM | `Clicks the element with that reference.` |
2947
- | `type` | `ref` (string, required), `text` (string, required), `submit` (boolean, true to submit its form after typing), `secret` (boolean, true to keep the text out of the receipt) | none | CDP and DOM | `Types into the text control with that reference; set submit to true to submit its form.` |
2948
- | `press` | `key` (string, required) | none | CDP | `Presses that key or chord, such as Enter or Control+a.` |
2949
- | `navigate` | `url` (string, required) | none | CDP | `Opens that absolute web address in the current tab.` |
2950
- | `wait` | `text` (string, required), `absent` (boolean, true to wait until the text is gone), `timeout` (integer seconds, default 5, at most 30) | `pure` | CDP and DOM | `Waits for text to appear; set absent to true to wait for it to leave.` |
2951
- | `dialog` | `accept` (boolean, required), `text` (string) | none | CDP, staged while a dialog opens | `Accepts or dismisses the open dialog.` |
2952
- | `tabs` | `search` (string, required) | `pure` | CDP, with `context` | `Lists the open tabs; the current one is marked.` |
2953
- | `switch` | `tab` (string, required) | none | CDP, with `context` | `Switches to a tab from tabs, such as t2.` |
2954
- | `record` | `journey` (string, required) | none | CDP and DOM, with `journeys` | `Starts recording your next actions as a journey with that name; call save when it is done.` |
2955
- | `save` | `description` (string, required) | none | CDP and DOM, with `journeys` | `Stops recording and saves the journey; describe what it achieves in one sentence.` |
2956
- | `journeys` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM, with `journeys` | `Lists the saved journeys with their steps and the parameters each one takes.` |
2957
- | `edit` | `journey` (string, required), `edits` (`anyOf`: array of `BrowserJourneyEditRequest` or a JSON string of that array, required) | none | CDP and DOM, with `journeys` | `Changes a saved journey: add, remove, or update steps by their ids from journeys, or declare a parameter.` |
2958
- | `replay` | `journey` (string, required), `inputs` (object of strings) | none | CDP and DOM, with `journeys` | `Replays a saved journey step by step; give each parameter's value under inputs.` |
2959
- | `forget` | `journey` (string, required) | none | CDP and DOM, with `journeys` | `Removes a saved journey and all its runs; the name is free to record again.` |
2960
- | page tools | the page's input schema, plus a required `purpose` string when that schema requires nothing | `untrusted` always; `pure` from `readOnly`; `consequential` from `consequential` | CDP through the registry, DOM through a source | the page's own description, advertised as authored under `untrusted` |
2958
+ A page-backed toolset advertises `look`, `read`, `plain`, `click`, `type`, `press`, `navigate`, and `wait`, stages `dialog` while a dialog is open, and advertises `tabs` and `switch` when it is given a `context`; a view-backed toolset over a DOM document advertises `look`, `read`, `plain`, `click`, `type`, and `wait`. Either toolset advertises `record`, `save`, `journeys`, `edit`, `replay`, `forget`, and `capture` when it is given `journeys`. Every tool declares at least one required parameter, because the streamed tool-call parser of Ollama 0.34.4 rejects a call to a tool that declares no parameter. The following table lists each tool with its advertised description.
2959
+
2960
+ | Tool | Parameters | Annotations | Placements | Description |
2961
+ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
2962
+ | `look` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM | `Shows the page's text and the elements you can act on, each with a reference like e4. Call it first and after the page changes.` |
2963
+ | `read` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM | `Reads the page as Markdown, with headings, tables, and link addresses. Call it to learn a fact; continue with the offset a cut result names.` |
2964
+ | `plain` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM | `Reads the page as plain text, without Markdown, link addresses, or image text. Call it for words to pass to wait or type.` |
2965
+ | `click` | `ref` (string, required) | none | CDP and DOM | `Clicks the element with that reference.` |
2966
+ | `type` | `ref` (string, required), `text` (string, required), `submit` (boolean, true to submit its form after typing), `secret` (boolean, true to keep the text out of the receipt) | none | CDP and DOM | `Types into the text control with that reference; set submit to true to submit its form.` |
2967
+ | `press` | `key` (string, required) | none | CDP | `Presses that key or chord, such as Enter or Control+a.` |
2968
+ | `navigate` | `url` (string, required) | none | CDP | `Opens that absolute web address in the current tab.` |
2969
+ | `wait` | `text` (string, required), `absent` (boolean, true to wait until the text is gone), `timeout` (integer seconds, default 5, at most 30) | `pure` | CDP and DOM | `Waits for text to appear; set absent to true to wait for it to leave.` |
2970
+ | `dialog` | `accept` (boolean, required), `text` (string) | none | CDP, staged while a dialog opens | `Accepts or dismisses the open dialog.` |
2971
+ | `tabs` | `search` (string, required) | `pure` | CDP, with `context` | `Lists the open tabs; the current one is marked.` |
2972
+ | `switch` | `tab` (string, required) | none | CDP, with `context` | `Switches to a tab from tabs, such as t2.` |
2973
+ | `record` | `journey` (string, required) | none | CDP and DOM, with `journeys` | `Starts recording your next actions as a journey with that name; call save when it is done.` |
2974
+ | `save` | `description` (string, required) | none | CDP and DOM, with `journeys` | `Stops recording and saves the journey; describe what it achieves in one sentence.` |
2975
+ | `journeys` | `search` (string, required), `offset` (integer, default 0) | `pure`, `untrusted` | CDP and DOM, with `journeys` | `Lists the saved journeys with their steps and the parameters each one takes.` |
2976
+ | `edit` | `journey` (string, required), `edits` (`anyOf`: array of `BrowserJourneyEditRequest` or a JSON string of that array, required) | none | CDP and DOM, with `journeys` | `Changes a saved journey: add, remove, or update steps by their ids from journeys, or declare a parameter.` |
2977
+ | `replay` | `journey` (string, required), `inputs` (object of strings) | none | CDP and DOM, with `journeys` | `Replays a saved journey step by step; give each parameter's value under inputs.` |
2978
+ | `capture` | `full` (boolean, required) | none | CDP and DOM, with `journeys`; requires a trusted view | `Saves the current view as a PNG in the runs directory and returns its path.` |
2979
+ | `forget` | `journey` (string, required) | none | CDP and DOM, with `journeys` | `Removes a saved journey and all its runs; the name is free to record again.` |
2980
+ | page tools | the page's input schema, plus a required `purpose` string when that schema requires nothing | `untrusted` always; `pure` from `readOnly`; `consequential` from `consequential` | CDP through the registry, DOM through a source | the page's own description, advertised as authored under `untrusted` |
2961
2981
 
2962
2982
  A call to one of the preceding tools that carries a parameter the tool does not advertise is refused before the tool's handler runs, with a `BrowserError` coded `BROWSER_TOOLSET_ARGUMENT` whose message is the receipt: `The look tool takes no ref parameter; call look with search and offset.` `validateBrowserToolArguments` performs that check; a page tool's arguments are the page's to check.
2963
2983
 
@@ -2965,6 +2985,8 @@ A text `wait` reads the main document body’s `innerText`; child-frame and shad
2965
2985
 
2966
2986
  An absent wait succeeds at its first check if the text was never present. Record an appearance wait before dismissal to prove the text was there. A misspelled string, an outline token such as `expanded=true`, offscreen `content-visibility: auto` text shown by `read`, or shadow-root-owned text shown by `look` can otherwise pass at once without checking the intended exit. A timeout isn’t recorded, and replay and a generated module stop at it.
2967
2987
 
2988
+ The `capture` tool returns only the saved image's absolute path. Set `full` to `true` for the full page or `false` for the viewport. It requires a trusted view with screenshot support and a runs store with `snapshot`; otherwise it refuses with `BROWSER_CAPTURE_UNTRUSTED` or `BROWSER_CAPTURE_UNAVAILABLE`. A held replay refuses it with `BROWSER_TOOLSET_BUSY`. It remains available with read-only journeys, like replay artifacts, and creates no journey or replay record.
2989
+
2968
2990
  ### Receipts
2969
2991
 
2970
2992
  On `look`, `read`, `plain`, `tabs`, and `journeys`, the required `search` string supplies whole words to match, not a site-search request. Use an empty string to list without matches. Words shorter than 3 letters or digits are ignored. On the first page only, entries sharing the most distinct words come first in a block using at most half the available room. `look` and `tabs` show matching rows; `read` and `plain` show `[OFFSET] LINE`; `journeys` shows `[OFFSET] HEADING` for matching journey headings. The block is outside the paged text, so offsets always address the original projection. An oversized first row is cut with `…` without splitting a surrogate pair, reserving room for the first later row that can fit beside it only when the cut keeps the leading token through its first space. Otherwise it cuts without reserving. Later rows that do not fit are skipped so shorter rows can follow. No matching word or no character before the ellipsis means no block.
@@ -3061,9 +3083,9 @@ In the following table `URL` is an address, `REF` an element reference, `ROLE` a
3061
3083
 
3062
3084
  The store proof measured the journey tools and `type`'s `secret` at 798 prompt tokens per turn on the store model's tokenizer (`qwen3.5:2b-q4_K_M`), and the full tool list at 1 651, on 2026-10-01 against the tree at `4a10abe`; the measurement moves with the tool copy. A 4 096-token window cut a page task's third turn, while a 16 384-token window held the proof's journey conversation. When a replay's final view must show a delayed confirmation, end the recording with a `wait` for that confirmation. When a step dismisses a message or closes a panel, follow it with a `wait` with `absent` set to `true` for its text, so the journey keeps the exit check.
3063
3085
 
3064
- A vocabulary case in [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts) bounds the copy a model reads, each tool's compact JSON name, description, and input schema, at 3 100 characters for the journey tools plus `type`'s `secret` property and at 6 700 for the full list. The measured full copy is 6 675 characters; 6 700 is the smallest multiple of 50 that holds it. The journey copy measures 3 090, giving the same bound rule 3 100. The character bound fails the suite when the copy grows, with no tokenizer installed; it is not a token count.
3086
+ A vocabulary case in [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts) bounds the copy a model reads, each tool's compact JSON name, description, and input schema, at 3 400 characters for the journey tools plus `type`'s `secret` property and at 7 000 for the full list. With `capture`, the measured full copy is 6 952 characters; 7 000 is the smallest multiple of 50 that holds it. The journey copy measures 3 367, giving the same bound rule 3 400. The character bound fails the suite when the copy grows, with no tokenizer installed; it is not a token count.
3065
3087
 
3066
- A journey is one user intent kept as JSON: a `name`, a one-sentence `description`, the `parameters` it takes, the `next` step number, and `steps` that mirror the toolset's own tool calls. An acting step names its element by role and exact accessible name, the way a receipt names it, and keeps the record-time `reference` and a `css` selector only as evidence a developer reads when a resolution is refused; replay never reads either. A `switch` step names its tab by URL and title. A model records, lists, edits, replays, and forgets journeys through the six journey tools; a developer compiles the same steps into a module. `validateBrowserJourney` asserts these invariants, and [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) gives each one a failing case:
3088
+ A journey is one user intent kept as JSON: a `name`, a one-sentence `description`, the `parameters` it takes, the `next` step number, and `steps` that mirror the toolset's own tool calls. An acting step names its element by role and exact accessible name, the way a receipt names it, and keeps the record-time `reference` and a `css` selector only as evidence a developer reads when a resolution is refused; replay never reads either. A `switch` step names its tab by URL and title. A model records, lists, edits, replays, and forgets journeys through the journey tools; a developer compiles the same steps into a module. `validateBrowserJourney` asserts these invariants, and [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) gives each one a failing case:
3067
3089
 
3068
3090
  1. `name` matches `BROWSER_JOURNEY_NAME_PATTERN`: lowercase words joined by hyphens, at most 64 characters, and none of the reserved device names `con`, `prn`, `aux`, `nul`, `com1` to `com9`, and `lpt1` to `lpt9`.
3069
3091
  2. A journey has at least one step. Step ids are unique, each is `s` followed by a number below `next`, and an added step takes `next` and increments it, so a removed id is never reused.
@@ -3071,7 +3093,7 @@ A journey is one user intent kept as JSON: a `name`, a one-sentence `description
3071
3093
  4. Every binding names a declared parameter, and every declared parameter is bound by at least one step.
3072
3094
  5. A secret parameter binds `type.text` only and has no default.
3073
3095
  6. A journey survives `JSON.stringify` and `parseBrowserJourney` unchanged.
3074
- 7. A step's action is `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `switch`, an adopted page tool, or `unresolved`; `look`, `read`, `plain`, `tabs`, and the six journey tools are never steps.
3096
+ 7. A step's action is `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `switch`, an adopted page tool, or `unresolved`; `look`, `read`, `plain`, `tabs`, and the journey tools are never steps.
3075
3097
 
3076
3098
  ### Record a journey
3077
3099
 
@@ -3223,7 +3245,7 @@ These invariants hold across the four faces (`src/core`, `src/browser`, `src/ser
3223
3245
  18. **Actions run one at a time.** The toolset runs actions in first-in, first-out order, and an action holds the queue until its receipt is produced; an action whose signal aborts while queued sends nothing. After a `mousePressed` or `keyDown` is sent, the matching release is sent without the signal, so an abort never leaves a button or key down, and the next action waits for a pending release. Every result and error message is cut at `limit` characters plus a footer. A `click`, `type`, or `press` on a page opens `page.navigation.record(frame)` before its first input and settles its receipt through that record, so the receipt's view follows the navigation the record selects, and the toolset holds no frame, session, or loader state of its own. While a replay holds the toolset, an action admitted after the hold that does not carry the hold's token is refused with `BROWSER_TOOLSET_BUSY` rather than queued, and the actions admitted before the hold complete first. The queue, bounds, destroy, hold, and navigation settlement cases in [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts), the selection cases in [`tests/src/core/BrowserNavigationRecord.test.ts`](../tests/src/core/BrowserNavigationRecord.test.ts), and the `claim 6` block of [`tests/service/journey.test.ts`](../tests/service/journey.test.ts) pin it.
3224
3246
  19. **A dialog interrupts every tool and stages `dialog`.** Every pending step of every tool is raced against the page's `dialog` event, so a tool returns a receipt naming the dialog while the blocked command waits; the `dialog` tool is advertised while the dialog is open and bypasses the queue, and every other tool refuses with a message naming the open dialog and ending `call dialog.` A replay admits a `dialog` step only after an `interrupted` action, the continuation the toolset stages, and under a hold a `dialog` from another caller is refused with `BROWSER_TOOLSET_BUSY`. The dialog cases in [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts) and [`tests/src/core/BrowserReplay.test.ts`](../tests/src/core/BrowserReplay.test.ts), the `confirm()` and `beforeunload` dialog cases in [`tests/service/toolset.test.ts`](../tests/service/toolset.test.ts), and the `claim 6` block of [`tests/service/journey.test.ts`](../tests/service/journey.test.ts) pin it.
3225
3247
  20. **CDP input is trusted and DOM input is not.** A page's `trusted` is `true`: clicks, keys, and hovers are `Input` events whose `isTrusted` is `true`. A DOM view's `trusted` is `false`: `click` is `HTMLElement.click()`, `fill` is the native value setter plus `input` and `change`, and `submit` is `requestSubmit()` observed by a `submit` listener, so a form that fails validation reports `did not submit` with the field's `validationMessage`. Its `click` and `type` receipts end `(untrusted event)`. It refuses rather than fakes a key press, a navigation, a file chooser, typing into `contenteditable`, a link or form whose target opens another browsing context, a disabled control, and a cross-origin frame. [`tests/src/browser/elements/BrowserDOMElement.test.ts`](../tests/src/browser/elements/BrowserDOMElement.test.ts) and [`tests/service/document.test.ts`](../tests/service/document.test.ts) pin it.
3226
- 21. **The toolset's names are reserved at `start()`.** `start()` rejects with a coded `BrowserError` and adds nothing when the manager already holds `look`, `read`, `plain`, `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `tabs`, or `switch` under a tool the toolset did not add, and a page tool under a reserved name is skipped with `reserved`. A page tool named `unresolved` is also skipped as reserved. A toolset constructed with `journeys` also reserves `record`, `save`, `journeys`, `edit`, `replay`, and `forget`: construction refuses a manager that holds one with `BROWSER_TOOLSET_RESERVED`, and a page tool under one is skipped with `reserved`. The `browse` server keeps its dispatchers on a manager of its own and forwards to the toolset's, so the toolset meets no foreign name. A consumer that replaces a reserved name after `start()` breaks the path a receipt names, such as `call dialog`. [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts), [`tests/src/core/BrowserJourneyToolset.test.ts`](../tests/src/core/BrowserJourneyToolset.test.ts), and [`tests/src/server/BrowserMCPServer.test.ts`](../tests/src/server/BrowserMCPServer.test.ts) pin it.
3248
+ 21. **The toolset's names are reserved at `start()`.** `start()` rejects with a coded `BrowserError` and adds nothing when the manager already holds `look`, `read`, `plain`, `click`, `type`, `press`, `navigate`, `wait`, `dialog`, `tabs`, or `switch` under a tool the toolset did not add, and a page tool under a reserved name is skipped with `reserved`. A page tool named `unresolved` is also skipped as reserved. A toolset constructed with `journeys` also reserves `record`, `save`, `journeys`, `edit`, `replay`, `forget`, and `capture`: construction refuses a manager that holds one with `BROWSER_TOOLSET_RESERVED`, and a page tool under one is skipped with `reserved`. The `browse` server keeps its dispatchers on a manager of its own and forwards to the toolset's, so the toolset meets no foreign name. A consumer that replaces a reserved name after `start()` breaks the path a receipt names, such as `call dialog`. [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts), [`tests/src/core/BrowserJourneyToolset.test.ts`](../tests/src/core/BrowserJourneyToolset.test.ts), and [`tests/src/server/BrowserMCPServer.test.ts`](../tests/src/server/BrowserMCPServer.test.ts) pin it.
3227
3249
  22. **The in-page toolset never drives its own document by default.** An action that navigates the realm's own document cannot return, so `createBrowserDOMView` and `createDocumentToolset` refuse `globalThis.document` with `BROWSER_DOCUMENT_OWN` unless `own` is `true`. [`tests/src/browser/factories.test.ts`](../tests/src/browser/factories.test.ts) pins it.
3228
3250
  23. **Limit: an `alert()` blocks the driven document.** The DOM placement never replaces `window.alert`, `confirm`, or `prompt`, so a click that opens one blocks the driven document's thread and the action does not return until a person answers it; the CDP placement stages `dialog` instead. [`tests/guides.test.ts`](../tests/guides.test.ts) pins that no `src/browser` module assigns those functions.
3229
3251
  24. **Limit: a `debugging` page tool is not adopted.** [Declared conformance gaps](#declared-conformance-gaps) records this limit in its entry "A `debugging` page tool is not adopted". [`tests/src/core/BrowserToolset.test.ts`](../tests/src/core/BrowserToolset.test.ts) and the skip rows of [`tests/conformance.test.ts`](../tests/conformance.test.ts) pin it.
@@ -3569,17 +3591,18 @@ The `browse` binary serves the vocabulary and the journey tools over MCP on stdi
3569
3591
  - `BROWSE_HEADLESS`: `true`, `false`, `1`, or `0`. Default: `true`.
3570
3592
  - `BROWSE_EXECUTABLE`: the path of the Chromium executable. Default: the browser `findSystemBrowser` finds.
3571
3593
  - `BROWSE_READONLY`: `true`, `false`, `1`, or `0`; `true` refuses `record`, `save`, `edit`, and `forget`, and `replay` still writes runs. Default: `false`.
3572
- - `BROWSE_POOL`: an integer from `1` through `3` setting the number of browsers the server keeps warm. Default: `1`.
3594
+ - `BROWSE_POOL`: an integer from `1` through `3` setting the number of browsers the server keeps, and so the most holders at the same time, the shared browser included; see [Run work in parallel](#run-work-in-parallel). Default: `1`.
3595
+ - `BROWSE_VIEWPORT`: positive integer dimensions in `WIDTHxHEIGHT` form, such as `390x844`. Applies to every page and popup, including those in spares and refills. Default: the browser's launch default.
3573
3596
 
3574
- A malformed value ends the process with exit code 1 and one line on standard error. Any other value of `BROWSE_HEADLESS` or `BROWSE_READONLY`, and a `BROWSE_POOL` that is not an integer, writes a `BROWSER_SERVER_ENVIRONMENT` line, such as `browse: BROWSER_SERVER_ENVIRONMENT: BROWSE_HEADLESS must be true, false, 1, or 0, not "sometimes"`. An integer `BROWSE_POOL` outside `1` through `3` writes `browse: BROWSER_SERVER_OPTIONS: pool.size must be an integer from 1 through 3`. On Linux a server running as root launches Chromium with `--no-sandbox`, because Chromium refuses to start as root with its sandbox on.
3597
+ A malformed value ends the process with exit code 1 and one line on standard error. Any other value of `BROWSE_HEADLESS` or `BROWSE_READONLY`, a `BROWSE_POOL` that is not an integer, and a malformed `BROWSE_VIEWPORT` write a `BROWSER_SERVER_ENVIRONMENT` line, such as `browse: BROWSER_SERVER_ENVIRONMENT: BROWSE_HEADLESS must be true, false, 1, or 0, not "sometimes"`. Viewport dimensions must be positive safe integers written as decimal digits with a lowercase `x` separator and no whitespace. An integer `BROWSE_POOL` outside `1` through `3` writes `browse: BROWSER_SERVER_OPTIONS: pool.size must be an integer from 1 through 3`. On Linux a server running as root launches Chromium with `--no-sandbox`, because Chromium refuses to start as root with its sandbox on.
3575
3598
 
3576
- Chromium starts when the server starts, before the client sends a request. The server launches its first browser, checks that it answers a CDP ping, and leases it to the session. `initialize` and every tool call wait for that lease, and `ping` and `tools/list` answer while the browser warms. With `BROWSE_POOL` at `2` or `3`, the other browsers warm after the first, and `initialize` does not wait for them. A launch that fails is retried one time. The end of input or `SIGTERM` closes every browser and removes its profile, the process exits with code 0, and a run without a fault writes nothing to standard error.
3599
+ Chromium starts when the server starts, before the client sends a request. The server launches its first browser, checks that it answers a CDP ping, and leases it as the shared browser, which the named tools drive. `initialize` and every tool call wait for that lease, and `ping` and `tools/list` answer while the browser warms. With `BROWSE_POOL` at `2` or `3`, the other browsers warm after the first, and `initialize` does not wait for them. A launch that fails is retried one time. The end of input or `SIGTERM` closes every browser and removes its profile, the process exits with code 0, and a run without a fault writes nothing to standard error.
3577
3600
 
3578
3601
  A client gives a server a limited time to answer `initialize`. On 2026-10-03, Claude Code's documentation gave 30 s and connected servers in the background, the Codex configuration reference gave 10 s through `startup_timeout_sec`, and Cursor's documentation gave no limit; see [Claude Code's MCP documentation](https://code.claude.com/docs/en/mcp), [the Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference), and [Cursor's MCP documentation](https://cursor.com/docs/context/mcp). On Windows 11 with Edge 154 on 2026-10-04, while a browser test suite ran beside it, the built binary answered `initialize` at most 2.07 s after its spawn at every `BROWSE_POOL` size, a leftover browser to sweep included. No client needs a longer startup timeout.
3579
3602
 
3580
- Set `BROWSE_POOL` to `2` or `3` to keep a warm spare for failover. The session holds one browser at a time, and a spare waits idle until the session's browser is lost; the next call then runs on the spare while a replacement warms, and concurrent calls share that one spare. At `1`, the next call after a loss waits for a replacement launch. In the 2026-10-04 run, the next successful call after a kill of the session's browser took a median 1.92 s at `1` and 0.40 s at `2`. On Windows 11 with Edge 154 on 2026-10-04, an idle spare's process tree used about 130% of one core in the first 20 s, then a median near 10%, and its summed working set grew from 1.22 GB to 1.78 GB over 2 minutes, with shared pages counted in every process that maps them. With `BROWSE_HEADLESS=false`, each spare opens its own window.
3603
+ Set `BROWSE_POOL` to `2` or `3` to keep warm browsers beyond the shared one. A browser no holder leases is a spare: it waits idle until `acquire` admits a holder on it or a holder's browser is lost. After a loss, the holder's next call runs on a spare while a replacement warms, and concurrent calls on that holder share its one replacement. At `1`, the next call after a loss waits for a replacement launch. In the 2026-10-04 run, the next successful call after a kill of the session's browser took a median 1.92 s at `1` and 0.40 s at `2`. On Windows 11 with Edge 154 on 2026-10-04, an idle spare's process tree used about 130% of one core in the first 20 s, then a median near 10%, and its summed working set grew from 1.22 GB to 1.78 GB over 2 minutes, with shared pages counted in every process that maps them. With `BROWSE_HEADLESS=false`, each spare opens its own window.
3581
3604
 
3582
- When the session's browser is lost, browse never repeats a call. A loss is the browser process exiting, its CDP connection dropping, the renderer of its current page crashing, or a CDP ping it fails before a call or after a failed one; a crashed background tab is not a loss. The following list gives what each call answers around a loss:
3605
+ When a holder's browser is lost, the shared browser's included, browse never repeats a call. A loss is the browser process exiting, its CDP connection dropping, the renderer of its current page crashing, or a CDP ping it fails before a call or after a failed one; a crashed background tab is not a loss. The following list gives what each call answers around a loss:
3583
3606
 
3584
3607
  - A call after the loss runs on a fresh browser that starts at `about:blank`, and its text opens with a `BROWSER_SERVER_CRASH:` note that names the cause and the lost page's URL. An element reference from the lost page is refused.
3585
3608
  - A call the loss interrupts answers `BROWSER_SERVER_UNRESOLVED:`: its outcome is unknown, and browse did not repeat it. Read the page before you repeat the call.
@@ -3589,6 +3612,10 @@ When the session's browser is lost, browse never repeats a call. A loss is the b
3589
3612
 
3590
3613
  A hang of the whole browser during a call can take two command deadlines, the call's and then the post-failure ping's, so in Codex set `tool_timeout_sec` for `browse` higher than the default 60 s.
3591
3614
 
3615
+ Cancelling a call ends its wait without cancelling the browser's liveness check. Concurrent checks share one ping per slot, so a later call joins the remaining deadline. A failed ping retires the slot and leaves the `BROWSER_SERVER_CRASH:` note for the successor's outcome.
3616
+
3617
+ A ping deadline forces the owned process to exit before slot teardown. On Windows, the service proof launches a Node stand-in that completes CDP setup and then withholds replies; it asserts that the pid exits and the call runs on a real browser successor. The `SIGSTOP` proof remains conditional on the host accepting that signal.
3618
+
3592
3619
  When no browser starts at setup, the server refuses on each surface and keeps answering until its input ends. Setup fails, for example, when the first browser fails to launch twice or the root cannot be created. The following list gives what each request answers, where `CAUSE` is the failure's message:
3593
3620
 
3594
3621
  - `initialize` answers the JSON-RPC error `-32000` with the message `BROWSER_SERVER_UNAVAILABLE: CAUSE` and `data.code` set to `BROWSER_SERVER_UNAVAILABLE`.
@@ -3616,13 +3643,13 @@ Claude Code 2.1.286 registers the binary for a checkout in four steps:
3616
3643
 
3617
3644
  Steps 2 and 3 ran on 2026-10-01 against a scratch checkout whose `node_modules/@orkestrel/browser` linked this package's build, with their output quoted. The approval in step 4 is interactive, and no approved Claude Code session drove the server in that run; the exchange that follows drove the command the entry names over stdio directly. With `@orkestrel/mcp` 0.0.34, a client that subscribes through `subscriptions/listen` receives `notifications/tools/list_changed` when the server mirrors a page tool, and a client that connects through `initialize` receives none and sees the tool at its next `tools/list`; which of the two Claude Code 2.1.286 opens is unread.
3618
3645
 
3619
- The following fence adapts the recorded exchange to the vocabulary that replaces `what` with `search` and adds `plain`, one request and the text of its answer per line, with the view after each receipt left out; the replay wrote `tmp/browsers/add-kettle/runs/2026-10-01T03-07-06.041Z-6d7e/` with `run.json`, `s1.png`, `s2.png`, and `s3.png`.
3646
+ The following fence adapts the recorded exchange to the vocabulary that replaces `what` with `search` and adds `plain` and the holder tools, one request and the text of its answer per line, with the view after each receipt left out; the replay wrote `tmp/browsers/add-kettle/runs/2026-10-01T03-07-06.041Z-6d7e/` with `run.json`, `s1.png`, `s2.png`, and `s3.png`.
3620
3647
 
3621
3648
  ```ts
3622
3649
  // -> initialize { protocolVersion: '2025-06-18' }
3623
3650
  // <- { protocolVersion: '2025-06-18', serverInfo: { name: 'browse', version: '0.0.19' }, capabilities: { tools: {} } }
3624
3651
  // -> tools/list
3625
- // <- look, read, plain, click, type, press, navigate, wait, dialog, tabs, switch, record, save, journeys, edit, replay, forget
3652
+ // <- look, read, plain, click, type, press, navigate, wait, dialog, tabs, switch, record, save, journeys, edit, replay, forget, acquire, execute, tools, destroy, capture
3626
3653
  // -> tools/call navigate { url: 'http://127.0.0.1:35605/' }
3627
3654
  // <- Navigated to http://127.0.0.1:35605/.
3628
3655
  // -> tools/call record { journey: 'add-kettle' }
@@ -3656,10 +3683,48 @@ The `packed browse binary` case of [`tests/distribution.test.ts`](../tests/distr
3656
3683
  On 2026-10-04, Claude Code 2.1.285 under `claude -p --mcp-config FILE --strict-mcp-config` and `codex exec` with `-c mcp_servers.browse.command`, `-c mcp_servers.browse.args`, and `-c mcp_servers.browse.env` overrides each started the built binary, where `FILE` names a JSON file holding the `browse` entry, with no saved client configuration. The following list gives what each client showed:
3657
3684
 
3658
3685
  - Claude Code connects `browse` when setup is refused and shows the refusal as the answer to the first tool call, a text that opens with `BROWSER_SERVER_UNAVAILABLE:` and names the cause.
3659
- - Codex hides a server whose `initialize` fails: the agent sees no `browse` tools, and neither the agent nor the `exec` output carries the cause. Run the binary from a terminal with the same environment to read its `browse:` lines.
3686
+ - Codex hides a server whose `initialize` fails: the agent sees no `browse` tools, and neither the agent nor the `exec` output carries the cause. Set `required = true` in the `browse` entry of Codex's MCP configuration: Codex then refuses to start the session and prints the refusal with its cause, such as `required MCP servers failed to initialize: browse: ... BROWSER_SERVER_UNAVAILABLE: spawn ... ENOENT.` (read with `codex exec -c mcp_servers.browse.required=true` on 2026-10-04).
3660
3687
  - Codex `exec` asks approval for each `browse` tool that is not read-only. Under the approval policy `never`, it refused `navigate` with `MCP tool call requires approval, but approval policy is never`, and `look` ran.
3661
3688
  - A client that ends its session ends the server before its teardown finishes. On Windows 11 no browser stayed running, and one `<pid>-<uuid>` profile folder without a `browse.json` record stayed; the next start on the same root removes it.
3662
3689
 
3690
+ ### Run work in parallel
3691
+
3692
+ Acquire a holder when work needs a browser of its own beside the shared one, such as a subagent that checks a page while you drive another through the named tools. Each holder runs on its own pooled browser, with its own profile, isolated context, pages, cookies, storage, and downloads, so its calls run beside the shared browser's calls and beside every other holder's. The named tools, such as `navigate` and `look`, keep serving the shared browser unchanged.
3693
+
3694
+ The following list gives the holder tools that `BROWSER_SERVER_COPY` defines:
3695
+
3696
+ - `acquire { purpose }`: admits a holder and answers JSON with the server-minted `holder` id and its browser's `tools` catalog. The `purpose` text describes the work and names the holder in a capacity refusal. Hand the id to the agent that does the work.
3697
+ - `execute { holder, name, arguments }`: runs the tool `name` from the holder's catalog with that tool's own arguments inside `arguments`, and answers what the tool answers.
3698
+ - `tools { holder }`: lists the holder's catalog, including the page tools its current page registers.
3699
+ - `destroy { holder }`: ends the holder and destroys its browser. A call still running on that holder answers `BROWSER_SERVER_UNRESOLVED:`, and a repeated `destroy` of the same holder succeeds again.
3700
+
3701
+ The following fence shows one holder from `acquire` to `destroy`, one request and the text of its answer per line, with the view after the receipt left out; `HOLDER_ID` stands for the id that `acquire` returns.
3702
+
3703
+ ```ts
3704
+ // -> tools/call acquire { purpose: 'Check the cart while the main agent edits the catalog' }
3705
+ // <- {"holder":"HOLDER_ID","tools":[/* the definitions of look, read, plain, and the rest of the catalog */]}
3706
+ // -> tools/call execute { holder: 'HOLDER_ID', name: 'navigate', arguments: { url: 'https://shop.example/cart' } }
3707
+ // <- Navigated to https://shop.example/cart.
3708
+ // -> tools/call tools { holder: 'HOLDER_ID' }
3709
+ // <- {"holder":"HOLDER_ID","tools":[/* the same catalog, with the page tools the cart page registers */]}
3710
+ // -> tools/call destroy { holder: 'HOLDER_ID' }
3711
+ // <- Holder destroyed.
3712
+ ```
3713
+
3714
+ `destroy` ends the holder's browser process and removes its profile folder, so the holder's pages, cookies, storage, and downloads are gone, and the next holder starts on a fresh browser with a fresh profile. Each browser saves downloads in its own profile, under `ROOT/.profiles/PID-UUID/downloads/`, so copy a file out before you destroy its holder; the end of the server removes the shared browser's downloads the same way. The `contains downloads and destroys their process and profile before capacity is reused cleanly` case of [`tests/service/browse.test.ts`](../tests/service/browse.test.ts) asserts the download path, the exited process, the removed profile, and a clean replacement against a real Chromium.
3715
+
3716
+ `BROWSE_POOL`, or `pool.size` for `BrowserMCPServer`, counts every browser, the shared browser included, so a size of `3` admits two holders. At capacity, `acquire` answers immediately with `BROWSER_SERVER_BUSY:` and launches nothing; its text lists each holder by id and purpose, the shared browser as `shared (Shared browser)`, and tells the agent to destroy a holder it no longer needs or to call the named tools to share the shared browser. A holder that `destroy` is ending counts until its browser is gone. An unknown or ended id answers `BROWSER_SERVER_HOLDER:` and never falls back to the shared browser.
3717
+
3718
+ A holder whose browser is lost waits for a spare or a replacement launch, and the `BROWSER_SERVER_CRASH:` note reaches that holder's next call only. Replays of one journey run together across holders, each writing its own run. While a replay of a journey persists its run on any holder, `forget` of that journey answers `BROWSER_JOURNEY_LOCKED: Journey NAME is locked; call forget again.`, where `NAME` is the journey's name, and a replay that starts while `forget` runs answers the same refusal for `replay`.
3719
+
3720
+ The following list gives the limits of holders:
3721
+
3722
+ - The default `BROWSE_POOL` of `1` keeps only the shared browser, so `acquire` always answers `BROWSER_SERVER_BUSY:` and the named tools always work. [ROADMAP item 14](../ROADMAP.md) holds the contention measurement that rules the default.
3723
+ - `tools/list` mirrors only the shared browser's page tools. A holder's page tools appear only in the catalog that `acquire` and `tools` return, and run through `execute`.
3724
+ - A holder keeps its browser until `destroy` or the end of the server, with no idle timeout. An abandoned holder costs one warm browser and one place of capacity, and the `BROWSER_SERVER_BUSY:` text names it.
3725
+ - Journey admission covers the holders of one server. A second `browse` process on the same root can still race a replay against `forget`.
3726
+ - Codex asks approval for `execute` and `destroy`, because neither is advertised read-only, so under an approval policy that asks, every call a holder makes through `execute` prompts. `acquire` carries no read-only annotation either, and `tools` is advertised read-only.
3727
+
3663
3728
  ### Publish native tools to a page
3664
3729
 
3665
3730
  A page that runs a built-in browser agent reads tools from its WebMCP registry, and `@orkestrel/mcp`'s bridge publishes a tool manager there. Publish `toolset.native`, never `toolset.tools`: the manager also holds the page tools the toolset adopted from the same registry, and publishing them would register each one as a proxy of itself. The following fence drives a same-origin child document, adopts that document's page tools through the bridge, and publishes the five generic tools back to it.
@@ -3704,6 +3769,8 @@ The following list names each test file and what it proves.
3704
3769
  - [`tests/setupServer.test.ts`](../tests/setupServer.test.ts): the ports, processes, scratch directories, CDP test server, fixture pages, the journey module stage, and the browse launch double and stdio pair the server and service suites share; the filesystem suite the file stores run, two processes over one directory included, lives in `tests/src/server/stores/suite.ts`.
3705
3770
  - [`tests/setupService.test.ts`](../tests/setupService.test.ts): the service project's browser flags, engine selection, and registry reading.
3706
3771
  - [`tests/service/browser.test.ts`](../tests/service/browser.test.ts): a real browser's launch, navigation, elements, frames, routes, snapshots, PDF, result limits, reattachment, transport loss, and shutdown; the out-of-process frame click, occlusion, hit-test, stale-reference, reading, and wait proofs; and the `WebMCP` domain reading and its live case.
3772
+
3773
+ - [`tests/service/browse.test.ts`](../tests/service/browse.test.ts): eager startup, process and renderer loss, forced exit of a hung Node stand-in, successor calls, and profile cleanup. The synthesized orphan case waits for the owned browser's process-exit event within the sweep's attach and close deadlines plus `BROWSER_KILL_GRACE_MS`.
3707
3774
  - [`tests/service/toolset.test.ts`](../tests/service/toolset.test.ts): one toolset task end to end through `createToolManager().execute`, the cart view in the receipt of a click whose form the server answers with a 303 redirect, the destination view after a form submission in a child frame, the `confirm()` and `beforeunload` dialogs, popups and tabs, and each receipt within its deadline; its `journey perform equality` block compares `perform` with a direct call for every native action, an editable combobox, a click that opens a dialog, a tab switch, a link that opens a popup, and a click in a same-origin child frame of the DOM placement.
3708
3775
  - [`tests/service/codegen.test.ts`](../tests/service/codegen.test.ts): the page recorder's steps for each gesture on Chromium against the fixture's own event log, the edit boundaries, and a password that never crosses the binding.
3709
3776
  - [`tests/service/journey.test.ts`](../tests/service/journey.test.ts): the `journey semantic replay` block, a changed page resolved by name with a duplicate refused before any input and a matching CSS selector refused; the `compiled module equality` block, each generated module and its replay reaching one page outcome with the same receipts, a gap, and the type check; and the `journey replay coordination, preparation, tools, and secrecy` block, the hold, a timeout, preparation before any side effect, the tools over the file stores, and a secret kept out of every artifact.
@@ -3747,7 +3814,7 @@ The following list names each test file and what it proves.
3747
3814
  - [`tests/src/core/recorders/BrowserRecorder.test.ts`](../tests/src/core/recorders/BrowserRecorder.test.ts): the toolset recorder's steps, the interrupted and child-frame gaps, the held journey's gap, secret bindings, and its lifecycle.
3748
3815
  - [`tests/src/core/BrowserReplay.test.ts`](../tests/src/core/BrowserReplay.test.ts): preparation before any hold, execution and stopping, the dialog continuation, abort, the run write and its bound, captures through the run store, output, and secrets.
3749
3816
  - [`tests/src/core/BrowserHold.test.ts`](../tests/src/core/BrowserHold.test.ts): the hold's token and its one release.
3750
- - [`tests/src/core/BrowserJourneyToolset.test.ts`](../tests/src/core/BrowserJourneyToolset.test.ts): the six tools, every result and refusal verbatim, the listing and its cut, `readonly`, the signal, the `ref` conversion, and destroy.
3817
+ - [`tests/src/core/BrowserJourneyToolset.test.ts`](../tests/src/core/BrowserJourneyToolset.test.ts): the journey tools, every result and refusal verbatim, the listing and its cut, `readonly`, the signal, the `ref` conversion, and destroy.
3751
3818
  - [`tests/src/core/stores/MemoryBrowserJourneyStore.test.ts`](../tests/src/core/stores/MemoryBrowserJourneyStore.test.ts) and [`tests/src/core/stores/MemoryBrowserRunStore.test.ts`](../tests/src/core/stores/MemoryBrowserRunStore.test.ts): the shared store suites over the memory twins, and a capture that keeps no bytes.
3752
3819
  - [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts): each journey invariant with a failing case, the step, parameter, and edit validators, and the run validator.
3753
3820
  - [`tests/src/core/BrowserDialog.test.ts`](../tests/src/core/BrowserDialog.test.ts): accepting and dismissing a dialog.