High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
Capture
Paired screenshot and accessibility snapshot from the same DOM epoch in
one HTTP call. Use this when the model needs to read pixels AND act on refs
in the same turn — the unpaired /screenshot + /snapshot sequence drifts
when the page mutates between calls.
# Default: file output, wait for page quiescence, bounds included
curl "http://localhost:9867/capture"
# CLI alternative — writes the image locally and prints a summary
pinchtab capture -o /tmp/cap.jpg
# Half-size image (snapshot/bounds unchanged)
pinchtab capture --scale 0.5
# Fail with 409 if the main frame navigates mid-capture
pinchtab capture --require-pair
# Full-document image; bounding boxes in page coords
pinchtab capture --beyond-viewport
# Scope to one element: image clips to it, snapshot subtree filters to it.
# Bounding boxes are relative to the clipped image origin.
pinchtab capture -s "#checkout-form"
Response (JSON)
{
"status": "ok",
"tabId": "tab_abc",
"url": "https://example.com/checkout",
"title": "Checkout",
"capturedAt": "2026-05-29T15:44:12.431Z",
"epoch": {
"frameId": "8E2F...A1",
"loaderId": "5C9D...0B",
"domEpoch": "ep_..."
},
"pairing": {
"navigated": false,
"captureDurationMs": 312
},
"image": {
"format": "jpeg",
"path": "/.../state/captures/cap-20260529-154412.jpg",
"bytes": 184223,
"coordinateSpace": "viewport",
"devicePixelRatio": 2,
"viewport": { "w": 1440, "h": 900, "scrollX": 0, "scrollY": 0 }
},
"snapshot": {
"filter": "interactive",
"nodeCount": 14,
"nodes": [
{
"ref": "e4", "role": "textbox", "name": "Email",
"boundingBox": { "x": 520, "y": 312, "w": 280, "h": 36 },
"visible": true
},
{
"ref": "e9", "role": "button", "name": "Submit",
"boundingBox": { "x": 520, "y": 1480, "w": 96, "h": 40 },
"visible": false
}
]
}
}
What pairing guarantees
The atomicity contract is "no main-frame navigation between the two CDP
calls" — pairing.navigated flips to true when the main frame's
loaderId changes during the capture window. Drift inside the same
document (React re-renders, IntersectionObserver mutations) is not
detected; wait=stable reduces but does not eliminate it.
epoch.domEpoch is the tab's ref vocabulary token — the same opaque value
/snapshot returns as vocabularyToken — and is also set on the
X-PinchTab-Vocab response header. It is kept while the new nodes share refs
with the previous vocabulary and re-minted when they do not. Echo it as vocab
on ref-based actions: a ref action under a token other than the tab's current
one is refused with 409 vocab_superseded.
Bounding boxes and coordinate space
When withBounds=true (the default), each snapshot node with a non-zero
backend node id gets a boundingBox and a visible flag, and a node that
cannot be measured gets neither.
boundingBox is the border box — the painted edge of the element, the
same rectangle pinchtab box, screenshot?annotate=true and
getBoundingClientRect report. Overlays and crop rectangles drawn from it
cover the control a viewer sees, and a box from /capture can be compared
directly with one from any of those surfaces.
The coordinate space depends on selector and beyondViewport:
viewport(default): boxes are viewport-relative CSS pixels. The image is the visible viewport.image.devicePixelRatiotells you the ratio of image pixels to CSS pixels.clip(whenselectoris set): boxes are relative to the cropped image origin. The response also includesimage.clipwith the original document-relative clip rectangle.document(whenbeyondViewport=true): boxes use page coordinates (box.xandbox.yinclude scroll offset). The image is the full document.
In all three, the image measures exactly the reported space times
image.devicePixelRatio times the scale you asked for (default 1):
scaling a boundingBox by devicePixelRatio × scale, from the origin the
space names, lands on the image's pixels. The mode never enters the
arithmetic, and neither does pinchtab set viewport — the only factor beyond
the reported ratio is the one you passed yourself, and the response reports
the page ratio rather than the product. At the default scale the ratio
alone is the whole mapping.
Keeping that identity costs the default capture the faster read-the-view path
— that path returns the real window surface, whose scale factor is the
screen's rather than the page's and which viewport emulation does not touch —
so an idle headed browser can make a /capture slower than a /screenshot.
visible is true when the box has positive area and intersects the
viewport — a cheap heuristic, not a strict occlusion check. A node
scrolled past, in either direction, is measured and reports
"visible": false.
Absent means not measured, never "no". visible appears exactly when
boundingBox does, so the key is missing only where no measurement was
taken: withBounds=false, a node with no backend node id, or a node whose
box query failed. Treat a missing visible as unknown and a present
false as off-screen; they are different answers.
visible here is not GET /visible
GET /visible (and pinchtab visible <ref>) answers a different question
under the same word: CSS rendered-ness — display, visibility,
opacity, and a laid-out or positioned box with non-zero size. Scroll
position is not an input, so an element far below the fold is "visible": true there while this snapshot reports "visible": false for the same node
at the same moment. Both answers are correct and both are wanted: one says
the element is rendered at all, the other says it is on screen right now.
GET /visible also returns onScreen, which is this snapshot's predicate
computed for that one element, so a single call answers both questions.
onScreen follows the same absent-means-not-measured rule as visible
above.
Useful flags
API Query Parameters
| Parameter | Description |
|---|---|
tabId |
Target a specific tab |
selector |
Scope: clips image and filters snapshot subtree to the same element |
filter |
interactive (default) or all |
format |
jpeg (default) or png |
quality |
JPEG quality 0-100 (default 80) |
depth |
Snapshot tree depth limit (default -1, full tree) |
output |
file (default), inline (base64 in JSON), or raw (bytes only — drops the snapshot) |
wait |
stable (default) waits for Page.lifecycleEvent quiescence (250ms silence / 750ms ceiling); load polls document.readyState until complete (2s ceiling); none skips the wait |
withBounds |
true (default) — populate boundingBox (the border box) + visible on every measurable snapshot node; false omits both keys everywhere |
beyondViewport |
true — capture the full scrollable document; coordinate space becomes document |
scale |
Rescale the output bitmap. Default 1. 0.5 halves each axis (quarter the pixels); out-of-range values are clamped |
requirePair |
true returns 409 if pairing.navigated would be true |
noAnimations |
true — inject prefers-reduced-motion CSS for the capture window |
CLI
| Flag | Description |
|---|---|
-o <path> |
Save the captured image locally (default: capture-<ts>.jpg) |
-s <selector> |
Scope: clips image and filters snapshot subtree |
--filter <name> |
Snapshot filter |
--format <fmt> |
jpeg or png (default: png when -o ends in .png, otherwise jpeg) |
-q <0-100> |
JPEG quality |
--depth <n> |
Snapshot depth limit |
--wait <mode> |
stable (default) / load / none |
--with-bounds |
Boolean (default true) |
--beyond-viewport |
Capture full document |
--scale <f> |
Bitmap rescale (e.g. 0.5) |
--require-pair |
Fail with 409 on mid-capture navigation |
--tab <id> |
Target a specific tab |
--json |
Print the full JSON response instead of the terse summary |
GET /tabs/{id}/capture is the same handler with the tab in the path. An
unknown output value is a 400; requirePair failing is a 409, as is a pending
JavaScript dialog (409 dialog_blocked).