Skip to content

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

11.3 KB
Raw Blame
package bridge

import (
	"context"
	"encoding/json"
	"fmt"
	"time"

	"github.com/chromedp/cdproto/cdp"
	"github.com/chromedp/cdproto/emulation"
	"github.com/chromedp/cdproto/page"
	"github.com/chromedp/chromedp"
	"github.com/pinchtab/pinchtab/internal/cdptk"
)

type ScreenshotFormat = page.CaptureScreenshotFormat
type ScreenshotClip = page.Viewport

const (
	ScreenshotFormatJpeg = page.CaptureScreenshotFormatJpeg
	ScreenshotFormatPng  = page.CaptureScreenshotFormatPng
)

// MinScale / MaxScale bound the bitmap rescale factor. Anything outside is
// almost certainly a mistake or a DoS — 50× would ask the renderer for a
// multi-gigapixel image.
const (
	MinScale = 0.05
	MaxScale = 4.0
)

func ClampScale(scale float64) float64 {
	if scale <= 0 {
		return 1
	}
	if scale < MinScale {
		return MinScale
	}
	if scale > MaxScale {
		return MaxScale
	}
	return scale
}

// fetchViewportSize returns window.innerWidth/innerHeight via one
// Runtime.evaluate round trip. Falls back to (0, 0) on any failure so the
// caller can decide whether to bail or skip the rescale.
func fetchViewportSize(ctx context.Context) (float64, float64) {
	const expression = `JSON.stringify([window.innerWidth, window.innerHeight])`
	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 0, 0
	}
	var dims [2]float64
	if err := json.Unmarshal([]byte(result.Result.Value), &dims); err != nil {
		return 0, 0
	}
	return dims[0], dims[1]
}

// fetchDocumentSize returns the scrollable document dimensions in CSS pixels.
// Used when beyond-viewport capture also needs clip.scale; the synthesized clip
// must cover the document, not just the current viewport.
func fetchDocumentSize(ctx context.Context) (float64, float64) {
	w, h, err := cdptk.DocumentSize(ctx)
	if err != nil {
		return 0, 0
	}
	return w, h
}

// 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

	// Scale rescales the rendered output bitmap. 1 (or 0) = native. 0.5
	// halves the image in each axis (quarter of the pixels). Applied via
	// CDP's clip.scale; when no Clip is otherwise set we synthesize one
	// covering the viewport so the parameter takes effect.
	Scale float64

	// ViewportWidth/ViewportHeight are used only when Scale != 1 and Clip is
	// nil — to build a viewport-covering clip. Callers fetch these from
	// observe.FetchLayout (or similar) before invoking CaptureScreenshot.
	ViewportWidth  float64
	ViewportHeight float64

	// DisableActivation suppresses the Page.bringToFront call that wakes a
	// backgrounded tab's compositor before capturing (the inverse of
	// instanceDefaults.captureAllowActivation, default true — so the zero
	// value here is the safe/reliable default even if a caller forgets to
	// set it). When true, capture relies solely on focus emulation and never
	// raises the tab in the operator's browser, accepting that a background
	// tab's capture may then block until the caller's deadline.
	DisableActivation bool
}

func scaledScreenshotClip(opts ScreenshotOpts, viewportWidth, viewportHeight, documentWidth, documentHeight float64) *page.Viewport {
	if opts.Scale <= 0 || opts.Scale == 1 {
		return cdptk.NormalizedViewport(opts.Clip)
	}
	if opts.Clip != nil {
		clip := *cdptk.NormalizedViewport(opts.Clip)
		clip.Scale *= opts.Scale
		return &clip
	}

	width, height := viewportWidth, viewportHeight
	if opts.BeyondViewport {
		width, height = documentWidth, documentHeight
	}
	if width <= 0 || height <= 0 {
		return nil
	}
	return &page.Viewport{
		X: 0, Y: 0,
		Width:  width,
		Height: height,
		Scale:  opts.Scale,
	}
}

// captureScreenshotWithoutActivation wakes a background renderer before
// capturing it. Focus emulation alone does not resume a backgrounded tab's
// compositor — that requires Page.bringToFront — so unless disableActivation
// is set, it always runs as well; focus emulation is layered on top only so
// document.hasFocus()/`:focus` reflect the capture as best-effort. When
// disableActivation is true, the tab is never raised in the operator's
// browser, accepting that its capture may then block until the caller's
// deadline (Chromium never resumes a backgrounded compositor without either
// activation or being brought into view).
func captureScreenshotWithoutActivation(ctx context.Context, shot *page.CaptureScreenshotParams, disableActivation bool) ([]byte, error) {
	executor := cdp.ExecutorFromContext(ctx)
	focusEmulated := emulation.SetFocusEmulationEnabled(true).Do(ctx) == nil
	if focusEmulated {
		defer func() {
			restoreCtx, cancel := context.WithTimeout(context.Background(), time.Second)
			defer cancel()
			restoreCtx = cdp.WithExecutor(restoreCtx, executor)
			_ = emulation.SetFocusEmulationEnabled(false).Do(restoreCtx)
		}()
	}
	if !disableActivation {
		_ = page.BringToFront().Do(ctx)
	}
	return shot.Do(ctx)
}

// 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.
//
// When Scale is non-default (not 0 and not 1), the function ensures a clip is
// passed to CDP — either by reusing the supplied one with Scale multiplied in,
// or by synthesizing a viewport-covering clip from ViewportWidth/Height. CDP's
// top-level capture call has no scale parameter outside of clip, so this is
// the only way to apply a render-time rescale.
func CaptureScreenshot(ctx context.Context, opts ScreenshotOpts) ([]byte, error) {
	// Known issue: two back-to-back /capture?scale=<n!=1> on the same
	// tab without nav between can hang on the second call. Workaround:
	// nav between captures (see e2e cli/capture-basic.sh).
	viewportWidth, viewportHeight := opts.ViewportWidth, opts.ViewportHeight
	documentWidth, documentHeight := 0.0, 0.0
	if opts.Scale > 0 && opts.Scale != 1 && opts.Clip == nil {
		if opts.BeyondViewport {
			documentWidth, documentHeight = fetchDocumentSize(ctx)
		} else if viewportWidth == 0 || viewportHeight == 0 {
			viewportWidth, viewportHeight = fetchViewportSize(ctx)
		}
	}
	clip := scaledScreenshotClip(opts, viewportWidth, viewportHeight, documentWidth, documentHeight)

	fromSurface := cdptk.CaptureFromSurface(opts.BeyondViewport, clip)

	return cdptk.CaptureWithSurfaceFallback(fromSurface, func(fromSurface bool) ([]byte, error) {
		var buf []byte
		err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
			shot := page.CaptureScreenshot().WithFormat(opts.Format).WithFromSurface(fromSurface)
			if clip != nil {
				shot = shot.WithClip(clip)
			}
			if opts.BeyondViewport && clip == nil {
				shot = shot.WithCaptureBeyondViewport(true)
			}
			if opts.Format == page.CaptureScreenshotFormatJpeg {
				shot = shot.WithQuality(int64(opts.Quality))
			}
			var inner error
			buf, inner = captureScreenshotWithoutActivation(ctx, shot, opts.DisableActivation)
			return inner
		}))
		return buf, err
	})
}

// ScreenshotClipForNode returns a page-coordinate clip for a backend node ID.
// Handlers use this bridge-owned helper so CDP details stay out of the handler
// layer.
func ScreenshotClipForNode(ctx context.Context, nodeID int64) (*ScreenshotClip, error) {
	// Bring target element into view before computing clip coordinates.
	if err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
		return chromedp.FromContext(ctx).Target.Execute(ctx, "DOM.scrollIntoViewIfNeeded", map[string]any{
			"backendNodeId": nodeID,
		}, nil)
	})); err != nil {
		return nil, fmt.Errorf("scroll into view: %w", err)
	}

	// Isolated world: boxFn reads getBoundingClientRect, so a main-world handle
	// would let the page steer the clip origin by redefining it.
	objectID, err := IsolatedNodeObjectID(ctx, nodeID)
	if err != nil {
		return nil, fmt.Errorf("resolve node: %w", err)
	}

	// The frame walk starts from the NODE's own view, not the ambient `window`.
	// An isolated-world handle runs in the world it was resolved into, which is
	// not necessarily the node's frame, and a bare `window` there is the wrong
	// frame's — its frameElement chain is empty and every frame offset is lost.
	const boxFn = `function() {
		const view = (this.ownerDocument && this.ownerDocument.defaultView) || window;
		const rect = this.getBoundingClientRect();
		let x = rect.left + (view.scrollX || view.pageXOffset || 0);
		let y = rect.top + (view.scrollY || view.pageYOffset || 0);
		try {
			let current = view;
			while (current && current.parent && current !== current.parent) {
				const frameEl = current.frameElement;
				if (!frameEl) {
					break;
				}
				const parent = current.parent;
				const frameRect = frameEl.getBoundingClientRect();
				x += frameRect.left + (parent.scrollX || parent.pageXOffset || 0);
				y += frameRect.top + (parent.scrollY || parent.pageYOffset || 0);
				current = parent;
			}
		} catch (e) {
			// Cross-origin ancestors can block frame traversal. Keep the deepest
			// reachable page coordinates in that case.
		}
		return { x, y, width: rect.width, height: rect.height };
	}`

	var callResult json.RawMessage
	if err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
		return chromedp.FromContext(ctx).Target.Execute(ctx, "Runtime.callFunctionOn", map[string]any{
			"functionDeclaration": boxFn,
			"objectId":            objectID,
			"returnByValue":       true,
		}, &callResult)
	})); err != nil {
		return nil, fmt.Errorf("read element box: %w", err)
	}

	var boxCall struct {
		Result struct {
			Value struct {
				X      float64 `json:"x"`
				Y      float64 `json:"y"`
				Width  float64 `json:"width"`
				Height float64 `json:"height"`
			} `json:"value"`
		} `json:"result"`
	}
	if err := json.Unmarshal(callResult, &boxCall); err != nil {
		return nil, fmt.Errorf("parse element box: %w", err)
	}

	box := boxCall.Result.Value
	if box.Width <= 0 || box.Height <= 0 {
		return nil, fmt.Errorf("element box is empty (width=%.2f height=%.2f)", box.Width, box.Height)
	}
	return &ScreenshotClip{
		X:      box.X,
		Y:      box.Y,
		Width:  box.Width,
		Height: box.Height,
		Scale:  1,
	}, nil
}

// CaptureScreenshot is the provider-aware entry point used across the BridgeAPI
// (screencast polling, recorder, annotated capture). It delegates to the shared
// package-level CaptureScreenshot engine so every provider gets the same
// rendering path, gated by b.Config.CaptureAllowActivation (default true).
func (b *Bridge) CaptureScreenshot(ctx context.Context, format string, quality int, clip *cdptk.ScreenshotClip) ([]byte, error) {
	cdpFormat := page.CaptureScreenshotFormatJpeg
	if format == "png" {
		cdpFormat = page.CaptureScreenshotFormatPng
	}
	vp := cdptk.ClipViewport(clip)
	disableActivation := b.Config != nil && !b.Config.CaptureAllowActivation
	buf, err := CaptureScreenshot(ctx, ScreenshotOpts{
		Format:            cdpFormat,
		Quality:           quality,
		Clip:              vp,
		DisableActivation: disableActivation,
	})
	if err != nil {
		return nil, fmt.Errorf("screenshot: %w", err)
	}
	return buf, nil
}