cocos-web-inspector-mcp 2.3.0 → 2.4.0

package/README.md

@@ -65,6 +65,7 @@ The V8 inspector has no page, so native mode registers only the tools that read
 - `cocos_type_text` taps the EditBox, waits for the engine's Android input activity (`CocosEditBoxActivity`), clears it, and types with `adb shell input text`, so `text-changed` fires per character. Text must be printable ASCII without `%s`. The device keyboard still processes the keys, so autocorrect or a Vietnamese Telex layout can rewrite them (`test` becomes `tét`); the result reports `matches: false` with the text the game received. `submit` presses Enter, which closes a single-line box with `editing-did-ended`; `editing-return` fires only from the activity's confirm button. Clearing uses `input keycombination`, Android 12+.
 - With `--allow-browser-data`, `cocos_network_requests` and `cocos_network_request` report XHR, `fetch` (which the native polyfill runs over XHR), and WebSocket traffic. The first network call installs hooks in the game that keep the last 200 requests and the last 50 frames per socket, so traffic before that call is not seen; the note says when capture started. Bodies and frames are masked like web bodies, headers like web headers. `cocos_storage` reads `localStorage` (native builds back it with SQLite); `session` and `cookies` report `available: false`, since native builds have neither.
 - `cocos_console_messages` (with `--allow-browser-data`) reads the app process's `Cocos`-tagged logcat lines, so it includes logs from before the server attached, bounded by the device log buffer. `console.log` and `console.debug` both report as `log`; an uncaught error spans several `error` lines.
+- `cocos_explain_visibility`, `cocos_explain_layout`, `cocos_animation_report`, `cocos_frame_profile`, and `cocos_event_trace` work on native. `cocos_frame_profile` returned no draw call or triangle ranges on the 3.8.8 Android build tested, so only frame times are reported there.
 - Not registered: `cocos_emulate_device`, `cocos_highlight_node`, `cocos_get_selection` (DOM overlays draw nothing), `cocos_analyze_batches` (the native 2D batcher runs in C++), and `cocos_step_frame` (stepping from the inspector renders outside the native frame loop and crashed the app).
 
 The inspector accepts one session at a time, so the server connects per call; Chrome DevTools can attach between calls, and a call made while DevTools is attached fails with `CDP_UNAVAILABLE`. An adb server restart or a USB drop takes the forward with it; when the endpoint stops answering, the server reads the port from logcat and forwards it again once before failing, so a call usually recovers on its own. If calls keep failing with `CDP_UNAVAILABLE`, run `doctor --native`. When a phone keeps dropping off USB (common through hubs), switch adb to Wi-Fi with `adb tcpip 5555` and `adb connect <phone-ip>:5555`, then forward and set `ANDROID_SERIAL=<phone-ip>:5555`; the endpoint stays `127.0.0.1`.
@@ -145,7 +146,7 @@ Add `--allow-runtime-mutation` for debugger tools, `--allow-browser-data` for co
 
 ## Tools
 
-All tool input objects are strict. Unknown fields are rejected. Inspection tools are annotated as read-only, idempotent, non-destructive, and closed-world. The highlight tool is annotated as a non-destructive, non-idempotent, closed-world temporary mutation because repeated calls reset its removal timer. Runtime debugger tools are non-read-only and closed-world; `cocos_click_node`, `cocos_drag_node`, and `cocos_type_text` are additionally destructive and open-world because game input handlers can reach real servers or make irreversible changes, and they, `cocos_step_frame`, and `cocos_analyze_batches` are non-idempotent.
+All tool input objects are strict. Unknown fields are rejected. Inspection tools are annotated as read-only, idempotent, non-destructive, and closed-world. The highlight tool is annotated as a non-destructive, non-idempotent, closed-world temporary mutation because repeated calls reset its removal timer. Runtime debugger tools are non-read-only and closed-world; `cocos_click_node`, `cocos_drag_node`, `cocos_type_text`, and `cocos_press_key` are additionally destructive and open-world because game input handlers can reach real servers or make irreversible changes, and they, `cocos_step_frame`, `cocos_analyze_batches`, and `cocos_event_trace` are non-idempotent. `cocos_frame_profile` is read-only but non-idempotent because each call samples new frames.
 
 | Tool | Purpose | Inputs |
 | --- | --- | --- |
@@ -157,12 +158,14 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `cocos_set_property` | Update one bounded public component data property. | `pageUrl?`; node `uuid`; `componentUuid`; `key`; primitive/vector/size/color `value` matching current shape |
 | `cocos_click_node` | Dispatch a real click at the visible center of one UI node so Button/touch handlers run (a tap under mobile emulation). Registered only with `--allow-runtime-mutation`. | `pageUrl?`; `uuid` |
 | `cocos_drag_node` | Drag from the visible center of one UI node with real pointer input (touch under mobile emulation), to scroll a ScrollView, flip a PageView, or move a Slider. | `pageUrl?`; `uuid`; `dx`, `dy` CSS pixels `-4000..4000`, not both zero; `steps?` `1..60`, default `10`; `durationMs?` `0..5000`, default `300` |
+| `cocos_press_key` | Press and release one key (Enter, Escape, Tab, Backspace, Delete, Space, arrows, Home, End, PageUp, PageDown, a letter, or a digit) for game keyboard handlers. Native builds send Android key events with `adb shell input keyevent`; the native engine reports the device Backspace key as `Delete`, so `Backspace` is refused there. | `pageUrl?`; `key` |
 | `cocos_type_text` | Tap one EditBox and type with real keyboard input, replacing its content, so `text-changed` and editing events fire. Returns the resulting text, or `redacted` for password boxes. | `pageUrl?`; `uuid`; `text` up to 2,000 chars; `submit?` presses Enter |
 | `cocos_analyze_batches` | Capture the 2D draw batches of the next rendered frame: the node that starts each batch and why the previous one broke. | `pageUrl?`; `limit?` `1..500`, default `100`; `tintMs?` `100..30000` overlays each batch in its own color |
 | `cocos_pause` | Pause the Cocos director when its public API supports it. | `pageUrl?` |
 | `cocos_resume` | Resume the Cocos director when its public API supports it. | `pageUrl?` |
 | `cocos_step_frame` | Advance a paused game by 1–60 fixed-delta frames through `cc.game.step`, then stay paused. Fails unless paused first. | `pageUrl?`, `frames?` |
 | `cocos_set_time_scale` | Speed up or slow down the whole game by scaling each frame's delta time; `1` restores it, no `scale` reads it. Registered only with `--allow-runtime-mutation`. | `pageUrl?`; `scale?` `(0, 100]` |
+| `cocos_event_trace` | Count Node events per event name and node for a bounded window to find event storms. Wraps `Node.prototype.emit` and restores it; arguments are never recorded. Registered only with `--allow-runtime-mutation`. | `pageUrl?`; `durationMs?` `100..10000`, default `2000`; `limit?` `1..200`, default `50` |
 | `cocos_show_stats` | Show or hide the engine's FPS, draw-call, and triangle overlay through the public `profiler` API. | `pageUrl?`; `visible` boolean |
 | `cocos_emulate_device` | Emulate a mobile device like the Chrome device toolbar: viewport, DPR, touch (mouse input arrives as touch), user agent and `navigator.platform`, and orientation; optionally slow the CPU or network. Settings merge across calls. | `pageUrl?`; `preset?` (`iphone-se`, `iphone-14`, `iphone-14-pro-max`, `pixel-7`, `galaxy-s20`, `ipad-mini`) or `width`+`height` `200..4000` with `deviceScaleFactor?` `1..4` and `mobile?`; `orientation?`; `cpuSlowdown?` `1..20`; `network?` (`online`, `offline`, `slow-3g`, `fast-3g`, `fast-4g`); `reload?`; or `reset: true` |
 | `cocos_scene_tree` | Return a bounded scene tree with node and component summaries. | `pageUrl?`; `maxDepth?` integer `0..20`, default `6`; `maxNodes?` integer `1..5000`, default `500` |
@@ -170,12 +173,17 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `cocos_get_components` | Return bounded component summaries for a node. | `pageUrl?`; `uuid` |
 | `cocos_get_node` | Return one node's path, parent, bounded direct children, and components. | `pageUrl?`; `uuid` |
 | `cocos_snapshot_subtree` | Return a bounded stateless hierarchy snapshot; clients compare snapshots. | `pageUrl?`; `uuid`; `maxDepth?`; `maxNodes?` |
+| `cocos_observe_changes` | Return an initial normalized semantic snapshot, then unchanged or compact added/removed/changed node deltas. Server-only baseline state; supported on web and native. | `pageUrl?`; optional `uuid` or `path`; `reset?`; `maxDepth?` `0..20`, default `6`; `maxNodes?` `1..5000`, default `500` |
 | `cocos_get_node_bounds` | Return bounded canvas/viewport bounds, anchor, world position, and visibility for one UI node. | `pageUrl?`; `uuid` |
-| `cocos_capture_node` | Return an in-memory viewport-clipped image for one visible UI node: PNG, falling back to JPEG when PNG exceeds the response limit; no file is written. | `pageUrl?`; `uuid` |
+| `cocos_capture_node` | Return an in-memory viewport-clipped image for one visible UI node: PNG, falling back to JPEG when PNG exceeds the response limit; no file is written. | `pageUrl?`; `uuid` or `path`; `maxBytes?` |
 | `cocos_get_properties` | Serialize public properties for a node or one component selected by type or UUID. | `pageUrl?`; `uuid`; `componentType?` or `componentUuid?`; `maxDepth?` integer `0..6`, default `3`; `0` returns top-level primitives |
 | `cocos_wait_for_property` | Poll one top-level property until it strictly equals a primitive value or the timeout passes. | `pageUrl?`; `uuid`; `componentType?` or `componentUuid?`; `key`; `equals`; `timeoutMs?` `100..30000`, default `5000`; `intervalMs?` `50..5000`, default `200` |
 | `cocos_explain_click` | Explain whether a tap reaches a node, or what a tap at a viewport point would hit, by replaying the engine's touch dispatch order without dispatching anything: the claiming node, the hit stack, and reasons. | `pageUrl?`; `uuid` or `path`, and/or `x`+`y` viewport CSS pixels |
 | `cocos_listener_report` | Report timers, update callbacks, tweens, and director/game/view listeners that outlive their owner: on destroyed or detached nodes and components, and unowned callbacks (arrow functions, `bind`) grouped by event and name. | `pageUrl?`; `limit?` `1..500`, default `100` |
+| `cocos_explain_visibility` | Explain why a node is not visible: inactive ancestor, disabled or transparent renderer, missing `spriteFrame`, empty Label, zero opacity/scale/size, a layer no active camera renders, outside the viewport, clipped by a Mask. Possibly-covered nodes come back as warnings. | `pageUrl?`; `uuid` or `path` |
+| `cocos_explain_layout` | Explain why a node has its size and position: Widget edges and align mode, a parent Layout, Label/Sprite size modes, ancestor scale, and its viewport rectangle. | `pageUrl?`; `uuid` or `path` |
+| `cocos_animation_report` | List Animation components with playing states, Spine/DragonBones current animations, and tween targets with action counts. | `pageUrl?`; `limit?` `1..500`, default `100` |
+| `cocos_frame_profile` | Sample real frames and report frame time (avg, p50, p95, max), fps, spikes, worst frames, and draw call and triangle ranges. The game must be running. | `pageUrl?`; `frames?` `2..600`, default `120`; `timeoutMs?` `100..30000`, default `10000` |
 | `cocos_dynamic_atlas` | Report the dynamic atlas: config, each page with its packed textures (position, size, a node that draws each), fill ratio and GPU bytes, and why visible sprites stayed out. | `pageUrl?`; `limit?` `1..500`, default `100` |
 | `cocos_asset_report` | List assets in the asset cache with type, `refCount`, bundle, texture GPU bytes, and a `status`: `used` (a live renderer references it), `dependency` (reached from one, the scene, or a persist-root node), `builtin`, or `unused`. Unused assets sort first. | `pageUrl?`; `type?` asset class such as `Texture2D`; `unusedOnly?`; `limit?` `1..500`, default `100` |
 | `cocos_call_method` | Call one public method of a node or component and return its bounded result or thrown error. Runs game code. Registered only with `--allow-method-call`. | `pageUrl?`; node `uuid`; `componentUuid?` (omit to call on the node); `method` identifier; `args?` up to 20 JSON values, where `{"$node": uuid}`, `{"$component": uuid}`, and `{"$asset": uuid}` pass live objects; `awaitMs?` `0..30000` waits for a returned promise; `maxDepth?` `0..6`, default `2` |
@@ -186,6 +194,8 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 | `cocos_get_selection` | Return the node the user last Alt+clicked on the game canvas: node summary and path, viewport box, and the hit stack under the point (topmost first). The first call installs the picker. | `pageUrl?`; `disable?` removes the picker, overlay, and selection |
 | `cocos_highlight_node` | Draw a temporary pointer-transparent overlay around a UI node. | `pageUrl?`; `uuid`; `durationMs?` integer `100..10000`, default `2000` |
 
+`cocos_observe_changes` stores at most 32 baselines per server process and evicts the least-recently-observed scope when full. Its scope includes the concrete page identity, URL, document ID, selector (`uuid`, `path`, or scene), and bounds; web reloads produce a new document ID and therefore a full result. Native V8 has no non-mutating document identity, so a native reload that retains the same scene UUID can be reported as a delta. `reset: true` discards the matching baseline and returns a full snapshot. Revisions do not change for `unchanged`; semantic changes increment them. A delta at least as large as its full normalized snapshot returns `mode: "full"` with `DELTA_NOT_SMALLER_THAN_FULL`. `delta.changed[].changes` compares the union of old and new fields, excludes `uuid`, and encodes removed optional fields as `null`; snapshot fields are otherwise non-null, so `null` unambiguously means removed. Snapshots contain only normalized node identity, hierarchy path, active state, transforms, local UI bounds, Label text, and Button interactability; transforms prefer Cocos local backing values `_lpos`, `_lrot`, and `_lscale`, then `_position`, `_rotation`, and `_scale`, then public data fields. No frame or render-time values. Image equality is intentionally omitted: it requires capture before comparison and image decoding/threshold policy, enlarging the response path.
+
 `cocos_runtime_diagnostics` does not enable profiler/statistics systems. Render metrics are read from the values `Root` and the GFX device already update every frame (the same sources as `root.fps` and `device.numDrawCalls`), whether or not the profiler is shown; draw calls include the profiler overlay when it is visible. Generic invalid-reference checks still return `UNSUPPORTED_PUBLIC_API`. `cocos_get_selection` lets the user point at a node instead of describing it: it installs a capture-phase listener that consumes only Alt+clicks on the game canvas, so the game never sees them, and draws a labelled pointer-transparent overlay. It picks the topmost active node whose box contains the point and that draws or takes input (a 2D renderer such as Sprite or Label, or a Button, Toggle, EditBox, or Slider). Inactive nodes, layout-only containers, and nodes at zero opacity (including through a parent) are skipped, so invisible full-screen blockers do not swallow picks. The selection is reported `stale` once that node leaves the scene, and the picker disappears on reload. `cocos_highlight_node` temporarily mutates the page DOM only. It does not mutate the Cocos node/component graph or game state. `cocos_capture_node` clips only to the visible browser viewport, never falls back to full-page capture, bounds captures by the visible viewport and encoded response size rather than a fixed pixel cap, returns PNG (or JPEG fallback) base64 in-memory, downscales down to 0.25× (reported as `scale`) when JPEG quality steps are not enough, and rejects responses still oversized after that. Mutation results provide `before` values for manual inverse calls, but restoration cannot undo lifecycle callbacks or other runtime side effects. `cocos_step_frame` uses the public `cc.game.step` (fixed `game.frameTime` delta); because `director.tick` skips logic while the director is paused, it resumes the director only for the synchronous step call and pauses it again. `cocos_show_stats` is an explicit configuration change; while the overlay is visible, draw-call metrics include it. `cocos_emulate_device` holds a CDP session per page: emulation ends on `reset`, when the server disconnects, or when the server process exits, and `reset` also clears viewport overrides set by other CDP clients on that page. Cocos reads the user agent and touch support at startup, so pass `reload: true` for the game to see a new device class. The tool returns after the canvas has resized to the new viewport, so a following click or capture sees the new layout. Network throttling only delays traffic; it never reads requests or responses.
 
 `cocos_type_text` exists because `EditBox.string` is an accessor that `cocos_set_property` refuses, and assigning it would skip the `text-changed` and `editing-did-ended` events that login forms listen for. It taps the EditBox, waits for the DOM input the engine opens, selects its content, and inserts the text through the browser keyboard. `submit` presses Enter: single-line boxes fire `editing-return` and close; multi-line boxes (the default `InputMode.ANY`) insert a newline instead. Password boxes (`InputFlag.PASSWORD`) report `redacted`, and `cocos_get_properties` omits their text. `cocos_drag_node` and `cocos_click_node` send mouse events normally and CDP touch events under mobile emulation, where Chrome would otherwise convert and never acknowledge the mouse input; Cocos only listens for touch once it detected a touch device at startup, so emulate with `reload: true` first.
@@ -196,13 +206,15 @@ All tool input objects are strict. Unknown fields are rejected. Inspection tools
 
 Every tool that acts on one node takes either `uuid` or `path`, never both. A path is the absolute scene path that `cocos_find_node` and `cocos_scene_tree` report, such as `/LoginScene/Canvas/panLogin/btnLogin`. Paths survive scene reloads, while node UUIDs created at runtime change on each load, so agents can act in one call instead of looking the UUID up first. Sibling nodes may share a name, so a path that matches more than one node fails with `AMBIGUOUS_NODE` and lists the candidate UUIDs; no tool acts on an ambiguous path. `cocos_call_method` arguments accept `{"$path": path}` the same way.
 
+Node ids such as `Node.1287` and `Comp.5601` are assigned at runtime and go stale after a scene switch or reload; prefer `path` or `cocos_find_node` over ids cached from earlier steps. A path starts with `/` and the root node name, so `Canvas/Btn` and `//Canvas` do not match. Optional string fields sent as `""` are treated as omitted. `cocos_call_method` rejects methods whose names start with `_` on purpose, since they are engine and game internals. `cocos_capture_node` takes `maxBytes` (1,000 to 200,000) to cap the base64 image size when the MCP client rejects large results; it downscales further instead of failing.
+
 ### Page selection
 
 Eligible game pages must use HTTP or HTTPS on a loopback host.
 
 - With one eligible page, `pageUrl` may be omitted.
 - With multiple eligible pages, `pageUrl` is required.
-- `pageUrl` must exactly match the full URL reported by the browser, including path, query, and fragment.
+- `pageUrl` must exactly match the full URL reported by the browser, including path, query, and fragment. A `PAGE_NOT_FOUND` error lists the open loopback pages (without query or fragment).
 - Tabs with identical URLs cannot be told apart; close duplicates before inspecting.
 
 Every MCP client pointed at the same CDP endpoint sees every loopback tab in that browser. When several projects run at once, give each project its own Chromium, port, and profile, then configure the server at project scope:
@@ -212,7 +224,7 @@ chrome --remote-debugging-address=127.0.0.1 --remote-debugging-port=9223 --user-
 claude mcp add cocos-web-inspector npx -- -y cocos-web-inspector-mcp@latest --cdp-endpoint http://127.0.0.1:9223
 ```
 
-Tool validation, connection, selection, and inspection failures are returned as MCP tool errors. Operational errors include JSON `structuredContent` and text content with stable `code` and `message` fields. Current codes include `CDP_UNAVAILABLE`, `NO_LOCAL_PAGE`, `MULTIPLE_PAGES`, `PAGE_NOT_FOUND`, `COCOS_NOT_FOUND`, `SCENE_NOT_READY`, `NODE_NOT_FOUND`, and `COMPONENT_NOT_FOUND`.
+Tool validation, connection, selection, and inspection failures are returned as MCP tool errors. Operational errors include JSON `structuredContent` and text content with stable `code` and `message` fields. Messages carry what is needed to retry: the endpoint and a launch hint for `CDP_UNAVAILABLE`, accepted keys for unknown arguments, candidate component UUIDs for `AMBIGUOUS_COMPONENT` and `COMPONENT_NOT_FOUND`, and the components that do have the method when `cocos_call_method` targets a node. `cocos_wait_for_property` keeps polling while the scene, node, or component is missing and reports `gone` with the last reason when the timeout passes. Current codes include `CDP_UNAVAILABLE`, `NO_LOCAL_PAGE`, `MULTIPLE_PAGES`, `PAGE_NOT_FOUND`, `COCOS_NOT_FOUND`, `SCENE_NOT_READY`, `NODE_NOT_FOUND`, and `COMPONENT_NOT_FOUND`.
 
 ### Output bounds
 
@@ -285,6 +297,14 @@ The test suite covers URL policy, CDP connection reuse and recovery, scene trave
 
 `cocos_set_time_scale` multiplies the delta time `director.tick` passes to components, the scheduler, tweens, animation, physics, and rendering, so the whole game runs faster or slower; frame stepping with `cocos_step_frame` still uses the fixed frame time. Reload or `scale: 1` restores normal speed.
 
+`cocos_explain_visibility` answers "why can I not see this". It reports definite `reasons` (`INACTIVE`, `RENDERER_DISABLED`, `NO_SPRITE_FRAME`, `EMPTY_TEXT`, `TRANSPARENT_COLOR`, `ZERO_OPACITY`, `ZERO_SCALE`, `ZERO_SIZE`, `LAYER_NOT_RENDERED`, `OUTSIDE_VIEWPORT`, `CLIPPED_BY_MASK`) and possible `warnings` (`NO_RENDERER`, `NO_ACTIVE_CAMERA`, `POSSIBLY_COVERED`). Covering is judged by an opaque Sprite's box only, so texture transparency and camera priority are ignored. It reads state and renders nothing.
+
+`cocos_explain_layout` names what drives a node's geometry. `explanations` codes include `WIDGET_STRETCHES_WIDTH`, `WIDGET_ALIGN_ONCE`, `LAYOUT_CONTROLS_POSITION`, `LAYOUT_CONTROLS_SIZE`, `LABEL_CONTROLS_SIZE`, `SPRITE_CONTROLS_SIZE`, and `SCALED_BY_ANCESTOR`. Call it after each `cocos_emulate_device` preset to see which constraint breaks.
+
+`cocos_frame_profile` subscribes to the director's after-draw event for the sample window and measures the wall-clock gap between frames, so garbage-collection pauses show as spikes. A spike is a frame over twice the median and over 33 ms.
+
+`cocos_event_trace` counts `emit` calls on nodes, which covers `TRANSFORM_CHANGED`, touch events, and custom events. It cannot see listeners on `director`, `game`, or `input`; use `cocos_listener_report` for those. Only one trace runs at a time.
+
 ### Dynamic atlas and asset leaks
 
 `cocos_dynamic_atlas` answers why sprites do or do not batch through the dynamic atlas. Each page lists its packed textures with their position, size, and one node that draws each, its `fill` (packed texture area over page area) and `shelfFill` (the height the shelf packer has used), and its GPU bytes. Runtime textures, such as Label text rendered in bitmap cache mode, have no asset uuid and report `runtime: true`. For every visible sprite outside the atlas it gives the reason, checked in the engine's own order: `DISABLED`, `NOT_TEXTURE2D`, `COMPRESSED`, `TOO_LARGE` (over `maxFrameSize`), `NOT_PACKABLE`, `FILTER` (not linear, or mipmapped), `ATLAS_FULL`, or `NOT_YET_RENDERED`. Pages are never compacted: removed textures leave holes until the atlas resets on scene change, so a high `shelfFill` with a low `fill` means wasted space.

package/dist/src/bridge.d.ts

@@ -24,6 +24,11 @@ export type BridgeRequest = {
     uuid: string;
     maxDepth?: number | undefined;
     maxNodes?: number | undefined;
+} | {
+    action: 'semanticSnapshot';
+    uuid?: string | undefined;
+    maxDepth?: number | undefined;
+    maxNodes?: number | undefined;
 } | {
     action: 'getComponents';
     uuid: string;
@@ -89,6 +94,23 @@ export type BridgeRequest = {
 } | {
     action: 'listenerReport';
     limit?: number | undefined;
+} | {
+    action: 'explainVisibility';
+    uuid: string;
+} | {
+    action: 'explainLayout';
+    uuid: string;
+} | {
+    action: 'animationReport';
+    limit?: number | undefined;
+} | {
+    action: 'frameProfile';
+    frames?: number | undefined;
+    timeoutMs?: number | undefined;
+} | {
+    action: 'eventTrace';
+    durationMs?: number | undefined;
+    limit?: number | undefined;
 } | {
     action: 'timeScale';
     scale?: number | undefined;
@@ -146,8 +168,8 @@ export declare function visibleClip(page: Page, uuid: string): Promise<Clip | {
     reason: string;
 }>;
 /** Whether base64 image data stays under the response ceiling. */
-export declare const fitsImage: (data: string) => boolean;
-export declare function captureNode(page: Page, uuid: string): Promise<unknown>;
+export declare const fitsImage: (data: string, limit?: number) => boolean;
+export declare function captureNode(page: Page, uuid: string, maxBytes?: number): Promise<unknown>;
 export declare function nodeCenter(page: Page, uuid: string): Promise<{
     x: number;
     y: number;
@@ -157,6 +179,9 @@ export declare function nodeCenter(page: Page, uuid: string): Promise<{
 export declare function clickNode(page: Page, uuid: string): Promise<unknown>;
 export declare function dragNode(page: Page, uuid: string, dx: number, dy: number, steps?: number, durationMs?: number): Promise<unknown>;
 export declare function typeText(page: Page, uuid: string, text: string, submit: boolean): Promise<unknown>;
+export declare const namedKeys: readonly ['Enter', 'Escape', 'Tab', 'Backspace', 'Delete', 'Space', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End', 'PageUp', 'PageDown'];
+export declare const keyPattern: RegExp;
+export declare function pressKey(page: Page, key: string): Promise<unknown>;
 export declare const devicePresets: {
     readonly 'iphone-se': {
         readonly width: 375;