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.goindex 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 []byteerr := chromedp.Run(ctx, chromedp.ActionFunc(func(ctx context.Context) error {@@ -324,16 +306,7 @@ func (b *Bridge) CaptureScreenshot(ctx context.Context, format string, quality iif 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.CaptureAllowActivationbuf, err := CaptureScreenshot(ctx, ScreenshotOpts{Format: cdpFormat,diff --git a/internal/bridge/screenshot_test.go b/internal/bridge/screenshot_test.goindex 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.goindex 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, qualitycdpFormat = 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, qualityreturn 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.EvaluateOptionif opts.AwaitPromise {diff --git a/internal/browsers/chrome/instance_from_surface_test.go b/internal/browsers/chrome/instance_from_surface_test.godeleted file mode 100644index 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.goindex 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) (*ScreenshotClipScale: 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.goindex f922e50c..c0a5914c 100644--- a/internal/cdptk/screenshot_test.go+++ b/internal/cdptk/screenshot_test.go@@ -3,9 +3,14 @@ package cdptk_testimport ("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")+ }+}