feat: add snapshot size limits and optional snapshots to fix token overflow

Implements comprehensive solution for browser_click and other interactive tools
returning massive responses (37K+ tokens) due to full page snapshots.

Features implemented:
1. **Snapshot size limits** (--max-snapshot-tokens, default 10k)
   - Automatically truncates large snapshots with helpful messages
   - Preserves essential info (URL, title, errors) when truncating
   - Shows exact token counts and configuration suggestions

2. **Optional snapshots** (--no-snapshots)
   - Disables automatic snapshots after interactive operations
   - browser_snapshot tool always works for explicit snapshots
   - Maintains backward compatibility (snapshots enabled by default)

3. **Differential snapshots** (--differential-snapshots)
   - Shows only changes since last snapshot instead of full page
   - Tracks URL, title, DOM structure, and console activity
   - Significantly reduces token usage for incremental operations

4. **Enhanced tool descriptions**
   - All interactive tools now document snapshot behavior
   - Clear guidance on when snapshots are included/excluded
   - Helpful suggestions for users experiencing token limits

Configuration options:
- CLI: --no-snapshots, --max-snapshot-tokens N, --differential-snapshots
- ENV: PLAYWRIGHT_MCP_INCLUDE_SNAPSHOTS, PLAYWRIGHT_MCP_MAX_SNAPSHOT_TOKENS, etc.
- Config file: includeSnapshots, maxSnapshotTokens, differentialSnapshots

Fixes token overflow errors while providing users full control over
snapshot behavior and response sizes.

Co-Authored-By: Claude <noreply@anthropic.com>

src/tools/keyboard.ts

@@ -27,7 +27,7 @@ const pressKey = defineTabTool({
   schema: {
     name: 'browser_press_key',
     title: 'Press a key',
-    description: 'Press a key on the keyboard',
+    description: 'Press a key on the keyboard. Returns page snapshot after keypress unless disabled with --no-snapshots.',
     inputSchema: z.object({
       key: z.string().describe('Name of the key to press or a character to generate, such as `ArrowLeft` or `a`'),
     }),
@@ -56,7 +56,7 @@ const type = defineTabTool({
   schema: {
     name: 'browser_type',
     title: 'Type text',
-    description: 'Type text into editable element',
+    description: 'Type text into editable element. Returns page snapshot after typing unless disabled with --no-snapshots.',
     inputSchema: typeSchema,
     type: 'destructive',
   },

src/tools/navigate.ts

@@ -23,7 +23,7 @@ const navigate = defineTool({
   schema: {
     name: 'browser_navigate',
     title: 'Navigate to a URL',
-    description: 'Navigate to a URL',
+    description: 'Navigate to a URL. Returns page snapshot after navigation unless disabled with --no-snapshots.',
     inputSchema: z.object({
       url: z.string().describe('The URL to navigate to'),
     }),

src/tools/snapshot.ts

@@ -25,14 +25,14 @@ const snapshot = defineTool({
   schema: {
     name: 'browser_snapshot',
     title: 'Page snapshot',
-    description: 'Capture accessibility snapshot of the current page, this is better than screenshot',
+    description: 'Capture complete accessibility snapshot of the current page. Always returns full snapshot regardless of --no-snapshots or size limits. Better than screenshot for understanding page structure.',
     inputSchema: z.object({}),
     type: 'readOnly',
   },
 
   handle: async (context, params, response) => {
     await context.ensureTab();
-    response.setIncludeSnapshot();
+    response.setForceIncludeSnapshot();
   },
 });
 
@@ -51,7 +51,7 @@ const click = defineTabTool({
   schema: {
     name: 'browser_click',
     title: 'Click',
-    description: 'Perform click on a web page',
+    description: 'Perform click on a web page. Returns page snapshot after click unless disabled with --no-snapshots. Large snapshots (>10k tokens) are truncated - use browser_snapshot for full capture.',
     inputSchema: clickSchema,
     type: 'destructive',
   },
@@ -85,7 +85,7 @@ const drag = defineTabTool({
   schema: {
     name: 'browser_drag',
     title: 'Drag mouse',
-    description: 'Perform drag and drop between two elements',
+    description: 'Perform drag and drop between two elements. Returns page snapshot after drag unless disabled with --no-snapshots.',
     inputSchema: z.object({
       startElement: z.string().describe('Human-readable source element description used to obtain the permission to interact with the element'),
       startRef: z.string().describe('Exact source element reference from the page snapshot'),
@@ -116,7 +116,7 @@ const hover = defineTabTool({
   schema: {
     name: 'browser_hover',
     title: 'Hover mouse',
-    description: 'Hover over element on page',
+    description: 'Hover over element on page. Returns page snapshot after hover unless disabled with --no-snapshots.',
     inputSchema: elementSchema,
     type: 'readOnly',
   },
@@ -142,7 +142,7 @@ const selectOption = defineTabTool({
   schema: {
     name: 'browser_select_option',
     title: 'Select option',
-    description: 'Select an option in a dropdown',
+    description: 'Select an option in a dropdown. Returns page snapshot after selection unless disabled with --no-snapshots.',
     inputSchema: selectOptionSchema,
     type: 'destructive',
   },