feat: smart video recording with viewport matching and enhanced tool descriptions

Video Recording Enhancements:
- Add intelligent recording modes: smart, continuous, action-only, segment
- Implement automatic viewport matching to eliminate gray borders in videos
- Add pause/resume functionality with manual and automatic control
- Default to 1280x720 HD recording with auto-viewport matching
- Enhanced browser_start_recording with autoSetViewport parameter

Smart Recording System:
- Smart mode: Auto-pause during waits, resume during actions (perfect for demos)
- Action-only mode: Only record during browser interactions
- Segment mode: Create separate video files for each action sequence
- Continuous mode: Traditional behavior with optional manual pause/resume

Tool Enhancements:
- Comprehensive descriptions for all video recording tools
- Professional context and use case guidance
- Integration with browser_wait_for for recordDuringWait parameter
- Action-aware recording in navigation and interaction tools
- Enhanced browser_recording_status with mode and viewport info

Documentation & Testing:
- Complete best practices guide for video recording workflows
- Viewport matching diagnostic and setup scripts
- Recommended video sizes and quality settings
- Gray border problem solution with automatic viewport matching

Solves the gray border issue by ensuring browser viewport matches video
recording dimensions, creating professional full-frame demo videos.

src/tools/wait.ts

@@ -23,11 +23,12 @@ const wait = defineTool({
   schema: {
     name: 'browser_wait_for',
     title: 'Wait for',
-    description: 'Wait for text to appear or disappear or a specified time to pass. Returns page snapshot after waiting (configurable via browser_configure_snapshots).',
+    description: 'Wait for text to appear or disappear or a specified time to pass. In smart recording mode, video recording is automatically paused during waits unless recordDuringWait is true.',
     inputSchema: z.object({
       time: z.number().optional().describe('The time to wait in seconds'),
       text: z.string().optional().describe('The text to wait for'),
       textGone: z.string().optional().describe('The text to wait for to disappear'),
+      recordDuringWait: z.boolean().optional().default(false).describe('Whether to keep video recording active during the wait (default: false in smart mode, true in continuous mode)'),
     }),
     type: 'readOnly',
   },
@@ -36,6 +37,17 @@ const wait = defineTool({
     if (!params.text && !params.textGone && !params.time)
       throw new Error('Either time, text or textGone must be provided');
 
+    // Handle smart recording for waits
+    const recordingInfo = context.getVideoRecordingInfo();
+    const shouldPauseDuringWait = recordingInfo.enabled && 
+      recordingInfo.mode !== 'continuous' && 
+      !params.recordDuringWait;
+
+    if (shouldPauseDuringWait) {
+      await context.endVideoAction('wait', true); // Pause recording for wait
+      response.addResult(`⏸️ Video recording paused during wait (mode: ${recordingInfo.mode})`);
+    }
+
     const code: string[] = [];
 
     if (params.time) {
@@ -57,7 +69,16 @@ const wait = defineTool({
       await locator.waitFor({ state: 'visible' });
     }
 
+    // Resume recording after wait if we paused it
+    if (shouldPauseDuringWait) {
+      await context.beginVideoAction('post-wait'); // Resume recording after wait
+      response.addResult(`▶️ Video recording resumed after wait`);
+    }
+
     response.addResult(`Waited for ${params.text || params.textGone || params.time}`);
+    if (params.recordDuringWait && recordingInfo.enabled) {
+      response.addResult(`🎥 Video recording continued during wait`);
+    }
     response.setIncludeSnapshot();
   },
 });