High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.
docs: correct the disproven headless no-op claim on the fromSurface predicate with the measured 2x2 (PIN-051)
Luigi Agostia8b021f804df
diff --git a/internal/browsers/chrome/instance.go b/internal/browsers/chrome/instance.goindex 7fd3b304..ceb9e3fb 100644--- a/internal/browsers/chrome/instance.go+++ b/internal/browsers/chrome/instance.go@@ -81,14 +81,22 @@ func (i *Instance) CaptureScreenshot(ctx context.Context, format string, quality// 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. In headless Chrome the flag is a-// no-op, which is why only this predicate, not a captured image, can pin the-// choice.+// 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}diff --git a/internal/browsers/chrome/instance_from_surface_test.go b/internal/browsers/chrome/instance_from_surface_test.goindex 1e077f44..733feda6 100644--- a/internal/browsers/chrome/instance_from_surface_test.go+++ b/internal/browsers/chrome/instance_from_surface_test.go@@ -6,10 +6,12 @@ import ("github.com/pinchtab/pinchtab/internal/cdptk")-// The browser-level clip tests cannot pin this choice on their own: in headless-// Chrome fromSurface is a no-op, so an always-true "simplification" produces-// byte-identical images and passes them. This is the guard that fails instead —-// the unclipped screencast poll must keep the direct view read.+// 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