testdriverai 7.3.34 → 7.3.36

package/.github/copilot-instructions.md

@@ -507,15 +507,64 @@ it("should incrementally build test", async (context) => {
 
 ```javascript
 const testdriver = TestDriver(context, {
-  newSandbox: true, // Create new sandbox (default: true)
-  preview: "browser", // "browser" | "ide" | "none" (default: "browser")
-  reconnect: false, // Reconnect to last sandbox (default: false)
-  keepAlive: 30000, // Keep sandbox alive after test (default: 30000ms / 30 seconds)
-  os: "linux", // 'linux' | 'windows' (default: 'linux')
-  resolution: "1366x768", // Sandbox resolution
-  cache: true, // Enable element caching (default: true)
-  cacheKey: "my-test", // Cache key for element finding
-  autoScreenshots: true, // Capture screenshots before/after each command (default: true)
+  // === Sandbox & Connection ===
+  newSandbox: true,          // Force creation of a new sandbox (default: true)
+  reconnect: false,          // Reconnect to last sandbox (default: false)
+  keepAlive: 30000,          // Keep sandbox alive after test in ms (default: 30000)
+  os: "linux",               // 'linux' | 'windows' (default: 'linux')
+  resolution: "1366x768",   // Sandbox resolution (e.g., '1920x1080')
+  ip: "203.0.113.42",       // Direct IP for self-hosted sandbox
+  sandboxAmi: "ami-1234",   // Custom AMI ID (AWS deployments)
+  sandboxInstance: "i3.metal", // EC2 instance type (AWS deployments)
+
+  // === Preview & Debugging ===
+  preview: "browser",        // "browser" | "ide" | "none" (default: "browser")
+  headless: false,           // @deprecated - use preview: "none" instead
+  debugOnFailure: false,     // Keep sandbox alive on test failure for debugging
+
+  // === Caching ===
+  cache: true,               // Enable element caching (default: true)
+  // Or use advanced caching config:
+  // cache: {
+  //   enabled: true,
+  //   thresholds: {
+  //     find: { screen: 0.05, element: 0.8 },
+  //     assert: 0.05
+  //   }
+  // },
+  cacheKey: "my-test",       // Cache key for element finding operations
+
+  // === Recording & Screenshots ===
+  dashcam: true,             // Enable/disable Dashcam video recording (default: true)
+  autoScreenshots: true,     // Capture screenshots before/after each command (default: true)
+
+  // === AI Configuration ===
+  ai: {                      // Global AI sampling configuration
+    temperature: 0,          // 0 = deterministic, higher = more creative
+    top: {
+      p: 0.9,               // Top-P nucleus sampling (0-1)
+      k: 40,                // Top-K sampling (1 = most likely, 0 = disabled)
+    },
+  },
+
+  // === Screen Change Detection ===
+  redraw: true,              // Enable redraw detection (default: true)
+  // Or use advanced redraw config:
+  // redraw: {
+  //   enabled: true,
+  //   thresholds: {
+  //     screen: 0.05,       // Pixel diff threshold (0-1), false to disable
+  //     network: false,     // Monitor network activity (default: false)
+  //   }
+  // },
+
+  // === Logging & Analytics ===
+  logging: true,             // Enable console logging output (default: true)
+  analytics: true,           // Enable analytics tracking (default: true)
+
+  // === Advanced ===
+  apiRoot: "https://...",    // API endpoint URL (for self-hosted deployments)
+  environment: {},           // Additional environment variables for the sandbox
 });
 ```
 

package/.github/workflows/windows-self-hosted.yaml

@@ -22,7 +22,7 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: testdriver-32
 
     steps:
       - name: Checkout repository
@@ -39,19 +39,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Debug Environment
-        run: |
-          echo "Checking environment variables..."
-          if [ -n "${{ secrets.TWOCAPTCHA_API_KEY }}" ]; then
-            echo "TWOCAPTCHA_API_KEY is set (length: ${#TWOCAPTCHA_API_KEY})"
-          else
-            echo "TWOCAPTCHA_API_KEY is NOT set"
-          fi
-        env:
-          TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}
-
-      - name: Run Windows tests with self-hosted instances
-        run: set -o pipefail && npx vitest run ${{ inputs.test_pattern }} 2>&1 | tee test-output.log
+      - name: Run Windows tests
+        run: set -o pipefail && npx vitest run ${{ inputs.test_pattern }} --maxWorkers 32 --sequence.concurrent 2>&1 | tee test-output.log
         env:
           TD_API_KEY: ${{ secrets.TD_API_KEY }}
           TWOCAPTCHA_API_KEY: ${{ secrets.TWOCAPTCHA_API_KEY }}

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [7.3.36](https://github.com/testdriverai/testdriverai/compare/v7.3.35...v7.3.36) (2026-02-24)
+
+
+### Reverts
+
+* Revert "Fix hanging node processes on Ctrl+C (#654)" (#683) ([5e68748](https://github.com/testdriverai/testdriverai/commit/5e6874825c6718e006bbf84e2ba5edae57d173ac)), closes [#654](https://github.com/testdriverai/testdriverai/issues/654) [#683](https://github.com/testdriverai/testdriverai/issues/683)
+
+
+
+## [7.3.35](https://github.com/testdriverai/testdriverai/compare/v7.3.34...v7.3.35) (2026-02-24)
+
+
+
 ## [7.3.34](https://github.com/testdriverai/testdriverai/compare/v7.3.33...v7.3.34) (2026-02-24)
 
 

package/agent/index.js

@@ -1635,105 +1635,6 @@ ${regression}
     this.emitter.emit(events.log.log, `${inputFile} (end)`);
   }
 
-  // Returns the path to the last sandbox file
-  getLastSandboxFilePath() {
-    const testdriverDir = path.join(process.cwd(), ".testdriver");
-    return path.join(testdriverDir, "last-sandbox");
-  }
-
-  // Returns full sandbox info from last-sandbox file (no timeout - let API validate)
-  getLastSandboxId() {
-    const lastSandboxFile = this.getLastSandboxFilePath();
-
-    if (fs.existsSync(lastSandboxFile)) {
-      try {
-        const fileContent = fs.readFileSync(lastSandboxFile, "utf-8").trim();
-
-        // Parse sandbox info (supports both old format and new format)
-        let sandboxInfo;
-        try {
-          sandboxInfo = JSON.parse(fileContent);
-        } catch {
-          return { sandboxId: fileContent || null };
-        }
-
-        return {
-          sandboxId: sandboxInfo.sandboxId || sandboxInfo.instanceId || null,
-          os: sandboxInfo.os || "linux",
-          ami: sandboxInfo.ami || null,
-          instanceType: sandboxInfo.instanceType || null,
-          timestamp: sandboxInfo.timestamp || null,
-        };
-      } catch {
-        // ignore errors
-      }
-    }
-    return null;
-  }
-
-  // Returns sandboxId to use if AMI/instance type match current requirements
-  getRecentSandboxId() {
-    const sandboxInfo = this.getLastSandboxId();
-
-    if (!sandboxInfo || !sandboxInfo.sandboxId) {
-      return null;
-    }
-
-    // Check if AMI and instance type match current requirements
-    const currentAmi = this.sandboxAmi || null;
-    const currentInstance = this.sandboxInstance || null;
-    const storedAmi = sandboxInfo.ami || null;
-    const storedInstance = sandboxInfo.instanceType || null;
-
-    if (currentAmi === storedAmi && currentInstance === storedInstance) {
-      return sandboxInfo.sandboxId;
-    } else {
-      this.emitter.emit(
-        events.log.log,
-        theme.dim(
-          "Recent sandbox found but AMI/instance type doesn't match current requirements",
-        ),
-      );
-      return null;
-    }
-  }
-
-  saveLastSandboxId(sandboxId, osType = "linux") {
-    const lastSandboxFile = this.getLastSandboxFilePath();
-    const testdriverDir = path.dirname(lastSandboxFile);
-
-    try {
-      // Ensure .testdriver directory exists
-      if (!fs.existsSync(testdriverDir)) {
-        fs.mkdirSync(testdriverDir, { recursive: true });
-      }
-
-      const sandboxInfo = {
-        sandboxId: sandboxId,
-        os: osType,
-        ami: this.sandboxAmi || null,
-        instanceType: this.sandboxInstance || null,
-        timestamp: new Date().toISOString(),
-      };
-      fs.writeFileSync(lastSandboxFile, JSON.stringify(sandboxInfo, null, 2), {
-        encoding: "utf-8",
-      });
-    } catch {
-      // ignore errors
-    }
-  }
-
-  clearRecentSandboxId() {
-    const lastSandboxFile = this.getLastSandboxFilePath();
-    try {
-      if (fs.existsSync(lastSandboxFile)) {
-        fs.unlinkSync(lastSandboxFile);
-      }
-    } catch {
-      // ignore errors
-    }
-  }
-
   async buildEnv(options = {}) {
     // If instance already exists, do not build environment again
     if (this.instance) {
@@ -1762,10 +1663,8 @@ ${regression}
 
     if (heal) this.healMode = heal;
 
-    // If createNew flag is set, clear the recent sandbox file to force creating a new sandbox
+    // If createNew flag is set, clear sandboxId to prevent reconnection attempts
     if (createNew) {
-      this.clearRecentSandboxId();
-      // Also clear this.sandboxId to prevent reconnection attempts
       this.sandboxId = null;
       if (!this.config.CI && !this.newSandbox) {
         this.emitter.emit(events.log.log, theme.dim("Creating a new sandbox"));
@@ -1780,8 +1679,6 @@ ${regression}
     // order is important!
     await this.connectToSandboxService();
 
-    const recentId = createNew ? null : this.getRecentSandboxId();
-
     // Set sandbox ID for reconnection (only if not creating new and recent ID exists)
     if (this.ip) {
       let instance = await this.sandbox.send({
@@ -1794,13 +1691,13 @@ ${regression}
       // Store connection params for reconnection
       // For direct IP connections, store as a direct type so reconnection
       // sends a 'direct' message instead of 'connect' with an IP as sandboxId
-      this.sandbox._lastConnectParams = {
+      this.sandbox.setConnectionParams({
         type: 'direct',
         ip: this.ip,
         sandboxId: instance?.instance?.instanceId || instance?.instance?.sandboxId || null,
         persist: true,
         keepAlive: this.keepAlive,
-      };
+      });
 
       // Mark instance socket as connected so console logs are forwarded
       this.sandbox.instanceSocketConnected = true;
@@ -1811,33 +1708,6 @@ ${regression}
       await this.runLifecycle("provision");
 
       return;
-    } else if (!createNew && recentId) {
-      // Only attempt to connect to existing sandbox if not in CI mode and not creating new
-      this.emitter.emit(
-        events.log.narration,
-        theme.dim(`using recent sandbox: ${recentId}`),
-      );
-      this.sandboxId = recentId;
-
-      try {
-        let instance = await this.connectToSandboxDirect(
-          this.sandboxId,
-          true, // always persist by default
-          this.keepAlive, // pass keepAlive TTL
-        );
-
-        this.instance = instance;
-
-        await this.renderSandbox(instance, headless);
-        return;
-      } catch (error) {
-        // If connection fails, fall through to creating a new sandbox
-        this.emitter.emit(
-          events.log.narration,
-          theme.dim(`failed to connect to recent sandbox, creating new one...`),
-        );
-        console.error("Failed to reconnect to sandbox:", error);
-      }
     } else if (!createNew && this.sandboxId && !this.config.CI) {
       // Only attempt to connect to existing sandbox if not in CI mode and not creating new
       // Attempt to connect to known instance
@@ -1892,9 +1762,6 @@ ${regression}
       this.sandboxId =
         newSandbox?.sandbox?.sandboxId || newSandbox?.sandbox?.instanceId;
 
-      // Use the configured sandbox OS type
-      this.saveLastSandboxId(this.sandboxId, this.sandboxOs);
-
       let instance = await this.connectToSandboxDirect(
         this.sandboxId,
         true, // always persist by default
@@ -2332,12 +2199,6 @@ Please check your network connection, TD_API_KEY, or the service status.`,
       }
 
       // Success - got a sandbox
-      if (response.sandbox && response.sandbox.sandboxId) {
-        this.saveLastSandboxId(response.sandbox.sandboxId, this.sandboxOs);
-      } else if (response.sandbox && response.sandbox.instanceId) {
-        this.saveLastSandboxId(response.sandbox.instanceId, this.sandboxOs);
-      }
-
       return response;
     }
   }

package/agent/lib/debugger-server.js

@@ -8,6 +8,8 @@ const logger = require("./logger");
 let server = null;
 let wss = null;
 let clients = new Set();
+let refCount = 0; // Number of active consumers (for concurrent test safety)
+let debuggerUrl = null; // Stored URL of running debugger
 
 function createDebuggerServer(config = {}) {
   const port = config.TD_DEBUGGER_PORT || 0; // 0 means find available port
@@ -76,7 +78,12 @@ function createDebuggerServer(config = {}) {
 
     // Start server on available port
     server.listen(port, "localhost", () => {
-      const actualPort = server.address().port;
+      const address = server.address();
+      if (!address) {
+        reject(new Error("Server started but address is not available"));
+        return;
+      }
+      const actualPort = address.port;
       resolve({ port: actualPort, server, wss });
     });
 
@@ -124,7 +131,43 @@ async function startDebugger(config = {}, emitter) {
   }
 }
 
-function stopDebugger() {
+/**
+ * Acquire a reference to the debugger server.
+ * Starts the server on first call; subsequent calls reuse the existing server.
+ * Each call increments a reference count — call releaseDebugger() when done.
+ *
+ * @param {Object} config - Debugger configuration
+ * @param {EventEmitter} emitter - Event emitter for broadcasting
+ * @returns {Promise<{port: number, url: string}>} Debugger connection info
+ */
+async function acquireDebugger(config = {}, emitter) {
+  refCount++;
+  if (server && debuggerUrl) {
+    // Server already running — reuse it
+    return { url: debuggerUrl };
+  }
+  // First consumer — start the server
+  const result = await startDebugger(config, emitter);
+  debuggerUrl = result.url;
+  return result;
+}
+
+/**
+ * Release a reference to the debugger server.
+ * Only actually stops the server when the last consumer releases.
+ */
+function releaseDebugger() {
+  if (refCount > 0) refCount--;
+  if (refCount > 0) return; // Other tests still using it
+  forceStopDebugger();
+}
+
+/**
+ * Forcefully stop the debugger server regardless of reference count.
+ * Used for process exit cleanup.
+ */
+function forceStopDebugger() {
+  refCount = 0;
   if (wss) {
     wss.close();
     wss = null;
@@ -136,12 +179,23 @@ function stopDebugger() {
   }
 
   clients.clear();
+  debuggerUrl = null;
+  module.exports.debuggerUrl = null;
+  module.exports.config = null;
   logger.log("Debugger server stopped");
 }
 
+// Keep stopDebugger as alias for forceStopDebugger for backward compatibility
+function stopDebugger() {
+  forceStopDebugger();
+}
+
 module.exports = {
   startDebugger,
   stopDebugger,
+  acquireDebugger,
+  releaseDebugger,
+  forceStopDebugger,
   broadcastEvent,
   createDebuggerServer,
   debuggerUrl: null,

package/agent/lib/sandbox.js

@@ -47,6 +47,7 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       this.reconnecting = false; // Prevent duplicate reconnection attempts
       this.pendingTimeouts = new Map(); // Track per-message timeouts
       this.pendingRetryQueue = []; // Queue of requests to retry after reconnection
+      this._lastConnectParams = null; // Connection params for reconnection (per-instance, not shared)
     }
 
     /**
@@ -98,7 +99,7 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
         // Add sandboxId to every message if we have a connected sandbox
         // This allows the API to reconnect if the connection was rerouted
         // Don't inject IP addresses as sandboxId — only valid instance/sandbox IDs
-        if (this._lastConnectParams?.sandboxId && !message.sandboxId) {
+        if (this._lastConnectParams?.sandboxId && !message.sandboxId) { 
           const id = this._lastConnectParams.sandboxId;
           // Only inject if it looks like a valid ID (not an IP address)
           if (id && !/^\d+\.\d+\.\d+\.\d+$/.test(id)) {
@@ -127,11 +128,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
             );
           }
         }, timeout);
-        // Don't let pending message timeouts prevent Node process from exiting
-        // (unref is not available in browser/non-Node environments)
-        if (timeoutId.unref) {
-          timeoutId.unref();
-        }
 
         // Track timeout so close() can clear it
         this.pendingTimeouts.set(requestId, timeoutId);
@@ -198,6 +194,22 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       }
     }
 
+    /**
+     * Set connection params for reconnection logic and sandboxId injection.
+     * Use this instead of directly assigning this._lastConnectParams from
+     * external code. Keeps the shape consistent and avoids stale state
+     * leaking across concurrent test runs.
+     * @param {Object|null} params
+     * @param {string} [params.type] - 'direct' for IP-based connections
+     * @param {string} [params.ip] - IP address for direct connections
+     * @param {string} [params.sandboxId] - Sandbox/instance ID
+     * @param {boolean} [params.persist] - Whether to persist the sandbox
+     * @param {number|null} [params.keepAlive] - Keep-alive TTL in ms
+     */
+    setConnectionParams(params) {
+      this._lastConnectParams = params ? { ...params } : null;
+    }
+
     async connect(sandboxId, persist = false, keepAlive = null) {
       let reply = await this.send({
         type: "connect",
@@ -209,14 +221,14 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       if (reply.success) {
         // Only store connection params after successful connection
         // This prevents malformed sandboxId from being attached to subsequent messages
-        this._lastConnectParams = { sandboxId, persist, keepAlive };
+        this.setConnectionParams({ sandboxId, persist, keepAlive });
         this.instanceSocketConnected = true;
         emitter.emit(events.sandbox.connected);
         // Return the full reply (includes url and sandbox)
         return reply;
       } else {
         // Clear any previous connection params on failure
-        this._lastConnectParams = null;
+        this.setConnectionParams(null);
         // Throw error to trigger fallback to creating new sandbox
         throw new Error(reply.errorMessage || "Failed to connect to sandbox");
       }
@@ -348,11 +360,6 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
           this.reconnecting = false;
         }
       }, delay);
-      // Don't let the reconnect timer prevent Node process from exiting
-      // (unref is not available in browser/non-Node environments)
-      if (this.reconnectTimer.unref) {
-        this.reconnectTimer.unref();
-      }
     }
 
     /**
@@ -461,12 +468,17 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
 
           if (!this.ps[message.requestId]) {
             // This can happen during reconnection (ps was cleared) or after timeout
-            // (promise was deleted). Only log at debug level since it's expected.
+            // (promise was deleted). Expected during polling loops (e.g. Chrome
+            // debugger readiness checks) where short-timeout exec calls regularly
+            // expire before the sandbox responds.  Only log in debug/verbose mode.
             if (!this.reconnecting) {
-              console.warn(
-                "No pending promise found for requestId:",
-                message.requestId,
-              );
+              const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
+              if (debugMode) {
+                console.warn(
+                  "No pending promise found for requestId:",
+                  message.requestId,
+                );
+              }
             }
             return;
           }
@@ -528,6 +540,7 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       this.instanceSocketConnected = false;
       this.authenticated = false;
       this.instance = null;
+      this._lastConnectParams = null;
 
       // Silently clear pending promises and retry queue without rejecting
       // (rejecting causes unhandled promise rejections during cleanup)

package/docs/v7/client.mdx

@@ -25,7 +25,7 @@ const testdriver = new TestDriver(apiKey, options)
   Configuration options for the client
   
   <Expandable title="properties">
-    <ParamField path="os" type="string" default="windows">
+    <ParamField path="os" type="string" default="linux">
       Operating system for the sandbox: `'windows'` or `'linux'`
     </ParamField>
     
@@ -33,7 +33,7 @@ const testdriver = new TestDriver(apiKey, options)
       Screen resolution for the sandbox (e.g., `'1920x1080'`, `'1366x768'`)
     </ParamField>
     
-    <ParamField path="apiRoot" type="string" default="https://testdriver-api.onrender.com">
+    <ParamField path="apiRoot" type="string">
       API endpoint URL (typically only changed for self-hosted deployments)
     </ParamField>
     
@@ -49,6 +49,111 @@ const testdriver = new TestDriver(apiKey, options)
       Automatically capture screenshots before and after each command. Screenshots are saved to `.testdriver/screenshots/<test>/` with descriptive filenames that include the line number and action name. Format: `<seq>-<action>-<phase>-L<line>-<description>.png`
     </ParamField>
     
+    <ParamField path="newSandbox" type="boolean" default="true">
+      Force creation of a new sandbox instead of reusing an existing one
+    </ParamField>
+    
+    <ParamField path="reconnect" type="boolean" default="false">
+      Reconnect to the last used sandbox instead of creating a new one. When `true`, provision methods (`chrome`, `vscode`, `installer`, etc.) will be skipped since the application is already running. Throws error if no previous sandbox exists.
+    </ParamField>
+    
+    <ParamField path="keepAlive" type="number" default="60000">
+      Keep sandbox alive for the specified number of milliseconds after disconnect. Set to `0` to terminate immediately on disconnect. Useful for debugging or reconnecting to the same sandbox.
+    </ParamField>
+    
+    <ParamField path="preview" type="string" default="browser">
+      Preview mode for live test visualization:
+      - `"browser"` — Opens debugger in default browser (default)
+      - `"ide"` — Opens preview in IDE panel (VSCode, Cursor - requires TestDriver extension)
+      - `"none"` — Headless mode, no visual preview
+    </ParamField>
+    
+    <ParamField path="headless" type="boolean" default="false">
+      **Deprecated**: Use `preview: "none"` instead. Run in headless mode without opening the debugger.
+    </ParamField>
+    
+    <ParamField path="debugOnFailure" type="boolean" default="false">
+      Keep the sandbox alive when a test fails so you can reconnect and debug interactively. The sandbox ID is printed to the console.
+    </ParamField>
+    
+    <ParamField path="ip" type="string">
+      Direct IP address to connect to a running sandbox instance (for self-hosted deployments)
+    </ParamField>
+    
+    <ParamField path="sandboxAmi" type="string">
+      Custom AMI ID for the sandbox instance (AWS deployments, e.g., `'ami-1234'`)
+    </ParamField>
+    
+    <ParamField path="sandboxInstance" type="string">
+      EC2 instance type for the sandbox (AWS deployments, e.g., `'i3.metal'`)
+    </ParamField>
+    
+    <ParamField path="cache" type="boolean | object" default="true">
+      Enable or disable element caching, or provide advanced threshold configuration.
+      
+      <Expandable title="advanced config">
+        <ParamField path="enabled" type="boolean" default="true">
+          Enable or disable caching
+        </ParamField>
+        
+        <ParamField path="thresholds" type="object">
+          Fine-tune cache matching
+          
+          <Expandable title="properties">
+            <ParamField path="find" type="object">
+              Thresholds for `find()` operations
+              
+              <Expandable title="properties">
+                <ParamField path="screen" type="number" default="0.05">
+                  Pixel diff threshold for screen comparison (0-1). `0.05` = 5% diff allowed.
+                </ParamField>
+                
+                <ParamField path="element" type="number" default="0.8">
+                  OpenCV template match threshold for element matching (0-1). `0.8` = 80% correlation.
+                </ParamField>
+              </Expandable>
+            </ParamField>
+            
+            <ParamField path="assert" type="number" default="0.05">
+              Pixel diff threshold for `assert()` operations (0-1). `0.05` = 5% diff allowed.
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    
+    <ParamField path="cacheKey" type="string">
+      Cache key for element finding operations. If provided, enables caching tied to this key.
+    </ParamField>
+    
+    <ParamField path="dashcam" type="boolean" default="true">
+      Enable or disable Dashcam video recording
+    </ParamField>
+    
+    <ParamField path="redraw" type="boolean | object" default="true">
+      Enable or disable screen-change (redraw) detection, or provide advanced configuration.
+      
+      <Expandable title="advanced config">
+        <ParamField path="enabled" type="boolean" default="true">
+          Enable or disable redraw detection
+        </ParamField>
+        
+        <ParamField path="thresholds" type="object">
+          Threshold configuration
+          
+          <Expandable title="properties">
+            <ParamField path="screen" type="number | false" default="0.05">
+              Pixel diff threshold (0-1). Set to `false` to disable screen redraw detection.
+            </ParamField>
+            
+            <ParamField path="network" type="boolean" default="false">
+              Enable or disable network activity monitoring
+            </ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    
     <ParamField path="environment" type="object">
       Additional environment variables to pass to the sandbox
     </ParamField>