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.goindex 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.goindex 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.mdindex e61dda0e..8417b2e7 100644--- a/docs/commands.md+++ b/docs/commands.md@@ -213,6 +213,11 @@ pinchtab screenshot -q <0-100> # JPEG qualitypinchtab screenshot -s <selector> # Capture a specific element by selectorpinchtab screenshot -s <selector> --css-1x # Export selector screenshot at CSS pixel sizepinchtab 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 tripspinchtab pdf # Export the active page as PDFpinchtab pdf -o <path> # Save PDF to a chosen pathpinchtab 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.mdindex 1338f13a..3a363d85 100644--- a/docs/endpoints.md+++ b/docs/endpoints.md@@ -241,6 +241,8 @@ Find body fields:```textGET /screenshotGET /tabs/{id}/screenshot+GET /capture+GET /tabs/{id}/captureGET /pdfPOST /pdfGET /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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.goindex 871e154d..469936b7 100644--- a/internal/bridge/observe_facade.go+++ b/internal/bridge/observe_facade.go@@ -2,6 +2,7 @@ package bridgeimport ("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.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.goindex 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 Undecideddiff --git a/internal/handlers/capture.go b/internal/handlers/capture.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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.goindex 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.goindex 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.goindex 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),// Interactiondiff --git a/internal/mcp/handlers_navigation.go b/internal/mcp/handlers_navigation.goindex 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.goindex 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.goindex 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.mdindex 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```bashpinchtab 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 refspinchtab 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 ffmpegpinchtab record stop # stop, encode, and save to path given at startdiff --git a/tests/manual/capture-drift-scenarios.md b/tests/manual/capture-drift-scenarios.mdnew file mode 100644index 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.htmlnew file mode 100644index 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.htmlnew file mode 100644index 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.htmlnew file mode 100644index 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.htmlnew file mode 100644index 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>