Skip to content

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.go
index 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.go
index 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