proto-view.mjs

Drives an already-running Chrome instance over CDP — console capture, JS eval, reload, click, drag, and paint/DOM probes — and exits.

Contributor tooling › proto-view.mjs

What it does

Connects to a Chrome instance already listening for CDP connections — proto-window.mjs, typically. Dispatches one of seven subcommands against the page opened last: check, console, eval, reload, drag, click, or probe. Prints the subcommand's result to stdout and exits, holding no session between invocations. Rejects any call that would resize or rescale the shared window, so every caller sees the page at its real size.

Usage

The minimal invocation that works:

npm run proto:view -- check

node tools/proto-view.mjs check

The first positional argument selects the subcommand — check, console, eval, reload, drag, click, or probe — and each takes its own flags from the table below.

Options

Flag	Value	What it does	Default
--port	<n>	The CDP port to connect to. Every subcommand takes it.	9222
--url	<substr>	Selects which open page to target, by a substring match against its URL. Every subcommand but check takes it; a miss lists the open pages' URLs in the error.	the page opened last
--errors	no value	On console, filters the captured lines down to exceptions and error-level console/log entries.	off — every captured line prints
--ms	<n>	On console, how long to collect console/log/exception events before returning.	1500
--expr	<js>	On eval, the JavaScript expression to evaluate in the page, awaited and returned by value. Required by eval.	none — required
--at	<x,y>	On click, the page coordinates to click. Required by click.	none — required
--from	<x,y>	On drag, the point the drag starts at. Required by drag, alongside --to.	none — required
--to	<x,y>	On drag, the point the drag ends at. Required by drag, alongside --from.	none — required
--steps	<n>	On drag, how many intermediate mouseMoved events to dispatch between --from and --to.	16
--selector	<css>	On probe, the CSS selector to inspect for existence, whether it is shown, size, and (for canvas/img/svg descendants) whether art painted or loaded. Required by probe.	none — required
--no-sweep	no value	On probe, skips the page-wide sweep for zero-area canvas/img elements outside the selector.	off — the sweep runs
--help	no value	Prints usage and exits, in place of a subcommand.	off — the given subcommand runs instead

Inputs and outputs

Reads: nothing on disk — every input is a CLI flag. Every effect is a CDP call over WebSocket to 127.0.0.1:<port> (/json/version, /json/list, then the target page's own webSocketDebuggerUrl). It connects to a CDP port; it does not bind one.

Writes: nothing on disk. What prints to stdout depends on the subcommand:

• console, eval, reload, drag, and click print a short confirmation or the evaluated value
• probe prints its full result as JSON
• check prints the browser and protocol version plus every open page

Every CDP call carries its own 15-second timeout, rejecting if Chrome does not answer in time.

Exit codes:

Code	Meaning
0	The subcommand succeeded, and for probe, the selector also passed: it exists, is visible, has nonzero area, and any canvas/img descendants painted or loaded.
1	A connection failure — no CDP browser listening, no matching --url target, the page threw, a CDP call timed out — or, for probe, a result that failed.
2	A usage error — a missing --expr, --at, --from/--to, or --selector for the subcommand that requires it, or an unrecognized subcommand.

No subcommand at all prints usage and exits 1; --help prints usage and exits 0.

Examples

Confirm a Chrome debug target is reachable before scripting against it:

node tools/proto-view.mjs check

Verify a changed element actually rendered — the ui-room workflow requires this before presenting any UI work:

node tools/proto-view.mjs probe --selector ".wf-panel"

Read what the page's console printed after an interaction, errors only:

node tools/proto-view.mjs console --errors

Notes

Rejects Emulation.setDeviceMetricsOverride, Browser.setWindowBounds, and any Emulation.setPageScaleFactor other than 1 at the protocol layer — the shared window is always driven at its real size, never resized or rescaled by a caller.

The probe sweep (on by default; --no-sweep turns it off) checks the whole page for zero-area canvas/img elements outside the selector. A selector can pass on its own while the sweep still fails the command for an unrelated element elsewhere on the page.

Connects to a running Chrome; it does not launch one — see proto-window.mjs. There is nothing to stop: each subcommand opens a session, runs, and closes it.

Source

tools/proto-view.mjs — part of Contributor tooling