Skip to content

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

refactor: single owner for the clip-requires-fromSurface rule (PIN-052)

Luigi Agosti35f632534324
diff --git a/internal/bridge/screenshot.go b/internal/bridge/screenshot.go
index c8b8063d..052f065c 100644
--- a/internal/bridge/screenshot.go
+++ b/internal/bridge/screenshot.go
@@ -136,24 +136,6 @@ func scaledScreenshotClip(opts ScreenshotOpts, viewportWidth, viewportHeight, do
}
}
-// captureFromSurface decides the Page.captureScreenshot fromSurface flag.
-//
-// fromSurface=false reads the renderer's current view directly instead of
-// waiting for a fresh compositor surface frame. On idle pages in headed browsers
-// (e.g. Cloak) the surface stops swapping frames, so the default fromSurface=true
-// blocks until the action deadline (~30s); reading from the view avoids that for
-// plain captures.
-//
-// Anything that changes the captured region needs the page recomposited, which
-// only happens with fromSurface=true: capture-beyond-viewport, a render-time
-// rescale, and the clip itself. Reading the view ignores the clip outright and
-// returns the whole viewport, so every non-nil clip takes the surface path —
-// keeping it off for a native-scale clip is what made a selector capture come
-// back byte-identical to an unclipped one.
-func captureFromSurface(beyondViewport bool, clip *page.Viewport) bool {
- return beyondViewport || clip != nil
-}
-
// 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
@@ -207,7 +189,7 @@ func CaptureScreenshot(ctx context.Context, opts ScreenshotOpts) ([]byte, error)
clip = scaledScreenshotClip(opts, viewportWidth, viewportHeight, documentWidth, documentHeight)
}
- fromSurface := captureFromSurface(opts.BeyondViewport, clip)
+ fromSurface := cdptk.CaptureFromSurface(opts.BeyondViewport, clip)
var buf []byte
err := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {
@@ -324,16 +306,7 @@ func (b *Bridge) CaptureScreenshot(ctx context.Context, format string, quality i
if format == "png" {
cdpFormat = page.CaptureScreenshotFormatPng
}
- var vp *page.Viewport
- if clip != nil {
- vp = &page.Viewport{
- X: clip.X,
- Y: clip.Y,
- Width: clip.Width,
- Height: clip.Height,
- Scale: clip.Scale,
- }
- }
+ vp := cdptk.ClipViewport(clip)
disableActivation := b.Config != nil && !b.Config.CaptureAllowActivation
buf, err := CaptureScreenshot(ctx, ScreenshotOpts{
Format: cdpFormat,
diff --git a/internal/bridge/screenshot_test.go b/internal/bridge/screenshot_test.go
index d2b8e01c..7e46ab94 100644
--- a/internal/bridge/screenshot_test.go
+++ b/internal/bridge/screenshot_test.go
@@ -103,29 +103,6 @@ func TestClampScale(t *testing.T) {
}
}
-func TestCaptureFromSurface(t *testing.T) {
- cases := []struct {
- name string
- beyondViewport bool
- clip *page.Viewport
- want bool
- }{
- {name: "plain viewport capture", want: false},
- {name: "beyond viewport forces surface", beyondViewport: true, want: true},
- {name: "native-scale clip forces surface", clip: &page.Viewport{Scale: 1}, want: true},
- {name: "zero-scale clip forces surface", clip: &page.Viewport{Scale: 0}, want: true},
- {name: "downscaled clip forces surface", clip: &page.Viewport{Scale: 0.25}, want: true},
- {name: "upscaled clip forces surface", clip: &page.Viewport{Scale: 2}, want: true},
- }
- for _, c := range cases {
- t.Run(c.name, func(t *testing.T) {
- if got := captureFromSurface(c.beyondViewport, c.clip); got != c.want {
- t.Fatalf("captureFromSurface(%v, %+v) = %v, want %v", c.beyondViewport, c.clip, got, c.want)
- }
- })
- }
-}
-
func TestProjectBoundsToClip(t *testing.T) {
nodes := []A11yNode{
{
diff --git a/internal/browsers/chrome/instance.go b/internal/browsers/chrome/instance.go
index d4568e5f..422cc857 100644
--- a/internal/browsers/chrome/instance.go
+++ b/internal/browsers/chrome/instance.go
@@ -51,22 +51,11 @@ func (i *Instance) CaptureScreenshot(ctx context.Context, format string, quality
cdpFormat = page.CaptureScreenshotFormatJpeg
}
- shot := page.CaptureScreenshot().WithFormat(cdpFormat).WithFromSurface(captureFromSurface(clip))
- if clip != nil {
- // Scale 0 means native, the contract bridge.ScreenshotOpts states and
- // normalises. CDP does not: it discards a scale-0 clip and returns the
- // whole viewport, which is the defect this path already had once.
- scale := clip.Scale
- if scale == 0 {
- scale = 1
- }
- shot = shot.WithClip(&page.Viewport{
- X: clip.X,
- Y: clip.Y,
- Width: clip.Width,
- Height: clip.Height,
- Scale: scale,
- })
+ const beyondViewport = false
+ vp := cdptk.ClipViewport(clip)
+ shot := page.CaptureScreenshot().WithFormat(cdpFormat).WithFromSurface(cdptk.CaptureFromSurface(beyondViewport, vp))
+ if vp != nil {
+ shot = shot.WithClip(vp)
}
if cdpFormat == page.CaptureScreenshotFormatJpeg && quality > 0 {
shot = shot.WithQuality(int64(quality))
@@ -81,33 +70,6 @@ func (i *Instance) CaptureScreenshot(ctx context.Context, format string, quality
return buf, nil
}
-// captureFromSurface reports whether a capture has to go through the
-// compositor surface. Only a clipped one does.
-//
-// fromSurface=false reads the renderer's current view directly instead of
-// waiting for a fresh compositor surface frame. On idle pages in headed
-// browsers (e.g. Cloak) the surface stops swapping frames, so the default
-// fromSurface=true blocks until the action deadline (~30s) — stalling one-shot
-// screenshots and polling screencast alike.
-//
-// Reading the view also discards the clip and returns the whole viewport
-// whatever region was asked for, so a clipped capture pays the surface path and
-// the BringToFront above is what keeps that affordable. Screencast polls with a
-// nil clip and keeps the fast read.
-//
-// Measured in headless Chrome on a 120x60 clip, so the flag is not a no-op
-// there and a clipped capture is exactly what makes it observable:
-//
-// fromSurface=true clip -> 120x60 fromSurface=false clip -> 756x413
-// fromSurface=true nil -> 756x413 fromSurface=false nil -> 756x413
-//
-// The nil-clip pair matches on dimensions, which is why the unclipped browser
-// test cannot pin this choice; its pixels do differ, but asserting that would
-// couple the test to Chrome's encoder. Hence the predicate test beside it.
-func captureFromSurface(clip *cdptk.ScreenshotClip) bool {
- return clip != nil
-}
-
func (i *Instance) Evaluate(ctx context.Context, expression string, result any, opts browsers.EvalOpts) error {
var chromedpOpts []chromedp.EvaluateOption
if opts.AwaitPromise {
diff --git a/internal/browsers/chrome/instance_from_surface_test.go b/internal/browsers/chrome/instance_from_surface_test.go
deleted file mode 100644
index 733feda6..00000000
--- a/internal/browsers/chrome/instance_from_surface_test.go
+++ /dev/null
@@ -1,34 +0,0 @@
-package chrome
-
-import (
- "testing"
-
- "github.com/pinchtab/pinchtab/internal/cdptk"
-)
-
-// The clipped browser test pins fromSurface=true for a clip; nothing else pins
-// fromSurface=false for a nil one, because both flags return the viewport at the
-// same dimensions and only the pixels differ. So an always-true
-// "simplification" passes every dimension assertion this package has. This is
-// the guard that fails instead — the unclipped screencast poll must keep the
-// direct view read rather than wait on a frame an idle headed page never swaps.
-func TestCaptureFromSurfaceOnlyForClippedCaptures(t *testing.T) {
- tests := []struct {
- name string
- clip *cdptk.ScreenshotClip
- want bool
- }{
- {name: "no clip keeps the fast view read", clip: nil, want: false},
- {name: "clip needs the compositor surface", clip: &cdptk.ScreenshotClip{Width: 120, Height: 60, Scale: 1}, want: true},
- {name: "offset clip needs the compositor surface", clip: &cdptk.ScreenshotClip{X: 40, Y: 60, Width: 120, Height: 60, Scale: 1}, want: true},
- {name: "zero-sized clip is still a clip", clip: &cdptk.ScreenshotClip{}, want: true},
- }
-
- for _, tt := range tests {
- t.Run(tt.name, func(t *testing.T) {
- if got := captureFromSurface(tt.clip); got != tt.want {
- t.Errorf("captureFromSurface(%+v) = %v, want %v", tt.clip, got, tt.want)
- }
- })
- }
-}
diff --git a/internal/cdptk/screenshot.go b/internal/cdptk/screenshot.go
index 43815ba6..1b2b2d92 100644
--- a/internal/cdptk/screenshot.go
+++ b/internal/cdptk/screenshot.go
@@ -5,6 +5,7 @@ import (
"encoding/json"
"fmt"
+ "github.com/chromedp/cdproto/page"
"github.com/chromedp/chromedp"
)
@@ -108,3 +109,59 @@ func ClipForNode(ctx context.Context, nodeID int64, css1x bool) (*ScreenshotClip
Scale: scale,
}, nil
}
+
+// CaptureFromSurface decides the Page.captureScreenshot fromSurface flag. It is the one
+// owner of that rule: it had two implementations that could not import each other, and
+// they had already drifted once — the bridge path was fixed while the RuntimeInstance
+// path kept fromSurface=false and went on applying a clip CDP discarded, so scoped and
+// beyond-viewport captures returned the full viewport with their annotation boxes mapped
+// into the clip's coordinate space.
+//
+// fromSurface=false reads the renderer's current view directly instead of waiting for a
+// fresh compositor surface frame. On idle pages in headed browsers (e.g. Cloak) the
+// surface stops swapping frames, so the default fromSurface=true blocks until the action
+// deadline (~30s) — stalling one-shot screenshots and polling screencast alike. That is
+// why the nil-clip fast path matters and must be preserved.
+//
+// Anything that changes the captured region needs the page recomposited, which only
+// happens with fromSurface=true: capture-beyond-viewport, a render-time rescale, and the
+// clip itself. Reading the view ignores the clip outright and returns the whole viewport,
+// so every non-nil clip takes the surface path — keeping it off for a native-scale clip
+// is what made a selector capture come back byte-identical to an unclipped one.
+//
+// Measured in headless Chrome on a 120x60 clip, so the flag is not a no-op there and a
+// clipped capture is exactly what makes it observable:
+//
+// fromSurface=true clip -> 120x60 fromSurface=false clip -> 756x413
+// fromSurface=true nil -> 756x413 fromSurface=false nil -> 756x413
+//
+// The nil-clip pair matches on dimensions, which is why an unclipped browser test cannot
+// pin this choice; hence the table test beside this function.
+func CaptureFromSurface(beyondViewport bool, clip *page.Viewport) bool {
+ return beyondViewport || clip != nil
+}
+
+// ClipViewport converts a ScreenshotClip into the page.Viewport CDP takes, and is the one
+// place the non-zero-scale rule is applied. A nil clip converts to nil, so callers keep
+// the nil-clip fast path CaptureFromSurface describes.
+//
+// Scale 0 means native — the contract ScreenshotOpts states and normalises. CDP does not:
+// it discards a scale-0 clip and returns the whole viewport, no error, exactly as it
+// discards a clip passed with fromSurface=false. Same symptom, same silence, so the two
+// rules belong to the same conversion rather than to whichever call site remembered.
+func ClipViewport(clip *ScreenshotClip) *page.Viewport {
+ if clip == nil {
+ return nil
+ }
+ scale := clip.Scale
+ if scale == 0 {
+ scale = 1
+ }
+ return &page.Viewport{
+ X: clip.X,
+ Y: clip.Y,
+ Width: clip.Width,
+ Height: clip.Height,
+ Scale: scale,
+ }
+}
diff --git a/internal/cdptk/screenshot_test.go b/internal/cdptk/screenshot_test.go
index f922e50c..c0a5914c 100644
--- a/internal/cdptk/screenshot_test.go
+++ b/internal/cdptk/screenshot_test.go
@@ -3,9 +3,14 @@ package cdptk_test
import (
"context"
"encoding/base64"
+ "io/fs"
+ "os"
+ "path/filepath"
+ "strings"
"testing"
"time"
+ "github.com/chromedp/cdproto/page"
"github.com/chromedp/chromedp"
"github.com/pinchtab/pinchtab/internal/cdptk"
"github.com/pinchtab/pinchtab/internal/testbrowser"
@@ -281,3 +286,114 @@ func TestAnnotationRectForNodeAppliesFrameOffset(t *testing.T) {
t.Errorf("in-frame rect size = %.0fx%.0f, want %dx%d", rect.W, rect.H, wantW, wantH)
}
}
+
+// The fromSurface rule had two implementations in packages that cannot import each other,
+// and they had already drifted once. This is the table that now stands for both.
+func TestCaptureFromSurface(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ beyondViewport bool
+ clip *page.Viewport
+ want bool
+ }{
+ {name: "plain capture keeps the fast read", beyondViewport: false, clip: nil, want: false},
+ {name: "any clip needs the surface", beyondViewport: false, clip: &page.Viewport{Width: 120, Height: 60, Scale: 1}, want: true},
+ {name: "a native-scale clip still needs it", beyondViewport: false, clip: &page.Viewport{Width: 120, Height: 60, Scale: 1}, want: true},
+ {name: "beyond viewport needs it with no clip", beyondViewport: true, clip: nil, want: true},
+ {name: "both", beyondViewport: true, clip: &page.Viewport{Width: 10, Height: 10, Scale: 1}, want: true},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ if got := cdptk.CaptureFromSurface(tc.beyondViewport, tc.clip); got != tc.want {
+ t.Errorf("cdptk.CaptureFromSurface(%v, %+v) = %v, want %v", tc.beyondViewport, tc.clip, got, tc.want)
+ }
+ })
+ }
+}
+
+// CDP discards a scale-0 clip exactly as it discards one passed with fromSurface=false —
+// whole viewport back, no error. No producer emits a scale-0 clip today, so this is a
+// latent guard rather than a live fix, and the clip has to be built by hand to reach it.
+func TestClipViewportAppliesTheNonZeroScaleRule(t *testing.T) {
+ if got := cdptk.ClipViewport(nil); got != nil {
+ t.Errorf("cdptk.ClipViewport(nil) = %+v, want nil so the nil-clip fast path survives", got)
+ }
+
+ for _, tc := range []struct {
+ name string
+ clip cdptk.ScreenshotClip
+ wantScale float64
+ }{
+ {name: "scale 0 means native, which CDP spells 1", clip: cdptk.ScreenshotClip{X: 40, Y: 60, Width: 120, Height: 60, Scale: 0}, wantScale: 1},
+ {name: "an explicit native scale is unchanged", clip: cdptk.ScreenshotClip{X: 40, Y: 60, Width: 120, Height: 60, Scale: 1}, wantScale: 1},
+ {name: "a real rescale is carried through", clip: cdptk.ScreenshotClip{X: 40, Y: 60, Width: 120, Height: 60, Scale: 0.5}, wantScale: 0.5},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ got := cdptk.ClipViewport(&tc.clip)
+ if got == nil {
+ t.Fatal("cdptk.ClipViewport returned nil for a non-nil clip")
+ }
+ if got.Scale != tc.wantScale {
+ t.Errorf("scale = %v, want %v — CDP silently discards a scale-0 clip", got.Scale, tc.wantScale)
+ }
+ if got.X != tc.clip.X || got.Y != tc.clip.Y || got.Width != tc.clip.Width || got.Height != tc.clip.Height {
+ t.Errorf("geometry = %+v, want it copied from %+v", got, tc.clip)
+ }
+ })
+ }
+}
+
+// The two rules are only "stated once" while nothing else converts a clip on its own. The
+// browser proof of the scale rule needs a browser and skips in the lightweight run, so
+// this is the browserless half: exactly one conversion of a cdptk.ScreenshotClip into a
+// page.Viewport in non-test code, and it is the one in this package.
+func TestOnlyCdptkConvertsAScreenshotClipToAViewport(t *testing.T) {
+ root, err := filepath.Abs("../..")
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ var scanned, converters int
+ walkErr := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if d.IsDir() {
+ if d.Name() == ".git" || d.Name() == "node_modules" || d.Name() == "dist" {
+ return fs.SkipDir
+ }
+ return nil
+ }
+ if !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+ return nil
+ }
+ body, readErr := os.ReadFile(path) // #nosec G304 -- files walked from this repo's own tree.
+ if readErr != nil {
+ return readErr
+ }
+ scanned++
+ src := string(body)
+ if !strings.Contains(src, "page.Viewport{") {
+ return nil
+ }
+ // A clip conversion reads a clip's fields; scaledScreenshotClip synthesises a
+ // viewport-covering clip from width/height instead and is not one.
+ if !strings.Contains(src, "clip.Width") || !strings.Contains(src, "clip.Height") {
+ return nil
+ }
+ converters++
+ rel, _ := filepath.Rel(root, path)
+ if filepath.Dir(rel) != filepath.Join("internal", "cdptk") {
+ t.Errorf("%s builds a page.Viewport from a clip's fields; that conversion carries the non-zero-scale rule and belongs to cdptk.ClipViewport alone", rel)
+ }
+ return nil
+ })
+ if walkErr != nil {
+ t.Fatalf("cannot scan the repo, so this census checks nothing: %v", walkErr)
+ }
+ if scanned < 100 {
+ t.Fatalf("scanned only %d Go files; this census would pass vacuously", scanned)
+ }
+ if converters == 0 {
+ t.Fatal("found no clip-to-viewport conversion at all; if ClipViewport was renamed or restructured, re-point this census rather than deleting it")
+ }
+}