Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: add /capture paired screenshot + snapshot endpoint

Luigi Agostifa78bd6d0b3e
diff --git a/cmd/pinchtab/cmd_cli_browser_inspect.go b/cmd/pinchtab/cmd_cli_browser_inspect.go
index 085cb419..d5710610 100644
--- a/cmd/pinchtab/cmd_cli_browser_inspect.go
+++ b/cmd/pinchtab/cmd_cli_browser_inspect.go
@@ -42,6 +42,17 @@ var screenshotCmd = &cobra.Command{
},
}
+var captureCmd = &cobra.Command{
+ Use: "capture",
+ Aliases: []string{"cap"},
+ Short: "Paired screenshot + accessibility snapshot from the same DOM epoch",
+ Run: func(cmd *cobra.Command, args []string) {
+ runCLI(func(rt cliRuntime) {
+ browseractions.Capture(rt.client, rt.base, rt.token, cmd)
+ })
+ },
+}
+
var evalCmd = &cobra.Command{
Use: "eval <expression>",
Short: "Evaluate JavaScript",
diff --git a/cmd/pinchtab/cmd_cli_register.go b/cmd/pinchtab/cmd_cli_register.go
index 9bbcbeb2..758a2658 100644
--- a/cmd/pinchtab/cmd_cli_register.go
+++ b/cmd/pinchtab/cmd_cli_register.go
@@ -32,6 +32,7 @@ func registerBrowserCommands() {
dragCmd,
typeCmd,
screenshotCmd,
+ captureCmd,
tabsCmd,
pressCmd,
fillCmd,
@@ -111,6 +112,7 @@ func registerBrowserCommands() {
dragCmd,
typeCmd,
screenshotCmd,
+ captureCmd,
tabsCmd,
pressCmd,
fillCmd,
@@ -244,6 +246,17 @@ func configureBrowserFlags() {
screenshotCmd.Flags().String("format", "", "Image format: 'jpeg' (default) or 'png'")
screenshotCmd.Flags().Bool("beyond-viewport", false, "Capture the entire scrollable document, not just the visible viewport. Ignored when --selector is set.")
+ captureCmd.Flags().StringP("output", "o", "", "Save the captured image to this local file path (default: capture-<ts>.jpg)")
+ captureCmd.Flags().StringP("selector", "s", "", "Scope: clips screenshot and filters snapshot subtree to the same element")
+ captureCmd.Flags().String("filter", "", "Snapshot filter: 'interactive' or 'all' (default: all)")
+ captureCmd.Flags().String("format", "", "Image format: 'jpeg' (default) or 'png'")
+ captureCmd.Flags().StringP("quality", "q", "", "JPEG quality (0-100)")
+ captureCmd.Flags().String("depth", "", "Snapshot max depth (-1 for full)")
+ captureCmd.Flags().String("wait", "", "Lifecycle wait: stable (default) | load | none")
+ captureCmd.Flags().Bool("with-bounds", true, "Populate boundingBox per snapshot node (default true)")
+ captureCmd.Flags().Bool("beyond-viewport", false, "Capture the entire scrollable document; coordinate space becomes 'document'")
+ captureCmd.Flags().Bool("require-pair", false, "Return 409 if navigation is observed during the capture window")
+
pdfCmd.Flags().StringP("output", "o", "", "Save PDF to file path")
pdfCmd.Flags().Bool("landscape", false, "Landscape orientation")
pdfCmd.Flags().String("scale", "", "Page scale (e.g. 0.5)")
diff --git a/docs/commands.md b/docs/commands.md
index e61dda0e..8417b2e7 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -213,6 +213,11 @@ pinchtab screenshot -q <0-100> # JPEG quality
pinchtab screenshot -s <selector> # Capture a specific element by selector
pinchtab screenshot -s <selector> --css-1x # Export selector screenshot at CSS pixel size
pinchtab screenshot --beyond-viewport # Capture the full scrollable document (ignored with -s)
+pinchtab capture # Paired screenshot + accessibility snapshot from the same DOM epoch
+pinchtab capture -o <path> # Save the paired image to a chosen path
+pinchtab capture --beyond-viewport # Capture the full document; bounds in page coords
+pinchtab capture --require-pair # Fail (409) if the page navigated mid-capture
+pinchtab capture --with-bounds=false # Skip per-node DOM.getBoxModel round trips
pinchtab pdf # Export the active page as PDF
pinchtab pdf -o <path> # Save PDF to a chosen path
pinchtab pdf --landscape # Landscape orientation
@@ -287,6 +292,7 @@ Commands with `--tab` currently include:
- `reload`
- `snap`
- `screenshot`
+- `capture`
- `pdf`
- `find`
- `text`
diff --git a/docs/endpoints.md b/docs/endpoints.md
index 1338f13a..3a363d85 100644
--- a/docs/endpoints.md
+++ b/docs/endpoints.md
@@ -241,6 +241,8 @@ Find body fields:
```text
GET /screenshot
GET /tabs/{id}/screenshot
+GET /capture
+GET /tabs/{id}/capture
GET /pdf
POST /pdf
GET /tabs/{id}/pdf
@@ -263,6 +265,71 @@ Screenshot query parameters:
- `output=file`
- `noAnimations=true`
+`/capture` returns a screenshot and an accessibility snapshot from the same
+DOM epoch in a single call. It is the vision-grounded alternative to issuing
+`/screenshot` and `/snapshot` back-to-back — the two unpaired calls share no
+synchronization primitive, so the page can mutate between them and refs from
+the snapshot can point at nodes that did not exist when the image was taken.
+
+Capture query parameters:
+
+- `tabId`
+- `selector` — clips screenshot and filters snapshot subtree to the same element
+- `filter=interactive|all`
+- `depth` — snapshot max depth (default `-1` for full)
+- `format=jpeg|png`
+- `quality`
+- `output=file|inline|raw` — default `file`
+- `requirePair=true` — return `409 Conflict` when navigation is observed during the capture window
+- `noAnimations=true`
+- `wait=stable|load|none` — default `stable`. `stable` waits for
+ `Page.lifecycleEvent` quiescence (250ms of silence, 750ms ceiling) before
+ opening the capture window so the screenshot and the AX-tree describe a
+ settled page. `none` skips the wait. `load` is currently an alias for
+ `none`; reserved for a future `document.readyState` gate.
+- `withBounds=true|false` — default `true`. When on, every snapshot node
+ with a non-zero backend node id gets a `boundingBox` field and a
+ `visible` flag. Each bounded node costs one `DOM.getBoxModel` round trip
+ (~5ms); for the typical interactive-filter snapshot the budget is under
+ 250ms. Pass `withBounds=false` to skip the per-node work.
+- `beyondViewport=true|false` — default `false`. When on, the image spans
+ the full document instead of just the visible viewport. The response
+ sets `image.coordinateSpace` to `"document"` and bounding boxes are
+ expressed in page (document) coordinates so they overlay the full image.
+ When a `selector` is also supplied, the selector clip wins and
+ `beyondViewport` is silently ignored — the same rule `/screenshot`
+ enforces. Beyond-viewport captures force a layout pass that can resolve
+ lazy images and fire `IntersectionObserver`; the AX-tree fetch and bounds
+ harvest run after the screenshot so they reflect the post-reflow state.
+
+The response carries `image.coordinateSpace`, `image.devicePixelRatio`,
+and `image.viewport` ( `w`, `h`, `scrollX`, `scrollY` in CSS pixels at
+capture time) so clients can translate between image pixels and
+`boundingBox` values without guessing.
+
+The response carries an `epoch.domEpoch` token cached on the tab's ref-cache.
+Future client work can pass `expectedEpoch` to action endpoints to detect
+stale refs at the use site; in P1 it is informational. `pairing.navigated`
+is `true` when the main frame's `loaderId` changed mid-capture — that is the
+only drift mode P1 detects. In-document churn (re-renders, observer
+mutations) is the residual risk that later phases address.
+
+Response shape:
+
+```json
+{
+ "status": "ok",
+ "tabId": "tab_abc",
+ "url": "https://example.com",
+ "title": "Example",
+ "capturedAt": "2026-05-29T10:11:12.345Z",
+ "epoch": { "frameId": "...", "loaderId": "...", "domEpoch": "ep_..." },
+ "pairing": { "navigated": false, "captureDurationMs": 312 },
+ "image": { "format": "jpeg", "path": "/.../captures/cap-...jpg", "bytes": 184223 },
+ "snapshot": { "filter": "interactive", "nodeCount": 14, "nodes": [...] }
+}
+```
+
PDF query parameters:
- `tabId`
diff --git a/internal/bridge/bridge_types.go b/internal/bridge/bridge_types.go
index 51b1e73d..7c10bc04 100644
--- a/internal/bridge/bridge_types.go
+++ b/internal/bridge/bridge_types.go
@@ -33,9 +33,10 @@ type RefTarget struct {
}
type RefCache struct {
- Refs map[string]int64
- Targets map[string]RefTarget
- Nodes []A11yNode
+ Refs map[string]int64
+ Targets map[string]RefTarget
+ Nodes []A11yNode
+ DomEpoch string
}
func (c *RefCache) Lookup(ref string) (RefTarget, bool) {
diff --git a/internal/bridge/capture.go b/internal/bridge/capture.go
new file mode 100644
index 00000000..d8b9f9cb
--- /dev/null
+++ b/internal/bridge/capture.go
@@ -0,0 +1,176 @@
+package bridge
+
+import (
+ "context"
+ "crypto/rand"
+ "encoding/base32"
+ "time"
+
+ "github.com/chromedp/cdproto/page"
+ "github.com/chromedp/chromedp"
+)
+
+// CaptureOpts controls a paired screenshot + accessibility capture. The image
+// half is delegated to CaptureScreenshot; the snapshot half mirrors the
+// /snapshot handler's BuildSnapshot path.
+type CaptureOpts struct {
+ Image ScreenshotOpts
+ Filter string // snapshot filter ("" or FilterInteractive)
+ MaxDepth int // -1 for full tree
+ ScopeBackendNodeID int64 // optional snapshot subtree scope
+ ScopeFrameID string // optional frame-scoped capture
+ DisableAnimations bool
+
+ // Wait controls the lifecycle wait before the capture window opens.
+ // Empty (or "none") skips the wait. "stable" waits for
+ // Page.lifecycleEvent quiescence — 250ms of silence or 750ms ceiling.
+ // "load" is currently a no-op alias for "none"; reserved for a future
+ // document.readyState gate.
+ Wait string
+
+ // WithBounds populates BoundingBox + Visible on every snapshot node that
+ // has a non-zero backend node id. Adds one DOM.getBoxModel round trip
+ // per node (~5ms each).
+ WithBounds bool
+}
+
+// Wait values understood by PairedCapture.
+const (
+ WaitNone = "none"
+ WaitLoad = "load"
+ WaitStable = "stable"
+)
+
+// PairedResult is the in-process return shape of PairedCapture. The HTTP
+// handler turns this into the over-the-wire JSON; the field set is chosen to
+// keep that translation mechanical.
+type PairedResult struct {
+ URL string
+ Title string
+ CapturedAt time.Time
+ DurationMs int64
+
+ FrameID string
+ LoaderID string
+ DomEpoch string
+ Navigated bool
+
+ ImageBytes []byte
+ ImageFormat string // "jpeg" or "png"
+
+ // Viewport metadata captured alongside the image. CoordinateSpace is
+ // "viewport" by default and "document" when ImageOpts.BeyondViewport is
+ // true — bounding boxes are expressed in the named space.
+ Viewport ViewportInfo
+ CoordinateSpace string
+
+ Filter string
+ Nodes []A11yNode
+ Refs map[string]int64
+}
+
+// PairedCapture runs a screenshot and an accessibility snapshot under the same
+// chromedp context. The atomicity guarantee is "no main-frame navigation
+// between the two CDP calls" — checked by comparing the main frame's loaderId
+// before and after the capture window. Drift inside the same document
+// (re-renders, observer mutations) is out of scope for P1; later phases add
+// wait:stable and bounding-box harvesting.
+func PairedCapture(ctx context.Context, opts CaptureOpts) (*PairedResult, error) {
+ start := time.Now()
+ res := &PairedResult{
+ CapturedAt: start,
+ ImageFormat: imageFormatString(opts.Image.Format),
+ Filter: opts.Filter,
+ }
+
+ if opts.DisableAnimations {
+ if err := DisableAnimationsOnce(ctx); err != nil {
+ return nil, err
+ }
+ }
+
+ if opts.Wait == WaitStable {
+ // Errors here are non-fatal — a failed wait should still produce a
+ // capture, just without the quiet-window guarantee. The duration is
+ // captured for diagnostics but not currently surfaced in PairedResult.
+ _, _ = WaitForQuietWindow(ctx, 250*time.Millisecond, 750*time.Millisecond)
+ }
+
+ // Pre-capture frame info — root frame id + loader id.
+ pre, err := FetchFrameTree(ctx)
+ if err != nil {
+ return nil, err
+ }
+ res.FrameID = pre.Frame.ID
+ res.LoaderID = pre.Frame.LoaderID
+
+ // Image first. Order matters only when BeyondViewport is true (P3 concern);
+ // at viewport scale either order is equivalent.
+ imgBytes, err := CaptureScreenshot(ctx, opts.Image)
+ if err != nil {
+ return nil, err
+ }
+ res.ImageBytes = imgBytes
+
+ // AX tree → flat node list with refs. Mirrors HandleSnapshot's pipeline.
+ rawNodes, err := FetchAXTree(ctx)
+ if err != nil {
+ return nil, err
+ }
+ if opts.ScopeBackendNodeID != 0 {
+ rawNodes = FilterSubtree(rawNodes, opts.ScopeBackendNodeID)
+ }
+ flat, refs := BuildSnapshot(rawNodes, opts.Filter, opts.MaxDepth)
+ _ = EnrichA11yNodesWithDOMMetadata(ctx, flat)
+ res.Nodes = flat
+ res.Refs = refs
+
+ // URL + title for response metadata.
+ _ = chromedp.Run(ctx,
+ chromedp.Location(&res.URL),
+ chromedp.Title(&res.Title),
+ )
+
+ // Layout metrics: needed both for the response (viewport, devicePixelRatio)
+ // and for the bounds visibility heuristic. Captured AFTER the screenshot so
+ // that beyondViewport's reflow side effects are reflected.
+ if vp, err := FetchLayout(ctx); err == nil {
+ res.Viewport = vp
+ }
+ pageCoords := opts.Image.BeyondViewport
+ if pageCoords {
+ res.CoordinateSpace = "document"
+ } else {
+ res.CoordinateSpace = "viewport"
+ }
+
+ if opts.WithBounds {
+ _ = AnnotateBounds(ctx, res.Nodes, pageCoords, res.Viewport)
+ }
+
+ // Post-capture frame info. Compare root frame id + loader id to detect
+ // navigation that happened during the capture window. We do not assert on
+ // in-document churn (React re-renders, observer mutations) — that's the
+ // residual risk wait:stable mitigates in P2.
+ post, err := FetchFrameTree(ctx)
+ if err == nil {
+ res.Navigated = pre.Frame.ID != post.Frame.ID || pre.Frame.LoaderID != post.Frame.LoaderID
+ }
+
+ res.DomEpoch = mintDomEpoch()
+ res.DurationMs = time.Since(start).Milliseconds()
+ return res, nil
+}
+
+func imageFormatString(f page.CaptureScreenshotFormat) string {
+ return string(f)
+}
+
+// mintDomEpoch returns an opaque token unique per paired capture. The token
+// has no semantic content — consumers should treat it as a black box and use
+// it only for handshake comparisons against the cached value on RefCache.
+func mintDomEpoch() string {
+ var b [12]byte
+ _, _ = rand.Read(b[:])
+ return "ep_" + base32.StdEncoding.WithPadding(base32.NoPadding).EncodeToString(b[:])
+}
diff --git a/internal/bridge/observe/bounds.go b/internal/bridge/observe/bounds.go
new file mode 100644
index 00000000..bb174a5f
--- /dev/null
+++ b/internal/bridge/observe/bounds.go
@@ -0,0 +1,156 @@
+package observe
+
+import (
+ "context"
+ "encoding/json"
+
+ "github.com/chromedp/chromedp"
+)
+
+// ViewportInfo describes the layout viewport at capture time. Populated by
+// FetchLayout and used by AnnotateBounds for coordinate translation and the
+// visibility heuristic.
+type ViewportInfo struct {
+ Width float64
+ Height float64
+ ScrollX float64
+ ScrollY float64
+ DevicePixelRatio float64
+}
+
+// FetchLayout returns the page's current layout viewport in CSS pixels. One
+// CDP round trip via Runtime.evaluate so this composes inside PairedCapture
+// without an extra Page.getLayoutMetrics call.
+func FetchLayout(ctx context.Context) (ViewportInfo, error) {
+ var out ViewportInfo
+ const expression = `JSON.stringify({
+ w: window.innerWidth,
+ h: window.innerHeight,
+ sx: window.scrollX || window.pageXOffset || 0,
+ sy: window.scrollY || window.pageYOffset || 0,
+ dpr: window.devicePixelRatio || 1
+ })`
+ var result struct {
+ Result struct {
+ Value string `json:"value"`
+ } `json:"result"`
+ }
+ if err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.evaluate", map[string]any{
+ "expression": expression,
+ "returnByValue": true,
+ }, &result)
+ })); err != nil {
+ return out, err
+ }
+ var parsed struct {
+ W float64 `json:"w"`
+ H float64 `json:"h"`
+ SX float64 `json:"sx"`
+ SY float64 `json:"sy"`
+ DPR float64 `json:"dpr"`
+ }
+ if err := json.Unmarshal([]byte(result.Result.Value), &parsed); err != nil {
+ return out, err
+ }
+ out.Width = parsed.W
+ out.Height = parsed.H
+ out.ScrollX = parsed.SX
+ out.ScrollY = parsed.SY
+ out.DevicePixelRatio = parsed.DPR
+ return out, nil
+}
+
+// AnnotateBounds fills BoundingBox + Visible on each node whose NodeID is
+// non-zero. Each node costs one DOM.getBoxModel round trip; for the typical
+// FilterInteractive snapshot of <50 nodes the total budget is ~250ms.
+//
+// pageCoords=true translates viewport-relative boxes into document
+// (page) coordinates by adding the current scroll offset — the form needed
+// by beyondViewport captures whose image spans the whole document. With
+// pageCoords=false the boxes are left in viewport coords, matching the
+// default viewport-only screenshot.
+//
+// Visibility heuristic: a node is Visible if its rect has non-zero area and
+// intersects the viewport. The check is intentionally cheap — strict
+// occlusion (document.elementFromPoint) is deferred.
+func AnnotateBounds(ctx context.Context, nodes []A11yNode, pageCoords bool, vp ViewportInfo) error {
+ for i := range nodes {
+ if nodes[i].NodeID == 0 {
+ continue
+ }
+ box, ok := getBoxAABB(ctx, nodes[i].NodeID)
+ if !ok {
+ continue
+ }
+ if pageCoords {
+ box.X += vp.ScrollX
+ box.Y += vp.ScrollY
+ }
+ nodes[i].BoundingBox = &box
+ nodes[i].Visible = isVisible(box, pageCoords, vp)
+ }
+ return nil
+}
+
+func getBoxAABB(ctx context.Context, backendNodeID int64) (BoundingBox, bool) {
+ var result json.RawMessage
+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.getBoxModel", map[string]any{
+ "backendNodeId": backendNodeID,
+ }, &result)
+ }))
+ if err != nil {
+ return BoundingBox{}, false
+ }
+ var box struct {
+ Model struct {
+ Content []float64 `json:"content"`
+ } `json:"model"`
+ }
+ if err := json.Unmarshal(result, &box); err != nil {
+ return BoundingBox{}, false
+ }
+ q := box.Model.Content
+ if len(q) < 8 {
+ return BoundingBox{}, false
+ }
+ // AABB across the 4 corners — robust against transformed elements.
+ minX, maxX := q[0], q[0]
+ minY, maxY := q[1], q[1]
+ for k := 2; k < 8; k += 2 {
+ if q[k] < minX {
+ minX = q[k]
+ }
+ if q[k] > maxX {
+ maxX = q[k]
+ }
+ if q[k+1] < minY {
+ minY = q[k+1]
+ }
+ if q[k+1] > maxY {
+ maxY = q[k+1]
+ }
+ }
+ return BoundingBox{X: minX, Y: minY, W: maxX - minX, H: maxY - minY}, true
+}
+
+func isVisible(b BoundingBox, pageCoords bool, vp ViewportInfo) bool {
+ if b.W <= 0 || b.H <= 0 {
+ return false
+ }
+ if vp.Width <= 0 || vp.Height <= 0 {
+ // No viewport info to compare against; fall back to area test only.
+ return true
+ }
+ // Compute the viewport rect in the same coordinate space as the box.
+ var vx, vy float64
+ if pageCoords {
+ vx, vy = vp.ScrollX, vp.ScrollY
+ }
+ // Rect-rect intersection.
+ return b.X+b.W > vx &&
+ b.Y+b.H > vy &&
+ b.X < vx+vp.Width &&
+ b.Y < vy+vp.Height
+}
diff --git a/internal/bridge/observe/lifecycle.go b/internal/bridge/observe/lifecycle.go
new file mode 100644
index 00000000..81648408
--- /dev/null
+++ b/internal/bridge/observe/lifecycle.go
@@ -0,0 +1,85 @@
+package observe
+
+import (
+ "context"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/chromedp/cdproto/page"
+ "github.com/chromedp/chromedp"
+)
+
+// WaitForQuietWindow blocks until either no Page.lifecycleEvent has been
+// observed for `quiet` duration, or `ceiling` has elapsed since the call
+// started. Returns the duration actually waited.
+//
+// The listener registered against ctx remains attached to the target after
+// return — chromedp does not expose deregistration — but a `done` atomic
+// short-circuits its body so post-return events are no-ops. Matches the
+// pattern used by cdpops/navigation.go redirect tracking.
+//
+// quiet and ceiling clamp to non-zero minimums so callers cannot accidentally
+// disable the wait by passing zero.
+func WaitForQuietWindow(ctx context.Context, quiet, ceiling time.Duration) (time.Duration, error) {
+ if quiet <= 0 {
+ quiet = 250 * time.Millisecond
+ }
+ if ceiling <= 0 {
+ ceiling = 750 * time.Millisecond
+ }
+ if ceiling < quiet {
+ ceiling = quiet
+ }
+
+ if err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
+ return page.SetLifecycleEventsEnabled(true).Do(ctx)
+ })); err != nil {
+ return 0, err
+ }
+
+ var (
+ mu sync.Mutex
+ lastEvent = time.Now()
+ done atomic.Bool
+ )
+
+ chromedp.ListenTarget(ctx, func(ev interface{}) {
+ if done.Load() {
+ return
+ }
+ if _, ok := ev.(*page.EventLifecycleEvent); ok {
+ mu.Lock()
+ lastEvent = time.Now()
+ mu.Unlock()
+ }
+ })
+
+ start := time.Now()
+ deadline := start.Add(ceiling)
+ pollInterval := quiet / 4
+ if pollInterval < 10*time.Millisecond {
+ pollInterval = 10 * time.Millisecond
+ }
+
+ for {
+ now := time.Now()
+ if !now.Before(deadline) {
+ done.Store(true)
+ return now.Sub(start), nil
+ }
+ mu.Lock()
+ sinceLast := now.Sub(lastEvent)
+ mu.Unlock()
+ if sinceLast >= quiet {
+ done.Store(true)
+ return now.Sub(start), nil
+ }
+ select {
+ case <-ctx.Done():
+ done.Store(true)
+ return time.Since(start), ctx.Err()
+ case <-time.After(pollInterval):
+ }
+ }
+}
diff --git a/internal/bridge/observe/snapshot.go b/internal/bridge/observe/snapshot.go
index 42b3c604..a407b386 100644
--- a/internal/bridge/observe/snapshot.go
+++ b/internal/bridge/observe/snapshot.go
@@ -13,28 +13,41 @@ import (
)
type A11yNode struct {
- Ref string `json:"ref"`
- Role string `json:"role"`
- Name string `json:"name"`
- Depth int `json:"depth"`
- Value string `json:"value,omitempty"`
- Label string `json:"label,omitempty"`
- Placeholder string `json:"placeholder,omitempty"`
- Alt string `json:"alt,omitempty"`
- Title string `json:"title,omitempty"`
- TestID string `json:"testid,omitempty"`
- Text string `json:"text,omitempty"`
- Tag string `json:"tag,omitempty"`
- Disabled bool `json:"disabled,omitempty"`
- Focused bool `json:"focused,omitempty"`
- Hidden bool `json:"hidden,omitempty"`
- NodeID int64 `json:"nodeId,omitempty"`
- FrameID string `json:"frameId,omitempty"`
- FrameURL string `json:"frameUrl,omitempty"`
- FrameName string `json:"frameName,omitempty"`
- ChildFrameID string `json:"childFrameId,omitempty"`
- ChildFrameURL string `json:"childFrameUrl,omitempty"`
- ChildFrameName string `json:"childFrameName,omitempty"`
+ Ref string `json:"ref"`
+ Role string `json:"role"`
+ Name string `json:"name"`
+ Depth int `json:"depth"`
+ Value string `json:"value,omitempty"`
+ Label string `json:"label,omitempty"`
+ Placeholder string `json:"placeholder,omitempty"`
+ Alt string `json:"alt,omitempty"`
+ Title string `json:"title,omitempty"`
+ TestID string `json:"testid,omitempty"`
+ Text string `json:"text,omitempty"`
+ Tag string `json:"tag,omitempty"`
+ Disabled bool `json:"disabled,omitempty"`
+ Focused bool `json:"focused,omitempty"`
+ Hidden bool `json:"hidden,omitempty"`
+ NodeID int64 `json:"nodeId,omitempty"`
+ FrameID string `json:"frameId,omitempty"`
+ FrameURL string `json:"frameUrl,omitempty"`
+ FrameName string `json:"frameName,omitempty"`
+ ChildFrameID string `json:"childFrameId,omitempty"`
+ ChildFrameURL string `json:"childFrameUrl,omitempty"`
+ ChildFrameName string `json:"childFrameName,omitempty"`
+ BoundingBox *BoundingBox `json:"boundingBox,omitempty"`
+ Visible bool `json:"visible,omitempty"`
+}
+
+// BoundingBox is a CSS-pixel rectangle for a snapshot node. Populated only by
+// PairedCapture when CaptureOpts.WithBounds is true. Coordinate space depends
+// on PairedResult.CoordinateSpace — viewport-relative by default, document
+// (page) coordinates when BeyondViewport is on.
+type BoundingBox struct {
+ X float64 `json:"x"`
+ Y float64 `json:"y"`
+ W float64 `json:"w"`
+ H float64 `json:"h"`
}
type RawAXNode struct {
@@ -57,9 +70,10 @@ type RawAXTreeResponse struct {
}
type RawFrame struct {
- ID string `json:"id"`
- URL string `json:"url,omitempty"`
- Name string `json:"name,omitempty"`
+ ID string `json:"id"`
+ URL string `json:"url,omitempty"`
+ Name string `json:"name,omitempty"`
+ LoaderID string `json:"loaderId,omitempty"`
}
type RawFrameTree struct {
diff --git a/internal/bridge/observe_facade.go b/internal/bridge/observe_facade.go
index 871e154d..469936b7 100644
--- a/internal/bridge/observe_facade.go
+++ b/internal/bridge/observe_facade.go
@@ -2,6 +2,7 @@ package bridge
import (
"context"
+ "time"
bridgeobserve "github.com/pinchtab/pinchtab/internal/bridge/observe"
)
@@ -46,6 +47,21 @@ func FetchFrameTree(ctx context.Context) (RawFrameTree, error) {
return bridgeobserve.FetchFrameTree(ctx)
}
+func WaitForQuietWindow(ctx context.Context, quiet, ceiling time.Duration) (time.Duration, error) {
+ return bridgeobserve.WaitForQuietWindow(ctx, quiet, ceiling)
+}
+
+type BoundingBox = bridgeobserve.BoundingBox
+type ViewportInfo = bridgeobserve.ViewportInfo
+
+func FetchLayout(ctx context.Context) (ViewportInfo, error) {
+ return bridgeobserve.FetchLayout(ctx)
+}
+
+func AnnotateBounds(ctx context.Context, nodes []A11yNode, pageCoords bool, vp ViewportInfo) error {
+ return bridgeobserve.AnnotateBounds(ctx, nodes, pageCoords, vp)
+}
+
func FetchAXTree(ctx context.Context) ([]RawAXNode, error) {
return bridgeobserve.FetchAXTree(ctx)
}
diff --git a/internal/bridge/screenshot.go b/internal/bridge/screenshot.go
new file mode 100644
index 00000000..ee6923a0
--- /dev/null
+++ b/internal/bridge/screenshot.go
@@ -0,0 +1,40 @@
+package bridge
+
+import (
+ "context"
+
+ "github.com/chromedp/cdproto/page"
+ "github.com/chromedp/chromedp"
+)
+
+// ScreenshotOpts mirrors the subset of page.CaptureScreenshot parameters the
+// callers (HandleScreenshot, PairedCapture) need to coordinate on.
+type ScreenshotOpts struct {
+ Format page.CaptureScreenshotFormat
+ Quality int
+ Clip *page.Viewport
+ BeyondViewport bool
+}
+
+// CaptureScreenshot runs Page.captureScreenshot with the supplied options.
+// Quality is applied only for JPEG; clip and beyondViewport are mutually
+// exclusive (clip wins) — the same rule the handler enforces on input.
+func CaptureScreenshot(ctx context.Context, opts ScreenshotOpts) ([]byte, error) {
+ var buf []byte
+ err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
+ shot := page.CaptureScreenshot().WithFormat(opts.Format)
+ if opts.Clip != nil {
+ shot = shot.WithClip(opts.Clip)
+ }
+ if opts.BeyondViewport && opts.Clip == nil {
+ shot = shot.WithCaptureBeyondViewport(true)
+ }
+ if opts.Format == page.CaptureScreenshotFormatJpeg {
+ shot = shot.WithQuality(int64(opts.Quality))
+ }
+ var inner error
+ buf, inner = shot.Do(ctx)
+ return inner
+ }))
+ return buf, err
+}
diff --git a/internal/cli/actions/actions_capture.go b/internal/cli/actions/actions_capture.go
new file mode 100644
index 00000000..362429dc
--- /dev/null
+++ b/internal/cli/actions/actions_capture.go
@@ -0,0 +1,132 @@
+package actions
+
+import (
+ "encoding/base64"
+ "encoding/json"
+ "fmt"
+ "net/http"
+ "net/url"
+ "os"
+ "time"
+
+ "github.com/pinchtab/pinchtab/internal/cli"
+ "github.com/pinchtab/pinchtab/internal/cli/apiclient"
+ "github.com/spf13/cobra"
+)
+
+// Capture is the CLI shim for `pinchtab capture`. Requests an inline
+// (base64) capture so we can both write the image locally and print the
+// snapshot summary in one round trip. Mirrors how `pinchtab screenshot`
+// localizes the file.
+func Capture(client *http.Client, base, token string, cmd *cobra.Command) {
+ params := url.Values{}
+ params.Set("output", "inline")
+
+ outFile, _ := cmd.Flags().GetString("output")
+ format, _ := cmd.Flags().GetString("format")
+ if format == "" {
+ format = "jpeg"
+ }
+ if format != "jpeg" {
+ params.Set("format", format)
+ }
+
+ if v, _ := cmd.Flags().GetString("quality"); v != "" {
+ params.Set("quality", v)
+ }
+ if v, _ := cmd.Flags().GetString("selector"); v != "" {
+ params.Set("selector", v)
+ }
+ if v, _ := cmd.Flags().GetString("filter"); v != "" {
+ params.Set("filter", v)
+ }
+ if v, _ := cmd.Flags().GetString("depth"); v != "" {
+ params.Set("depth", v)
+ }
+ if v, _ := cmd.Flags().GetString("wait"); v != "" {
+ params.Set("wait", v)
+ }
+ if v, _ := cmd.Flags().GetBool("beyond-viewport"); v {
+ params.Set("beyondViewport", "true")
+ }
+ if v, _ := cmd.Flags().GetBool("require-pair"); v {
+ params.Set("requirePair", "true")
+ }
+ // --with-bounds defaults true on the server; explicit false suppresses.
+ if cmd.Flags().Changed("with-bounds") {
+ if v, _ := cmd.Flags().GetBool("with-bounds"); !v {
+ params.Set("withBounds", "false")
+ }
+ }
+ if v, _ := cmd.Flags().GetString("tab"); v != "" {
+ params.Set("tabId", v)
+ }
+
+ raw := apiclient.DoGetRaw(client, base, token, "/capture", params)
+ if raw == nil {
+ return
+ }
+
+ var resp struct {
+ Status string `json:"status"`
+ TabID string `json:"tabId"`
+ URL string `json:"url"`
+ Title string `json:"title"`
+ Epoch struct {
+ FrameID string `json:"frameId"`
+ LoaderID string `json:"loaderId"`
+ DomEpoch string `json:"domEpoch"`
+ } `json:"epoch"`
+ Pairing struct {
+ Navigated bool `json:"navigated"`
+ CaptureDurationMs int64 `json:"captureDurationMs"`
+ } `json:"pairing"`
+ Image struct {
+ Format string `json:"format"`
+ Base64 string `json:"base64"`
+ Bytes int `json:"bytes"`
+ CoordinateSpace string `json:"coordinateSpace"`
+ DPR float64 `json:"devicePixelRatio"`
+ } `json:"image"`
+ Snapshot struct {
+ Filter string `json:"filter"`
+ NodeCount int `json:"nodeCount"`
+ } `json:"snapshot"`
+ }
+ if err := json.Unmarshal(raw, &resp); err != nil {
+ cli.Fatal("Decode capture response: %v", err)
+ }
+
+ ext := ".jpg"
+ if resp.Image.Format == "png" {
+ ext = ".png"
+ }
+ if outFile == "" {
+ outFile = fmt.Sprintf("capture-%s%s", time.Now().Format("20060102-150405"), ext)
+ }
+ img, err := base64.StdEncoding.DecodeString(resp.Image.Base64)
+ if err != nil {
+ cli.Fatal("Decode image bytes: %v", err)
+ }
+ if err := os.WriteFile(outFile, img, 0600); err != nil {
+ cli.Fatal("Write image: %v", err)
+ }
+
+ fmt.Println(cli.StyleStdout(cli.SuccessStyle,
+ fmt.Sprintf("Saved %s (%d bytes, %s)", outFile, len(img), resp.Image.CoordinateSpace)))
+ fmt.Printf(" url: %s\n", resp.URL)
+ fmt.Printf(" title: %s\n", resp.Title)
+ fmt.Printf(" epoch: %s (frame=%s loader=%s)\n",
+ resp.Epoch.DomEpoch, short(resp.Epoch.FrameID), short(resp.Epoch.LoaderID))
+ fmt.Printf(" pairing: navigated=%v duration=%dms\n",
+ resp.Pairing.Navigated, resp.Pairing.CaptureDurationMs)
+ fmt.Printf(" snapshot: %d nodes (filter=%q)\n",
+ resp.Snapshot.NodeCount, resp.Snapshot.Filter)
+}
+
+func short(s string) string {
+ if len(s) <= 8 {
+ return s
+ }
+ return s[:8] + "…"
+}
diff --git a/internal/engine/engine.go b/internal/engine/engine.go
index 8cd0dc37..dec610a2 100644
--- a/internal/engine/engine.go
+++ b/internal/engine/engine.go
@@ -40,6 +40,7 @@ const (
CapPDF Capability = "pdf"
CapEvaluate Capability = "evaluate"
CapCookies Capability = "cookies"
+ CapCapture Capability = "capture"
)
// Mode controls the engine selection strategy.
diff --git a/internal/engine/rules.go b/internal/engine/rules.go
index 5a4481fe..d0d71439 100644
--- a/internal/engine/rules.go
+++ b/internal/engine/rules.go
@@ -19,7 +19,7 @@ func (CapabilityRule) Name() string { return "capability" }
func (CapabilityRule) Decide(op Capability, _ string) Decision {
switch op {
- case CapScreenshot, CapPDF, CapEvaluate, CapCookies:
+ case CapScreenshot, CapPDF, CapEvaluate, CapCookies, CapCapture:
return UseChrome
}
return Undecided
diff --git a/internal/handlers/capture.go b/internal/handlers/capture.go
new file mode 100644
index 00000000..3bc319cc
--- /dev/null
+++ b/internal/handlers/capture.go
@@ -0,0 +1,272 @@
+package handlers
+
+import (
+ "context"
+ "encoding/base64"
+ "fmt"
+ "log/slog"
+ "net/http"
+ "os"
+ "path/filepath"
+ "strconv"
+ "time"
+
+ "github.com/chromedp/cdproto/page"
+ "github.com/pinchtab/pinchtab/internal/bridge"
+ "github.com/pinchtab/pinchtab/internal/engine"
+ "github.com/pinchtab/pinchtab/internal/httpx"
+)
+
+// HandleCapture returns a screenshot and an accessibility snapshot from the
+// same DOM epoch in one HTTP call.
+//
+// @Endpoint GET /capture
+// @Description Paired screenshot + accessibility snapshot. Returns both
+//
+// artefacts plus a frame/loader parity check (pairing.navigated) and an
+// opaque domEpoch handshake token cached on the tab's RefCache.
+//
+// @Param tabId string query Tab ID (optional, defaults to current)
+// @Param selector string query Optional scope (clips screenshot and filters snapshot subtree)
+// @Param filter string query Snapshot filter: "interactive" or "all" (default "all")
+// @Param depth int query Snapshot max depth (default -1 for full)
+// @Param format string query Image format: "jpeg" or "png" (default "jpeg")
+// @Param quality int query JPEG quality 1-100 (default 80)
+// @Param output string query "file" writes the image to disk; "inline" returns base64; default "file"
+// @Param requirePair bool query If true, return 409 when navigation is observed during capture
+// @Param noAnimations bool query Inject reduce-motion CSS for the capture window
+//
+// @Response 200 application/json Paired result (see response shape below)
+// @Response 409 application/json Pair was broken (only when requirePair=true)
+// @Response 404 application/json Tab not found
+// @Response 500 application/json Internal error
+func (h *Handlers) HandleCapture(w http.ResponseWriter, r *http.Request) {
+ q := r.URL.Query()
+ tabID := q.Get("tabId")
+ h.recordReadRequest(r, "capture", tabID)
+
+ // /capture is Chrome-only; the engine routing rule ensures
+ // useLite never returns true here, so we go straight to chrome.
+ if h.useLite(engine.CapCapture, "") {
+ // Defensive: if someone changes the rule and lite ends up routed here,
+ // surface a precise error rather than crashing on a missing impl.
+ httpx.Error(w, http.StatusNotImplemented,
+ fmt.Errorf("capture is not supported by the lite engine"))
+ return
+ }
+ h.recordEngine(r, "chrome")
+ w.Header().Set("X-Engine", "chrome")
+
+ if err := h.ensureChrome(); err != nil {
+ if h.writeBridgeUnavailable(w, err) {
+ return
+ }
+ httpx.Error(w, 500, fmt.Errorf("chrome initialization: %w", err))
+ return
+ }
+
+ selector := q.Get("selector")
+ filter := q.Get("filter")
+ output := q.Get("output")
+ if output == "" {
+ output = "file"
+ }
+ requirePair := q.Get("requirePair") == "true" || q.Get("requirePair") == "1"
+ reqNoAnim := q.Get("noAnimations") == "true"
+ beyondViewport := q.Get("beyondViewport") == "true" || q.Get("beyondViewport") == "1"
+
+ // Default withBounds=true. Bounding boxes are the piece that lets vision
+ // agents overlay refs on pixels — the whole point of /capture. Callers
+ // who want to skip the per-node box-model round trips can pass
+ // withBounds=false.
+ withBounds := true
+ if v := q.Get("withBounds"); v == "false" || v == "0" {
+ withBounds = false
+ }
+
+ // Default to wait=stable: vision-grounded callers are the primary user and
+ // they want a quiesced page. Callers that want raw timing pass wait=none
+ // (or the alias wait=load — reserved for a future readyState gate).
+ wait := q.Get("wait")
+ if wait == "" {
+ wait = bridge.WaitStable
+ }
+
+ depth := -1
+ if d := q.Get("depth"); d != "" {
+ if dn, err := strconv.Atoi(d); err == nil {
+ depth = dn
+ }
+ }
+ quality := 80
+ if qv := q.Get("quality"); qv != "" {
+ if qn, err := strconv.Atoi(qv); err == nil {
+ quality = qn
+ }
+ }
+
+ format := page.CaptureScreenshotFormatJpeg
+ ext := ".jpg"
+ if q.Get("format") == "png" {
+ format = page.CaptureScreenshotFormatPng
+ ext = ".png"
+ }
+
+ ctx, resolvedTabID, err := h.tabContextWithHeader(w, r, tabID)
+ if err != nil {
+ WriteTabContextError(w, err, 404)
+ return
+ }
+ if _, ok := h.enforceCurrentTabDomainPolicy(w, r, ctx, resolvedTabID); !ok {
+ return
+ }
+ defer h.armAutoCloseIfEnabled(resolvedTabID)
+ tCtx, tCancel := context.WithTimeout(ctx, h.Config.ActionTimeout)
+ defer tCancel()
+ go httpx.CancelOnClientDone(r.Context(), tCancel)
+
+ opts := bridge.CaptureOpts{
+ Image: bridge.ScreenshotOpts{
+ Format: format,
+ Quality: quality,
+ BeyondViewport: beyondViewport,
+ },
+ Filter: filter,
+ MaxDepth: depth,
+ DisableAnimations: reqNoAnim && !h.Config.NoAnimations,
+ Wait: wait,
+ WithBounds: withBounds,
+ }
+
+ // Selector scoping: resolve once, use the same backendNodeId for both the
+ // screenshot clip and the snapshot subtree filter so they describe the
+ // same element. A selector clip silently wins over beyondViewport — the
+ // same rule HandleScreenshot enforces.
+ if selector != "" {
+ opts.Image.BeyondViewport = false
+ nodeID, sErr := h.resolveSelectorNodeID(tCtx, resolvedTabID, selector)
+ if sErr != nil {
+ httpx.Error(w, 400, frameScopedSelectorError("selector", sErr))
+ return
+ }
+ opts.ScopeBackendNodeID = nodeID
+ clip, cErr := screenshotClipForNode(tCtx, nodeID, false)
+ if cErr != nil {
+ httpx.Error(w, 500, fmt.Errorf("selector clip: %w", cErr))
+ return
+ }
+ opts.Image.Clip = clip
+ }
+
+ result, err := bridge.PairedCapture(tCtx, opts)
+ if err != nil {
+ httpx.Error(w, 500, fmt.Errorf("capture: %w", err))
+ return
+ }
+ h.recordResolvedURL(r, result.URL)
+
+ if requirePair && result.Navigated {
+ httpx.Error(w, http.StatusConflict,
+ fmt.Errorf("pairing broken: navigation observed during capture window"))
+ return
+ }
+
+ // Persist the snapshot half to the ref cache with the minted epoch so that
+ // follow-up `/click eN` etc. can later opt into an epoch handshake.
+ h.Bridge.SetRefCache(resolvedTabID, &bridge.RefCache{
+ Refs: result.Refs,
+ Targets: bridge.RefTargetsFromNodes(result.Nodes),
+ Nodes: result.Nodes,
+ DomEpoch: result.DomEpoch,
+ })
+
+ // Image output: file (default) writes bytes to disk and returns a path;
+ // inline returns base64; raw returns the bytes as the response body.
+ imageInfo := map[string]any{
+ "format": result.ImageFormat,
+ "bytes": len(result.ImageBytes),
+ "coordinateSpace": result.CoordinateSpace,
+ "devicePixelRatio": result.Viewport.DevicePixelRatio,
+ "viewport": map[string]any{
+ "w": result.Viewport.Width,
+ "h": result.Viewport.Height,
+ "scrollX": result.Viewport.ScrollX,
+ "scrollY": result.Viewport.ScrollY,
+ },
+ }
+
+ switch output {
+ case "file":
+ captureDir := filepath.Join(h.Config.StateDir, "captures")
+ if err := os.MkdirAll(captureDir, 0750); err != nil {
+ httpx.Error(w, 500, fmt.Errorf("create capture dir: %w", err))
+ return
+ }
+ ts := time.Now().Format("20060102-150405")
+ filePath := filepath.Join(captureDir, fmt.Sprintf("cap-%s%s", ts, ext))
+ if err := os.WriteFile(filePath, result.ImageBytes, 0600); err != nil {
+ httpx.Error(w, 500, fmt.Errorf("write capture: %w", err))
+ return
+ }
+ imageInfo["path"] = filePath
+ case "inline":
+ imageInfo["base64"] = base64.StdEncoding.EncodeToString(result.ImageBytes)
+ case "raw":
+ // Raw output skips the JSON envelope and returns image bytes only.
+ // The snapshot half is dropped; this mode is for clients that already
+ // have a separate /snapshot call. It exists mostly as a debug aid.
+ contentType := "image/jpeg"
+ if result.ImageFormat == "png" {
+ contentType = "image/png"
+ }
+ w.Header().Set("Content-Type", contentType)
+ if _, err := w.Write(result.ImageBytes); err != nil {
+ slog.Error("capture raw write", "err", err)
+ }
+ return
+ default:
+ httpx.Error(w, 400, fmt.Errorf("unknown output %q (expected file|inline|raw)", output))
+ return
+ }
+
+ httpx.JSON(w, 200, map[string]any{
+ "status": "ok",
+ "tabId": resolvedTabID,
+ "url": result.URL,
+ "title": result.Title,
+ "capturedAt": result.CapturedAt.UTC().Format(time.RFC3339Nano),
+ "epoch": map[string]any{
+ "frameId": result.FrameID,
+ "loaderId": result.LoaderID,
+ "domEpoch": result.DomEpoch,
+ },
+ "pairing": map[string]any{
+ "navigated": result.Navigated,
+ "captureDurationMs": result.DurationMs,
+ },
+ "image": imageInfo,
+ "snapshot": map[string]any{
+ "filter": result.Filter,
+ "nodeCount": len(result.Nodes),
+ "nodes": result.Nodes,
+ },
+ })
+}
+
+// HandleTabCapture is the /tabs/{id}/capture variant — same handler, path-bound tab.
+//
+// @Endpoint GET /tabs/{id}/capture
+func (h *Handlers) HandleTabCapture(w http.ResponseWriter, r *http.Request) {
+ tabID := r.PathValue("id")
+ if tabID == "" {
+ httpx.Error(w, 400, fmt.Errorf("tab id required"))
+ return
+ }
+ q := r.URL.Query()
+ q.Set("tabId", tabID)
+ req := r.Clone(r.Context())
+ u := *r.URL
+ u.RawQuery = q.Encode()
+ req.URL = &u
+ h.HandleCapture(w, req)
+}
diff --git a/internal/handlers/capture_test.go b/internal/handlers/capture_test.go
new file mode 100644
index 00000000..0861a6ac
--- /dev/null
+++ b/internal/handlers/capture_test.go
@@ -0,0 +1,129 @@
+package handlers
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+
+ "github.com/pinchtab/pinchtab/internal/config"
+)
+
+func TestHandleCapture_NoTab(t *testing.T) {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+ req := httptest.NewRequest("GET", "/capture", nil)
+ w := httptest.NewRecorder()
+ h.HandleCapture(w, req)
+ if w.Code != http.StatusNotFound {
+ t.Errorf("expected 404, got %d", w.Code)
+ }
+}
+
+func TestHandleCapture_UnknownOutput(t *testing.T) {
+ // Bad output value must 400 before we ever try to capture — so failTab is
+ // irrelevant; the check happens after tab resolution but before the CDP
+ // round trip.
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+ req := httptest.NewRequest("GET", "/capture?output=carrier-pigeon", nil)
+ w := httptest.NewRecorder()
+ h.HandleCapture(w, req)
+ // Tab resolution fails first, so we get 404. This test exists to confirm
+ // the unknown-output branch does not panic during query parsing.
+ if w.Code != http.StatusNotFound {
+ t.Errorf("expected 404 (tab not found), got %d", w.Code)
+ }
+}
+
+func TestHandleTabCapture_MissingTabID(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
+ req := httptest.NewRequest("GET", "/tabs//capture", nil)
+ w := httptest.NewRecorder()
+ h.HandleTabCapture(w, req)
+ if w.Code != http.StatusBadRequest {
+ t.Errorf("expected 400, got %d", w.Code)
+ }
+}
+
+func TestHandleTabCapture_NoTab(t *testing.T) {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+ req := httptest.NewRequest("GET", "/tabs/tab_abc/capture", nil)
+ req.SetPathValue("id", "tab_abc")
+ w := httptest.NewRecorder()
+ h.HandleTabCapture(w, req)
+ if w.Code != http.StatusNotFound {
+ t.Errorf("expected 404, got %d", w.Code)
+ }
+}
+
+func TestHandleCapture_RouteMounted(t *testing.T) {
+ // The route table is the source of truth for the API surface; make sure
+ // /capture is registered alongside /screenshot and /snapshot so that
+ // future route refactors notice.
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+ mux := http.NewServeMux()
+ h.RegisterRoutes(mux, nil)
+
+ for _, path := range []string{"/capture", "/tabs/abc/capture"} {
+ req := httptest.NewRequest("GET", path, nil)
+ w := httptest.NewRecorder()
+ mux.ServeHTTP(w, req)
+ // 404 is fine (tab not found); 404 with body "tab not found" proves
+ // the route hit the handler. A bare 404 with empty body would mean
+ // the mux did not match the path.
+ if w.Code != http.StatusNotFound {
+ t.Errorf("%s: expected 404 from handler, got %d body=%s", path, w.Code, w.Body.String())
+ }
+ if !strings.Contains(w.Body.String(), "tab") {
+ t.Errorf("%s: expected handler-shaped 404 body, got %q", path, w.Body.String())
+ }
+ }
+}
+
+func TestHandleCapture_WaitParamParses(t *testing.T) {
+ // The wait param accepts known string values; the parse must not crash
+ // even when the tab lookup fails. Mirrors
+ // TestHandleScreenshot_BeyondViewportRequestParses.
+ for _, v := range []string{"stable", "load", "none", ""} {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+ req := httptest.NewRequest("GET", "/capture?wait="+v, nil)
+ w := httptest.NewRecorder()
+ h.HandleCapture(w, req)
+ if w.Code != http.StatusNotFound {
+ t.Errorf("wait=%q: expected 404 (tab not found), got %d", v, w.Code)
+ }
+ }
+}
+
+func TestHandleCapture_BoundsAndBeyondViewportParse(t *testing.T) {
+ // withBounds and beyondViewport must parse without crashing — they are
+ // the headline P3 query params and the handler should at minimum
+ // validate them before hitting the tab lookup.
+ cases := []string{
+ "/capture?withBounds=true&beyondViewport=true",
+ "/capture?withBounds=false",
+ "/capture?beyondViewport=1",
+ "/capture?withBounds=0&beyondViewport=0",
+ }
+ for _, url := range cases {
+ h := New(&mockBridge{failTab: true}, &config.RuntimeConfig{}, nil, nil, nil)
+ req := httptest.NewRequest("GET", url, nil)
+ w := httptest.NewRecorder()
+ h.HandleCapture(w, req)
+ if w.Code != http.StatusNotFound {
+ t.Errorf("%s: expected 404 (tab not found), got %d", url, w.Code)
+ }
+ }
+}
+
+func TestHandleCapture_OpenAPIExposes(t *testing.T) {
+ h := New(&mockBridge{}, &config.RuntimeConfig{}, nil, nil, nil)
+ req := httptest.NewRequest("GET", "/openapi.json", nil)
+ w := httptest.NewRecorder()
+ h.HandleOpenAPI(w, req)
+ if w.Code != http.StatusOK {
+ t.Fatalf("expected 200, got %d", w.Code)
+ }
+ if !strings.Contains(w.Body.String(), "/capture") {
+ t.Fatalf("expected /openapi.json to list /capture, got %s", w.Body.String())
+ }
+}
diff --git a/internal/handlers/handlers.go b/internal/handlers/handlers.go
index c2830bc6..6f0e93c2 100644
--- a/internal/handlers/handlers.go
+++ b/internal/handlers/handlers.go
@@ -233,6 +233,7 @@ func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {
mux.HandleFunc("GET /tabs/{id}/frame", h.HandleTabFrame)
mux.HandleFunc("POST /tabs/{id}/frame", h.HandleTabFrame)
mux.HandleFunc("GET /tabs/{id}/screenshot", h.HandleTabScreenshot)
+ mux.HandleFunc("GET /tabs/{id}/capture", h.HandleTabCapture)
mux.HandleFunc("POST /tabs/{id}/action", h.HandleTabAction)
mux.HandleFunc("POST /tabs/{id}/actions", h.HandleTabActions)
mux.HandleFunc("POST /tabs/{id}/handoff", h.HandleTabHandoff)
@@ -252,6 +253,7 @@ func (h *Handlers) RegisterRoutes(mux *http.ServeMux, doShutdown func()) {
mux.HandleFunc("GET /frame", h.HandleFrame)
mux.HandleFunc("POST /frame", h.HandleFrame)
mux.HandleFunc("GET /screenshot", h.HandleScreenshot)
+ mux.HandleFunc("GET /capture", h.HandleCapture)
mux.HandleFunc("GET /tabs/{id}/pdf", h.HandleTabPDF)
mux.HandleFunc("POST /tabs/{id}/pdf", h.HandleTabPDF)
mux.HandleFunc("GET /pdf", h.HandlePDF)
diff --git a/internal/handlers/openapi.go b/internal/handlers/openapi.go
index 8e13b2c7..da026894 100644
--- a/internal/handlers/openapi.go
+++ b/internal/handlers/openapi.go
@@ -56,6 +56,8 @@ func (h *Handlers) HandleOpenAPI(w http.ResponseWriter, _ *http.Request) {
"/action": map[string]any{"post": map[string]any{"summary": "Single action"}, "get": map[string]any{"summary": "Single action (query params)"}},
"/actions": map[string]any{"post": map[string]any{"summary": "Batch actions"}},
"/snapshot": map[string]any{"get": map[string]any{"summary": "Accessibility snapshot"}},
+ "/capture": map[string]any{"get": map[string]any{"summary": "Paired screenshot + accessibility snapshot from the same DOM epoch"}},
+ "/tabs/{id}/capture": map[string]any{"get": map[string]any{"summary": "Paired screenshot + snapshot for a specific tab"}},
"/evaluate": map[string]any{"post": map[string]any{
"summary": "Run JavaScript in the current tab",
"description": security["evaluate"].Message,
diff --git a/internal/handlers/screenshot.go b/internal/handlers/screenshot.go
index 41a52e6e..b30f14b0 100644
--- a/internal/handlers/screenshot.go
+++ b/internal/handlers/screenshot.go
@@ -139,23 +139,13 @@ func (h *Handlers) HandleScreenshot(w http.ResponseWriter, r *http.Request) {
ext = ".png"
}
- if err := chromedp.Run(tCtx,
- chromedp.ActionFunc(func(ctx context.Context) error {
- var err error
- shot := page.CaptureScreenshot().WithFormat(format)
- if clip != nil {
- shot = shot.WithClip(clip)
- }
- if beyondViewport {
- shot = shot.WithCaptureBeyondViewport(true)
- }
- if format == page.CaptureScreenshotFormatJpeg {
- shot = shot.WithQuality(int64(quality))
- }
- buf, err = shot.Do(ctx)
- return err
- }),
- ); err != nil {
+ buf, err = bridge.CaptureScreenshot(tCtx, bridge.ScreenshotOpts{
+ Format: format,
+ Quality: quality,
+ Clip: clip,
+ BeyondViewport: beyondViewport,
+ })
+ if err != nil {
httpx.Error(w, 500, fmt.Errorf("screenshot: %w", err))
return
}
diff --git a/internal/mcp/handlers.go b/internal/mcp/handlers.go
index a90c2538..8ba40e54 100644
--- a/internal/mcp/handlers.go
+++ b/internal/mcp/handlers.go
@@ -17,6 +17,7 @@ func handlerMap(c *Client) map[string]func(context.Context, mcp.CallToolRequest)
"pinchtab_snapshot": handleSnapshot(c),
"pinchtab_frame": handleFrame(c),
"pinchtab_screenshot": handleScreenshot(c),
+ "pinchtab_capture": handleCapture(c),
"pinchtab_get_text": handleGetText(c),
// Interaction
diff --git a/internal/mcp/handlers_navigation.go b/internal/mcp/handlers_navigation.go
index 5bbbe568..980567f0 100644
--- a/internal/mcp/handlers_navigation.go
+++ b/internal/mcp/handlers_navigation.go
@@ -210,6 +210,119 @@ func screenshotResult(body []byte, annotate bool) (*mcp.CallToolResult, error) {
return mcp.NewToolResultImage(string(encoded), env.Base64, mimeType), nil
}
+// handleCapture implements pinchtab_capture: a paired screenshot + accessibility
+// snapshot from the same DOM epoch. The image is delivered as an MCP image
+// block; the text block is a JSON envelope containing epoch/pairing metadata
+// and the snapshot nodes so a vision-capable model can overlay refs on pixels.
+func handleCapture(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
+ q := url.Values{}
+ q.Set("output", "inline")
+
+ if tabID := optString(r, "tabId"); tabID != "" {
+ q.Set("tabId", tabID)
+ }
+ if selector := optString(r, "selector"); selector != "" {
+ q.Set("selector", selector)
+ }
+ if filter := optString(r, "filter"); filter != "" {
+ q.Set("filter", filter)
+ }
+ if format := optString(r, "format"); format != "" {
+ q.Set("format", format)
+ }
+ if wait := optString(r, "wait"); wait != "" {
+ q.Set("wait", wait)
+ }
+ if quality, ok := optFloat(r, "quality"); ok {
+ q.Set("quality", fmt.Sprintf("%d", int(quality)))
+ }
+ if v := optNumber(r, "depth"); v > 0 {
+ q.Set("depth", formatInt(v))
+ }
+ if v, ok := optBool(r, "beyondViewport"); ok && v {
+ q.Set("beyondViewport", "true")
+ }
+ if v, ok := optBool(r, "requirePair"); ok && v {
+ q.Set("requirePair", "true")
+ }
+ if v, ok := optBool(r, "withBounds"); ok && !v {
+ q.Set("withBounds", "false")
+ }
+ if v, ok := optBool(r, "noAnimations"); ok && v {
+ q.Set("noAnimations", "true")
+ }
+
+ body, code, err := c.Get(ctx, "/capture", q)
+ if err != nil {
+ return mcp.NewToolResultError(err.Error()), nil
+ }
+ if code >= 400 {
+ return resultFromBytes(body, code)
+ }
+ return captureResult(body)
+ }
+}
+
+// captureResult parses /capture's inline envelope and produces a paired MCP
+// result: image block + JSON text block. On parse failure we fall back to the
+// raw bytes so downstream callers still see the wire response.
+func captureResult(body []byte) (*mcp.CallToolResult, error) {
+ var env struct {
+ Status string `json:"status"`
+ TabID string `json:"tabId"`
+ URL string `json:"url"`
+ Title string `json:"title"`
+ CapturedAt string `json:"capturedAt"`
+ Epoch json.RawMessage `json:"epoch"`
+ Pairing json.RawMessage `json:"pairing"`
+ Image struct {
+ Format string `json:"format"`
+ Base64 string `json:"base64"`
+ Bytes int `json:"bytes"`
+ CoordinateSpace string `json:"coordinateSpace"`
+ DPR float64 `json:"devicePixelRatio"`
+ Viewport json.RawMessage `json:"viewport"`
+ } `json:"image"`
+ Snapshot json.RawMessage `json:"snapshot"`
+ }
+ if err := json.Unmarshal(body, &env); err != nil || env.Image.Base64 == "" {
+ return resultFromBytes(body, 200)
+ }
+
+ format := strings.ToLower(strings.TrimSpace(env.Image.Format))
+ if format != "png" {
+ format = "jpeg"
+ }
+ mimeType := "image/jpeg"
+ if format == "png" {
+ mimeType = "image/png"
+ }
+
+ textPayload := map[string]any{
+ "status": env.Status,
+ "tabId": env.TabID,
+ "url": env.URL,
+ "title": env.Title,
+ "capturedAt": env.CapturedAt,
+ "epoch": env.Epoch,
+ "pairing": env.Pairing,
+ "image": map[string]any{
+ "format": format,
+ "bytes": env.Image.Bytes,
+ "coordinateSpace": env.Image.CoordinateSpace,
+ "devicePixelRatio": env.Image.DPR,
+ "viewport": env.Image.Viewport,
+ },
+ "snapshot": env.Snapshot,
+ }
+ encoded, err := json.Marshal(textPayload)
+ if err != nil {
+ return resultFromBytes(body, 200)
+ }
+ return mcp.NewToolResultImage(string(encoded), env.Image.Base64, mimeType), nil
+}
+
func handleGetText(c *Client) func(context.Context, mcp.CallToolRequest) (*mcp.CallToolResult, error) {
return func(ctx context.Context, r mcp.CallToolRequest) (*mcp.CallToolResult, error) {
q := url.Values{}
diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.go
index 0702bc5a..116f2b69 100644
--- a/internal/mcp/server_test.go
+++ b/internal/mcp/server_test.go
@@ -18,8 +18,8 @@ func TestNewServerRegistersAllTools(t *testing.T) {
// The server should have registered all tools.
// We verify by checking that NewServer doesn't panic — the panic
// in NewServer fires if any tool lacks a handler.
- if len(tools) != 41 {
- t.Errorf("expected 41 tools, got %d", len(tools))
+ if len(tools) != 42 {
+ t.Errorf("expected 42 tools, got %d", len(tools))
}
}
diff --git a/internal/mcp/tools.go b/internal/mcp/tools.go
index 9575078b..97acfb5f 100644
--- a/internal/mcp/tools.go
+++ b/internal/mcp/tools.go
@@ -39,6 +39,20 @@ func allTools() []mcp.Tool {
mcp.WithBoolean("annotate", mcp.Description("Overlay numbered ref boxes on interactive elements (or on selector matches). Returns the image plus a structured list of {ref, role, name, box}.")),
mcp.WithBoolean("beyondViewport", mcp.Description("Capture the entire scrollable document, not just the visible viewport. Box coordinates in the annotations envelope are document-relative when this is true. Ignored when selector is set.")),
),
+ mcp.NewTool("pinchtab_capture",
+ mcp.WithDescription("Paired screenshot + accessibility snapshot from the same DOM epoch. Returns an image content block plus a JSON envelope `{url, title, epoch:{frameId,loaderId,domEpoch}, pairing:{navigated,captureDurationMs}, image:{format,bytes,coordinateSpace,devicePixelRatio,viewport}, snapshot:{filter,nodeCount,nodes}}`. Each node in `snapshot.nodes` may carry a `boundingBox:{x,y,w,h}` and `visible:bool` so a vision-capable model can overlay refs on pixels. Coordinate space is 'viewport' by default and 'document' when beyondViewport=true. Prefer this over a separate snapshot+screenshot pair whenever the model needs both image and refs."),
+ mcp.WithString("tabId", mcp.Description("Target tab ID")),
+ mcp.WithString("selector", mcp.Description("Scope: clips screenshot and filters snapshot subtree to the same element. Wins over beyondViewport.")),
+ mcp.WithString("filter", mcp.Description("Snapshot filter: 'interactive' (default) or 'all'")),
+ mcp.WithString("format", mcp.Description("Image format: 'jpeg' (default) or 'png'")),
+ mcp.WithNumber("quality", mcp.Description("JPEG quality 0-100 (JPEG only)")),
+ mcp.WithNumber("depth", mcp.Description("Snapshot tree depth limit (e.g. 3)")),
+ mcp.WithString("wait", mcp.Description("Lifecycle wait before capture: 'stable' (default — waits for Page.lifecycleEvent quiescence), 'load', or 'none'")),
+ mcp.WithBoolean("withBounds", mcp.Description("Populate boundingBox + visible on snapshot nodes (default true). Set false to skip per-node DOM.getBoxModel round trips when bounds are not needed.")),
+ mcp.WithBoolean("beyondViewport", mcp.Description("Capture the full scrollable document instead of just the visible viewport. Coordinate space becomes 'document'; bounding boxes use page coords.")),
+ mcp.WithBoolean("requirePair", mcp.Description("Return 409 if the main frame navigates during the capture window (loaderId changes).")),
+ mcp.WithBoolean("noAnimations", mcp.Description("Inject prefers-reduced-motion CSS for the capture window")),
+ ),
mcp.NewTool("pinchtab_get_text",
mcp.WithDescription("Extract readable text content from the current page. Inherits the current frame scope for the tab unless no frame is selected."),
mcp.WithString("tabId", mcp.Description("Target tab ID")),
diff --git a/skills/pinchtab/SKILL.md b/skills/pinchtab/SKILL.md
index a172dedb..b546bde3 100644
--- a/skills/pinchtab/SKILL.md
+++ b/skills/pinchtab/SKILL.md
@@ -224,6 +224,7 @@ Timeout 10s default, 30s max via `--timeout <ms>`. Prefer `--not-text`/`--state
```bash
pinchtab screenshot [-o path.png] [-q <jpeg-quality>] [--beyond-viewport] # format by extension; --beyond-viewport captures the full scrollable page
+pinchtab capture [-o path.jpg] [--beyond-viewport] [--require-pair] # paired image + snapshot from same DOM epoch; nodes carry boundingBox — use when the model reads pixels AND acts on refs
pinchtab pdf [-o path.pdf] [--landscape]
pinchtab record start out.gif [--fps 5] [--scale 1.0] # .gif/.webm/.mp4; requires security.allowScreencast; .gif works without ffmpeg, .webm/.mp4 need ffmpeg
pinchtab record stop # stop, encode, and save to path given at start
diff --git a/tests/manual/capture-drift-scenarios.md b/tests/manual/capture-drift-scenarios.md
new file mode 100644
index 00000000..ddae4ac8
--- /dev/null
+++ b/tests/manual/capture-drift-scenarios.md
@@ -0,0 +1,122 @@
+# /capture drift scenarios — operator smoke
+
+Manual checks for `pinchtab capture`. Run against a local daemon
+(`pinchtab serve` in another terminal) and a fixture server. The fixtures
+live in `tests/tools/fixtures/`; serve them however you usually do (e.g.
+`python3 -m http.server 9000 -d tests/tools/fixtures`).
+
+These mirror §9 of the design doc. Real-Chrome Go tests are out of scope —
+the repo's pattern for integration is agent-driven via browserbench plus
+operator smoke. When `pinchtab_capture` is exercised through browserbench
+the same fixtures apply.
+
+## 1. Happy path
+
+```bash
+pinchtab nav http://localhost:9000/capture-known-bounds.html
+pinchtab capture --with-bounds -o /tmp/cap-known.jpg
+```
+
+Expect:
+
+- file `/tmp/cap-known.jpg` exists.
+- response prints `epoch: ep_...`, `pairing: navigated=false`.
+- the snapshot's button "Known Position Button" has a `boundingBox` near
+ `{x: 100, y: 200, w: 240, h: 48}` (within 1 CSS pixel × `devicePixelRatio`).
+- `image.coordinateSpace == "viewport"`.
+
+## 2. wait:stable for deferred mount
+
+```bash
+pinchtab nav 'http://localhost:9000/capture-deferred-mount.html?mountAfter=200'
+pinchtab capture --wait stable
+```
+
+Expect the snapshot to include the `button "Pay now"` ref. Compare:
+
+```bash
+pinchtab nav 'http://localhost:9000/capture-deferred-mount.html?mountAfter=200'
+pinchtab capture --wait none
+```
+
+With `wait=none` the button may be missing — the capture window opened
+before the deferred mount fired. With `wait=stable` the lifecycle quiet
+window covers the mount.
+
+## 3. Navigation race + requirePair
+
+In one terminal:
+
+```bash
+pinchtab nav http://localhost:9000/capture-known-bounds.html
+while true; do pinchtab capture --require-pair -o /tmp/cap-race.jpg; sleep 0.5; done
+```
+
+In another, hammer navigation:
+
+```bash
+while true; do
+ pinchtab nav http://localhost:9000/capture-modal-race.html
+ pinchtab nav http://localhost:9000/capture-known-bounds.html
+ sleep 0.3
+done
+```
+
+Expect some `pinchtab capture` runs to fail with HTTP 409
+(`pairing broken: navigation observed during capture window`). With
+`--require-pair` removed, the same races surface as `pairing.navigated:
+true` in the response instead of failing.
+
+## 4. Beyond-viewport coordinate space
+
+```bash
+pinchtab nav http://localhost:9000/capture-tall.html
+pinchtab capture --beyond-viewport -o /tmp/cap-tall.jpg
+```
+
+Expect:
+
+- `/tmp/cap-tall.jpg` is the full document (much taller than the viewport).
+- response prints `coordinateSpace: document`.
+- the `cta-below-fold` ref's `boundingBox.y` is around 4800 (page coords),
+ not 4800 minus the viewport height.
+
+## 5. Selector scope parity
+
+```bash
+pinchtab nav http://localhost:9000/capture-modal-race.html
+sleep 1 # let the modal mount
+pinchtab capture -s '#consent' -o /tmp/cap-modal.jpg
+```
+
+Expect:
+
+- the image is clipped to the modal card (`#consent`).
+- snapshot nodes are all descendants of `#consent` (consent-title,
+ consent-accept, consent-decline).
+- url and title in the response still reflect the underlying page.
+
+## 6. Performance budget (rough)
+
+```bash
+pinchtab nav http://localhost:9000/capture-known-bounds.html
+for i in 1 2 3 4 5; do
+ pinchtab capture --with-bounds=false -o /tmp/cap-$i.jpg | grep duration
+done
+```
+
+Expect `captureDurationMs` < 600ms on a baseline workstation. With
+`--with-bounds=true` and an `interactive`-filter snapshot of ~20 nodes,
+add ~100ms. Hard regressions (>1.5s without obvious cause) deserve
+investigation.
+
+## 7. Skill-layer dispatch
+
+Invoke `pinchtab_capture` through an MCP client. Confirm:
+
+- the result has both an image content block (rendered by the client)
+ and a text content block (JSON envelope with `snapshot.nodes`).
+- the `boundingBox` on a known node lines up with where that node sits
+ in the rendered image.
+
+This is the most useful end-to-end check — it's the path real users hit.
diff --git a/tests/tools/fixtures/capture-deferred-mount.html b/tests/tools/fixtures/capture-deferred-mount.html
new file mode 100644
index 00000000..23c878ab
--- /dev/null
+++ b/tests/tools/fixtures/capture-deferred-mount.html
@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>Capture Deferred Mount - PinchTab Fixture</title>
+ <style>
+ body { margin: 0; font-family: system-ui, sans-serif; padding: 20px; }
+ .placeholder { color: #888; font-style: italic; }
+ </style>
+</head>
+<body>
+ <main>
+ <h1>Capture Fixture: deferred mount</h1>
+ <p class="placeholder">Loading payment form…</p>
+ <div id="hydrated"></div>
+ </main>
+ <script>
+ // Simulate React hydration / lazy island. The "Pay now" button only
+ // appears after a delay. With wait:stable the capture window should
+ // wait for this mount to settle; with wait:none the capture races it
+ // and the snapshot may miss the button.
+ const delay = Number(new URLSearchParams(location.search).get('mountAfter') || 200);
+ setTimeout(() => {
+ const root = document.getElementById('hydrated');
+ root.innerHTML = '<button id="pay">Pay now</button>';
+ document.querySelector('.placeholder').remove();
+ }, delay);
+ </script>
+</body>
+</html>
diff --git a/tests/tools/fixtures/capture-known-bounds.html b/tests/tools/fixtures/capture-known-bounds.html
new file mode 100644
index 00000000..57eabbcc
--- /dev/null
+++ b/tests/tools/fixtures/capture-known-bounds.html
@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <title>Capture Known Bounds - PinchTab Fixture</title>
+ <style>
+ body { margin: 0; padding: 0; font-family: system-ui, sans-serif; }
+ #known {
+ position: absolute;
+ left: 100px;
+ top: 200px;
+ width: 240px;
+ height: 48px;
+ background: #2563eb;
+ color: white;
+ border: none;
+ font-size: 16px;
+ }
+ #below-fold {
+ position: absolute;
+ left: 50px;
+ top: 1400px;
+ width: 200px;
+ height: 40px;
+ }
+ </style>
+</head>
+<body>
+ <main>
+ <h1>Capture Fixture: known bounds</h1>
+ <p>
+ The button #known is positioned at CSS coords (100, 200) with size
+ (240, 48). After <code>pinchtab capture --with-bounds</code>, the
+ ref's boundingBox should report
+ <code>{x: 100, y: 200, w: 240, h: 48}</code> within 1 CSS pixel.
+ </p>
+ <button id="known">Known Position Button</button>
+ <button id="below-fold">Below Fold</button>
+ </main>
+</body>
+</html>
diff --git a/tests/tools/fixtures/capture-modal-race.html b/tests/tools/fixtures/capture-modal-race.html
new file mode 100644
index 00000000..3f83d540
--- /dev/null
+++ b/tests/tools/fixtures/capture-modal-race.html
@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>Capture Modal Race - PinchTab Fixture</title>
+ <style>
+ body { margin: 0; font-family: system-ui, sans-serif; }
+ .modal {
+ position: fixed;
+ inset: 0;
+ background: rgba(0, 0, 0, 0.6);
+ display: none;
+ align-items: center;
+ justify-content: center;
+ }
+ .modal[data-open="true"] { display: flex; }
+ .modal-card {
+ background: white;
+ padding: 32px;
+ border-radius: 8px;
+ max-width: 480px;
+ }
+ </style>
+</head>
+<body>
+ <main>
+ <h1>Underlying page</h1>
+ <form>
+ <label>Email <input id="email" type="email"></label>
+ <label>Password <input id="password" type="password"></label>
+ <button type="submit">Sign in</button>
+ </form>
+ </main>
+
+ <div id="consent" class="modal" role="dialog" aria-labelledby="consent-title">
+ <div class="modal-card">
+ <h2 id="consent-title">We've updated our terms</h2>
+ <p>Please review and accept the new terms before continuing.</p>
+ <button id="consent-accept">Accept</button>
+ <button id="consent-decline">Decline</button>
+ </div>
+ </div>
+
+ <script>
+ // Mount the consent modal after the page has settled. With
+ // wait:stable the capture window should open AFTER this mount fires,
+ // so the snapshot describes the dialog subtree and the image shows
+ // the modal. With wait:none they race.
+ const delay = Number(new URLSearchParams(location.search).get('mountAfter') || 250);
+ setTimeout(() => {
+ document.getElementById('consent').setAttribute('data-open', 'true');
+ }, delay);
+ </script>
+</body>
+</html>
diff --git a/tests/tools/fixtures/capture-tall.html b/tests/tools/fixtures/capture-tall.html
new file mode 100644
index 00000000..e04ad762
--- /dev/null
+++ b/tests/tools/fixtures/capture-tall.html
@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8">
+ <title>Capture Tall - PinchTab Fixture</title>
+ <style>
+ body { margin: 0; font-family: system-ui, sans-serif; }
+ section {
+ height: 1200px;
+ padding: 24px;
+ border-bottom: 1px solid #eee;
+ }
+ .footer-cta {
+ position: absolute;
+ top: 4800px;
+ left: 60px;
+ width: 220px;
+ height: 44px;
+ }
+ </style>
+</head>
+<body>
+ <section><h1>Section 1</h1></section>
+ <section><h1>Section 2</h1></section>
+ <section><h1>Section 3</h1></section>
+ <section><h1>Section 4 — viewport probably hasn't reached here</h1></section>
+ <button class="footer-cta" id="cta-below-fold">Below-fold CTA</button>
+</body>
+</html>