update redraw

Author: ianjennings

agent/lib/commands.js

@@ -469,6 +469,7 @@ const createCommands = (
       if (action !== "hover") {
         // Update timestamp for the actual click action
         elementData.timestamp = Date.now();
+        
 
         if (action === "click" || action === "left-click") {
           await sandbox.send({ type: "leftClick", x, y, ...elementData });
@@ -928,7 +929,7 @@ const createCommands = (
             interactionType: "wait",
             session: sessionId,
             input: { timeout },
-            timestamp: waitTimestamp, // Absolute epoch timestamp - frontend calculates relative using clientStartDate
+            timestamp: waitTimestamp, // Use dashcam elapsed time instead of absolute time
             duration: waitDuration,
             success: true,
           });

agent/lib/redraw.js

@@ -8,7 +8,6 @@ const DEFAULT_REDRAW_OPTIONS = {
   enabled: true,           // Master switch to enable/disable redraw detection
   screenRedraw: true,      // Enable screen redraw detection
   networkMonitor: true,    // Enable network activity monitoring
-  diffThreshold: 0.1,     // Percentage threshold for screen diff (0.01 = 0.01%)
 };
 
 // Factory function that creates redraw functionality with the provided system instance
@@ -20,10 +19,6 @@ const createRedraw = (
 ) => {
   // Merge default options with provided defaults
   const baseOptions = { ...DEFAULT_REDRAW_OPTIONS, ...defaultOptions };
-  // Support legacy redrawThresholdPercent number argument
-  if (typeof defaultOptions === 'number') {
-    baseOptions.diffThreshold = defaultOptions;
-  }
 
   const networkUpdateInterval = 15000;
 
@@ -35,7 +30,13 @@ const createRedraw = (
 
   let measurements = [];
   let networkSettled = true;
-  let screenHasRedrawn = null;
+  
+  // Screen stability tracking
+  let initialScreenImage = null;    // The image captured at start() - reference point
+  let lastScreenImage = null;       // Previous frame for consecutive comparison
+  let hasChangedFromInitial = false; // Has screen changed from initial state?
+  let consecutiveFramesStable = false; // Are consecutive frames now stable?
+  let screenMeasurements = [];      // Track consecutive frame diffs for stability detection
 
   // Track network interval to ensure only one exists
   let networkInterval = null;
@@ -45,7 +46,11 @@ const createRedraw = (
     lastRxBytes = null;
     measurements = [];
     networkSettled = true;
-    screenHasRedrawn = false;
+    initialScreenImage = null;
+    lastScreenImage = null;
+    hasChangedFromInitial = false;
+    consecutiveFramesStable = false;
+    screenMeasurements = [];
   };
 
   const parseNetworkStats = (thisRxBytes, thisTxBytes) => {
@@ -85,6 +90,40 @@ const createRedraw = (
     }
   };
 
+  // Parse screen diff stats for consecutive frame stability
+  // Detects when consecutive frames have stopped changing
+  const parseConsecutiveDiffStats = (diffPercent) => {
+    screenMeasurements.push(diffPercent);
+
+    // Keep last 10 measurements for stability detection
+    if (screenMeasurements.length > 10) {
+      screenMeasurements.shift();
+    }
+
+    // Need at least 2 measurements to determine stability
+    if (screenMeasurements.length < 2) {
+      consecutiveFramesStable = false;
+      return;
+    }
+
+    let avgDiff = screenMeasurements.reduce((acc, d) => acc + d, 0) / screenMeasurements.length;
+
+    let stdDevDiff = Math.sqrt(
+      screenMeasurements.reduce((acc, d) => acc + Math.pow(d - avgDiff, 2), 0) /
+        screenMeasurements.length,
+    );
+
+    let zIndexDiff = stdDevDiff !== 0 ? (diffPercent - avgDiff) / stdDevDiff : 0;
+
+    // Consecutive frames are stable when z-index is negative (current diff is below average)
+    // or diff is essentially zero (< 0.1% accounts for compression artifacts)
+    if (screenMeasurements.length >= 2 && (diffPercent < 0.1 || zIndexDiff < 0)) {
+      consecutiveFramesStable = true;
+    } else {
+      consecutiveFramesStable = false;
+    }
+  };
+
   async function updateNetwork() {
     if (sandbox && sandbox.instanceSocketConnected) {
       let network = await sandbox.send({
@@ -141,8 +180,6 @@ const createRedraw = (
     }
   }
 
-  let startImage = null;
-
   // Start network monitoring only when needed
   function startNetworkMonitoring() {
     if (!networkInterval) {
@@ -187,17 +224,18 @@ const createRedraw = (
       startNetworkMonitoring();
     }
 
-    // Only capture start image if screen redraw is enabled
+    // Capture initial image for screen stability monitoring
     if (currentOptions.screenRedraw) {
-      startImage = await system.captureScreenPNG(0.25, true);
-      emitter.emit(events.log.debug, `[redraw] start() - captured startImage: ${startImage}`);
+      initialScreenImage = await system.captureScreenPNG(0.25, true);
+      lastScreenImage = initialScreenImage;
+      emitter.emit(events.log.debug, `[redraw] start() - captured initial image: ${initialScreenImage}`);
     }
 
-    return startImage;
+    return initialScreenImage;
   }
 
   async function checkCondition(resolve, startTime, timeoutMs, options) {
-    const { enabled, screenRedraw, networkMonitor, diffThreshold } = options;
+    const { enabled, screenRedraw, networkMonitor } = options;
 
     // If redraw is disabled, resolve immediately
     if (!enabled) {
@@ -207,33 +245,51 @@ const createRedraw = (
 
     let nowImage = screenRedraw ? await system.captureScreenPNG(0.25, true) : null;
     let timeElapsed = Date.now() - startTime;
-    let diffPercent = 0;
+    let diffFromInitial = 0;
+    let diffFromLast = 0;
     let isTimeout = timeElapsed > timeoutMs;
 
-    // Check screen redraw if enabled and we have a start image to compare against
-    if (screenRedraw && !screenHasRedrawn && startImage && nowImage) {
-      emitter.emit(events.log.debug, `[redraw] checkCondition() - comparing images: ${JSON.stringify({ startImage, nowImage })}`);
-      diffPercent = await imageDiffPercent(startImage, nowImage);
-      emitter.emit(events.log.debug, `[redraw] checkCondition() - diffPercent: ${diffPercent}, threshold: ${diffThreshold}`);
-      screenHasRedrawn = diffPercent > diffThreshold;
-      emitter.emit(events.log.debug, `[redraw] checkCondition() - screenHasRedrawn: ${screenHasRedrawn}`);
-    } else if (screenRedraw && !startImage) {
-      // If no start image was captured, capture one now and wait for next check
-      emitter.emit(events.log.debug, '[redraw] checkCondition() - no startImage, capturing now');
-      startImage = await system.captureScreenPNG(0.25, true);
+    // Screen stability detection:
+    // 1. Check if screen has changed from initial (detect transition)
+    // 2. Check if consecutive frames are stable (detect settling)
+    if (screenRedraw && nowImage) {
+      // Compare to initial image - has the screen changed at all?
+      if (initialScreenImage && !hasChangedFromInitial) {
+        diffFromInitial = await imageDiffPercent(initialScreenImage, nowImage);
+        emitter.emit(events.log.debug, `[redraw] checkCondition() - diffFromInitial: ${diffFromInitial}`);
+        // Consider changed if diff > 0.1% (accounts for compression artifacts)
+        if (diffFromInitial > 0.1) {
+          hasChangedFromInitial = true;
+          emitter.emit(events.log.debug, `[redraw] checkCondition() - screen has changed from initial!`);
+        }
+      }
+      
+      // Compare consecutive frames - has the screen stopped changing?
+      if (lastScreenImage && lastScreenImage !== initialScreenImage) {
+        diffFromLast = await imageDiffPercent(lastScreenImage, nowImage);
+        emitter.emit(events.log.debug, `[redraw] checkCondition() - diffFromLast: ${diffFromLast}`);
+        parseConsecutiveDiffStats(diffFromLast);
+        emitter.emit(events.log.debug, `[redraw] checkCondition() - consecutiveFramesStable: ${consecutiveFramesStable}, measurements: ${screenMeasurements.length}`);
+      }
+      
+      // Update last image for next comparison
+      lastScreenImage = nowImage;
     }
 
-    // If screen redraw is disabled, consider it as "redrawn"
-    const effectiveScreenRedrawn = screenRedraw ? screenHasRedrawn : true;
+    // Screen is settled when: it has changed from initial AND consecutive frames are now stable
+    const screenSettled = hasChangedFromInitial && consecutiveFramesStable;
+    
+    // If screen redraw is disabled, consider it as "settled"
+    const effectiveScreenSettled = screenRedraw ? screenSettled : true;
     // If network monitor is disabled, consider it as "settled"
     const effectiveNetworkSettled = networkMonitor ? networkSettled : true;
 
-    // Log redraw status
+    // Log redraw status - show both change detection and stability
     let redrawText = !screenRedraw
       ? theme.dim(`disabled`)
-      : effectiveScreenRedrawn
+      : effectiveScreenSettled
         ? theme.green(`y`)
-        : theme.dim(`${diffPercent}/${diffThreshold}%`);
+        : theme.dim(`${hasChangedFromInitial ? '✓' : '?'}→${consecutiveFramesStable ? '✓' : diffFromLast.toFixed(1)}%`);
     let networkText = !networkMonitor
       ? theme.dim(`disabled`)
       : effectiveNetworkSettled
@@ -248,9 +304,11 @@ const createRedraw = (
     emitter.emit(events.redraw.status, {
       redraw: {
         enabled: screenRedraw,
-        hasRedrawn: effectiveScreenRedrawn,
-        diffPercent,
-        threshold: diffThreshold,
+        settled: effectiveScreenSettled,
+        hasChangedFromInitial,
+        consecutiveFramesStable,
+        diffFromInitial,
+        diffFromLast,
         text: redrawText,
       },
       network: {
@@ -268,9 +326,11 @@ const createRedraw = (
       },
     });
 
-    if ((effectiveScreenRedrawn && effectiveNetworkSettled) || isTimeout) {
+    if ((effectiveScreenSettled && effectiveNetworkSettled) || isTimeout) {
       emitter.emit(events.redraw.complete, {
-        screenHasRedrawn: effectiveScreenRedrawn,
+        screenSettled: effectiveScreenSettled,
+        hasChangedFromInitial,
+        consecutiveFramesStable,
         networkSettled: effectiveNetworkSettled,
         isTimeout,
         timeElapsed,

agent/lib/sandbox.js

@@ -36,6 +36,25 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
       this.uniqueId = Math.random().toString(36).substring(7);
       this.os = null; // Store OS value to send with every message
       this.sessionInstance = sessionInstance; // Store session instance to include in messages
+      this.traceId = null; // Sentry trace ID for debugging
+    }
+
+    /**
+     * Get the Sentry trace ID for this session
+     * Useful for debugging with customers - they can share this ID to look up their traces
+     * @returns {string|null} The trace ID or null if not authenticated
+     */
+    getTraceId() {
+      return this.traceId;
+    }
+
+    /**
+     * Get the Sentry trace URL for this session
+     * @returns {string|null} The full Sentry trace URL or null if no trace ID
+     */
+    getTraceUrl() {
+      if (!this.traceId) return null;
+      return `https://testdriver.sentry.io/trace/${this.traceId}`;
     }
 
     send(message, timeout = 300000) {
@@ -122,7 +141,15 @@ const createSandbox = (emitter, analytics, sessionInstance) => {
 
       if (reply.success) {
         this.authenticated = true;
-        emitter.emit(events.sandbox.authenticated);
+        
+        // Log and store the Sentry trace ID for debugging
+        if (reply.traceId) {
+          this.traceId = reply.traceId;
+          console.log(`[Sandbox] Sentry Trace ID: ${reply.traceId}`);
+          console.log(`[Sandbox] View trace: https://testdriver.sentry.io/trace/${reply.traceId}`);
+        }
+        
+        emitter.emit(events.sandbox.authenticated, { traceId: reply.traceId });
         return true;
       }
     }

docs/v7/features/stable.mdx

@@ -102,10 +102,10 @@ await testdriver.find('element', {
   }
 }).click();
 
-// Adjust screen diff sensitivity
-await testdriver.find('animated button', {
+// Disable only screen monitoring (keep network monitoring)
+await testdriver.find('animated element', {
   redraw: {
-    diffThreshold: 0.05 // Higher threshold = less sensitive to changes
+    screenRedraw: false // Skip screen stability, still wait for network
   }
 }).click();
 ```
@@ -299,9 +299,8 @@ const testdriver = new TestDriver({
   apiKey: process.env.TD_API_KEY,
   redraw: {
     enabled: true,            // Master switch for redraw detection
-    screenRedraw: true,       // Enable screen change detection
+    screenRedraw: true,       // Enable screen stability detection
     networkMonitor: true,     // Enable network activity monitoring
-    diffThreshold: 0.01,      // Screen diff threshold (0.01 = 0.01%)
   }
 });
 ```
@@ -312,14 +311,14 @@ const testdriver = new TestDriver({
 // Override redraw settings for specific actions
 await testdriver.find('fast element', {
   redraw: {
-    enabled: false // Skip redraw detection
+    enabled: false // Skip redraw detection entirely
   }
 }).click();
 
-await testdriver.find('element with subtle changes', {
+await testdriver.find('element with animation', {
   redraw: {
-    diffThreshold: 0.05, // Less sensitive to screen changes
-    networkMonitor: false // Skip network monitoring
+    screenRedraw: false, // Skip screen stability check
+    networkMonitor: true // Still wait for network to settle
   }
 }).click();
 ```
@@ -337,7 +336,7 @@ const testdriver = new TestDriver({
 
 await testdriver.find('element').click();
 // Console output will show:
-// [redraw] Screen change detected: 0.15% (threshold: 0.01%)
+// [redraw] Screen diff: 0.15%
 // [redraw] Network activity: 1250 b/s
 // [redraw] Waiting for stability...
 ```

interfaces/cli/lib/base.js

@@ -73,12 +73,13 @@ class BaseCommand extends Command {
     };
 
     let isConnected = false;
+    const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
 
-    // Use pattern matching for log events, but skip log:Debug
+    // Use pattern matching for log events, but skip log:Debug unless debug mode is enabled
     this.agent.emitter.on("log:*", (message) => {
       const event = this.agent.emitter.event;
 
-      if (event === events.log.debug) return;
+      if (event === events.log.debug && !debugMode) return;
 
       if (event === events.log.narration && isConnected) return;
       console.log(message);

sdk.js

@@ -2297,14 +2297,15 @@ class TestDriverSDK {
   _setupLogging() {
     // Track the last fatal error message to throw on exit
     let lastFatalError = null;
+    const debugMode = process.env.VERBOSE || process.env.DEBUG || process.env.TD_DEBUG;
 
     // Set up markdown logger
     createMarkdownLogger(this.emitter);
 
     // Set up basic event logging
     this.emitter.on("log:**", (message) => {
       const event = this.emitter.event;
-      if (event === events.log.debug) return;
+      if (event === events.log.debug && !debugMode) return;
       if (this.loggingEnabled && message) {
         const prefixedMessage = this.testContext
           ? `[${this.testContext}] ${message}`