Skip to content

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

feat: CSS animation disabling (P4)

Mario6df4f862d9e2
diff --git a/README.md b/README.md
index 82f9a971..e98fa426 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,7 @@ Pinchtab launches its own Chrome with a persistent profile at `~/.pinchtab/chrom
- πŸ•΅οΈ **Stealth mode** β€” patches `navigator.webdriver`, spoofs UA, hides automation flags
- πŸ’Ύ **Session persistence** β€” cookies, auth, tabs survive restarts
- 🚫 **Image blocking** β€” skip image downloads for faster, leaner browsing (`BRIDGE_BLOCK_IMAGES` or per-request)
+- 🎬 **Animation disabling** β€” freeze CSS animations/transitions for consistent snapshots (`BRIDGE_NO_ANIMATIONS` or `?noAnimations=true`)
- πŸ“ **Text extraction** β€” readability mode (strips nav/ads) or raw `innerText`
- πŸ”„ **Smart diff** β€” `?diff=true` returns only changes since last snapshot
- πŸ“„ **Text format** β€” `?format=text` for indented tree (~40-60% fewer tokens than JSON)
@@ -110,6 +111,8 @@ Pinchtab launches its own Chrome with a persistent profile at `~/.pinchtab/chrom
| `POST` | `/action` | Click, type, fill, press, focus, hover, select, scroll |
| `POST` | `/evaluate` | Execute JavaScript |
| `POST` | `/tab` | Open/close tabs |
+| `POST` | `/tab/lock` | Lock tab for exclusive agent access |
+| `POST` | `/tab/unlock` | Release tab lock |
### Query Parameters (snapshot)
| Param | Description |
@@ -119,6 +122,20 @@ Pinchtab launches its own Chrome with a persistent profile at `~/.pinchtab/chrom
| `depth=N` | Max tree depth |
| `diff=true` | Return only added/changed/removed nodes since last snapshot |
| `format=text` | Indented plain text instead of JSON (~40-60% fewer tokens) |
+| `format=compact` | One-line-per-node format (56-64% fewer tokens than JSON) |
+| `selector=CSS` | Scope tree to a CSS selector subtree (e.g. `?selector=main`) |
+| `maxTokens=N` | Truncate output to ~N tokens |
+| `noAnimations=true` | Disable CSS animations before capture |
+| `output=file` | Save snapshot to disk instead of returning |
+| `path=/custom/path` | Custom file path (with `output=file`) |
+
+### Query Parameters (screenshot)
+| Param | Description |
+|-------|-------------|
+| `tabId` | Target tab (default: first tab) |
+| `quality=N` | JPEG quality (default: 80) |
+| `noAnimations=true` | Disable CSS animations before capture |
+| `output=file` | Save screenshot to disk instead of returning |
### Query Parameters (text)
| Param | Description |
@@ -140,6 +157,7 @@ All via environment variables:
| `BRIDGE_NO_RESTORE` | `false` | Skip restoring tabs from previous session |
| `BRIDGE_CHROME_VERSION` | `133.0.6943.98` | Chrome version in User-Agent strings (keep current to avoid detection) |
| `BRIDGE_BLOCK_IMAGES` | `false` | Block image loading (faster, lower bandwidth) |
+| `BRIDGE_NO_ANIMATIONS` | `false` | Disable CSS animations/transitions globally |
| `BRIDGE_TIMEOUT` | `15` | Action timeout (seconds) |
| `BRIDGE_NAV_TIMEOUT` | `30` | Navigation timeout (seconds) |
| `BRIDGE_CHROME_VERSION` | `133.0.6943.98` | Chrome UA version string |
diff --git a/TODO.md b/TODO.md
index 81451d36..cc465ede 100644
--- a/TODO.md
+++ b/TODO.md
@@ -29,7 +29,7 @@ P2 (K11 file path, blockImages on CreateTab) β€” all resolved.
### P4: Quality of Life
- [ ] **Headed mode testing** β€” Run Section 2 tests to validate non-headless.
- [ ] **Ad blocking** β€” Basic tracker blocking for cleaner snapshots.
-- [ ] **CSS animation disabling** β€” Faster page loads, more consistent snapshots.
+- [x] **CSS animation disabling** β€” `BRIDGE_NO_ANIMATIONS` env + `?noAnimations=true` per-request.
- [ ] **Randomized window sizes** β€” Avoid automation fingerprint.
### Minor
diff --git a/animations.go b/animations.go
new file mode 100644
index 00000000..a6391a21
--- /dev/null
+++ b/animations.go
@@ -0,0 +1,50 @@
+package main
+
+import (
+ "context"
+
+ "github.com/chromedp/cdproto/emulation"
+ "github.com/chromedp/cdproto/page"
+ "github.com/chromedp/chromedp"
+)
+
+// disableAnimationsCSS is injected to force-disable all CSS animations and transitions.
+const disableAnimationsCSS = `
+(function() {
+ const style = document.createElement('style');
+ style.setAttribute('data-pinchtab', 'no-animations');
+ style.textContent = '*, *::before, *::after { animation: none !important; animation-duration: 0s !important; transition: none !important; transition-duration: 0s !important; scroll-behavior: auto !important; }';
+ (document.head || document.documentElement).appendChild(style);
+})();
+`
+
+// injectNoAnimations adds a persistent script (via CDP) that disables CSS
+// animations on every document load. Used when BRIDGE_NO_ANIMATIONS=true.
+func (b *Bridge) injectNoAnimations(ctx context.Context) {
+ _ = chromedp.Run(ctx,
+ chromedp.ActionFunc(func(ctx context.Context) error {
+ _, err := page.AddScriptToEvaluateOnNewDocument(disableAnimationsCSS).Do(ctx)
+ return err
+ }),
+ chromedp.ActionFunc(func(ctx context.Context) error {
+ return emulation.SetEmulatedMedia().
+ WithFeatures([]*emulation.MediaFeature{
+ {Name: "prefers-reduced-motion", Value: "reduce"},
+ }).Do(ctx)
+ }),
+ )
+}
+
+// disableAnimationsOnce runs the animation-disabling CSS on the current page
+// (one-shot, for per-request ?noAnimations=true).
+func disableAnimationsOnce(ctx context.Context) {
+ _ = chromedp.Run(ctx,
+ chromedp.Evaluate(disableAnimationsCSS, nil),
+ chromedp.ActionFunc(func(ctx context.Context) error {
+ return emulation.SetEmulatedMedia().
+ WithFeatures([]*emulation.MediaFeature{
+ {Name: "prefers-reduced-motion", Value: "reduce"},
+ }).Do(ctx)
+ }),
+ )
+}
diff --git a/animations_test.go b/animations_test.go
new file mode 100644
index 00000000..92c56502
--- /dev/null
+++ b/animations_test.go
@@ -0,0 +1,45 @@
+package main
+
+import (
+ "strings"
+ "testing"
+)
+
+func TestDisableAnimationsCSSContent(t *testing.T) {
+ // Verify the injected CSS contains the critical rules
+ if !strings.Contains(disableAnimationsCSS, "animation: none !important") {
+ t.Error("missing animation: none rule")
+ }
+ if !strings.Contains(disableAnimationsCSS, "transition: none !important") {
+ t.Error("missing transition: none rule")
+ }
+ if !strings.Contains(disableAnimationsCSS, "animation-duration: 0s !important") {
+ t.Error("missing animation-duration: 0s rule")
+ }
+ if !strings.Contains(disableAnimationsCSS, "transition-duration: 0s !important") {
+ t.Error("missing transition-duration: 0s rule")
+ }
+ if !strings.Contains(disableAnimationsCSS, "scroll-behavior: auto !important") {
+ t.Error("missing scroll-behavior: auto rule")
+ }
+ if !strings.Contains(disableAnimationsCSS, "data-pinchtab") {
+ t.Error("missing data-pinchtab attribute for identification")
+ }
+}
+
+func TestDisableAnimationsCSSIsIIFE(t *testing.T) {
+ trimmed := strings.TrimSpace(disableAnimationsCSS)
+ if !strings.HasPrefix(trimmed, "(function()") {
+ t.Error("CSS injection should be wrapped in IIFE")
+ }
+ if !strings.HasSuffix(trimmed, "();") {
+ t.Error("CSS injection should end with IIFE invocation")
+ }
+}
+
+func TestNoAnimationsConfigDefault(t *testing.T) {
+ // Default should be false (env not set in tests)
+ if noAnimations {
+ t.Error("noAnimations should default to false")
+ }
+}
diff --git a/bridge.go b/bridge.go
index f2583890..39c849c5 100644
--- a/bridge.go
+++ b/bridge.go
@@ -98,6 +98,9 @@ func (b *Bridge) TabContext(tabID string) (context.Context, string, error) {
// Inject stealth script on newly attached tabs
b.injectStealth(ctx)
+ if noAnimations {
+ b.injectNoAnimations(ctx)
+ }
b.tabs[tabID] = &TabEntry{ctx: ctx, cancel: cancel}
return ctx, tabID, nil
@@ -172,6 +175,10 @@ func (b *Bridge) CreateTab(url string) (string, context.Context, context.CancelF
// Inject stealth script before navigation so it applies to the first page load
b.injectStealth(ctx)
+ if noAnimations {
+ b.injectNoAnimations(ctx)
+ }
+
// Apply global resource blocking on new tabs
if blockMedia {
_ = setResourceBlocking(ctx, mediaBlockPatterns)
diff --git a/config.go b/config.go
index b55bec5d..29ad0328 100644
--- a/config.go
+++ b/config.go
@@ -59,6 +59,7 @@ var (
blockMedia = os.Getenv("BRIDGE_BLOCK_MEDIA") == "true" // superset: images + fonts + CSS + video
chromeBinary = os.Getenv("CHROME_BINARY") // path to Chrome/Chromium binary
chromeExtraFlags = os.Getenv("CHROME_FLAGS") // extra flags (space-separated)
+ noAnimations = os.Getenv("BRIDGE_NO_ANIMATIONS") == "true"
actionTimeout = 15 * time.Second
navigateTimeout = 30 * time.Second
shutdownTimeout = 10 * time.Second
diff --git a/handler_snapshot.go b/handler_snapshot.go
index d4cfa1d9..1030368f 100644
--- a/handler_snapshot.go
+++ b/handler_snapshot.go
@@ -25,6 +25,7 @@ func (b *Bridge) handleSnapshot(w http.ResponseWriter, r *http.Request) {
outputPath := r.URL.Query().Get("path") // custom file path for output=file
selector := r.URL.Query().Get("selector") // CSS selector to scope snapshot
maxTokensStr := r.URL.Query().Get("maxTokens") // truncate output to ~N tokens
+ reqNoAnim := r.URL.Query().Get("noAnimations") == "true"
maxDepthStr := r.URL.Query().Get("depth")
maxDepth := -1
if maxDepthStr != "" {
@@ -49,6 +50,10 @@ func (b *Bridge) handleSnapshot(w http.ResponseWriter, r *http.Request) {
defer tCancel()
go cancelOnClientDone(r.Context(), tCancel)
+ if reqNoAnim && !noAnimations {
+ disableAnimationsOnce(tCtx)
+ }
+
var rawResult json.RawMessage
if err := chromedp.Run(tCtx,
chromedp.ActionFunc(func(ctx context.Context) error {
diff --git a/handlers.go b/handlers.go
index 0b0a2818..7fb6f562 100644
--- a/handlers.go
+++ b/handlers.go
@@ -58,6 +58,7 @@ func (b *Bridge) handleTabs(w http.ResponseWriter, r *http.Request) {
func (b *Bridge) handleScreenshot(w http.ResponseWriter, r *http.Request) {
tabID := r.URL.Query().Get("tabId")
output := r.URL.Query().Get("output")
+ reqNoAnim := r.URL.Query().Get("noAnimations") == "true"
ctx, _, err := b.TabContext(tabID)
if err != nil {
@@ -69,6 +70,10 @@ func (b *Bridge) handleScreenshot(w http.ResponseWriter, r *http.Request) {
defer tCancel()
go cancelOnClientDone(r.Context(), tCancel)
+ if reqNoAnim && !noAnimations {
+ disableAnimationsOnce(tCtx)
+ }
+
var buf []byte
quality := 80
if q := r.URL.Query().Get("quality"); q != "" {