High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
package bridge
import (
"context"
"crypto/rand"
"encoding/base32"
"time"
"github.com/chromedp/cdproto/page"
"github.com/chromedp/chromedp"
"github.com/pinchtab/pinchtab/internal/cdptk"
)
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. "load" polls document.readyState
// until it reaches "complete" (2s ceiling). "stable" waits for
// Page.lifecycleEvent quiescence — 250ms of silence, 750ms ceiling.
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
}
const (
WaitNone = "none"
WaitLoad = "load"
WaitStable = "stable"
)
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, "document" when ImageOpts.BeyondViewport is true,
// and "clip" for selector-clipped captures. Bounding boxes are expressed in
// the named space.
Viewport ViewportInfo
CoordinateSpace string
Clip *page.Viewport
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. opts.Wait == "stable"
// adds a Page.lifecycleEvent quiet-window wait before the window opens.
// opts.WithBounds populates a viewport-, document-, or clip-relative
// BoundingBox per snapshot node via DOM.getBoxModel. Residual risk:
// in-document churn (React re-renders, IntersectionObserver mutations) is not
// detected — wait:stable reduces but does not eliminate it.
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
}
}
// Wait errors are non-fatal — degrade rather than fail the capture.
switch opts.Wait {
case WaitStable:
_, _ = WaitForQuietWindow(ctx, 250*time.Millisecond, 750*time.Millisecond)
case WaitLoad:
_, _ = WaitForReadyState(ctx, 2*time.Second)
}
pre, err := FetchFrameTree(ctx)
if err != nil {
return nil, err
}
res.FrameID = pre.Frame.ID
res.LoaderID = pre.Frame.LoaderID
// Layout metrics: captured BEFORE the screenshot so opts.Image.Scale can
// synthesize a viewport-covering clip when no other clip is set. Also
// populates the response viewport / devicePixelRatio for clients.
if vp, err := FetchLayout(ctx); err == nil {
res.Viewport = vp
opts.Image.ViewportWidth = vp.Width
opts.Image.ViewportHeight = vp.Height
}
// Image first. Order matters only when BeyondViewport is true (P3 concern);
// at viewport scale either order is equivalent.
imgBytes, err := CaptureScreenshot(ctx, captureImageOpts(opts.Image, res.Viewport))
if err != nil {
return nil, err
}
res.ImageBytes = imgBytes
rawNodes, err := FetchAXTree(ctx)
if err != nil {
return nil, err
}
if opts.ScopeFrameID != "" {
rawNodes = FilterAXNodesByFrame(rawNodes, opts.ScopeFrameID)
}
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
_ = chromedp.Run(ctx,
chromedp.Location(&res.URL),
chromedp.Title(&res.Title),
)
pageCoords := opts.Image.BeyondViewport
if opts.Image.Clip != nil {
res.CoordinateSpace = "clip"
clip := *opts.Image.Clip
res.Clip = &clip
pageCoords = true
} else if pageCoords {
res.CoordinateSpace = "document"
} else {
res.CoordinateSpace = "viewport"
}
if opts.WithBounds {
_ = AnnotateBounds(ctx, res.Nodes, pageCoords, res.Viewport)
if opts.Image.Clip != nil {
projectBoundsToClip(res.Nodes, *opts.Image.Clip)
}
}
// 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
}
// captureImageOpts settles which region the capture renders. A caller's own clip and a
// beyond-viewport capture already composite, so they are left exactly as asked; only the
// default — no clip, viewport space — is redirected onto cdptk.ViewportClip, which is
// what makes the returned image match the viewport and devicePixelRatio this response
// reports. The clip is added to the SCREENSHOT options alone: the response metadata is
// derived from what the caller asked for, so a synthesized clip must not turn the
// reported coordinateSpace into "clip".
func captureImageOpts(image ScreenshotOpts, vp ViewportInfo) ScreenshotOpts {
if image.Clip != nil || image.BeyondViewport {
return image
}
if clip := cdptk.ViewportClip(vp.ScrollX, vp.ScrollY, vp.Width, vp.Height); clip != nil {
image.Clip = clip
}
return image
}
func imageFormatString(f page.CaptureScreenshotFormat) string {
return string(f)
}
func projectBoundsToClip(nodes []A11yNode, clip page.Viewport) {
for i := range nodes {
if nodes[i].BoundingBox == nil {
continue
}
nodes[i].BoundingBox.X -= clip.X
nodes[i].BoundingBox.Y -= clip.Y
}
}
// FilterAXNodesByFrame keeps only nodes whose FrameID matches frameID; an empty
// frameID returns nodes unchanged. Shared by paired capture and the handler
// snapshot/annotated-screenshot flows so frame-scoped filtering cannot drift.
func FilterAXNodesByFrame(nodes []RawAXNode, frameID string) []RawAXNode {
if frameID == "" {
return nodes
}
filtered := make([]RawAXNode, 0, len(nodes))
for _, n := range nodes {
if n.FrameID == frameID {
filtered = append(filtered, n)
}
}
return filtered
}
// 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[:])
}